codebyplan 1.5.0 → 1.8.0

package/templates/skills/cbp-ship/reference/npm-publish-monorepo.md

@@ -0,0 +1,252 @@
+# Monorepo Publishing — pnpm Workspaces
+
+Publishing one or more packages from a pnpm workspace. Workspace layout, `pnpm publish` vs `npm publish`, per-package `publishConfig`, version-management tools (changesets vs release-please), public/private separation, pre-publish gates.
+
+## Workspace Layout
+
+A typical pnpm monorepo with mixed published and internal packages:
+
+```
+repo/
+├── pnpm-workspace.yaml
+├── package.json                # private: true; root tooling only
+├── packages/
+│   ├── published/
+│   │   ├── cli/                # @codebyplan/cli — published
+│   │   ├── design-tokens/
+│   │   └── auth/
+│   └── internal/
+│       ├── eslint-config/      # @codebyplan/eslint-config — private
+│       └── tsconfig/
+└── apps/
+    ├── web/                    # not published
+    └── backend/
+```
+
+`pnpm-workspace.yaml`:
+
+```yaml
+packages:
+  - "packages/*/*"
+  - "apps/*"
+```
+
+`packages/published/*` vs `packages/internal/*` is **organisational**. What keeps internal packages off the registry is `"private": true` in their `package.json` — pnpm refuses to publish private packages and skips them silently in `pnpm -r publish`.
+
+## Root `package.json`
+
+Always private at the root — never accidentally publish the workspace meta-package:
+
+```json
+{
+  "name": "codebyplan-monorepo",
+  "private": true,
+  "scripts": {
+    "build": "turbo run build",
+    "test": "turbo run test",
+    "lint:packages": "turbo run lint:package",
+    "release": "changeset publish"
+  }
+}
+```
+
+## Per-Package `package.json`
+
+A published workspace package needs `publishConfig`:
+
+```json
+{
+  "name": "@codebyplan/cli",
+  "version": "1.4.2",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": { "codebyplan": "./dist/cli.js" },
+  "files": ["dist", "README.md"],
+  "engines": { "node": ">=20" },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codebyplan/codebyplan.git",
+    "directory": "packages/published/cli"
+  }
+}
+```
+
+Notes:
+
+- `repository.directory` tells the registry which subfolder this package lives in. Required for provenance attestations to validate.
+- `publishConfig.access: "public"` is required for scoped packages (`@codebyplan/*`). Without it the first publish fails with `402 Payment Required`.
+- `publishConfig.provenance: true` is the package.json equivalent of `--provenance` on the CLI.
+
+An internal package just sets `"private": true`:
+
+```json
+{
+  "name": "@codebyplan/eslint-config",
+  "version": "0.0.0",
+  "private": true,
+  "main": "./index.js"
+}
+```
+
+## `pnpm publish` vs `npm publish`
+
+| Capability | `pnpm publish` | `npm publish` |
+|------------|----------------|----------------|
+| Recursive (`-r`) — publish all changed packages | Yes | No |
+| `--filter` to scope to a subset | Yes | No |
+| Auto-includes workspace root `LICENSE` | Yes | No |
+| Rewrites `workspace:*` deps to actual versions in tarball | Yes — automatic | No |
+| `--no-git-checks` | Yes | No |
+| OIDC trusted publishing | Yes (npm CLI underneath) | Yes |
+
+For a pnpm monorepo, **always use `pnpm publish`** — `npm publish` will leak `workspace:*` protocol strings into the published tarball and consumers will get install errors.
+
+`pnpm publish -r` only publishes packages whose `version` is not already on the registry — safe to run repeatedly.
+
+## Version Management — Changesets vs release-please
+
+Two dominant tools. Both work with pnpm + GitHub Actions OIDC.
+
+### Changesets
+
+Maintainer-friendly — every PR adds a `.changeset/*.md` file declaring intent:
+
+```
+.changeset/funky-tigers-dance.md
+---
+"@codebyplan/cli": minor
+"@codebyplan/auth": patch
+---
+
+Added --provenance flag to publish command. Auth payload now includes scope.
+```
+
+Workflow:
+
+1. `pnpm changeset` while authoring a PR. Pick affected packages and bump types.
+2. PR merges to main. Changesets GitHub Action opens (or updates) a "Version Packages" PR that consumes pending changesets, bumps versions, regenerates CHANGELOGs.
+3. Merging the Version Packages PR triggers `pnpm changeset publish` → calls `pnpm publish -r` for every bumped package.
+
+`.changeset/config.json` essentials:
+
+```json
+{
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": ["@codebyplan/web", "@codebyplan/backend"]
+}
+```
+
+`ignore` excludes apps that are deployed but never published.
+
+Strengths: explicit intent per change; supports linked/fixed package groups; rich CHANGELOG output. Weaknesses: every PR must remember to add a changeset (the bot enforces this).
+
+### release-please
+
+Conventional-commit-driven — version is inferred from commit messages (`feat:` → minor, `fix:` → patch, `feat!:` or `BREAKING CHANGE:` → major):
+
+1. Developer writes conventional-commit messages.
+2. release-please GitHub Action watches main, opens a release PR per package summarising commits since the last tag.
+3. Merging the release PR creates a git tag, GitHub release, and triggers a separate publish workflow.
+
+`release-please-config.json`:
+
+```json
+{
+  "packages": {
+    "packages/published/cli": { "release-type": "node" },
+    "packages/published/auth": { "release-type": "node" }
+  },
+  "plugins": ["node-workspace"]
+}
+```
+
+The `node-workspace` plugin keeps `workspace:*` deps in sync across the bump.
+
+Strengths: zero per-PR ceremony when commit hygiene is enforced. Weaknesses: monorepo config is more involved; granular bump control is harder.
+
+### Picking one
+
+- Conventional commits enforced → release-please.
+- Want explicit per-PR intent and rich CHANGELOGs → Changesets.
+- OSS / mixed contributors → Changesets (the bot reminds people).
+
+CodeByPlan uses Changesets for `packages/published/*`.
+
+## Pre-Publish Gates
+
+Run these in CI before `pnpm publish -r`:
+
+| # | Gate | Command |
+|---|------|---------|
+| 1 | Build | `pnpm -r --filter "./packages/published/*" build` |
+| 2 | Test | `pnpm -r --filter "./packages/published/*" test` |
+| 3 | publint | `pnpm -r --filter "./packages/published/*" exec publint` |
+| 4 | attw | `pnpm -r --filter "./packages/published/*" exec attw --pack .` |
+| 5 | Dry-run pack | `pnpm -r --filter "./packages/published/*" publish --dry-run` |
+
+[publint](https://publint.dev) catches missing `exports`, broken `main` pointers, type-definition exclusion, ESM/CJS misalignment. [Are The Types Wrong](https://arethetypeswrong.github.io/) validates that the published tarball resolves correctly under both CJS and ESM consumers across conditional-export combinations.
+
+The dry-run output lists every file that would be in the tarball plus total size. Compare against `files` in `package.json` — anything outside `files` means the glob is wrong (or `.npmignore` is interfering).
+
+`pnpm publish -r` skips already-published versions automatically, but for clarity:
+
+```bash
+pnpm -r --filter "./packages/published/*" exec sh -c \
+  'npm view "$npm_package_name@$npm_package_version" version 2>/dev/null \
+   && echo "ALREADY PUBLISHED" && exit 1 || true'
+```
+
+Wire gates 3-4 as a turbo task in each package's `package.json`:
+
+```json
+{
+  "scripts": {
+    "lint:package": "publint && attw --pack ."
+  }
+}
+```
+
+Then in CI before publish: `pnpm turbo run lint:package`.
+
+## Public / Private Separation Recap
+
+| Layer | Mechanism | Purpose |
+|-------|-----------|---------|
+| Folder convention | `packages/published/*` vs `packages/internal/*` | Human signal |
+| `private: true` | `package.json` per internal package | Hard block — pnpm refuses to publish |
+| Changesets `ignore` | `.changeset/config.json` | Keeps deployed apps off the version PR |
+| Workspace dep protocol | `"@codebyplan/foo": "workspace:*"` | Internal deps stay internal; pnpm rewrites at publish time |
+
+When an internal package is published by mistake:
+
+1. `npm unpublish @scope/pkg@x.y.z` within 72 hours, OR
+2. `npm deprecate @scope/pkg@"<= x.y.z" "Internal package — do not use"` after that.
+
+Then add `"private": true` and ship.
+
+## Sources
+
+- [pnpm — publish](https://pnpm.io/cli/publish)
+- [pnpm — workspaces](https://pnpm.io/workspaces)
+- [npm Docs — package.json](https://docs.npmjs.com/cli/v10/configuring-npm/package-json)
+- [Changesets](https://github.com/changesets/changesets)
+- [release-please](https://github.com/googleapis/release-please)
+- [publint](https://publint.dev/)
+- [Are The Types Wrong](https://arethetypeswrong.github.io/)
+- [npm CLI source](https://github.com/npm/cli)

package/templates/skills/cbp-ship/reference/npm-publish-oidc-trusted.md

@@ -0,0 +1,157 @@
+# npm OIDC Trusted Publishing
+
+Modern publish flow: no NPM_TOKEN, no leak risk. npm trusts a short-lived OIDC token issued by your CI provider. Provenance attestations are generated automatically and recorded in a public transparency ledger (Sigstore).
+
+This is the **default publish path for `/cbp-ship`** when the npm-package surface is in play — it's the publish path the orchestrator should reach for first.
+
+## How It Works
+
+1. CI job starts. The CI provider (GitHub Actions, GitLab CI, CircleCI) mints a short-lived OIDC ID token signed with its public key.
+2. `npm publish` reads the OIDC token from the runner and exchanges it with the npm registry for a one-shot publish credential.
+3. npm validates the OIDC token's claims — `repository`, `workflow`, `ref`, `aud` — against the trusted-publisher rule registered for the package.
+4. If the claims match, the publish is accepted. If not, the publish is rejected with `403`.
+5. (GitHub Actions / GitLab only) npm automatically generates a Sigstore provenance attestation linking the published tarball to the exact commit, workflow file, and runner image that built it. The attestation is logged to the [Rekor transparency ledger](https://search.sigstore.dev/).
+
+The OIDC token's lifetime is measured in minutes; it is bound to the workflow run; it cannot be replayed. There is nothing for an attacker to exfiltrate from the runner that survives the job.
+
+## Supported Providers
+
+| Provider | OIDC | Auto-provenance |
+|----------|------|-----------------|
+| GitHub Actions (GitHub-hosted runners) | Yes | Yes |
+| GitLab CI/CD (GitLab.com shared runners) | Yes | Yes |
+| CircleCI cloud | Yes | No (must pass `--provenance` manually with extra setup) |
+| Self-hosted runners (any provider) | Not supported | Not supported |
+
+Self-hosted runners cannot use trusted publishing today — the npm registry does not yet validate signing certificates from non-cloud OIDC issuers.
+
+## Setup — GitHub Actions
+
+### Step 1 — Register the trusted publisher on npmjs.com
+
+1. Sign in at https://www.npmjs.com.
+2. Navigate to your package: `npmjs.com/package/<your-pkg>`.
+3. Settings → **Trusted Publishers** → **Add publisher**.
+4. Select **GitHub Actions**, then fill in:
+   - **Organization or user**: e.g. `codebyplan`
+   - **Repository**: e.g. `codebyplan`
+   - **Workflow filename**: e.g. `release.yml` (just the filename, not the full path)
+   - **Environment** (optional): e.g. `production` — restricts to runs scoped to a GitHub Actions environment
+
+If the package does not yet exist on the registry, you must publish it once with a classic token before you can register a trusted publisher (npm requires the package to exist to attach a trust rule).
+
+### Step 2 — Update the workflow
+
+Add `id-token: write` to the job's permissions and use a recent npm CLI (≥9.5.0; npm 10+ is recommended).
+
+```yaml
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read       # checkout
+      id-token: write      # OIDC — required for trusted publishing
+      attestations: write  # required for provenance attestations
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm build
+
+      - run: pnpm test
+
+      - name: Verify publish (dry run)
+        run: pnpm publish --dry-run --access public
+
+      - name: Lint package shape
+        run: |
+          pnpm dlx publint
+          pnpm dlx @arethetypeswrong/cli --pack
+
+      - name: Publish to npm
+        run: pnpm publish --access public --provenance --no-git-checks
+```
+
+Notes:
+
+- **No `NODE_AUTH_TOKEN` env var.** That's the entire point — there is no token to leak. The `setup-node` action wires up `.npmrc` to the registry URL; OIDC handshake happens inside `npm publish`.
+- `--provenance` is **automatic** on GitHub Actions OIDC publishes (npm enables it implicitly), but passing the flag is harmless and makes intent explicit. `publishConfig.provenance: true` in `package.json` is the third equivalent.
+- `--no-git-checks` (pnpm-only) bypasses the "current branch must be the publish branch, working tree must be clean" check. Safe in CI where the runner has a fresh clone at a tag.
+
+## Provenance Attestations
+
+A provenance attestation is a JSON document signed by Sigstore that describes:
+
+- The source repository URL and the exact commit SHA that was built.
+- The workflow file path and the run ID.
+- The builder identity (e.g. `https://github.com/actions/runner`).
+- The npm package name, version, and tarball SHA.
+
+After publish, the npm registry shows a "Provenance" badge on the package page linking to the Sigstore record.
+
+### Verifying attestations as a consumer
+
+```bash
+npm audit signatures
+```
+
+This walks every dependency in the current project, checks the registry signature on each tarball, and validates any provenance attestations. A failure means either the package was tampered with after publish or its signing identity changed unexpectedly.
+
+For a single package without installing it:
+
+```bash
+npm view <pkg> --json | jq '.dist.attestations'
+```
+
+Returns the URL of the attestation bundle on the registry; the bundle is a Sigstore-format JSON that can be verified with `cosign` or the `sigstore-js` library.
+
+## Comparison vs Classic NPM_TOKEN
+
+| Aspect | Classic NPM_TOKEN | OIDC Trusted Publishing |
+|--------|-------------------|--------------------------|
+| Secret stored in CI | Yes — long-lived token | No |
+| Rotation burden | Manual; forgotten tokens are common | None — every publish mints a fresh credential |
+| Leak blast radius | Token works from anywhere until revoked | Credential expires in minutes; bound to one workflow run |
+| Provenance | Manual `--provenance` + extra setup | Automatic on GitHub Actions / GitLab |
+| Setup complexity | Generate token, paste into CI secrets | One-time npm web UI registration |
+| Works on self-hosted runners | Yes | No (today) |
+| Works locally | Yes | No (no OIDC issuer) |
+
+Classic tokens still have a place: local release machines, self-hosted runners, providers npm doesn't trust yet. For everything else, OIDC is the default in 2026.
+
+## Failure Modes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `403 Forbidden — OIDC publish requires id-token: write` | Workflow missing the permission | Add `permissions.id-token: write` to the job |
+| `403 — trusted publisher mismatch` | Workflow filename, repo, or org doesn't match the rule | Re-check the trusted-publisher rule on npmjs.com matches `${{ github.repository }}` and `${{ github.workflow_ref }}` exactly |
+| `Provenance generation failed: repository field mismatch` | `package.json` `repository.url` doesn't match the GitHub repo URL | Set `"repository": { "type": "git", "url": "git+https://github.com/<org>/<repo>.git" }` (case-sensitive) |
+| Attestations missing on the registry page | Used CircleCI without manual provenance setup | Either accept (CircleCI limitation) or migrate to GitHub Actions / GitLab |
+| `OIDC token unavailable` from a self-hosted runner | Trusted publishing not supported there | Fall back to a granular token, or move the publish job to a GitHub-hosted runner |
+
+## Sources
+
+- [npm Docs — Trusted publishers](https://docs.npmjs.com/trusted-publishers)
+- [npm Docs — Generating provenance statements](https://docs.npmjs.com/generating-provenance-statements)
+- [npm Docs — npm audit signatures](https://docs.npmjs.com/cli/v10/commands/npm-audit)
+- [Sigstore](https://www.sigstore.dev/) — signing infrastructure
+- [npm CLI source](https://github.com/npm/cli)

package/templates/skills/cbp-ship/reference/npm-publish-overview.md

@@ -0,0 +1,171 @@
+# npm Publish — Overview
+
+Reference for the `/cbp-ship` orchestrator's `npm-package` surface. Covers what `npm publish` does, registry types, 2FA tiers, package metadata that affects publish output, and `latest` dist-tag semantics.
+
+## What `npm publish` Does
+
+`npm publish` packs the current package into a tarball and uploads it to a registry, registering the version under the package name. Once a version is published it is **immutable** — you cannot republish the same `name@version` (you can only `npm unpublish` within 72 hours, and only if no other public package depends on it).
+
+Pack rules:
+
+1. CLI computes the file list from (in order): `files` field in `package.json`, `.npmignore`, `.gitignore`. Always-included: `package.json`, `README*`, `LICENSE*`, the file at `main`/`bin`/`exports`. Always-excluded: `node_modules`, `.git`, `.npmrc`, `package-lock.json`.
+2. CLI runs lifecycle scripts: `prepublishOnly` → `prepack` → tarball write → `postpack` → `publish` → `postpublish`.
+3. Tarball uploaded to registry with auth (token or OIDC); registry assigns the `latest` dist-tag unless `--tag <name>` overrides.
+
+`npm publish --dry-run` runs all the above except the upload — use it to preview the file list and lifecycle execution.
+
+## Registry Types
+
+| Registry | Purpose | URL |
+|----------|---------|-----|
+| Public registry | Default; what `npm install <pkg>` hits | `https://registry.npmjs.org` |
+| GitHub Packages | npm packages scoped to a GitHub org | `https://npm.pkg.github.com` |
+| Private registry | Verdaccio, Nexus, JFrog Artifactory, Bytesafe, Cloudsmith | self-hosted or vendor URL |
+
+Registry selection comes from (highest precedence first):
+
+1. `publishConfig.registry` in `package.json`
+2. `--registry <url>` on the CLI
+3. `npm_config_registry` env var
+4. `registry=` line in `.npmrc` (project, then user, then global)
+5. Default — `https://registry.npmjs.org`
+
+Scoped packages (`@scope/name`) can route by scope: `@cbp-registry=https://npm.pkg.github.com` in `.npmrc` sends only that scope to GH Packages.
+
+## 2FA Tiers
+
+npm offers two 2FA modes (set with `npm profile enable-2fa <mode>`):
+
+| Mode | Covers | Use case |
+|------|--------|----------|
+| `auth-only` | Login, profile changes | Convenience — publishes work with token alone |
+| `auth-and-writes` | Login + every publish, `dist-tag`, `unpublish`, `access` change | Hardened — publish requires fresh OTP |
+
+Publishing requires **one** of:
+
+- 2FA enabled on the account (any mode), OR
+- A **granular access token** with "bypass 2FA" enabled (legacy automation tokens are deprecated; granular is the modern equivalent).
+
+For CI flows the modern recommendation is **OIDC trusted publishing** (no token at all) — see [npm-publish-oidc-trusted.md](./npm-publish-oidc-trusted.md). Granular tokens with bypass-2FA remain valid for non-CI release machines.
+
+## Package Metadata That Matters at Publish Time
+
+### `exports`
+
+Modern entry-point map. Replaces `main` for resolvers that honour it (Node ≥12.20, all modern bundlers). Conditional exports let you ship CJS + ESM + types from one package:
+
+```json
+{
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  }
+}
+```
+
+Always export `./package.json` — toolchains (`publint`, `attw`) and some bundlers expect it. If `exports` is set, `main` becomes a fallback only for legacy resolvers.
+
+### `files`
+
+Allowlist of paths to include in the tarball. Prefer `files` over `.npmignore` — allowlists fail closed (forgetting to ignore a build artefact never leaks a secret):
+
+```json
+{
+  "files": ["dist", "README.md", "LICENSE"]
+}
+```
+
+`package.json`, `README*`, `LICENSE*` are always included regardless. `test/`, `__tests__/`, `*.test.*` are excluded automatically.
+
+### `publishConfig`
+
+Per-package override of registry config, applied only at publish time. Common keys:
+
+```json
+{
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "tag": "next",
+    "provenance": true
+  }
+}
+```
+
+- `access: "public"` is required when first publishing a scoped package (`@scope/name`); otherwise registry assumes private and rejects free-tier accounts.
+- `tag: "next"` (or any non-`latest`) keeps the version off the default install pointer — useful for prereleases.
+- `provenance: true` is the package.json equivalent of `--provenance` (see [npm-publish-oidc-trusted.md](./npm-publish-oidc-trusted.md)).
+
+### `engines`
+
+Declares Node/npm version compatibility:
+
+```json
+{
+  "engines": { "node": ">=20.0.0", "pnpm": ">=10.0.0" }
+}
+```
+
+By default `engines` is advisory (warns, does not fail). `engine-strict=true` in `.npmrc` makes it a hard error on install.
+
+### `bin`
+
+Maps CLI command names to file paths. The published tarball will mark these executable; the install will create symlinks in `node_modules/.bin`:
+
+```json
+{
+  "bin": { "codebyplan": "./dist/cli.js" }
+}
+```
+
+The target file must have a shebang (`#!/usr/bin/env node`).
+
+## `latest` Dist-Tag Semantics
+
+When a user runs `npm install <pkg>` without a version specifier, npm resolves to whatever the `latest` dist-tag points at. Implications:
+
+- The first publish of a package always becomes `latest`.
+- Subsequent publishes become `latest` **unless** `--tag <name>` is passed (or `publishConfig.tag` is set to something other than `latest`).
+- Publishing a hotfix to an older major (e.g. `1.5.3` after `2.0.0` is already `latest`) will overwrite `latest` to point back at `1.5.3` — almost always a mistake. Use `npm publish --tag legacy` for hotfixes on old majors, then `npm dist-tag add <pkg>@1.5.3 v1-legacy` to give consumers an explicit pointer.
+
+Common dist-tag conventions:
+
+| Tag | Convention |
+|-----|-----------|
+| `latest` | Default install target — stable releases only |
+| `next` | Upcoming version (often release candidates) |
+| `beta` / `alpha` | Prereleases — opt-in via `npm install pkg@beta` |
+| `canary` / `nightly` | Auto-published from main branch |
+
+Manage tags after publish:
+
+```bash
+npm dist-tag ls <pkg>             # list all tags
+npm dist-tag add <pkg>@<ver> next # promote a version to a tag
+npm dist-tag rm <pkg> beta        # remove a tag (does not unpublish)
+```
+
+Tags must not parse as valid semver ranges — `v1.4` is rejected, `v1-legacy` is fine.
+
+## Pre-Publish Checklist
+
+For a clean publish via `/cbp-ship`:
+
+1. `npm whoami` (or OIDC trust verified) — confirm auth context.
+2. `npm publish --dry-run` — review the file list; nothing surprising.
+3. `npx publint` — lint package.json shape.
+4. `npx @arethetypeswrong/cli --pack` — verify type resolution across CJS/ESM.
+5. Version bump committed and tagged in git (release-please or changesets handles this).
+6. CI green on the commit being published.
+
+## Sources
+
+- [npm Docs — package.json](https://docs.npmjs.com/cli/v10/configuring-npm/package-json)
+- [npm Docs — npm publish](https://docs.npmjs.com/cli/v10/commands/npm-publish)
+- [npm Docs — npm dist-tag](https://docs.npmjs.com/cli/v10/commands/npm-dist-tag)
+- [npm Docs — Configuring 2FA](https://docs.npmjs.com/configuring-two-factor-authentication)
+- [npm CLI source](https://github.com/npm/cli)

package/templates/skills/cbp-ship/reference/preflight-checklist.md

@@ -0,0 +1,88 @@
+# Pre-flight Checklist
+
+Run before invoking `/cbp-ship`. The orchestrator's Step 1 detection runs this implicitly; this file documents what it checks and what to do when a check fails.
+
+## Universal pre-flight (every shipment)
+
+| # | Check | Why | If fails |
+|---|---|---|---|
+| 1 | `gh auth status` succeeds | gh CLI is needed for tag push, release verification | `gh auth login` |
+| 2 | Working tree is clean (no uncommitted changes) | Shipping uncommitted code = ghosts | Commit or stash; do NOT proceed |
+| 3 | Current branch matches expected post-promotion branch | Caller (`/cbp-checkpoint-end`) just merged into PRODUCTION | If wrong, `git checkout` correct branch |
+| 4 | `.codebyplan/` files are parseable | All config reads from per-concern files | Fix JSON; or run `npx codebyplan config` |
+| 5 | Active checkpoint exists in DB | Shipment is per-checkpoint | Run `/cbp-todo` to find/create checkpoint |
+| 6 | `checkpoint.context.check_results` exists | Checkpoint check must pass before shipment | Run `/cbp-checkpoint-check` first |
+
+## Per-surface pre-flight
+
+The detection script (`scripts/detect-surfaces.sh`) emits `configured: false` with a `reason` when a surface fails its pre-flight. Rather than duplicating those reasons here, see each surface's `## Configured indicators` section in its reference file.
+
+Quick reference:
+
+| Surface | Critical pre-flight check |
+|---|---|
+| `vercel-web` | `vercel whoami` succeeds AND `.vercel/project.json` exists |
+| `expo-mobile` | `eas whoami` succeeds AND `eas.json` parseable AND credentials valid (`eas credentials` audit) |
+| `tauri-desktop` | All 9 GH secrets present in repo (`gh secret list`) |
+| `npm-package` | `npm whoami` succeeds AND 2FA enabled AND local version > registry version |
+| `vscode-ext` | `vsce verify-pat <publisher>` succeeds |
+| `railway-backend` | `railway whoami` succeeds AND service is linked AND env vars set |
+| `supabase` | `supabase projects list` succeeds AND project ref matches |
+
+## Recommended pre-flight when adding a new surface
+
+If you're configuring a surface for the first time (via `/cbp-ship-configure`), run these once:
+
+1. **For Vercel**:
+   - Verify build works locally: `pnpm build`
+   - Verify env vars are documented: `cat .env.example`
+   - Verify domain DNS is healthy if using custom domain
+
+2. **For Expo / mobile**:
+   - Verify Apple Developer account is enrolled (paid)
+   - Verify ASC API key is generated and `.p8` file is readable
+   - Verify EAS project is created: `eas project:info`
+   - Run a development build first: `eas build --profile development --platform ios`
+
+3. **For Tauri desktop**:
+   - Generate signing key: `npx tauri signer generate -w ~/.tauri/{app}.key`
+   - Export Apple Developer ID cert as `.p12`
+   - Upload all 9 GH secrets per architecture doc
+   - Test the workflow on a non-production tag first (e.g., `v0.0.0-test`)
+
+4. **For npm package**:
+   - Verify `package.json` has `name`, `version`, `description`, `keywords`, `repository`, `license`, `author`
+   - Run `npm pack --dry-run` and verify the tarball contains the right files
+   - Run `pnpm publint` to catch metadata issues
+   - Run `pnpm attw --pack` to verify TS types resolve correctly
+
+5. **For VS Code extension**:
+   - Create a publisher account at https://aka.ms/vscode-create-publisher
+   - Generate PAT with "Marketplace → Manage" scope
+   - Run `vsce verify-pat <publisher>` — succeeds = good
+   - Verify `package.json` has `displayName`, `description`, `categories`, `icon` (≥128×128 PNG)
+
+6. **For Railway**:
+   - Create project: `railway init`
+   - Link service: `railway link`
+   - Add env vars: `railway variables set KEY=VALUE`
+   - Configure health endpoint in service code (`/health` returning 200)
+   - Test deploy: `railway up`
+
+7. **For Supabase**:
+   - Verify migrations directory is initialized: `ls supabase/migrations/`
+   - Link project: `supabase link --project-ref <ref>`
+   - Generate baseline migration if existing schema: `supabase db dump > supabase/migrations/0000_baseline.sql`
+   - Verify types path: `supabase gen types typescript --project-id <ref> > types.ts`
+
+## When pre-flight fails mid-shipment
+
+If `/cbp-ship` is mid-shipment and a per-surface pre-flight fails:
+
+1. Mark that surface failed
+2. Continue with remaining surfaces (don't halt the whole shipment unless `supabase` failed)
+3. Surface the failure in the final report
+4. Suggest the user run `/cbp-ship-configure --surface=<id>` to fix
+5. After fix, re-run `/cbp-ship` — it picks up where it left off (verified surfaces are skipped)
+
+The shipment record (`checkpoint.context.shipment`) tracks per-surface status, so partial re-runs are safe.