@linzumi/cli 0.0.22-beta → 0.0.24-beta

package/README.md

@@ -32,8 +32,20 @@ starts that hot-reload app on your computer, creates the shared support
 channel, starts a Linzumi Codex session in a work thread, and opens the
 browser editor pointed at the demo app.
 
+Terms:
+
+- **Bootstrapper Codex**: the outer Codex started by the pasted command. It
+  sets up Linzumi and local processes, but does not edit the demo app.
+- **Linzumi Commander**: the long-running local bridge started with
+  `linzumi commander`; it owns the secure tunnel, trusted folder, browser
+  editor, and inner Codex launch.
+- **Linzumi Codex session**: the inner agent running inside the Linzumi thread;
+  it edits `/tmp/hello_linzumi` and posts progress.
+- **Human**: the workspace owner who opens the one-time login link and watches
+  the work in `#general` and `#linzumi-support`.
+
 The snippet uses automatic command approval and full local process access
-because the bootstrapper must start a real runner and browser editor on this
+because the bootstrapper must start a real Linzumi Commander and browser editor on this
 computer. It is intentionally not the dangerous sandbox-bypass mode.
 
 Today, your AI coding agent has two homes, both bad.
@@ -104,7 +116,7 @@ stays available for compatibility. The bootstrap agent will confirm your
 email and workspace choice up front, ask for the emailed code after signup
 sends it, say hello to `@sean` in the shared support channel,
 generate `/tmp/hello_linzumi`, start its hot-reload Node server, start the
-runner for that folder, start a Linzumi Codex session in a work thread, and
+Commander for that folder, start a Linzumi Codex session in a work thread, and
 open the browser editor. The Linzumi Codex session then adds confetti to the
 demo page while you watch. Workspace names are plain display names from 2 to
 100 characters; Linzumi generates the URL-safe workspace slug.
@@ -117,25 +129,28 @@ Codex command.
 npx -y @linzumi/cli@latest signup --email alice@example.com --workspace-name "Alice's Linzumi" --agent-name BuildBot
 npx -y @linzumi/cli@latest claim --pending <pending_id> --code <XXXX-XXXX>
 npx -y @linzumi/cli@latest channel post <support_channel_id> "Hello @sean, starting this launch run."
-npx -y @linzumi/cli@latest hello
+npx -y @linzumi/cli@latest thread new "Hello Linzumi confetti" --message "Preparing the Hello Linzumi demo. Next I will generate /tmp/hello_linzumi, start its hot-reload server bound to 0.0.0.0 on port 8787, and ask Linzumi Codex to add confetti when the page loads."
+commander_id="hello-linzumi-commander-${thread_id%%-*}"
+npx -y @linzumi/cli@latest init-hello-linzumi-demo-app --parent-dir /tmp --name hello_linzumi --host 0.0.0.0 --port 8787 --reset --json
 (cd /tmp/hello_linzumi && npm run dev > /tmp/hello_linzumi/dev.log 2>&1 &)
-npx -y @linzumi/cli@latest thread new "Hello Linzumi confetti" --message "Please add confetti when the page loads."
-npx -y @linzumi/cli@latest agent runner /tmp/hello_linzumi \
-  --runner-id hello-linzumi-agent \
+npx -y @linzumi/cli@latest commander /tmp/hello_linzumi \
+  --runner-id "$commander_id" \
   --allowed-cwd /tmp/hello_linzumi \
   --forward-port 8787 \
   --sandbox danger-full-access \
   --approval-policy never
 ```
 
-The agent-owned runner reads `~/.linzumi/agent-token.json`, uses the
+The agent-owned Commander reads `~/.linzumi/agent-token.json`, uses the
 workspace/channel scope from the approval flow, trusts only the selected
 folder, advertises the explicit preview port, and listens only to the
-approving human unless `--listen-user` is explicitly passed. The bootstrap
-agent waits for `Runner connected:` before starting Codex in the Linzumi
+approving human unless `--listen-user` is explicitly passed. Use a unique
+Commander id per launch thread; Linzumi stores trusted-folder config per
+Commander id, so reusing an old fixed id can pick up stale allowed-cwd config.
+The bootstrap agent waits for `Runner connected:` before starting Codex in the Linzumi
 thread.
 
-By default, the runner downloads the Linzumi-approved `code-server`
+By default, the Commander downloads the Linzumi-approved `code-server`
 runtime for your platform and verifies its checksum before enabling the
 browser editor. Linux editor launches are wrapped with `bubblewrap`
 (`bwrap`) for filesystem confinement.
@@ -146,20 +161,20 @@ workspace. The claim also provisions `#linzumi-support`, a shared channel
 connected to Linzumi's workspace so our team can see setup issues from our
 side; the bootstrap agent posts a hello there with the printed
 `support_channel_id`.
