kylon-cli 0.7.5-next.1111 → 0.7.5-next.1113

package/README.md

@@ -26,7 +26,9 @@ It installs the pinned CLI bundle under `~/.kylon` (no sudo; a machine
 without Node.js gets a private, checksum-verified runtime under
 `~/.kylon/runtime` that only Kylon uses), puts `kylon` on your PATH, records
 the serving environment as the default `--server-url`, and chains straight
-into `kylon login`. Rerunning it is safe. Non-production deployments serve
+into `kylon login`. Rerunning it is safe: on a machine that already has
+Kylon, it verifies the installation and repairs a damaged one before it
+updates it. Non-production deployments serve
 the same script from their own API origin (for example
 `https://api.purework.ai/install.sh` installs `@next` and logs into dev).
 `KYLON_INSTALL_NO_LOGIN=1` installs without starting the login;
@@ -84,6 +86,61 @@ service can be installed (a source build, or a Windows machine whose policy
 blocks scheduled tasks) the daemon runs in the foreground until `Ctrl+C`, and
 `connect` says so.
 
+### Connecting with a setup command: `kylon connect --intent computer`
+
+The Kylon app connects this computer through the installed CLI, without a
+browser and without signing anyone in:
+
+```bash
+kylon connect --setup-token <token> --workspace <id> --server-url <url> --intent computer --attempt <id> --json
+```
+
+The setup token (single use, 30 minutes, minted for one workspace) is the
+approval: the CLI starts a device authorization with `intent: "computer"`,
+receives this computer's key, writes the registration, and installs and starts
+the gateway service as `kylon connect` does (`--no-start` registers only). It
+writes no human credential: `workspace-auth.json` is never read or written, so
+`kylon workspace` commands still need `kylon login`. `--setup-token`,
+`--workspace` and an explicit `--server-url` are all required (the production
+default never applies), and `--attempt` names the app's attempt (a standalone
+run mints one).
+
+Nothing is spent before the checks pass: a registration of another server
+refuses with the usual "already connected to a different server" message, and
+a registration of another workspace refuses with `computer_in_other_workspace`
+until `kylon disconnect` clears it. A registration of this workspace only runs
+the service step. An enrollment in flight is recorded in
+`desktop-onboarding/enrollment-<digest>.json` (mode 0600; the request's
+capability and the key's fingerprint, never the key) before the request is
+sent, so a run that stopped part way is finished by the next one: it asks the
+server again and commits the same key, or cancels what is owed first.
+
+With `--json`, stdout carries exactly one document,
+`{ ok, workspace_id, computer_id, install_id, connected_at, credential_id, created, attempt_id, generation, service, placement }`,
+and progress goes to stderr. A failure is `{ ok: false, kind: "error", code,
+text, details }` with `details.retryable`, for example `setup_token_rejected`
+(generate a new setup command), `computer_intent_unsupported` (the server
+predates this form), `enrollment_in_progress`, or `enrollment_poll_exhausted`
+(run the same command again to pick up where it left off); an argument error
+of these forms (a flag without its value included) is the same document with
+`missing_required_argument` or `invalid_arguments` and exit code 2. A request
+the server ends (`denied`, or `expired` past its re-delivery window) is
+cancelled on the server before a new one starts, since its key may already
+have been delivered.
+
+`kylon connect --cancel --attempt <id> --json` cancels that attempt's pending
+connection: it settles the request on the server the record names (whatever
+this installation is registered with meanwhile, and without touching that
+registration or its service), or keeps a connection the attempt had already
+completed and revokes nothing. Its answer is
+`{ ok, outcome, generation, request_id?, destroyed? }`, where `outcome` is
+`cancelled`, `committed`, `sealed_only` (another attempt has taken the
+connection over; nothing changed), `no_journal`, or `incomplete` (Kylon could
+not be reached, or this computer's saved connection could not be read while a
+delivered key may be in it, `reason: "registration_unreadable"`; the same
+command finishes it). Its failure reports go to the record's server only,
+never to the default one.
+
 ### `kylon onboard`
 
 `kylon onboard` is the terminal-first way to start: it creates a **new**
@@ -328,13 +385,20 @@ curl -fsSL https://api.kylon.io/install.sh | sh
 
 (`https://api.purework.ai/install.sh` on dev; Windows:
 `powershell -c "irm https://api.kylon.io/install.ps1 | iex"`.) On a machine
-that already has Kylon the script never overwrites the managed bundle. It
-repairs the environment around it — a vanished Node.js gets the private
-runtime, the launcher and PATH snippet are rewritten, the serving deployment
-is re-recorded — and then asks the installed CLI to update itself with
-`kylon upgrade`. This is the command the CLI's update notice, `kylon gateway
-status`, the unknown-command hint, and the workspace's update surfaces all
-print; each spells it for the deployment the machine was set up against.
+that already has Kylon, `install.sh` first verifies the managed bundle. One
+that does not answer `--version` with `kylon <version>`, or answers another
+version than its sidecar records, is replaced with the release the script
+pins unless another installation holds the installation lock, and the
+damaged copy stays beside it as `kylon-bundle.mjs.broken-<time>`. A bundle
+that answers is never overwritten, even without a readable sidecar, which is
+how the CLI's own rollback leaves it (`install.ps1` never overwrites the
+bundle). The script also repairs the environment around it — a vanished
+Node.js gets the private runtime, the launcher and PATH snippet are
+rewritten, the serving deployment is re-recorded — and then asks the
+installed CLI to update itself with `kylon upgrade`. This is the command the
+CLI's update notice, `kylon gateway status`, the unknown-command hint, and the
+workspace's update surfaces all print; each spells it for the deployment the
+machine was set up against.
 
 `kylon upgrade` is the engine underneath the script, and can be run on its
 own when the environment is known to be healthy. It resolves the newest build

package/dist/kylon-bundle.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.7.5-next.1111",
-  "fingerprint": "11ca730ded846584858fb1ac531b7f1e3a4912901c4807700e18bc3934bd0cdc",
-  "source_commit": "cc095db82941b24e192ad6fb79d29d2d7926f741"
+  "version": "0.7.5-next.1113",
+  "fingerprint": "a3b074989af11825dc7c1afe484cb4e5bec070d8b0c1be6c082edcdca79ccb22",
+  "source_commit": "99e212702e94382b8c1423179f5598cf2f6c1fd2"
 }