@escalay/kit 1.7.0 → 1.8.0

package/README.md

@@ -130,5 +130,14 @@ npx skills add escalay/api-kit
 | [`api-kit-build`](skills/api-kit-build/SKILL.md) | start a new API, move an app onto the kit, take a newer kit |
 | [`api-kit-feature`](skills/api-kit-feature/SKILL.md) | add a feature folder: schema, repo, routes, handlers, tools, tests |
 | [`api-kit-review`](skills/api-kit-review/SKILL.md) | check an API is agent-ready: the commands to run and what a failure means |
+| [`npm-release`](skills/npm-release/SKILL.md) | set up or run releases of any npm package from GitHub Actions, or find out why one failed |
+
+## Releases
+
+Merging a pull request is the only manual step. Its title, a Conventional Commit, becomes a line of the release
+notes; merging the release pull request publishes `@escalay/kit` and `create-escalay` to npm from GitHub Actions,
+with provenance and no npm token. How it works, and how to set it up in another repo:
+[docs/releasing.md](docs/releasing.md). `pnpm release:check` says whether a release is ready, and
+`npx shadcn add escalay/api-kit/npm-release` copies the setup into another repo.
 
 Working on the kit itself: [AGENTS.md](AGENTS.md). Licence: [MIT](LICENSE).

package/cli.mjs

@@ -6,7 +6,7 @@
  * `--web-dir` (relative to `--dir`, remembered in kit.json) puts the browser parts in their own folder, still
  * tracked by the one kit.json (as `@web/<file>`).
  *
- *   kit list                                  parts, what they need, which are installed
+ *   kit list                                  parts, what they need, which are installed; then the root items
  *   kit add core guide mcp testing [--dir src/kit] [--web-dir ../web] [--install]
  *   kit diff [--dir src/kit] [--patch]        per file: unchanged, you edited, kit changed, both
  *   kit update [part…] [--dir src/kit] [--force]
@@ -32,8 +32,12 @@ const KIT = dirname(fileURLToPath(import.meta.url))
 const REPO = 'escalay/api-kit'
 const rangeOf = (dependency) => [dependency.slice(0, dependency.lastIndexOf('@')), dependency.slice(dependency.lastIndexOf('@') + 1)]
 /** registry.json is a shadcn registry; a part's requires are its dependencies on this repo, a dependency without a range is a peer. */