-Keep demo work in task threads; use the support channel when signup, runner,
+Keep demo work in task threads; use the support channel when signup, Commander,
 preview, or browser-editor setup gets stuck.
 
-Once the runner is online, the bootstrap agent can ask Linzumi to start
+Once the Commander is online, the bootstrap agent can ask Linzumi to start
 Codex and open the browser editor for the same thread and folder:
 
 ```bash
 npx -y @linzumi/cli@latest codex start <thread_id> \
-  --runner hello-linzumi-agent \
+  --runner "$commander_id" \
   --cwd /tmp/hello_linzumi \
   --work-description "Work only in /tmp/hello_linzumi. Add tasteful confetti when the Hello Linzumi page loads, keep the hot-reload app working on port 8787, and post the exact files changed."
 
 npx -y @linzumi/cli@latest editor open <thread_id> \
-  --runner hello-linzumi-agent \
+  --runner "$commander_id" \
   --cwd /tmp/hello_linzumi
 ```
 
@@ -261,7 +276,7 @@ intentionally. Every action is auditable from the thread.
 ## Pinning a version
 
 ```bash
-npm install -g @linzumi/cli@0.0.22-beta
+npm install -g @linzumi/cli@0.0.24-beta
 linzumi --version
 ```
 
@@ -284,7 +299,7 @@ linzumi connect \
 ### All the flags
 
 ```text
---agent-token-file <path>   Agent token cache for `linzumi agent runner`
+--agent-token-file <path>   Agent token cache for `linzumi commander`
 --oauth-callback-host <ip>  Sign-in callback host your browser can reach
 --codex-bin <path>          Codex executable, default `codex`
 --model <name>              Model requested for Codex sessions and labelled in Linzumi

package/dist/index.js

@@ -7773,48 +7773,92 @@ Launch target:
 }
 
 // src/helloLinzumiProject.ts
-import { existsSync as existsSync7, mkdirSync as mkdirSync7, readFileSync as readFileSync6, writeFileSync as writeFileSync6 } from "node:fs";
+import { existsSync as existsSync7, mkdirSync as mkdirSync7, readFileSync as readFileSync6, rmSync as rmSync2, writeFileSync as writeFileSync6 } from "node:fs";
 import { dirname as dirname7, join as join7, resolve as resolve5 } from "node:path";
 import { fileURLToPath } from "node:url";
 var defaultHelloLinzumiProjectDir = "/tmp/hello_linzumi";
+var defaultHelloLinzumiProjectName = "hello_linzumi";
+var defaultHelloLinzumiParentDir = "/tmp";
+var defaultHelloLinzumiPort = 8787;
+var defaultHelloLinzumiHost = "0.0.0.0";
 var markerFile = ".linzumi-demo-project";
 var moduleDir = dirname7(fileURLToPath(import.meta.url));
 var linzumiLogoSvg = readFileSync6(join7(moduleDir, "assets", "linzumi-logo.svg"), "utf8");
-function createHelloLinzumiProject(rootPath = defaultHelloLinzumiProjectDir) {
-  const root = resolve5(rootPath);
-  assertWritableDemoRoot(root);
+function createHelloLinzumiProject(input = {}) {
+  const options = typeof input === "string" ? { rootPath: input } : input;
+  const root = resolveHelloProjectRoot(options);
+  const port = options.port ?? defaultHelloLinzumiPort;
+  const host = normalizeHost(options.host);
+  assertTcpPort(port);
+  assertWritableDemoRoot(root, options.reset === true);
   mkdirSync7(join7(root, "src"), { recursive: true });
-  for (const file of demoFiles()) {
+  for (const file of demoFiles({ root, port, host })) {
     writeFileSync6(join7(root, file.path), file.content, "utf8");
   }
   return {
     root,
-    port: 8787,
+    port,
+    host,
     startCommand: "npm run dev",
-    previewUrl: "http://127.0.0.1:8787"
+    previewUrl: `http://${host}:${port}`
   };
 }
