Publishing packages

A library is a peko.toml with [package] and [lib]. Only a package can be published.

peko verify           # pack in memory and check, writing nothing
peko deploy package   # pack, verify, upload

Run verify first. It reports hard errors that make a package unpublishable and warnings for missing registry metadata, and it is the same check publishing runs.

What verify checks

• The container header and that the framed sections fit the file.
• The embedded manifest parses and is a [package] with [lib].
• Registry-quality fields: a blank description, a missing license, no authors, or no repository each produce a warning.
• The payload decompresses, and the packed peko.toml matches the embedded one.
• The [lib].root entry file is present in the payload.
• Build artifacts have not leaked in.

The upload

Publishing is a three-step handshake: request an upload slot, PUT the container to a signed storage URL, then signal completion. The server reads the name, version, and dependencies from the embedded manifest, validates them, computes the checksum, and rejects a duplicate version.

The version is then pending admin review and appears on the public index once approved. Maximum package size is 50 MB. A published version cannot be overwritten; bump the version.

Publishing needs a session and a verified email.

Uploading from the browser

A .pkpkg built by the CLI can also be uploaded on the platform at /packages/publish instead of going through peko deploy package. The container is the same either way, and so is the review that follows, so use whichever fits: the command for a normal release, the web form when the machine holding the package is not the one signed in.

To produce the container without uploading, run peko verify, which packs it in memory, or pack it as part of a release process and upload the file.

The .pkpkg container

[32-byte header][embedded peko.toml][zstd(tar(source))][optional signature]

The header carries a magic value, the container version, the compression tag, a flags byte, and the two section lengths. The embedded manifest is the verbatim on-disk peko.toml.

The payload excludes .peko/, target/, peko.lock, and any .pkpkg. It does not currently exclude node_modules/ or .git/, so a library that carries either should keep them out of the package directory.

Integrity comes from a SHA-256 checksum recorded in the index and verified on download. The format reserves a signature trailer, but nothing signs a .pkpkg today.

Gated packages, from the consumer side

Some packages on the registry are distributed as prebuilt bundles rather than source, and need a paid entitlement to download. Publishing those is an administrative process, not something a package author does with the CLI.

Consuming one is transparent: peko add <name> as usual. What arrives carries definition-only stubs and compiled objects rather than source, so the analyzer sees the full API while the implementation stays closed. See the Dependencies page for the failure cases.