@linzumi/cli 0.0.1-beta

package/README.md

@@ -0,0 +1,177 @@
+# @linzumi/cli
+
+```text
+        .  *  .        .      *
+   *       _.-"""-._        .
+        .-'  _   _  '-.  *
+       /    (o)_(o)    \
+      |        .-.       |       mouse in the grove
+      |     .-(   )-.    |       listening for Kandan
+       \   /   '-'   \  /
+        '-.\__     __/.-'
+            /|     |\
+          _/ |  |  | \_
+        .'   |__|__|   '.
+       /   .  /___\  .   \
+      '._.'  /_____\  '._.'
+```
+
+Linzumi's CLI package. It installs the `linzumi` executable.
+
+The current CLI is intentionally small: it connects this machine to Kandan as a
+local Codex runner.
+
+## Install
+
+Install the exact beta version:
+
+```bash
+npm install -g @linzumi/cli@0.0.1-beta
+```
+
+Or install the current beta tag:
+
+```bash
+npm install -g @linzumi/cli@beta
+```
+
+Check that the executable is available:
+
+```bash
+linzumi --version
+```
+
+Expected output for this beta:
+
+```bash
+linzumi 0.0.1-beta
+```
+
+## Basic Use
+
+Run the CLI without arguments to start the default connection command:
+
+```bash
+linzumi
+```
+
+That prints the connection guide and tells you to start the local runner
+connection flow from Kandan.
+
+You can print the same guide directly:
+
+```bash
+linzumi connect
+```
+
+`linzumi connect` is the user-facing command. The CLI runs on your local
+computer; Kandan does not execute this binary for you. Kandan shows the command
+or connection details, and you run them locally.
+
+## Connect To The Linzumi Workspace
+
+1. Install the CLI:
+
+```bash
+npm install -g @linzumi/cli@0.0.1-beta
+```
+
+2. Confirm the CLI is installed:
+
+```bash
+linzumi --version
+```
+
+3. Open Kandan in your browser and switch to the Linzumi workspace.
+
+4. Start the local runner connection flow in Kandan.
+
+5. Copy the command Kandan shows you and run it in a terminal on this computer.
+
+6. Leave that terminal process running while you use the local runner from
+Kandan.
+
+For orientation, running the CLI without arguments prints the local connection
+guide:
+
+```bash
+linzumi
+```
+
+## Commands
+
+Supported commands right now:
+
+```bash
+linzumi
+linzumi connect
+linzumi --help
+linzumi --version
+linzumi connect --help
+linzumi connect --version
+```
+
+`local-codex-runner` is still accepted as a compatibility alias:
+
+```bash
+linzumi local-codex-runner
+```
+
+## Runner Protocol
+
+During the connection flow, Kandan may tell you to run a command shaped like:
+
+```bash
+linzumi connect app-server --listen ws://127.0.0.1:45021
+```
+
+That trailing `app-server --listen <url>` is runner protocol. It is not a
+separate Linzumi feature; it is the Codex app-server mode that lets this local
+process open the websocket Kandan will connect to.
+
+## Configuration
+
+The Kandan local runner flow should give you the command or configuration to run
+on your machine. For manual testing, the same configuration can be supplied with
+environment variables:
+
+```bash
+export LINZUMI_LOCAL_CODEX_RUNNER_LINZ_BIN=/path/to/kandan-local-bridge-linz
+export LINZUMI_LOCAL_CODEX_RUNNER_VM_ID=lzrunner123
+export LINZUMI_LOCAL_CODEX_RUNNER_REMOTE_CODEX_BIN=.kandan/tools/codex/0.116.0/bin/codex
+export LINZUMI_LOCAL_CODEX_RUNNER_REMOTE_ENV=.kandan/runtime/agents/13/channels/8/codex_app_server/runtime.env.sh
+```
+
+Or with flags:
+
+```bash
+linzumi connect \
+  --linz-bin /path/to/kandan-local-bridge-linz \
+  --vm-id lzrunner123 \
+  --remote-codex-bin .kandan/tools/codex/0.116.0/bin/codex \
+  --remote-env .kandan/runtime/agents/13/channels/8/codex_app_server/runtime.env.sh \
+  app-server --listen ws://127.0.0.1:45021
+```
+
+The runner executes:
+
+```bash
+<linz-bin> exec <vm-id> -- sh -lc "exec <remote-kandan-linz> app-server --env-file <remote-env> <remote-codex-bin> <listen-url>"
+```
+
+## Troubleshooting
+
+If `linzumi` is not found, confirm the global npm bin directory is on your
+`PATH`:
+
+```bash
+npm bin -g
+```
+
+If `linzumi connect` reports missing configuration, use the full command or
+configuration shown by Kandan's local runner connection flow. Manual launches
+need the environment variables or flags listed above.
+
+If the runner starts but Kandan cannot connect, check that the `--listen` URL
+was supplied by Kandan and that the configured LINZ bridge command can reach the
+runner VM.

