@linzumi/cli 0.0.5-beta → 0.0.7-beta

package/README.md

@@ -1,152 +1,264 @@
-# @linzumi/cli
+# Linzumi CLI
 
-```text
-            ___       ___
-         .-'   '-. .-'   '-.
-       .'         '         '.
-      /     _           _     \
-     |    .' '.       .' '.    |
-     |   /     \ .-. /     \   |
-      \  \      (o o)      /  /
-       '._'._    \_/    _.'_.'
-            |     |     |
-            |    /|\    |
-            |___/ | \___|
-                \_|_/
-                 / \
-```
+Connect your computer to Kandan so you can run Codex locally from the browser.
+
+Linzumi gives Kandan a secure, authenticated bridge to your own machine. You
+keep the code, shells, editors, and preview servers local. Kandan gives you the
+web UI, sharing controls, HTTPS editor access, forwarded previews, and Codex
+session orchestration.
 
-Linzumi's CLI package. It installs the `linzumi` executable.
+## Copy And Paste
 
-The initial CLI command connects this computer to Kandan as a local Codex
-runner. It wraps the same local runner that was previously started with
-`bun run start -- ...`.
+Use a Chromium-based browser such as Chrome, Edge, Arc, or Brave.
 
-## Install
+```bash
+npm install -g @linzumi/cli@beta && linzumi start ~/code
+```
 
-Install the exact beta version:
+To pin this exact beta:
 
 ```bash
-npm install -g @linzumi/cli@0.0.5-beta
+npm install -g @linzumi/cli@0.0.7-beta && linzumi start ~/code
 ```
 
-Or install the current beta tag:
+Use a different folder if your projects live somewhere else:
 
 ```bash
-npm install -g @linzumi/cli@beta
+npm install -g @linzumi/cli@beta && linzumi start ~/work/my-app
 ```
 
-This beta expects Bun and Codex to be available locally:
+That command opens Kandan, walks you through signup or sign-in, connects this
+computer, and lets Kandan start Codex against the folder you chose.
+
+## What You Can Do
+
+After `linzumi start` is connected, try this from Kandan:
+
+1. Start a Codex session.
+2. Ask Codex to inspect or edit a file in the folder you allowed.
+3. Open the local editor from Kandan.
+4. Start a dev server locally, then open its forwarded preview from Kandan.
+5. Share editor or preview access with another user.
+
+The editor and previews open on Kandan HTTPS URLs. They should not expose
+`localhost` URLs to the browser.
+
+## What Linzumi Runs Locally
+
+The CLI starts a local runner process on your computer. That runner:
+
+- launches or connects to Codex locally
+- downloads the Kandan-approved editor runtime when needed
+- starts code-server for the allowed folder
+- exposes only explicitly approved local ports through Kandan
+- keeps Kandan auth cookies and bearer tokens away from local services
+
+Kandan remains the control plane. Browser traffic terminates at Kandan first,
+where auth, grants, and allowed-port policy are enforced before traffic is sent
+through the runner tunnel.
+
+In the local-service hop, `127.0.0.1` means your computer, not the Kandan
+server.
+
+## Requirements
+
+Install these before running the beta:
 
 ```bash
+node --version
+npm --version
 bun --version
 codex --version
-linzumi --version
 ```
 
-Expected CLI output:
+Expected:
+
+- Node.js 20 or newer
+- npm
+- Bun 1.2 or newer
+- Codex CLI
+- Chrome, Edge, Arc, Brave, or another Chromium-based browser
+
+Safari is semi-supported for now. Use Chromium for the best editor and
+collaboration behavior.
+
+## First Run
 
 ```bash
-linzumi 0.0.5-beta
+linzumi start ~/code
+```
+
+What happens:
+
+1. The CLI opens Kandan.
+2. You sign up or sign in.
+3. Kandan asks permission to connect this computer.
+4. The CLI stores a scoped local-runner token.
+5. The CLI checks Bun, Codex, and the Kandan editor runtime.
+6. Kandan shows the computer as connected.
+
+The first editor launch can download a Kandan-approved runtime archive. Later
+runs reuse the verified runtime from:
+
+```text
+~/.linzumi/editor-runtimes
 ```
 
-## Prod Quick Start
+The production path does not use a random local `code-server` install. Kandan
+publishes a checksummed runtime manifest, and the CLI only advertises editor
+readiness after that runtime is verified locally.
+
+## Good Things To Try
 