+const ITEMS = JSON.parse(readFileSync(join(KIT, 'registry.json'), 'utf8')).items
+/** Root items (`meta.root`) are repo setup the shadcn CLI installs at the repo root: not parts, so `add`, `adopt` and `doctor` never see them. */
+const ROOT_ITEMS = ITEMS.filter((item) => item.meta?.root)
+const shadcnAdd = (name) => `npx shadcn add ${REPO}/${name}`
 const REGISTRY = Object.fromEntries(
-  JSON.parse(readFileSync(join(KIT, 'registry.json'), 'utf8')).items.map((item) => [
+  ITEMS.filter((item) => !item.meta?.root).map((item) => [
     item.name,
     {
       description: item.description,
@@ -73,6 +77,7 @@ const lockPath = join(dir, 'kit.json')
 const withRequired = (wanted) => {
   const all = new Set()
   const visit = (name) => {
+    if (ROOT_ITEMS.some((item) => item.name === name)) fail(`"${name}" goes to the repo root, not into ${dirArg}: \`${shadcnAdd(name)}\``)
     if (!REGISTRY[name]) fail(`no module "${name}". Modules: ${Object.keys(REGISTRY).join(', ')}`)
     if (all.has(name)) return
     for (const required of REGISTRY[name].requires ?? []) visit(required)
@@ -291,6 +296,7 @@ const commands = {
       const needs = [...(module.requires ?? []), ...Object.keys(module.dependencies ?? {})]
       console.log(`${installed.has(name) ? '●' : '○'} ${name.padEnd(11)} ${module.description}${needs.length ? `\n  ${''.padEnd(11)} needs: ${needs.join(', ')}` : ''}`)
     }
+    for (const { name, description } of ROOT_ITEMS) console.log(`◇ ${name.padEnd(11)} ${description}\n  ${''.padEnd(11)} at the repo root: ${shadcnAdd(name)}`)
   },
 
   add: () => {

package/docs/releasing.md

@@ -0,0 +1,97 @@
+# Releasing
+
+How an npm package gets from a merged pull request to the registry with no manual step. The same setup works in
+any pnpm repo: `npx shadcn add escalay/api-kit/npm-release` copies it (the workflow, the release-please files, the
+check and this page).
+
+## How a change becomes a release
+
+1. **A pull request with a Conventional Commit title.** CI checks the title, because it becomes the commit.
+2. **Squash and merge.** The title is now one commit on `main`, and one line of the next release notes.
+3. **The release pull request.** `release.yml` runs release-please on every push to `main`. It opens, and keeps
+   current, one pull request titled `chore(main): release X.Y.Z`: the version bumps and `CHANGELOG.md`.
+   `feat` raises the minor version, `fix` and `perf` the patch, a `!` after the type the major.
+4. **Merge it when you want to release.** That is the only decision a person makes.
+5. **Publish.** The same workflow tags `vX.Y.Z`, drafts the GitHub release, then typechecks and tests the tagged
+   commit, packs every public package, publishes each to npm, waits until npm serves them, runs
+   `scripts/release-smoke.sh X.Y.Z` when the repo has one, attaches the tarballs and publishes the GitHub release.
+6. **Check.** `pnpm release:check` on `main` says, one line each, whether anything is off.
+
+## What the pipeline guarantees
+
+- **No npm token exists.** npm trusts this repo's `release.yml` in the `npm` environment (OIDC); nothing to leak
+  or rotate.
+- **Provenance.** Every version carries a signed statement of the commit and workflow run that built it.
+- **Tested twice.** The gate runs on the pull request and again on the exact commit that is published.
+- **One version everywhere.** Every public package in the workspace is released together at the manifest's
+  version; `workspace:` ranges are written as real versions in the tarballs.
+- **A stranger can install it.** The job fails unless the registry serves each `name@version`, and, with a smoke
+  script, unless a fresh install passes.
+- **The GitHub release shows only what shipped.** It stays a draft until npm has the packages, and carries the
+  exact tarballs.
+
+## One-time setup for a package repo
+
+The repo uses pnpm, has `packageManager` in `package.json`, a `.node-version` whose npm is 11.5.1 or newer
+(Node 24), `typecheck` and `test` scripts, and a `repository.url` in every published `package.json` that points
+at the GitHub repo (provenance checks it).
+
+1. Copy the setup: `npx shadcn add escalay/api-kit/npm-release`, then add
+   `"release:check": "node scripts/release-check.mjs"` to the scripts.
+2. **Publish the first version by hand** (`pnpm publish --access public`). A package must exist on npm before a
+   trusted publisher can be added to it.
+3. Write that version into `.release-please-manifest.json` (`{".": "1.0.0"}`). With more than one public
+   package, list each other `package.json` under `extra-files` in `release-please-config.json`
+   (`{"type": "json", "path": "packages/<name>/package.json", "jsonpath": "$.version"}`).
+4. Trust the workflow, once per package (asks for your npm second factor):
+   `npm trust github <package> --file release.yml --repo <owner>/<repo> --env npm --allow-publish`
+5. On GitHub: an environment named `npm` (Settings → Environments; limit it to the `main` branch), and
+   Settings → Actions → General → "Allow GitHub Actions to create and approve pull requests".
+6. Branch rules for `main`: pull requests only, squash merging only with the pull request title as the commit
+   message, and the CI checks required. A pull request opened by the workflow's own token does not start CI, so
+   on the release pull request the required checks never report: merge it as an administrator, or close and
+   reopen it to start them. Its commits were all tested on their own pull requests, and the publish job tests again.
+7. `pnpm release:check` until every line is ✓.
+
+The workflow file must stay named `release.yml`: the trusted publisher names it.
+
+## Titles that read well as release notes
+
+The title is read by someone deciding whether to upgrade. Say what changed for them, imperative and lowercase,
+without the ticket, the file or the how.
+
+| Good | Bad | Why |
+|---|---|---|
+| `feat: add cursor pages to boards` | `feat: boards changes` | says nothing |
+| `fix: answer 404 for a board that was deleted` | `fix: bug in handlers.ts` | names a file, not a behaviour |
+| `feat(cli)!: drop the --legacy flag` | `refactor: remove flag` | a breaking change hidden from the notes |
+| `perf: embed a batch in one request` | `feat: performance` | wrong type, no content |
+| `docs: explain how to rotate API keys` | `Update README.md` | not a Conventional Commit; CI refuses it |
+
+`feat`, `fix`, `perf`, `docs` and `revert` appear in the notes (as New, Fixed, Faster, Documentation, Reverted).
+`refactor`, `chore`, `test`, `build` and `ci` do not, and release nothing on their own.
+
+## When a release fails
+
+- **Run the failed jobs again** (Actions → the run → "Re-run failed jobs", not "all jobs": a full re-run finds
+  no new release and skips publishing). The publish step skips every `name@version` npm already has.
+- **A version can never be published twice**, even after unpublishing. If a published version is bad, fix it and
+  release the next one; `npm deprecate <package>@<version> "<why>"` warns people off the bad one.
+- **"npm still does not serve …" after 20 minutes.** npm can hold a new version back before serving it. The
+  package was published; when `npm view <package>@<version>` answers, run the failed jobs again.
+- **`npm publish` answers 404 or "OIDC".** The trusted publisher does not match: `npm trust list <package>` must
+  show this repo, `release.yml` and the `npm` environment.
+- **The smoke check fails.** The packages are public and broken for new installs. Fix forward with a `fix:` pull
+  request and merge the next release pull request; the GitHub release of the bad version stays a draft.
+- **No release pull request appears.** Only `feat`, `fix`, `perf` and breaking changes raise a version; check the
+  repository setting from step 5.
+
+## Checking a published package
+
+```bash
+npm view <package> dist.attestations     # the provenance statement's URL and type
+npm audit signatures                     # in a project that installed it: signatures and attestations verify
+```
+
+On npmjs.com the version shows a "Built and signed on GitHub Actions" badge that links to the commit and the
+workflow run. The same tarballs are attached to the GitHub release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@escalay/kit",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "type": "module",
   "description": "Agent-ready HTTP APIs as parts an app copies in (shadcn-style): Hono + zod OpenAPI 3.1, HAL links, problem+json, cursors, ETags, API keys, discovery, a generated agent guide with skills, an MCP server over the same routes, vector search by words, picture and likeness, and its headless browser side.",
   "license": "MIT",
@@ -56,6 +56,7 @@
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.web.json && tsc --noEmit -p test/workers/tsconfig.json",
     "test": "vitest run",
     "test:starter": "node scripts/starter-check.mjs",
+    "release:check": "node scripts/release-check.mjs",
     "kit": "node cli.mjs"
   }
 }

package/registry.json

@@ -507,6 +507,42 @@
         "entry": true,
         "web": true
       }
+    },
+    {
+      "name": "npm-release",
+      "type": "registry:item",
+      "title": "npm release",
+      "description": "Releases of an npm package with no manual step: release-please keeps a release pull request, merging it publishes every public package from GitHub Actions with npm trusted publishing and provenance, waits until npm serves them and publishes the GitHub release; with a read-only release check and the standard that explains it. For any pnpm repo; its files go to the repo root",
+      "files": [
+        {
+          "path": ".github/workflows/release.yml",
+          "type": "registry:file",
+          "target": "~/.github/workflows/release.yml"
+        },
+        {
+          "path": "templates/npm-release/release-please-config.json",
+          "type": "registry:file",
+          "target": "~/release-please-config.json"
+        },
+        {
+          "path": "templates/npm-release/release-please-manifest.json",
+          "type": "registry:file",
+          "target": "~/.release-please-manifest.json"
+        },
+        {
+          "path": "scripts/release-check.mjs",
+          "type": "registry:file",
+          "target": "~/scripts/release-check.mjs"
+        },
+        {
+          "path": "docs/releasing.md",
+          "type": "registry:file",
+          "target": "~/docs/releasing.md"
+        }
+      ],
+      "meta": {
+        "root": true
+      }
     }
   ]
 }

package/templates/npm-release/release-please-config.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "release-type": "node",
+  "include-component-in-tag": false,
+  "draft": true,
+  "force-tag-creation": true,
+  "always-update": true,
+  "changelog-sections": [
+    {
+      "type": "feat",
+      "section": "New"
+    },
+    {
+      "type": "fix",
+      "section": "Fixed"
+    },
+    {
+      "type": "perf",
+      "section": "Faster"
+    },
+    {
+      "type": "docs",
+      "section": "Documentation"
+    },
+    {
+      "type": "revert",
+      "section": "Reverted"
+    },
+    {
+      "type": "refactor",
+      "section": "Refactored",
+      "hidden": true
+    },
+    {
+      "type": "chore",
+      "section": "Chores",
+      "hidden": true
+    },
+    {
+      "type": "test",
+      "section": "Tests",
+      "hidden": true
+    },
+    {
+      "type": "build",
+      "section": "Build",
+      "hidden": true
+    },
+    {
+      "type": "ci",
+      "section": "CI",
+      "hidden": true
+    }
+  ],
+  "packages": {
+    ".": {}
+  },
+  "pull-request-header": "Merging this pull request releases the version below: it is tagged, published to npm, checked from the registry, and then announced.",
+  "pull-request-footer": "Edit nothing here by hand; it is rewritten whenever main changes."
+}

package/templates/npm-release/release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.0.0"
+}