Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

5.5 KB
Raw Blame

Releasing the SDK

@macro-inc/sdk publishes to npm when a merge to main raises the version in packages/sdk/package.json. There is no release PR, no dispatch, and no tag to push: bump the version in the same PR that changes the SDK, and merging it releases. If the version is unchanged, the release workflow resolves to a no-op.

Release SDK validates the package, runs npm publish, and only then pushes the sdk-vX.Y.Z tag, so a release tag always names a commit that actually shipped.

Agents can use release-sdk.

Bump

From packages/sdk, on the branch carrying your SDK change:

just bump          # patch; also accepts minor, major, or an explicit X.Y.Z

The script refuses a version npm already has, and touches only the version field. Commit it with the rest of your change — reviewers should see the API change and the version it ships in one diff.

Then run the same validation the release workflow runs:

bun install --frozen-lockfile
bun run check && bun test && bun run coverage && bun run build && bun run check:pack
npm pack --dry-run --ignore-scripts

The compiled JavaScript and declaration files referenced by exports must appear in the package listing. check:pack installs the tarball into isolated core, browser, and Node consumers and checks imports, types, and bundle isolation. coverage checks endpoint wrappers, not test coverage. SDK Check runs the same package suite on the PR and again on the merge to main. Generated-code freshness is checked on the PR by the web app workflow's Generated Code Check; if it reports staleness, run just update-generated and review the diff. Run just check from the repository root before committing.

Forgetting to bump publishes nothing, which is the intended failure mode: open a follow-up PR with the bump.

What happens on merge

Release SDK runs on any push to main touching packages/sdk/package.json:

  1. bun scripts/resolve-release.ts reads the manifest version and asks npm about it. Already published → no-op. Below what npm serves → fails, since that is an accidental downgrade. The policy lives in scripts/release.ts, shared with just bump and unit-tested in tests/release.test.ts; semver does the comparing.
  2. bun install --frozen-lockfile, then check, test, coverage, build, check:pack.
  3. npm publish --access public over OIDC trusted publishing. A prerelease version publishes under the next dist-tag so it never becomes what a plain npm install resolves to.
  4. Pushes the lightweight tag sdk-vX.Y.Z at the released commit.

Verify:

gh run list --repo macro-inc/macro --workflow release-sdk.yml --branch main \
  --json databaseId,headSha,status,conclusion,url
npm view "@macro-inc/sdk@<version>" version dist.tarball --json --registry=https://registry.npmjs.org
npm view @macro-inc/sdk dist-tags --json --registry=https://registry.npmjs.org

A merged bump, a green job, or a pushed tag is not proof of publication; the npm version is. If the run has not appeared or npm has not updated, allow a short bounded wait and report pending status rather than claiming success.

One-time npm setup

Publication uses OIDC trusted publishing, so no npm token lives in GitHub secrets. A package maintainer must register the publisher once, on npmjs.com:

Setting Value
Provider GitHub Actions
Organization macro-inc
Repository macro
Workflow filename release-sdk.yml
Environment Leave blank; the job declares no environment
Allowed actions Allow direct publishing with npm publish

Register publish-sdk.yml as a second trusted publisher to keep the recovery path below working. Until this is done, every release fails at npm publish with an authentication error. Do not interpret network or authentication errors as proof that the package or version is available. npm documents the requirement in its trusted publishing guide.

packages/sdk/package.json must keep repository metadata matching https://github.com/macro-inc/macro.

Recovery

Publish SDK remains as the manual path, triggered by pushing an sdk-v* tag. Use it when a release commit is already on main but the automatic run failed for a transient reason and left the version unpublished:

git fetch origin main --tags
git merge-base --is-ancestor "$sdk_release_sha" origin/main
git tag "sdk-v${sdk_version}" "$sdk_release_sha"
git push origin "refs/tags/sdk-v${sdk_version}"

It re-checks that the tag version matches the manifest and that the commit is on main. Tags pushed by Release SDK use GITHUB_TOKEN, which does not start another workflow run, so the two paths never double-publish.

On failure, read the job logs and check npm before retrying: a run may have published before a later step failed. Code fixes go through a new PR and a new version. Never overwrite an existing npm version, move a release tag, or publish locally as a shortcut. Report missing npm access or setup as a concrete blocker.

Maintaining the workflows

Both workflows are generated from Rust: release_sdk.rs and publish_sdk.rs. Change the source and regenerate with cargo x workflows from the repository root; do not hand-edit the generated YAML.