-For the Linzumi workspace in prod, this is the first command to try:
+Start from a real project:
 
 ```bash
-npm install -g @linzumi/cli@0.0.5-beta
+linzumi start ~/code/my-app
+```
 
-linzumi connect \
-  --kandan-url wss://serve.kandanai.com \
-  --workspace linzumi \
-  --channel seans-playground \
-  --codex-bin codex \
-  --launch-tui
+Then in Kandan:
+
+```text
+Summarize this repository and tell me how to run it locally.
 ```
 
-The runner handles OAuth itself. If the cached Kandan token is missing or
-rejected, it opens the OAuth flow and saves the refreshed auth cache.
-By default it listens for replies from the authenticated Kandan user.
+If your app starts a dev server:
 
-For a more explicit launch that pins the Codex model, reasoning effort, and
-fast service tier:
+```bash
+npm run dev
+```
+
+Open the detected forwarded port from Kandan. If a port is not auto-detected,
+restart with an explicit approved port:
 
 ```bash
-linzumi connect \
-  --kandan-url wss://serve.kandanai.com \
-  --workspace linzumi \
-  --channel seans-playground \
-  --codex-bin codex \
-  --model gpt-5.5 \
-  --reasoning-effort low \
-  --fast \
-  --launch-tui
+linzumi start ~/code/my-app --forward-port 3000
+```
+
+For a shared editor test, invite another user, open the local editor, and edit
+the same file. Chromium should show remote cursor labels and selections.
+
+## Hosted Kandan
+
+For a hosted Kandan deployment, point the CLI at the hosted websocket URL:
+
+```bash
+linzumi start ~/code/my-app --kandan-url wss://<your-kandan-host>
 ```
 
-## Basic Use
+For Render-hosted Kandan, public TLS should work without local certificate
+flags. The CLI derives the HTTPS API origin from the websocket URL for OAuth,
+runtime manifest download, and runtime archive download.
 
-Running `linzumi` without arguments prints the local runner guide:
+For local development with a private CA:
 
 ```bash
-linzumi
+KANDAN_TLS_CA_FILE=/path/to/ca.crt linzumi start ~/code/my-app \
+  --kandan-url wss://linzumi.io:4140
 ```
 
-Start the runner for a Kandan workspace/channel:
+## Tailscale Development
+
+If your browser needs to reach a local Kandan server through Tailscale:
 
 ```bash
-linzumi connect \
-  --kandan-url wss://serve.kandanai.com \
-  --workspace linzumi \
-  --channel seans-playground \
-  --codex-bin codex \
-  --launch-tui
+linzumi start ~/code/my-app \
+  --kandan-url ws://100.71.192.98:4162 \
+  --oauth-callback-host 100.71.192.98
 ```
 
-Leave that terminal process running while Kandan uses the local runner.
+Use your own Tailscale IP.
 
 ## Commands
 
-Supported commands right now:
-
 ```bash
 linzumi
 linzumi --help
 linzumi --version
+linzumi start <folder>
 linzumi connect --help
 linzumi connect [runner options]
 linzumi auth [auth options]
 ```
 
-`linzumi local-codex-runner` is accepted as a compatibility alias for
-`linzumi connect`.
+Most people should use `linzumi start`.
+
+`linzumi connect` is the lower-level command for connecting to an explicit
+workspace and channel:
+
+```bash
+linzumi connect \
+  --kandan-url wss://serve.kandanai.com \
+  --workspace default \
+  --channel general \
+  --cwd ~/code/my-app
+```
 
 ## Useful Options
 
 ```bash
---kandan-url <ws-url>       Kandan websocket URL, for example wss://serve.kandanai.com
---workspace <slug>          Workspace slug, for example linzumi
---channel <slug|w/c>        Channel slug, or workspace/channel
---kandan-thread-id <uuid>   Resume an existing Kandan thread
---listen-user <user|all>    User whose replies are accepted, default authenticated user
---cwd <path>                Working directory for Codex
---codex-bin <path>          Codex executable, default codex
---model <name>              Codex model
---reasoning-effort <value>  Codex reasoning effort
---fast                      Request the fast service tier
---launch-tui                Launch codex --remote against the app-server
+--kandan-url <ws-url>       Kandan websocket URL
 --oauth-callback-host <ip>  Callback host reachable by your browser
+--runner-id <id>            Stable id for this computer
+--codex-bin <path>          Codex executable, default codex
+--model <name>              Codex model metadata shown in Kandan
+--reasoning-effort <value>  Codex reasoning metadata shown in Kandan
+--fast                      Mark this runner as low-latency
+--forward-port <ports>      Comma-separated local ports Kandan may expose
+--allowed-cwd <paths>       Comma-separated roots Kandan may use
+--log-file <path>           JSONL runner event log
 ```
 
