@linzumi/cli 0.0.4-beta → 0.0.6-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.4-beta
+npm install -g @linzumi/cli@0.0.6-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.4-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.4-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.6-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,32 @@
 {
   "name": "@linzumi/cli",
-  "version": "0.0.4-beta",
-  "description": "Linzumi local Codex runner CLI.",
+  "version": "0.0.6-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"
+  }
 }

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()];
+}