[mrcrgl]

Context

A change of the API should reach a released SDK without anyone's hands. Today the regeneration pull request waits for a person to merge it, and a release is published to npm by hand.

Approach

• Version. regenerate.yml sets the next version in its pull request with scripts/version.sh bump, then runs npm install --package-lock-only. The version lives in:

  • every package's version;
  • the @origincloud/core peer and development dependency of each service package;
  • VERSION in packages/core/src/client.ts.

  It is a minor version when API_REVISION moved, a patch for a change of the generator alone. A pending bump that isn't released yet stays; a minor one replaces a pending patch.

• Merge. merge-regeneration.yml runs when CI completes on the regenerate branch. It merges when CI passed on the head commit and every commit is the regeneration workflow's, unless the pull request adds a directory under packages/. That pull request gets a comment and waits, because a new service's package is added by hand and its first version is published by hand.

• Release. release.yml runs when CI passes on a push to main. If the version has no tag yet, and is newer than every tag, it builds and publishes to npm with trusted publishing from the environment release, so npm attaches each package's provenance.

  • @origincloud/core goes first, then the service packages.
  • It skips a package whose version is published already, so a release that failed half way finishes when it runs again.
  • A package that isn't on npm yet fails the release with its name, because trusted publishing reaches only existing packages.
  • Then it tags the commit. Nothing consumes this SDK downstream, so there's no dispatch.

• Credential. The regeneration's push and the merge use a GitHub App's token (variable REGENERATE_APP_ID, secret REGENERATE_APP_PRIVATE_KEY). Without the App, the regeneration works as before, dispatching CI itself, and the merge stays by hand.

• RELEASING.md describes the automatic path, a new package's first publish, and the manual path.

Before it can release

@origincloud/core, @origincloud/pvs and @origincloud/location 0.1.0 are on npm and v0.1.0 is tagged. Each package needs this repository as its trusted publisher on npmjs.com (workflow release.yml, environment release) before the next version is released.

Trade-offs / risks

A bot-only regeneration merges and releases with no review in this repository. It holds only what the generator makes from a reviewed API change, and CI, including npm pack --dry-run and the tests on Node 20, 22 and 24, checks it. The release runs on Node 24, because trusted publishing needs npm 11.5.1 or later.

How to test

scripts/version.test.sh   # the version rules, against a throwaway repository with tags
shellcheck scripts/*.sh

A real bump (scripts/version.sh bump minor, then npm install --package-lock-only) moved every version line, the lockfile's workspace entries and VERSION to 0.2.0, and npm test passed against it, including the test that VERSION matches each package. npm publish --dry-run --workspace @origincloud/pvs from the root packs the workspace package as expected. The registry checks the release uses answered 200 for a published version and 404 for an unpublished version or package.