package/bin/linzumi.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+import { runCli } from "../src/cli.js";
+
+const result = runCli({
+  argv: process.argv.slice(2),
+  env: process.env,
+  cwd: process.cwd(),
+  stdout: process.stdout,
+  stderr: process.stderr,
+});
+
+if (result.exitCode !== 0) {
+  process.exit(result.exitCode);
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@linzumi/cli",
+  "version": "0.0.1-beta",
+  "description": "Linzumi local Codex runner CLI.",
+  "type": "module",
+  "bin": {
+    "linzumi": "bin/linzumi.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node ./test/local-codex-runner.test.js"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/src/cli.js

@@ -0,0 +1,240 @@
+import { spawnSync } from "node:child_process";
+
+const version = "0.0.1-beta";
+
+const requiredEnv = {
+  linzBin: "LINZUMI_LOCAL_CODEX_RUNNER_LINZ_BIN",
+  vmId: "LINZUMI_LOCAL_CODEX_RUNNER_VM_ID",
+  remoteCodexBin: "LINZUMI_LOCAL_CODEX_RUNNER_REMOTE_CODEX_BIN",
+  remoteEnv: "LINZUMI_LOCAL_CODEX_RUNNER_REMOTE_ENV",
+};
+
+const usage = `linzumi connect [OPTIONS]
+
+Connects this machine to Kandan as the local Codex runner.
+
+This command runs on your local computer. Use the command shown by Kandan's
+local runner connection flow to start the local Codex runner here.
+
+Options:
+  --linz-bin <path>            LINZ CLI or bridge wrapper to execute
+  --vm-id <id>                 LINZ runner VM id
+  --remote-codex-bin <path>    Remote Codex binary path
+  --remote-env <path>          Remote env-file path
+  --remote-kandan-linz <path>  Remote kandan_linz path
+  --help                       Show this help
+  --version                    Show CLI version
+
+Environment defaults:
+  ${requiredEnv.linzBin}
+  ${requiredEnv.vmId}
+  ${requiredEnv.remoteCodexBin}
+  ${requiredEnv.remoteEnv}
+  LINZUMI_LOCAL_CODEX_RUNNER_REMOTE_KANDAN_LINZ
+
+Internal runner protocol:
+  linzumi connect [OPTIONS] app-server --listen <url>
+`;
+
+const defaultRemoteKandanLinz = "/home/linz/.kandan/runner/bin/kandan_linz";
+
+const connectGuide = `linzumi connect
+
+This command connects this machine to Kandan as a local Codex runner.
+
+Open Kandan, start the local runner connection flow, and follow the command it
+shows you. Run that command on this computer.
+
+For help:
+  linzumi connect --help
+`;
+
+const isBlank = (value) => typeof value !== "string" || value.trim() === "";
+
+const readOptionValue = (tokens, index, name) => {
+  const value = tokens[index + 1];
+  if (isBlank(value)) {
+    return { ok: false, error: `${name} requires a value` };
+  }
+
+  return { ok: true, value, nextIndex: index + 2 };
+};
+
+const shellQuote = (value) => `'${value.replaceAll("'", "'\"'\"'")}'`;
+
+export const buildRemoteCommand = ({ remoteKandanLinz, remoteEnv, remoteCodexBin, listenUrl }) => {
+  const rendered = [
+    "exec",
+    shellQuote(remoteKandanLinz),
+    "app-server",
+    "--env-file",
+    shellQuote(remoteEnv),
+    shellQuote(remoteCodexBin),
+    shellQuote(listenUrl),
+  ];
+
+  return rendered.join(" ");
+};
+
+const normalizeRemotePath = (path) => {
+  if (path.startsWith("/")) {
+    return path;
+  }
+
+  return `/home/linz/${path}`;
+};
+
+export const parseLocalCodexRunnerArgs = ({ argv, env }) => {
+  const options = {
+    linzBin: env[requiredEnv.linzBin],
+    vmId: env[requiredEnv.vmId],
+    remoteCodexBin: env[requiredEnv.remoteCodexBin],
+    remoteEnv: env[requiredEnv.remoteEnv],
+    remoteKandanLinz:
+      env.LINZUMI_LOCAL_CODEX_RUNNER_REMOTE_KANDAN_LINZ ?? defaultRemoteKandanLinz,
+  };
+  const command = [];
+
+  let index = 0;
+  while (index < argv.length) {
+    const token = argv[index];
+
+    switch (token) {
+      case "--help":
+      case "-h":
+        return { ok: true, help: true };
+      case "--version":
+        return { ok: true, version: true };
+      case "--linz-bin": {
+        const parsed = readOptionValue(argv, index, "--linz-bin");
+        if (!parsed.ok) return parsed;
+        options.linzBin = parsed.value;
+        index = parsed.nextIndex;
+        break;
+      }
+      case "--vm-id": {
+        const parsed = readOptionValue(argv, index, "--vm-id");
+        if (!parsed.ok) return parsed;
+        options.vmId = parsed.value;
+        index = parsed.nextIndex;
+        break;
+      }
+      case "--remote-codex-bin": {
+        const parsed = readOptionValue(argv, index, "--remote-codex-bin");
+        if (!parsed.ok) return parsed;
+        options.remoteCodexBin = parsed.value;
+        index = parsed.nextIndex;
+        break;
+      }
+      case "--remote-env": {
+        const parsed = readOptionValue(argv, index, "--remote-env");
+        if (!parsed.ok) return parsed;
+        options.remoteEnv = parsed.value;
+        index = parsed.nextIndex;
+        break;
+      }
+      case "--remote-kandan-linz": {
+        const parsed = readOptionValue(argv, index, "--remote-kandan-linz");
+        if (!parsed.ok) return parsed;
+        options.remoteKandanLinz = parsed.value;
+        index = parsed.nextIndex;
+        break;
+      }
+      case "--":
+        command.push(...argv.slice(index + 1));
+        index = argv.length;
+        break;
+      default:
+        command.push(...argv.slice(index));
+        index = argv.length;
+        break;
+    }
+  }
+
+  const [subcommand, listenFlag, listenUrl, ...extra] = command;
+  if (subcommand !== "app-server" || listenFlag !== "--listen" || isBlank(listenUrl) || extra.length > 0) {
+    return {
+      ok: false,
+      error: "connect must be launched by Kandan with the internal runner protocol",
+    };
+  }
+
+  const missing = Object.entries(options)
+    .filter(([, value]) => isBlank(value))
+    .map(([name]) => name);
+
+  if (missing.length > 0) {
+    return { ok: false, error: `missing connect option(s): ${missing.join(", ")}` };
+  }
+
+  return {
+    ok: true,
+    options: {
+      ...options,
+      remoteCodexBin: normalizeRemotePath(options.remoteCodexBin),
+      remoteEnv: normalizeRemotePath(options.remoteEnv),
+      remoteKandanLinz: normalizeRemotePath(options.remoteKandanLinz),
+      listenUrl,
+    },
+  };
+};
+
+export const runLocalCodexRunner = ({ argv, env, cwd, spawn = spawnSync }) => {
+  if (argv.length === 0) {
+    return { exitCode: 0, stdout: connectGuide, stderr: "" };
+  }
+
+  const parsed = parseLocalCodexRunnerArgs({ argv, env });
+
+  if (!parsed.ok) {
+    return { exitCode: 64, stdout: "", stderr: `${parsed.error}\n` };
+  }
+
+  if (parsed.help) {
+    return { exitCode: 0, stdout: usage, stderr: "" };
+  }
+
+  if (parsed.version) {
+    return { exitCode: 0, stdout: `linzumi ${version}\n`, stderr: "" };
+  }
+
+  const { linzBin, vmId, remoteKandanLinz, remoteEnv, remoteCodexBin, listenUrl } = parsed.options;
+  const remoteCommand = buildRemoteCommand({ remoteKandanLinz, remoteEnv, remoteCodexBin, listenUrl });
+  const result = spawn(linzBin, ["exec", vmId, "--", "sh", "-lc", remoteCommand], {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "inherit", "inherit"],
+  });
+
+  if (result.error) {
+    return { exitCode: 127, stdout: "", stderr: `${result.error.message}\n` };
+  }
+
+  return { exitCode: result.status ?? 1, stdout: "", stderr: "" };
+};
+
+export const runCliToResult = ({ argv, env, cwd, spawn = spawnSync }) => {
+  const [command, ...rest] = argv;
+
+  switch (command) {
+    case undefined:
+      return runLocalCodexRunner({ argv: [], env, cwd, spawn });
+    case "connect":
+    case "local-codex-runner":
+      return runLocalCodexRunner({ argv: rest, env, cwd, spawn });
+    case "--help":
+    case "-h":
+      return { exitCode: 0, stdout: usage, stderr: "" };
+    case "--version":
+      return { exitCode: 0, stdout: `linzumi ${version}\n`, stderr: "" };
+    default:
+      return { exitCode: 64, stdout: "", stderr: `unknown linzumi command: ${command}\n${usage}` };
+  }
+};
+
+export const runCli = ({ argv, env, cwd, stdout, stderr, spawn = spawnSync }) => {
+  const result = runCliToResult({ argv, env, cwd, spawn });
+  if (result.stdout !== "") stdout.write(result.stdout);
+  if (result.stderr !== "") stderr.write(result.stderr);
+  return { exitCode: result.exitCode };
+};