-Run `linzumi connect --help` for the full option list.
+`--code-server-bin` exists only as a development override. It is not the
+supported production editor path.
 
 ## Troubleshooting
 
-If `linzumi` is not found, confirm the global npm bin directory is on your
-`PATH`.
+Check the CLI version:
+
+```bash
+linzumi --version
+```
+
+Expected:
+
+```text
+linzumi 0.0.7-beta
+```
+
+If `linzumi` is not found, your global npm bin directory is not on `PATH`.
+
+If `bun` is not found, install Bun and rerun `linzumi start`.
+
+If `codex` is not found, install or configure the Codex CLI, or pass
+`--codex-bin`.
 
-If `bun` is not found, install Bun first. This beta wraps the existing Bun local
-runner implementation instead of a Node rewrite.
+If OAuth opens but does not return to the CLI, pass an
+`--oauth-callback-host` that your browser can reach.
+
+If the editor does not become ready, do not install a local code-server package
+as a workaround. The server-managed runtime must download and verify cleanly.
+Rerun the CLI and check the runner log.
+
+If collaboration behaves oddly in Safari, retry in Chromium. Safari is currently
+semi-supported.
+
+## For Kandan Release Engineers
+
+The production contract is:
+
+1. Build the server-approved editor runtime archive.
+2. Publish the manifest and archive from Kandan.
+3. Publish the CLI beta.
+4. The CLI downloads only the approved runtime archive.
+5. The CLI verifies the archive SHA before advertising editor readiness.
+
+For local package verification:
+
+```bash
+bun test
+npm pack --dry-run
+```
 
-If OAuth opens but does not return to the CLI, pass `--oauth-callback-host` with
-an IP address that your browser can reach, such as your Tailscale IP.
+The npm package must include this README, `bin/linzumi.js`, and the `src`
+runtime files.

package/package.json

