Skip to content

PUBLISHING.md

Latest commit

 

History

History
177 lines (138 loc) · 5.03 KB

PUBLISHING.md

File metadata and controls

177 lines (138 loc) · 5.03 KB

Publishing Guide

This is the operator runbook for publishing Charter packages to npm.

Scope

Publishable packages:

  • @stackbilt/types
  • @stackbilt/core
  • @stackbilt/adf
  • @stackbilt/git
  • @stackbilt/classify
  • @stackbilt/validate
  • @stackbilt/drift
  • @stackbilt/blast
  • @stackbilt/surface
  • @stackbilt/policies
  • @stackbilt/ci
  • @stackbilt/cli

Repository root package (charter) is private and must not be published.

Phase 1: Preflight (You Run This)

  1. Ensure clean working tree:
git status
  1. Ensure npm auth:
npm whoami
  1. Ensure release gates pass:
pnpm install
pnpm run clean
pnpm run typecheck
pnpm run build
pnpm run test
pnpm run publish:check

Phase 2: Version Bump

Use one synchronized version for all @stackbilt/* packages until multi-version strategy is introduced.

  1. Set new version in each packages/*/package.json.
# Example: bump all packages to 0.4.0
for pkg in packages/*/package.json; do
  sed -i 's/"version": ".*"/"version": "0.4.0"/' "$pkg"
done

Note: Published package dependencies must not contain workspace: protocol specifiers. Use concrete semver ranges (for example, "^0.4.0").

Phase 3: Artifact Validation (Required)

  1. Verify packed package manifests do not contain workspace: dependency specifiers:
pnpm run publish:check
  1. Dry-run packed contents per package:
(cd packages/types && pnpm pack --dry-run)
(cd packages/core && pnpm pack --dry-run)
(cd packages/adf && pnpm pack --dry-run)
(cd packages/git && pnpm pack --dry-run)
(cd packages/classify && pnpm pack --dry-run)
(cd packages/validate && pnpm pack --dry-run)
(cd packages/drift && pnpm pack --dry-run)
(cd packages/blast && pnpm pack --dry-run)
(cd packages/surface && pnpm pack --dry-run)
(cd packages/ci && pnpm pack --dry-run)
(cd packages/cli && pnpm pack --dry-run)
  1. Verify CLI behavior before publish:
node packages/cli/dist/bin.js --version
node packages/cli/dist/bin.js
node packages/cli/dist/bin.js why
node packages/cli/dist/bin.js --help
node packages/cli/dist/bin.js setup --detect-only --format json
node packages/cli/dist/bin.js setup --format json --yes
node packages/cli/dist/bin.js doctor --format json
node packages/cli/dist/bin.js validate --format json --ci
node packages/cli/dist/bin.js drift --format json --ci
node packages/cli/dist/bin.js audit --format json
node packages/cli/dist/bin.js adf init
node packages/cli/dist/bin.js adf fmt .ai/core.adf
node packages/cli/dist/bin.js adf bundle --task "test task" --format json
node packages/cli/dist/bin.js blast packages/types/src/index.ts --format json
node packages/cli/dist/bin.js surface --format json

When reviewing detect output, confirm:

  • suggestedPreset and selectedPreset are sensible for the repo layout.
  • detected.sources includes expected manifests (root and nested where applicable).

Phase 4: Publish (Dependency Order)

Publish in this order:

  1. @stackbilt/types
  2. @stackbilt/core, @stackbilt/adf, @stackbilt/git, @stackbilt/classify, @stackbilt/validate, @stackbilt/drift, @stackbilt/blast, @stackbilt/surface, @stackbilt/policies, @stackbilt/ci
  3. @stackbilt/cli

@stackbilt/blast and @stackbilt/surface are zero-dependency and can be published in any order relative to the other standalone analyzers. They are only required at publish time by @stackbilt/cli.

# All packages declare publishConfig.access: "public", so --access flag is not needed.
pnpm --filter @stackbilt/types publish
pnpm --filter @stackbilt/core publish
pnpm --filter @stackbilt/adf publish
pnpm --filter @stackbilt/git publish
pnpm --filter @stackbilt/classify publish
pnpm --filter @stackbilt/validate publish
pnpm --filter @stackbilt/drift publish
pnpm --filter @stackbilt/blast publish
pnpm --filter @stackbilt/surface publish
pnpm --filter @stackbilt/policies publish
pnpm --filter @stackbilt/ci publish
pnpm --filter @stackbilt/cli publish

Phase 5: Post-Publish Verification

In a clean external repo:

npx @stackbilt/cli@latest --version
npx @stackbilt/cli@latest
npx @stackbilt/cli@latest why
npx @stackbilt/cli@latest setup --detect-only --format json
npx @stackbilt/cli@latest setup --ci github
npx @stackbilt/cli@latest doctor --format json
npx @stackbilt/cli@latest validate --format json --ci
npx @stackbilt/cli@latest drift --format json --ci
npx @stackbilt/cli@latest audit --format json

Confirm:

  • .charter/ scaffold exists.
  • workflow file is generated when requested.
  • behavior matches docs and exit-code contract.
  • mixed-stack repos are detected correctly, or can be corrected with explicit --preset fullstack.

Release Artifacts

After successful publish:

  1. Create git tag (for example v0.1.1).
  2. Publish release notes summarizing user-visible changes.
  3. Update CHANGELOG.md.

Rollback

If a bad version ships:

  1. Publish a patch fix immediately.
  2. Deprecate broken version(s):
npm deprecate @stackbilt/cli@<bad_version> "Broken release: use <fixed_version>"
  1. Call out corrective version in release notes.