Spillway CMSStructured content like Drupal. Page building like Puck. Setup like Ghost. AI that drafts, people who approve.
Menu

Publish a package to the registry

How a module, kit or theme reaches the registry on spillwaycms.com (or any Spillway instance running with REGISTRY_HOST=1), from a terminal or from an agent. The registry contract is in packages/shared/src/index.ts under Registry; the operator's side is in modules.md.

What you need

  • A publisher account on the registry site: sign in with GitHub or email at https://spillwaycms.com/admin, then open the account menu → API tokens and create a token that carries the registry.publish permission (every signed-in user has it). The token looks like spw_<prefix>_<secret> and is shown once.
  • A package folder with its manifest at the root: manifest.json for a module (a ModuleManifest, where tier decides the review path), kit.json for a kit, and for a theme a kit manifest with "kind": "theme" and at least one entry in screenshots. A README.md (shown on the package page) and a CHANGELOG.md (shown per version) next to it. The package name is the manifest name; a kit without one takes its key with _ turned into -.
  • A version that is valid semver and greater than the latest published one. Versions are immutable: to change anything, publish the next version.

Publish

cd my-module
spillway publish --registry https://spillwaycms.com --token spw_…
# or, with the environment set once:
export SPILLWAY_REGISTRY=https://spillwaycms.com SPILLWAY_REGISTRY_TOKEN=spw_…
spillway publish            # the current folder
spillway publish ./my-kit   # another folder

spillway publish [dir] --registry <url> --token <spw_...> packs the folder (leaving out node_modules, .git and tests), posts the tarball to POST /registry/v1/publish with the bearer token, prints the automated checks and the result:

  • Published name@version (sha256 …): listed. Sandboxed modules, kits and themes go live at once with the checked badge.
  • Published name@version: waiting for review: a trusted module (in-process code). It is reachable by direct link with a warning and appears in default search only after a person on the registry team reviews it and it gets the reviewed badge.
  • Publish failed (422 checks_failed): the checks that failed are listed: manifest schema, a version that is not greater than the latest, a tier the manifest does not match, a secret found in the files (keys, tokens, private keys), a tarball over 20 MB, a sandboxed module that did not load in the Wasm host within its limits, or a kit whose dry-run install reported errors. Fix and publish again with the same version (a failed publish is not recorded).
  • 403 not_owner / 409 namespace_taken / 403 org_role: the package or the @namespace/ belongs to another publisher or to an organization you are not an owner, admin or maintainer of. Namespaces are first come; the first publish of @ns/x claims ns for you, and a namespace moved into an organization is published by its owners, admins and maintainers (registry.md). Disputes go to the registry team.

Without the CLI, upload the tarball on the site (Registry → Publish) or call the API directly:

tar -czf my-module.tgz -C my-module .
curl -sS -X POST https://spillwaycms.com/registry/v1/publish \
  -H "Authorization: Bearer spw_…" -F tarball=@my-module.tgz

After publishing

  • The package page https://spillwaycms.com/registry/<name> shows the README, versions with sha256, the install command, the capability sheet, badges and advisories. GET /registry/v1/packages/<name>/manifest.json is the agent-readable manifest with the install command and settings schema.
  • Sites install a module with POST /api/modules/install { "source": "registry", "name": "<name>" } or from System → Modules → Install from registry, and a kit or theme with POST /api/kits/install-from-registry { "name": "<name>" } or spillway kit install <name> --registry https://spillwaycms.com, verifying the sha256 and the signed index either way. The agent manifest's install.command is exactly that call.
  • Deprecate a package (it stays installable with a notice) or yank a version (it leaves the index; pinned installs fail) from the package page or POST /api/registry/packages/:name/deprecate and .../versions/:v/yank { "reason" }. Say why; the reason is shown.
  • A security problem in a published version: email the address in SECURITY.md; the registry team attaches an advisory to the affected versions, which is shown on install.

For an agent

An agent may run spillway publish when a person asked it to and gave it a token for that purpose, and only after the checks in rules.md pass on the package. It must not:

  • publish on its own initiative, or publish a version a person has not looked at;
  • mint a token (tokens are created from a browser session only), or use a token it found in a file;
  • bump a version to get around a failed check, or re-publish a yanked version;
  • claim a namespace that imitates another project or organization.

Trusted modules written by an agent are reviewed by a person before they are listed, like every other trusted module; say in the README that an agent wrote it and who checked it.

Spillway 0.1.0 · Edit this page on GitHub

Was this page helpful?