@@ -1,26 +1,33 @@
 {
   "name": "@linzumi/cli",
-  "version": "0.0.5-beta",
-  "description": "Linzumi local Codex runner CLI.",
+  "version": "0.0.7-beta",
+  "description": "Connect your computer to Kandan for local Codex sessions, editors, and forwarded previews",
   "type": "module",
   "bin": {
     "linzumi": "bin/linzumi.js"
   },
   "files": [
+    "README.md",
     "bin",
-    "src",
-    "README.md"
+    "src"
   ],
   "scripts": {
-    "start": "bun run src/index.ts",
-    "test": "bun test"
-  },
-  "engines": {
-    "bun": ">=1.1.0",
-    "node": ">=22.0.0"
+    "test": "bun test",
+    "pack:dry-run": "npm pack --dry-run"
   },
+  "keywords": [
+    "linzumi",
+    "kandan",
+    "codex",
+    "local-runner"
+  ],
+  "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
-  "license": "MIT"
+  "engines": {
+    "node": ">=20",
+    "bun": ">=1.2.0"
+  },
+  "readme": "# Linzumi CLI\n\nConnect your computer to Kandan so you can run Codex locally from the browser.\n\nLinzumi gives Kandan a secure, authenticated bridge to your own machine. You\nkeep the code, shells, editors, and preview servers local. Kandan gives you the\nweb UI, sharing controls, HTTPS editor access, forwarded previews, and Codex\nsession orchestration.\n\n## Copy And Paste\n\nUse a Chromium-based browser such as Chrome, Edge, Arc, or Brave.\n\n```bash\nnpm install -g @linzumi/cli@beta && linzumi start ~/code\n```\n\nTo pin this exact beta:\n\n```bash\nnpm install -g @linzumi/cli@0.0.7-beta && linzumi start ~/code\n```\n\nUse a different folder if your projects live somewhere else:\n\n```bash\nnpm install -g @linzumi/cli@beta && linzumi start ~/work/my-app\n```\n\nThat command opens Kandan, walks you through signup or sign-in, connects this\ncomputer, and lets Kandan start Codex against the folder you chose.\n\n## What You Can Do\n\nAfter `linzumi start` is connected, try this from Kandan:\n\n1. Start a Codex session.\n2. Ask Codex to inspect or edit a file in the folder you allowed.\n3. Open the local editor from Kandan.\n4. Start a dev server locally, then open its forwarded preview from Kandan.\n5. Share editor or preview access with another user.\n\nThe editor and previews open on Kandan HTTPS URLs. They should not expose\n`localhost` URLs to the browser.\n\n## What Linzumi Runs Locally\n\nThe CLI starts a local runner process on your computer. That runner:\n\n- launches or connects to Codex locally\n- downloads the Kandan-approved editor runtime when needed\n- starts code-server for the allowed folder\n- exposes only explicitly approved local ports through Kandan\n- keeps Kandan auth cookies and bearer tokens away from local services\n\nKandan remains the control plane. Browser traffic terminates at Kandan first,\nwhere auth, grants, and allowed-port policy are enforced before traffic is sent\nthrough the runner tunnel.\n\nIn the local-service hop, `127.0.0.1` means your computer, not the Kandan\nserver.\n\n## Requirements\n\nInstall these before running the beta:\n\n```bash\nnode --version\nnpm --version\nbun --version\ncodex --version\n```\n\nExpected:\n\n- Node.js 20 or newer\n- npm\n- Bun 1.2 or newer\n- Codex CLI\n- Chrome, Edge, Arc, Brave, or another Chromium-based browser\n\nSafari is semi-supported for now. Use Chromium for the best editor and\ncollaboration behavior.\n\n## First Run\n\n```bash\nlinzumi start ~/code\n```\n\nWhat happens:\n\n1. The CLI opens Kandan.\n2. You sign up or sign in.\n3. Kandan asks permission to connect this computer.\n4. The CLI stores a scoped local-runner token.\n5. The CLI checks Bun, Codex, and the Kandan editor runtime.\n6. Kandan shows the computer as connected.\n\nThe first editor launch can download a Kandan-approved runtime archive. Later\nruns reuse the verified runtime from:\n\n```text\n~/.linzumi/editor-runtimes\n```\n\nThe production path does not use a random local `code-server` install. Kandan\npublishes a checksummed runtime manifest, and the CLI only advertises editor\nreadiness after that runtime is verified locally.\n\n## Good Things To Try\n\nStart from a real project:\n\n```bash\nlinzumi start ~/code/my-app\n```\n\nThen in Kandan:\n\n```text\nSummarize this repository and tell me how to run it locally.\n```\n\nIf your app starts a dev server:\n\n```bash\nnpm run dev\n```\n\nOpen the detected forwarded port from Kandan. If a port is not auto-detected,\nrestart with an explicit approved port:\n\n```bash\nlinzumi start ~/code/my-app --forward-port 3000\n```\n\nFor a shared editor test, invite another user, open the local editor, and edit\nthe same file. Chromium should show remote cursor labels and selections.\n\n## Hosted Kandan\n\nFor a hosted Kandan deployment, point the CLI at the hosted websocket URL:\n\n```bash\nlinzumi start ~/code/my-app --kandan-url wss://<your-kandan-host>\n```\n\nFor Render-hosted Kandan, public TLS should work without local certificate\nflags. The CLI derives the HTTPS API origin from the websocket URL for OAuth,\nruntime manifest download, and runtime archive download.\n\nFor local development with a private CA:\n\n```bash\nKANDAN_TLS_CA_FILE=/path/to/ca.crt linzumi start ~/code/my-app \\\n  --kandan-url wss://linzumi.io:4140\n```\n\n## Tailscale Development\n\nIf your browser needs to reach a local Kandan server through Tailscale:\n\n```bash\nlinzumi start ~/code/my-app \\\n  --kandan-url ws://100.71.192.98:4162 \\\n  --oauth-callback-host 100.71.192.98\n```\n\nUse your own Tailscale IP.\n\n## Commands\n\n```bash\nlinzumi\nlinzumi --help\nlinzumi --version\nlinzumi start <folder>\nlinzumi connect --help\nlinzumi connect [runner options]\nlinzumi auth [auth options]\n```\n\nMost people should use `linzumi start`.\n\n`linzumi connect` is the lower-level command for connecting to an explicit\nworkspace and channel:\n\n```bash\nlinzumi connect \\\n  --kandan-url wss://serve.kandanai.com \\\n  --workspace default \\\n  --channel general \\\n  --cwd ~/code/my-app\n```\n\n## Useful Options\n\n```bash\n--kandan-url <ws-url>       Kandan websocket URL\n--oauth-callback-host <ip>  Callback host reachable by your browser\n--runner-id <id>            Stable id for this computer\n--codex-bin <path>          Codex executable, default codex\n--model <name>              Codex model metadata shown in Kandan\n--reasoning-effort <value>  Codex reasoning metadata shown in Kandan\n--fast                      Mark this runner as low-latency\n--forward-port <ports>      Comma-separated local ports Kandan may expose\n--allowed-cwd <paths>       Comma-separated roots Kandan may use\n--log-file <path>           JSONL runner event log\n```\n\n`--code-server-bin` exists only as a development override. It is not the\nsupported production editor path.\n\n## Troubleshooting\n\nCheck the CLI version:\n\n```bash\nlinzumi --version\n```\n\nExpected:\n\n```text\nlinzumi 0.0.7-beta\n```\n\nIf `linzumi` is not found, your global npm bin directory is not on `PATH`.\n\nIf `bun` is not found, install Bun and rerun `linzumi start`.\n\nIf `codex` is not found, install or configure the Codex CLI, or pass\n`--codex-bin`.\n\nIf OAuth opens but does not return to the CLI, pass an\n`--oauth-callback-host` that your browser can reach.\n\nIf the editor does not become ready, do not install a local code-server package\nas a workaround. The server-managed runtime must download and verify cleanly.\nRerun the CLI and check the runner log.\n\nIf collaboration behaves oddly in Safari, retry in Chromium. Safari is currently\nsemi-supported.\n\n## For Kandan Release Engineers\n\nThe production contract is:\n\n1. Build the server-approved editor runtime archive.\n2. Publish the manifest and archive from Kandan.\n3. Publish the CLI beta.\n4. The CLI downloads only the approved runtime archive.\n5. The CLI verifies the archive SHA before advertising editor readiness.\n\nFor local package verification:\n\n```bash\nbun test\nnpm pack --dry-run\n```\n\nThe npm package must include this README, `bin/linzumi.js`, and the `src`\nruntime files."
 }

