kylon-cli 0.1.0 → 0.2.0-next.138

package/README.md

@@ -6,36 +6,31 @@ Requires Node.js 22 or newer.
 
 ## Install
 
-The current release train ships a single self-contained `.mjs` bundle
-as a GitHub Release asset on the `fre-so/p2` repo. The Web UI
+The CLI is published to npm as
+[`kylon-cli`](https://www.npmjs.com/package/kylon-cli). The Web UI
 generates two separate commands — an **install** step and a **run**
 step — each with its own Copy button. Operators paste the install
 once per host (and any time they want to upgrade) and the run
-whenever they want to start the daemon. npm is on the roadmap (see
-[Planned: npm install](#planned-npm-install) below) but not wired yet.
+whenever they want to start the daemon.
 
 ### Step 1 — Install kylon (once per host, re-paste to upgrade)
 
 ```bash
-gh release download --repo fre-so/p2 --pattern 'kylon.mjs' --output /tmp/kylon.new \
-  && chmod +x /tmp/kylon.new \
-  && sudo mv /tmp/kylon.new /usr/local/bin/kylon
+npm install -g kylon-cli@latest
 ```
 
-Downloads the latest bundle to an unprivileged scratch file, flips
-the executable bit, and `sudo mv`'s it into `/usr/local/bin/kylon`
-atomically. The repo is private, so `gh` (authenticated via
-`gh auth login`) is required instead of plain `curl`.
+Installs the CLI globally so the `kylon` binary lands on PATH — the
+gateway daemon's child `kylon workspace …` calls (issued by the
+provider subprocess) resolve it there. Re-run to upgrade to whatever
+the dist-tag now points to. If the global install needs elevated
+permissions, prefix it with `sudo`.
 
-Re-paste to upgrade: the `sudo mv` overwrites the binary in place
-with whatever the latest release publishes as `kylon.mjs`. If you
-want a specific build instead of latest, download the matching
-`kylon-vX.Y.Z.mjs` from that release's page — every release
-publishes both the stable-name `kylon.mjs` and the versioned copy.
+The dist-tag tracks the environment: production installs `@latest`,
+dev installs `@next` (newest prerelease). To pin a specific build,
+install `kylon-cli@X.Y.Z`.
 
-Requirements: Node.js 22+, [GitHub CLI](https://cli.github.com/)
-(`gh auth login`), `sudo`. Linux / macOS only (Windows operators
-should use WSL).
+Requirements: Node.js 22+ (npm ships with Node). Linux / macOS only
+(Windows operators should use WSL).
 
 ### Step 2 — Start the gateway daemon
 
@@ -65,21 +60,45 @@ pnpm --filter kylon-cli build
 See [Development → Exposing `kylon` to provider subprocesses](#exposing-kylon-to-provider-subprocesses)
 for the debugger-friendly tsx-based dev loop.
 
-### Planned: npm install
+### Release channels
 
-The npm distribution path is designed (see
-[`docs/journal_docs/04_13_cli_npx_gateway_run_release_plan.md`](../../docs/journal_docs/04_13_cli_npx_gateway_run_release_plan.md))
-and this package is already publish-ready (`packages/cli/package.json`
-has the metadata and `prepack` runs `bundle:release`). Publishing is
-held pending the rollout-config side of that plan (platform-served
-`recommendedCliVersion`), at which point the Web UI will drop the
-Install step entirely and flip the Run step to
-`npx -y kylon-cli@<recommended> gateway run …`. Don't `npm publish`
-ad-hoc before that — the first live release should come out through
-the paired CI workflow so the token path is exercised end-to-end.
+npm dist-tags are the version pointer — there is no server-side version
+policy. Every merge to `develop` publishes a prerelease to the `next` tag
+(`.github/workflows/cli-publish.yml`); cutting a `kylon-cli-vX.Y.Z`
+release tag publishes a stable to `latest`. dev installs `@next` and prd
+installs `@latest`, so each environment tracks its own train.
+
+Cutting a stable is a manual, when-ready step: tag a validated build
+`kylon-cli-vX.Y.Z` and push the tag; CI publishes it to `latest`. Don't
+`npm publish` ad-hoc — releases go through the CI workflow so the OIDC
+publish path is exercised end-to-end.
 
 ## Usage
 
+### Onboard an invited external agent
+
+The Web UI provides one operator-run command after an external agent is
+created. Run it from the project directory the agent should use:
+
+```bash
+npx --yes kylon-cli@latest onboard \
+  --url 'https://api.kylon.io/docs/agent-onboard/<opaque-token>'
+```
+
+The command resolves the invitation without printing its API key, checks the
+local provider, verifies Codex or Claude Code authentication, connects the
+gateway, binds a working directory, and starts the foreground daemon. On first
+onboarding it uses the current directory. Re-onboarding the same agent preserves
+its registered provider and directory, safely interrupts unfinished work owned
+by the displaced connection, and replaces the foreground daemon. If Codex or
+Claude Code is logged out, an interactive terminal launches the provider's own
+login flow and verifies authentication again before connecting.
+
+Use `--workdir <path>` to select a different directory or `--no-start` to
+configure and validate without opening the long-running connection. Generic
+providers can supply their one-shot command with `--agent-command <command>`;
+an interactive terminal prompts for it when the flag is omitted.
+
 ### Run
 
 `gateway run` is the recommended entrypoint for external agent operators.
@@ -291,9 +310,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
 
@@ -339,7 +358,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 |
 
 The `bundle:release` path runs esbuild with `--minify`, then passes the
 output through `javascript-obfuscator`. It's also what the `prepack` hook
@@ -423,12 +442,11 @@ API server is the security boundary.
 
 ## Release
 
-Today there is **one** active release channel: a bundled `.mjs`
-uploaded as a GitHub Release asset. The npm channel is designed and
-publish-ready but intentionally held pending the
-`recommendedCliVersion` rollout config described in
-[`docs/journal_docs/04_13_cli_npx_gateway_run_release_plan.md`](../../docs/journal_docs/04_13_cli_npx_gateway_run_release_plan.md).
-See [Planned: npm publish](#planned-npm-publish) below.
+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
 
@@ -440,121 +458,39 @@ 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)
-
-Once npm is live, risky changes can go out under a `next` dist-tag so
-the Web UI's recommended version is untouched:
-
-```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
-```
+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`.