kylon-cli 0.1.0-next.12 → 0.1.0-next.13

package/README.md

@@ -286,9 +286,9 @@ shim. The shim execs `node --import tsx <src>`, so:
 - On SIGINT/SIGTERM the tmpdir is wiped.
 
 This flag is **only compiled into local (non-minified) builds**. The
-npm package, the GitHub Release bundle, and any `bundle:release`
-output reject `--dev-cli-shim` as an unknown argument and omit it from
-`--help`, so it can never accidentally ship.
+npm package and any `bundle:release` output reject `--dev-cli-shim` as
+an unknown argument and omit it from `--help`, so it can never
+accidentally ship.
 
 ### Debugging both the daemon and `kylon workspace` calls
 
@@ -334,7 +334,7 @@ The release artifact is a single-file ESM bundle produced by
 |---|---|---|---|
 | `pnpm --filter kylon-cli bundle` | `dist/kylon-bundle.mjs` | _(none)_ | debugging the bundled shape while keeping readable names — not shipped |
 | `pnpm --filter kylon-cli bundle:minify` | `dist/kylon-bundle.mjs` | `--minify` | reproducing the pre-obfuscation size and behavior for a bisect |
-| `pnpm --filter kylon-cli bundle:release` | `dist/kylon-bundle.mjs` | `--minify --obfuscate` | what ships on npm and in GitHub Releases |
+| `pnpm --filter kylon-cli bundle:release` | `dist/kylon-bundle.mjs` | `--minify --obfuscate` | what ships on npm (and the frozen fallback bundle) |
 
 The `bundle:release` path runs esbuild with `--minify`, then passes the
 output through `javascript-obfuscator`. It's also what the `prepack` hook
@@ -418,14 +418,11 @@ API server is the security boundary.
 
 ## Release
 
