Publish a Package

Overview

The Synoema registry is source-only: every package consists exclusively of .sno source files. No compiled binaries, shared libraries, or native objects are accepted. This policy lets the registry typecheck every upload before it is published, giving consumers confidence that any package they install will compile against their version of the language.

Publishing a package requires three things:

1. A valid sno.toml manifest in the package directory
2. A lib.sno entry point that passes sno check
3. An authenticated session created with sno pkg login

sno.toml — Package manifest

Place sno.toml at the root of your package directory. The [package] section is required; the others are strongly recommended for registry discoverability.

[package]
name        = "my-package"
version     = "1.0.0"
description = "One-sentence description for registry search"
keywords    = ["keyword1", "keyword2", "keyword3"]
license     = "Apache-2.0"
repository  = "https://github.com/you/my-package"

[package.exports]
functions = ["my_func", "helper_func", "MyType"]

[package.use_cases]
tasks = [
  "parse JSON from an HTTP response",
  "validate structured data",
]

[package.capabilities]
network    = false   # true if the package makes outbound network calls
filesystem = false   # true if the package reads or writes files
spawn      = false   # true if the package spawns OS threads or processes

Required fields

Recommended fields

Source-only policy

The registry rejects uploads containing files with these extensions:

.so  .dll  .bin  .o  .dylib  .exe  .a

If your package wraps a native library, document the installation steps in your README and use fd_popen or a shell-out builtin to call the external tool at runtime. The .sno wrapper itself will be accepted by the registry.

CLI workflow

Step 1 — Authenticate

Run once per machine. Opens a browser tab for GitHub or Google OAuth:

sno pkg login

Your API key is saved to ~/.sno/config.toml automatically. If you prefer to supply the key directly (for CI environments), use:

sno pkg login --key sno_YOUR_KEY_HERE

Step 2 — Prepare your package

Your directory must contain at least:

my-package/
├── sno.toml      # package manifest
└── lib.sno       # entry point — must pass `sno check`

Verify locally before publishing:

sno check lib.sno     # typecheck — must exit 0
sno doc lib.sno       # preview generated docs

Step 3 — Publish

Run from inside the package directory:

sno publish

The CLI will:

1. Read sno.toml for name and version
2. Detect breaking changes relative to the previously published version and prompt for confirmation
3. Pack the directory into a .tar.gz archive
4. Upload to the registry with a SHA-256 checksum

To skip the breaking-change prompt in CI:

sno publish --no-breaking-check

Rate limits

The registry enforces a limit of 10 uploads per publisher per hour. Pre-release versions (1.0.0-beta.1) and stable versions share the same counter.

Quality gates

Every upload is validated server-side before it is stored. All of the following must pass:

Yanking a version

If you need to retract a release, yank it. Yanked versions remain downloadable for existing users but are excluded from sno pkg add pkg@latest and the GET /pkg/{name}/latest endpoint.

sno pkg yank my-package@1.0.0

Yanking is irreversible via the CLI. Contact registry support to un-yank a version.

What's Next