-function assertWritableDemoRoot(root) {
+function resolveHelloProjectRoot(options) {
+  if (options.rootPath !== undefined && (options.parentDir !== undefined || options.name !== undefined)) {
+    throw new Error("linzumi init-hello-linzumi-demo-app accepts either --dir or --parent-dir/--name, not both");
+  }
+  if (options.rootPath !== undefined) {
+    return resolve5(options.rootPath);
+  }
+  const name = normalizeProjectName(options.name ?? defaultHelloLinzumiProjectName);
+  return resolve5(options.parentDir ?? defaultHelloLinzumiParentDir, name);
+}
+function normalizeProjectName(value) {
+  const name = value.trim();
+  if (name === "" || name === "." || name === ".." || name.includes("/") || name.includes("\\")) {
+    throw new Error("--name must be a single directory name");
+  }
+  return name;
+}
+function normalizeHost(value) {
+  const host = value?.trim() ?? defaultHelloLinzumiHost;
+  if (host === "") {
+    throw new Error("--host must not be empty");
+  }
+  return host;
+}
+function assertTcpPort(port) {
+  if (Number.isInteger(port) && port > 0 && port <= 65535) {
+    return;
+  }
+  throw new Error("--port must be a TCP port from 1 to 65535");
+}
+function assertWritableDemoRoot(root, reset) {
   if (!existsSync7(root)) {
     return;
   }
   const markerPath = join7(root, markerFile);
-  if (existsSync7(markerPath) && readFileSync6(markerPath, "utf8").trim() === "hello-linzumi") {
+  const isDemoRoot = existsSync7(markerPath) && readFileSync6(markerPath, "utf8").trim() === "hello-linzumi";
+  if (isDemoRoot && reset) {
+    rmSync2(root, { recursive: true, force: true });
     return;
   }
-  throw new Error(`${root} already exists and is not a Linzumi demo project; move it before rerunning linzumi hello`);
+  if (isDemoRoot) {
+    return;
+  }
+  throw new Error(`${root} already exists and is not a Linzumi demo project; move it before rerunning linzumi init-hello-linzumi-demo-app`);
 }
-function demoFiles() {
+function demoFiles(options) {
   return [
     { path: markerFile, content: `hello-linzumi
 ` },
     { path: "package.json", content: packageJson },
-    { path: "server.mjs", content: serverSource },
+    { path: "server.mjs", content: serverSource(options) },
     { path: "index.html", content: htmlSource },
-    { path: "src/main.js", content: mainSource },
+    { path: "src/main.js", content: mainSource(options) },
     { path: "src/styles.css", content: cssSource },
     { path: "src/linzumi-logo.svg", content: linzumiLogoSvg },
-    { path: "README.md", content: readmeSource }
+    { path: "README.md", content: readmeSource(options) }
   ];
 }
 var packageJson = `${JSON.stringify({
@@ -7828,12 +7872,13 @@ var packageJson = `${JSON.stringify({
   }
 }, null, 2)}
 `;
-var serverSource = `import { createReadStream, existsSync, statSync, watch } from "node:fs";
+var serverSource = ({ host, port }) => `import { createReadStream, existsSync, statSync, watch } from "node:fs";
 import { extname, join, normalize } from "node:path";
 import { createServer } from "node:http";
 
 const root = process.cwd();
-const port = Number(process.env.PORT ?? "8787");
+const port = Number(process.env.PORT ?? "${port}");
+const host = process.env.HOST ?? ${JSON.stringify(host)};
 const clients = new Set();
 
 const contentTypes = new Map([
@@ -7844,7 +7889,7 @@ const contentTypes = new Map([
 ]);
 
 const server = createServer((request, response) => {
-  const url = new URL(request.url ?? "/", "http://127.0.0.1");
+  const url = new URL(request.url ?? "/", "http://0.0.0.0");
 
   if (url.pathname === "/events") {
     response.writeHead(200, {
@@ -7891,10 +7936,10 @@ for (const watchedPath of [join(root, "index.html"), join(root, "src")]) {
   });
 }
 
-server.listen(port, "127.0.0.1", () => {
+server.listen(port, host, () => {
   const address = server.address();
   const actualPort = typeof address === "object" && address !== null ? address.port : port;
-  process.stdout.write(\`Hello Linzumi listening on http://127.0.0.1:\${actualPort}\\n\`);
+  process.stdout.write(\`Hello Linzumi listening on http://\${host}:\${actualPort}\\n\`);
 });
 `;
 var htmlSource = `<!doctype html>
@@ -8180,7 +8225,9 @@ h1 {
   }
 }
 `;
-var mainSource = `const prompts = [
+var mainSource = ({ root, host, port }) => `const projectLabel = ${JSON.stringify(`${root} · ${host}:${port}`)};
+
+const prompts = [
   "Add a soft confetti burst when I click the heading.",
   "Make this a kanban board with three columns for my groceries.",
   "Add a guestbook so my team can sign in.",
@@ -8236,7 +8283,7 @@ document.querySelector("#app").innerHTML = \`
     </div>
 
     <div class="footer-note">
-      <code>/tmp/hello_linzumi · localhost:8787</code>
+      <code>\${escape(projectLabel)}</code>
       <a href="https://linzumi.com" target="_blank" rel="noreferrer">linzumi.com →</a>
     </div>
   </div>
@@ -8261,10 +8308,10 @@ events.addEventListener("reload", () => {
   window.location.reload();
 });
 `;
-var readmeSource = `# Linzumi launch demo
+var readmeSource = ({ host, port }) => `# Linzumi launch demo
 
 A tiny Node-only HTTP server with browser live reload, generated by
-\`linzumi hello\`.
+\`linzumi init-hello-linzumi-demo-app\`.
 
 Run it:
 
@@ -8272,7 +8319,8 @@ Run it:
 npm run dev
 \`\`\`
 
-Then open http://127.0.0.1:8787. The page reloads when \`index.html\` or files
+The app binds to \`${host}\` by default so Linzumi can reach it through the
+secure tunnel. Then open http://${host}:${port}. The page reloads when \`index.html\` or files
 under \`src/\` change.
 
 The bootstrap agent in your terminal has already opened the browser VS Code
@@ -8318,6 +8366,12 @@ var flagDefinitions = new Map([
 ]);
 var helloFlagDefinitions = new Map([
   ["dir", { kind: "value" }],
+  ["parent-dir", { kind: "value" }],
+  ["name", { kind: "value" }],
+  ["port", { kind: "value" }],
+  ["host", { kind: "value" }],
+  ["reset", { kind: "boolean" }],
+  ["json", { kind: "boolean" }],
   ["help", { kind: "boolean" }]
 ]);
 if (isMainModule()) {
@@ -8343,7 +8397,7 @@ async function main(args) {
       process.stdout.write(connectGuideText());
       return;
     case "version":
-      process.stdout.write(`linzumi 0.0.22-beta
+      process.stdout.write(`linzumi 0.0.24-beta
 `);
       return;
     case "auth":
@@ -8393,10 +8447,12 @@ function parseCommand(args) {
     case "paths":
       return { command: "paths", args: rest };
     case "hello":
+    case "init-hello-linzumi-demo-app":
       return { command: "hello", args: rest };
     case "agent":
       return rest[0] === "runner" ? { command: "agentRunner", args: rest.slice(1) } : { command: "agent", args: rest };
     case "agent-runner":
+    case "commander":
       return { command: "agentRunner", args: rest };
     case "signup":
     case "claim":
@@ -8422,12 +8478,32 @@ function runHelloCommand(args) {
     process.stdout.write(helloHelpText());
     return;
   }
-  const project = createHelloLinzumiProject(stringValue3(values, "dir") ?? defaultHelloLinzumiProjectDir);
+  const project = createHelloLinzumiProject({
+    rootPath: stringValue3(values, "dir"),
+    parentDir: stringValue3(values, "parent-dir") === undefined ? undefined : resolveUserPath(required(values, "parent-dir")),
+    name: stringValue3(values, "name"),
+    port: tcpPortValue(values, "port"),
+    host: stringValue3(values, "host"),
+    reset: values.get("reset") === true
+  });
+  if (values.get("json") === true) {
+    process.stdout.write(`${JSON.stringify({
+      project_dir: project.root,
+      dev_command: project.startCommand,
+      preview_url: project.previewUrl,
+      port: project.port,
+      host: project.host
+    })}
+`);
+    return;
+  }
   process.stdout.write(`project_dir: ${project.root}
 `);
   process.stdout.write(`dev_command: ${project.startCommand}
 `);
   process.stdout.write(`preview_url: ${project.previewUrl}
+`);
+  process.stdout.write(`bind_host: ${project.host}
 `);
 }
 function runPathsCommand(args) {
@@ -8611,7 +8687,7 @@ async function parseAgentRunnerArgs(args, deps = {
   }
   rejectAgentRunnerTargetingFlags(values);
   if (cwdArg !== undefined && values.has("cwd")) {
-    throw new Error("linzumi agent runner accepts either <folder> or --cwd, not both");
+    throw new Error("linzumi commander accepts either <folder> or --cwd, not both");
   }
   const tokenFilePath = stringValue3(values, "agent-token-file") ?? defaultAgentTokenFilePath();
   const tokenFile = readStoredAgentTokenFile(tokenFilePath, deps.readTextFile);
@@ -8677,14 +8753,14 @@ function readAgentTokenTextFile(path) {
 function rejectAgentRunnerTargetingFlags(values) {
   const unsupportedFlags = ["workspace", "channel", "token", "auth-file", "oauth-callback-host"].filter((flag) => values.has(flag));
   if (unsupportedFlags.length > 0) {
-    throw new Error(`linzumi agent runner uses the claimed agent token scope; remove ${unsupportedFlags.map((flag) => `--${flag}`).join(", ")}.`);
+    throw new Error(`linzumi commander uses the claimed agent token scope; remove ${unsupportedFlags.map((flag) => `--${flag}`).join(", ")}.`);
   }
 }
 function requiredStoredAgentChannel(channelId) {
   if (channelId !== undefined) {
     return channelId;
   }
-  throw new Error("agent token file is missing channelId; rerun linzumi claim before starting an agent runner");
+  throw new Error("agent token file is missing channelId; rerun linzumi claim before starting a Commander");
 }
 function requiredStoredOwnerUsername(ownerUsername) {
   if (ownerUsername !== undefined) {
@@ -8742,7 +8818,7 @@ async function parseRunnerArgs(args, deps = {
     process.exit(0);
   }
   if (values.get("version") === true) {
-    process.stdout.write(`linzumi 0.0.22-beta
+    process.stdout.write(`linzumi 0.0.24-beta
 `);
     process.exit(0);
   }
@@ -8941,6 +9017,17 @@ function positiveIntegerValue(values, key) {
   }
   throw new Error(`--${key} must be a positive integer`);
 }
+function tcpPortValue(values, key) {
+  const value = stringValue3(values, key);
+  if (value === undefined) {
+    return;
+  }
+  const parsed = Number(value);
+  if (Number.isInteger(parsed) && parsed > 0 && parsed <= 65535) {
+    return parsed;
+  }
+  throw new Error(`--${key} must be a TCP port from 1 to 65535`);
+}
 function helpText() {
   return `Linzumi local Codex runner
 
@@ -8952,8 +9039,8 @@ Usage:
   linzumi post <thread_id> <message>
   linzumi inbox <thread_id> --since-last
   linzumi done <thread_id> --message <message>
-  linzumi hello
-  linzumi agent runner <folder> [options]
+  linzumi init-hello-linzumi-demo-app
+  linzumi commander <folder> [options]
   linzumi start <folder> [options]
   linzumi paths list|add|remove [path]
   linzumi connect --kandan-url <ws-url> --workspace <slug> --channel <slug> [options]
@@ -8994,8 +9081,8 @@ Examples:
     linzumi thread new "Hello world" --message "Starting now. ETA 3m."
     linzumi post thr_abc123 "PR is open"
     linzumi done thr_abc123 --message "Done: https://github.com/example/repo/pull/1"
-    linzumi hello
-    linzumi agent runner ~/code/my-app --runner-id launch-agent-runner
+    linzumi init-hello-linzumi-demo-app
+    linzumi commander ~/code/my-app --runner-id launch-commander
     linzumi start ~/
     linzumi start ~/code/my-app
     linzumi connect --workspace <your-workspace> --channel <your-channel> --launch-tui
@@ -9019,19 +9106,27 @@ function helloHelpText() {
   return `Linzumi Hello demo project
 
 Usage:
-  linzumi hello [--dir <path>]
+  linzumi init-hello-linzumi-demo-app [--dir <path>]
+  linzumi init-hello-linzumi-demo-app [--parent-dir <path> --name <dirname>]
 
 Creates a tiny Node-only "Hello Linzumi" app with browser live reload.
 
 Default:
   ${defaultHelloLinzumiProjectDir}
+  host ${defaultHelloLinzumiHost}, port ${defaultHelloLinzumiPort}
 
 After creation:
   cd ${defaultHelloLinzumiProjectDir}
   npm run dev
 
 Options:
-  --dir <path>  Override the project directory for tests or local experiments.
+  --dir <path>         Exact project directory.
+  --parent-dir <path>  Parent directory, default ${defaultHelloLinzumiParentDir}.
+  --name <dirname>     Project directory name with --parent-dir, default ${defaultHelloLinzumiProjectName}.
+  --host <host>        Bind host baked into the demo app, default ${defaultHelloLinzumiHost}.
+  --port <port>        Port baked into the demo app, default ${defaultHelloLinzumiPort}.
+  --reset              Recreate an existing marked Linzumi demo directory.
+  --json               Print machine-readable project details.
 `;
 }
 function pathsHelpText() {
@@ -9079,13 +9174,14 @@ Examples:
 `;
 }
 function agentRunnerHelpText() {
-  return `Linzumi agent-owned local runner
+  return `Linzumi Commander
 
 Usage:
+  linzumi commander <folder> [options]
   linzumi agent runner <folder> [options]
 
 What it does:
-  Starts this computer as the claimed agent's scoped local runner. The command
+  Starts this computer as the claimed agent's scoped Linzumi Commander. The command
   reads ~/.linzumi/agent-token.json, uses its workspace/channel scope, trusts
   only the selected folder by default, and listens only to the owning human
   recorded during claim unless --listen-user is passed.
@@ -9093,7 +9189,7 @@ What it does:
 Options:
   --agent-token-file <path>   Agent token cache, default ~/.linzumi/agent-token.json
   --kandan-url <ws-url>       Kandan websocket base URL. Defaults deterministically from the stored apiUrl.
-  --runner-id <id>            Stable local runner id
+  --runner-id <id>            Stable Commander id
   --codex-bin <path>          Codex executable, default codex
   --code-server-bin <path>    Custom development code-server executable. By default Kandan installs the approved editor runtime.
   --listen-user <user>        Human whose replies Codex may accept, default owner from claim
@@ -9103,11 +9199,11 @@ Options:
   --approval-policy <value>   Approval-policy metadata shown in Kandan
   --forward-port <ports>      Comma-separated local TCP ports Kandan may expose as previews
   --allowed-cwd <paths>       Override the selected folder with comma-separated trusted roots
-  --fast                      Mark this runner as low-latency/fast in Kandan
+  --fast                      Mark this Commander as low-latency/fast in Linzumi
 
 Examples:
-  linzumi agent runner "$PWD" --runner-id hello-world-agent
-  linzumi agent runner ~/code/my-app --kandan-url ws://127.0.0.1:4162 --runner-id local-qa-agent
+  linzumi commander "$PWD" --runner-id hello-world-commander
+  linzumi commander ~/code/my-app --kandan-url ws://127.0.0.1:4162 --runner-id local-qa-commander
 `;
 }
 function connectGuideText() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linzumi/cli",
-  "version": "0.0.22-beta",
+  "version": "0.0.24-beta",
   "description": "Linzumi CLI — point a Codex agent at the real code on your laptop, with your team watching and steering from shared threads.",
   "type": "module",
   "bin": {