-> **Note:** The active release channel is now **npm**. `cli-verify.yml`
-> validates and `cli-publish.yml` publishes via OIDC — a prerelease to the
-> `next` tag on every merge to `main`, a stable to `latest` when a
-> `kylon-cli-vX.Y.Z` tag is pushed. See [Release channels](#release-channels)
-> under Install for the install-side summary. The GitHub-Release bundle
-> subsections below are a **legacy fallback being retired**, kept only until
-> that removal lands; treat their specifics (`NPM_TOKEN`, `cli/vX.Y.Z` tags,
-> `recommendedCliVersion`) as historical, not current.
+The CLI ships via **npm dist-tags** — there is no server-side version policy.
+`cli-verify.yml` validates on PRs and pushes; `cli-publish.yml` publishes via
+OIDC (no token): a prerelease to the `next` tag on every merge to `main`, and a
+stable to `latest` when a `kylon-cli-vX.Y.Z` tag is pushed. dev installs
+`@next`, prd installs `@latest`.
 
 ### Versioning
 
@@ -437,121 +434,48 @@ Use explicit semver in `packages/cli/package.json`:
 | minor (`0.1.x → 0.2.0`) | backward-compatible capability (new command, new flag) |
 | major (`0.x.x → 1.0.0`) | breaking change to CLI contract or runtime behavior |
 
-The GitHub Release tag still uses the historical
-`cli/v0.0.${github.run_number}` scheme, which is fine as an opaque
-build id while there is no consumer that pins to it. The moment we
-flip the npm plan on, bump `packages/cli/package.json` to explicit
-semver and let the publish workflow own version selection.
+Prerelease builds are versioned `0.1.0-next.<run>` automatically by
+`cli-publish.yml`; a stable release is whatever you tag — bump
+`packages/cli/package.json` to the target semver, then push the matching
+`kylon-cli-vX.Y.Z` tag.
 
-### Active channel — GitHub Release asset
+### Publishing
 
-Triggered automatically by `.github/workflows/release-cli.yml` on any
-push to `main` that touches `packages/cli/**`,
-`packages/workspace-cli-core/**`, or `packages/types/**`. The workflow:
+- **Prerelease (automatic):** every merge to `main` touching the CLI publishes
+  `0.1.0-next.<run>` to the `next` tag via `cli-publish.yml` (OIDC, no
+  `NPM_TOKEN`). dev tracks this tag, so dev always dogfoods the newest build.
+- **Stable (manual, when ready):** bump `packages/cli/package.json` to the
+  target version, merge, then tag the commit on `main`:
 
-1. Runs `pnpm --filter kylon-cli bundle:release` (obfuscated output).
-2. Smoke-tests `node packages/cli/dist/kylon-bundle.mjs --help`.
-3. Copies the bundle to **two** asset names under the release:
-   - `kylon-v0.0.${run_number}.mjs` — versioned, useful for pinning.
-   - `kylon.mjs` — stable name, downloadable via
-     `gh release download --repo fre-so/p2 --pattern 'kylon.mjs'`.
-4. Creates a GitHub Release tagged `cli/v0.0.${run_number}` with both
-   `.mjs` files attached.
+  ```bash
+  git pull
+  git tag kylon-cli-v0.1.1
+  git push origin kylon-cli-v0.1.1   # cli-publish.yml publishes it to `latest`
+  npm view kylon-cli dist-tags        # verify
+  ```
 
-The repo is private, so downloads require `gh` (authenticated) rather
-than plain `curl`. This is the shape the Web UI generates:
+  Do not `npm publish` ad-hoc — releases go through the workflow so the OIDC
+  provenance path is exercised end to end.
 
-```bash
-gh release download --repo fre-so/p2 --pattern 'kylon.mjs' --output /tmp/kylon
-chmod +x /tmp/kylon
-sudo mv /tmp/kylon /usr/local/bin/kylon
-```
+### Rollback
 
-Pin to a specific build by downloading the versioned asset from its
-release page instead.
-
-No npm token required; the workflow only needs `contents: write`.
-
-### Rollback (GitHub channel)
-
-If the most recent push produced a broken CLI:
-
-1. Identify the last known good release under
-   <https://github.com/fre-so/p2/releases>.
-2. Manually re-upload that release's bundle under the name
-   `kylon.mjs` on the most recent release — that's what the Web UI's
-   stable URL resolves against. (Alternatively, revert the bad commit
-   and let `release-cli.yml` cut a new release.)
-3. Hosts with persistent installs re-run `curl -fsSL … -o
-   /usr/local/bin/kylon` to pull the rolled-back bundle.
-
-There is no equivalent of `npm deprecate` on GitHub Releases, so a
-broken bundle is "fixed" only by publishing a newer one.
-
-### Planned: npm publish
-
-This package is already wired for `npm publish` (metadata, `files`,
-`prepack`, `publishConfig.access: public`). The only things missing
-are the publish CI workflow and the owning npm account. The plan:
-
-1. Someone claims `kylon-cli` on npm (the name is currently 404).
-2. A granular publish token (Read + Write on `kylon-cli`) is stored
-   as the `NPM_TOKEN` GitHub Actions secret on `fre-so/p2`.
-3. Split the release automation:
-   - **`cli-verify.yml`** — runs on PRs and pushes touching
-     `packages/cli/**`. Runs typecheck, lint, test, `bundle:release`,
-     and `npm pack`. Does not publish.
-   - **`cli-publish.yml`** — runs on push of tag `cli/vX.Y.Z`.
-     Verifies the tag matches `packages/cli/package.json#version`,
-     then `pnpm --filter kylon-cli publish --access public
-     --no-git-checks` with
-     `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}`.
-4. The API exposes `recommendedCliVersion`; the Web UI flips from
-   the `curl` shape above to `npx -y kylon-cli@<recommended> gateway
-   run …`.
-
-Until (2) + (3) land, do **not** `npm publish` ad-hoc — the first
-live release should come out through the paired CI workflow so the
-token path is exercised end-to-end. Once the workflow exists, the
-release ritual becomes:
+npm publishes are immutable; roll back by re-pointing the tag, not by
+unpublishing:
 
 ```bash
-# 1. On a release branch
-pnpm --filter kylon-cli version 0.1.1   # bumps packages/cli/package.json only
-
-# 2. Merge to main via PR, verify CI is green
-
-# 3. Tag the commit on main
-git pull
-git tag cli/v0.1.1
-git push origin cli/v0.1.1
-
-# 4. GitHub Actions publishes; verify
-npm view kylon-cli@0.1.1 dist-tags
+npm dist-tag add kylon-cli@<last-good> latest   # move the channel back
+npm deprecate kylon-cli@<bad> "Broken release — use <last-good>."
 ```
 
-Rollback once npm is live: flip `recommendedCliVersion` in the API
-back to the last known good version (new operators get that version
-in their install command; in-flight daemons keep their current CLI
-until they restart). If the pushed version is actively broken, also
-`npm deprecate kylon-cli@<bad> "…"` so operators that ignore the
-recommendation see a warning. Do not `npm unpublish`.
-
-### Pre-release channel (npm-era, also planned)
+Operators on `@latest` pick up the re-pointed version the next time they
+`npm install -g kylon-cli@latest`; in-flight daemons keep their current CLI
+until they restart. Do not `npm unpublish`.
 
-Once npm is live, risky changes can go out under a `next` dist-tag so
-the Web UI's recommended version is untouched:
+### Fallback bundle (deprecated)
 
-```bash
-# 1. Bump to a prerelease version
-pnpm --filter kylon-cli version 0.2.0-next.0
-
-# 2. Publish under the `next` dist-tag
-cd packages/cli && pnpm publish --tag next --access public --no-git-checks
-
-# 3. Operators can opt in explicitly
-npx -y kylon-cli@next gateway run …
-
-# 4. Promote to `latest` once validated
-npm dist-tag add kylon-cli@0.2.0-next.0 latest
-```
+A single-file bundle is still served at `/docs/cli/kylon.mjs` (redirecting to
+the public CDN) as a grace-period fallback for pre-npm install commands. It is
+**frozen**: `release-cli.yml` — which built and uploaded it on every CLI push —
+has been removed, so no new bundles are produced. The endpoint will be retired
+once `docs.kylon.io` and any in-the-wild `curl` install commands have moved to
+npm.