package/src/authResolution.ts

@@ -13,6 +13,7 @@ export type LocalRunnerTokenResolutionArgs = {
   readonly explicitToken?: string | undefined;
   readonly workspaceSlug?: string | undefined;
   readonly channelSlug?: string | undefined;
+  readonly onboarding?: "start" | undefined;
   readonly authFilePath?: string | undefined;
   readonly callbackHost?: string | undefined;
   readonly reportRejectedCachedToken?: (() => void) | undefined;
@@ -61,6 +62,7 @@ async function acquireAndCacheToken(args: LocalRunnerTokenResolutionArgs): Promi
     kandanUrl: args.kandanUrl,
     workspaceSlug: args.workspaceSlug,
     channelSlug: args.channelSlug,
+    onboarding: args.onboarding,
     callbackHost: args.callbackHost,
   });
 

package/src/boundedCache.ts

@@ -0,0 +1,57 @@
+/*
+- Date: 2026-04-26
+  Spec: kandan/server_v2/plans/2026-04-26-local-codex-driver-worldclass-spec.md
+  Relationship: Provides bounded in-memory registries for local Codex runner
+  state so long turns keep O(1) keyed lookup while retaining deterministic
+  eviction order for transcript reconciliation.
+*/
+
+export type BoundedCache<TValue> = {
+  readonly limit: number;
+  readonly values: Map<string, TValue>;
+};
+
+export function createBoundedCache<TValue>(limit: number): BoundedCache<TValue> {
+  if (!Number.isInteger(limit) || limit <= 0) {
+    throw new Error(`invalid bounded cache limit: ${limit}`);
+  }
+
+  return {
+    limit,
+    values: new Map(),
+  };
+}
+
+export function getBoundedCacheValue<TValue>(
+  cache: BoundedCache<TValue>,
+  key: string,
+): TValue | undefined {
+  return cache.values.get(key);
+}
+
+export function rememberBoundedCacheValue<TValue>(
+  cache: BoundedCache<TValue>,
+  key: string,
+  value: TValue,
+): void {
+  cache.values.set(key, value);
+
+  while (cache.values.size > cache.limit) {
+    const evicted = cache.values.keys().next().value;
+
+    if (evicted !== undefined) {
+      cache.values.delete(evicted);
+    }
+  }
+}
+
+export function forgetBoundedCacheValue<TValue>(
+  cache: BoundedCache<TValue>,
+  key: string,
+): void {
+  cache.values.delete(key);
+}
+
+export function boundedCacheValues<TValue>(cache: BoundedCache<TValue>): TValue[] {
+  return [...cache.values.values()];
+}