linkshell-cli 0.1.0

package/src/commands/doctor.ts

@@ -0,0 +1,119 @@
+import { execSync } from "node:child_process";
+import { loadConfig, getConfigPath } from "../config.js";
+
+interface CheckResult {
+  name: string;
+  ok: boolean;
+  detail: string;
+}
+
+function check(name: string, fn: () => string): CheckResult {
+  try {
+    return { name, ok: true, detail: fn() };
+  } catch (e) {
+    return { name, ok: false, detail: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+function which(bin: string): string | undefined {
+  try {
+    return execSync(`which ${bin}`, { encoding: "utf8", timeout: 5000 }).trim() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function checkGateway(url: string): Promise<CheckResult> {
+  try {
+    const httpUrl = url.replace(/\/ws\/?$/, "").replace(/^wss:/, "https:").replace(/^ws:/, "http:");
+    const start = Date.now();
+    const res = await fetch(`${httpUrl}/healthz`, { signal: AbortSignal.timeout(5000) });
+    const latency = Date.now() - start;
+    if (!res.ok) return { name: "Gateway", ok: false, detail: `HTTP ${res.status}` };
+    return { name: "Gateway", ok: true, detail: `reachable (${latency}ms)` };
+  } catch (e) {
+    return { name: "Gateway", ok: false, detail: e instanceof Error ? e.message : "unreachable" };
+  }
+}
+
+export async function runDoctor(gatewayUrl?: string): Promise<void> {
+  const config = loadConfig();
+  const gateway = gatewayUrl ?? config.gateway;
+
+  process.stdout.write("\n  LinkShell Doctor\n\n");
+
+  const results: CheckResult[] = [];
+
+  // Node.js version
+  results.push(check("Node.js", () => {
+    const ver = process.versions.node;
+    const major = Number(ver.split(".")[0]);
+    if (major < 18) throw new Error(`v${ver} (need >= 18)`);
+    return `v${ver}`;
+  }));
+
+  // node-pty
+  results.push(check("node-pty", () => {
+    try {
+      require("node-pty");
+      return "loaded";
+    } catch {
+      // Try dynamic import path for ESM
+      try {
+        execSync("node -e \"require('node-pty')\"", { timeout: 5000, stdio: "pipe" });
+        return "loaded";
+      } catch {
+        throw new Error("native module not built — run: pnpm approve-builds && pnpm install --force");
+      }
+    }
+  }));
+
+  // Claude CLI
+  const claudePath = which("claude");
+  if (claudePath) {
+    results.push(check("Claude CLI", () => {
+      const ver = execSync("claude --version 2>&1", { encoding: "utf8", timeout: 5000 }).trim();
+      return `${ver} (${claudePath})`;
+    }));
+  } else {
+    results.push({ name: "Claude CLI", ok: false, detail: "not found — npm i -g @anthropic-ai/claude-code" });
+  }
+
+  // Codex CLI
+  const codexPath = which("codex");
+  if (codexPath) {
+    results.push(check("Codex CLI", () => `found (${codexPath})`));
+  } else {
+    results.push({ name: "Codex CLI", ok: false, detail: "not found — npm i -g @openai/codex" });
+  }
+
+  // Config
+  results.push(check("Config", () => {
+    const path = getConfigPath();
+    const cfg = loadConfig();
+    const keys = Object.keys(cfg).filter((k) => cfg[k as keyof typeof cfg] !== undefined);
+    if (keys.length === 0) return `${path} (empty — run: linkshell setup)`;
+    return `${path} (${keys.join(", ")})`;
+  }));
+
+  // Gateway
+  if (gateway) {
+    results.push(await checkGateway(gateway));
+  } else {
+    results.push({ name: "Gateway", ok: false, detail: "no gateway configured — run: linkshell setup" });
+  }
+
+  // Print results
+  for (const r of results) {
+    const icon = r.ok ? "\x1b[32m✓\x1b[0m" : "\x1b[31m✗\x1b[0m";
+    process.stdout.write(`  ${icon} ${r.name}: ${r.detail}\n`);
+  }
+
+  const failed = results.filter((r) => !r.ok);
+  process.stdout.write("\n");
+  if (failed.length === 0) {
+    process.stdout.write("  \x1b[32mAll checks passed.\x1b[0m\n\n");
+  } else {
+    process.stdout.write(`  \x1b[33m${failed.length} issue(s) found.\x1b[0m\n\n`);
+  }
+}

package/src/commands/setup.ts

@@ -0,0 +1,65 @@
+import * as readline from "node:readline";
+import { loadConfig, saveConfig, getConfigPath } from "../config.js";
+import type { LinkShellConfig } from "../config.js";
+
+function ask(rl: readline.Interface, question: string, defaultValue?: string): Promise<string> {
+  const suffix = defaultValue ? ` (${defaultValue})` : "";
+  return new Promise((resolve) => {
+    rl.question(`  ${question}${suffix}: `, (answer) => {
+      resolve(answer.trim() || defaultValue || "");
+    });
+  });
+}
+
+function choose(rl: readline.Interface, question: string, options: string[], defaultIdx = 0): Promise<string> {
+  return new Promise((resolve) => {
+    process.stdout.write(`  ${question}\n`);
+    for (let i = 0; i < options.length; i++) {
+      const marker = i === defaultIdx ? "\x1b[36m>\x1b[0m" : " ";
+      process.stdout.write(`  ${marker} ${i + 1}. ${options[i]}\n`);
+    }
+    rl.question(`  Choice (${defaultIdx + 1}): `, (answer) => {
+      const idx = Number(answer.trim()) - 1;
+      resolve(options[idx >= 0 && idx < options.length ? idx : defaultIdx]!);
+    });
+  });
+}
+
+export async function runSetup(): Promise<void> {
+  const existing = loadConfig();
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  process.stdout.write("\n  LinkShell Setup\n\n");
+
+  const gateway = await ask(rl, "Gateway URL", existing.gateway ?? "wss://localhost:8787/ws");
+
+  const provider = await choose(
+    rl,
+    "Default provider:",
+    ["claude", "codex", "custom"],
+    ["claude", "codex", "custom"].indexOf(existing.provider ?? "claude"),
+  ) as LinkShellConfig["provider"];
+
+  let command: string | undefined;
+  if (provider === "custom") {
+    command = await ask(rl, "Custom command", existing.command ?? "bash");
+  }
+
+  const clientName = await ask(rl, "Client name", existing.clientName ?? require("os").hostname());
+
+  rl.close();
+
+  const config: LinkShellConfig = {
+    gateway,
+    provider,
+    command,
+    clientName,
+  };
+
+  saveConfig(config);
+
+  process.stdout.write(`\n  \x1b[32mConfig saved to ${getConfigPath()}\x1b[0m\n\n`);
+  process.stdout.write("  Next steps:\n");
+  process.stdout.write("    linkshell doctor    — verify your setup\n");
+  process.stdout.write("    linkshell start     — start a bridge session\n\n");
+}

package/src/config.ts

@@ -0,0 +1,34 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+export interface LinkShellConfig {
+  gateway?: string;
+  pairingGateway?: string;
+  provider?: "claude" | "codex" | "custom";
+  command?: string;
+  clientName?: string;
+  cols?: number;
+  rows?: number;
+}
+
+const CONFIG_DIR = join(homedir(), ".linkshell");
+const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+
+export function loadConfig(): LinkShellConfig {
+  try {
+    if (!existsSync(CONFIG_FILE)) return {};
+    return JSON.parse(readFileSync(CONFIG_FILE, "utf8")) as LinkShellConfig;
+  } catch {
+    return {};
+  }
+}
+
+export function saveConfig(config: LinkShellConfig): void {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n", "utf8");
+}
+
+export function getConfigPath(): string {
+  return CONFIG_FILE;
+}

package/src/index.ts

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { BridgeSession } from "./runtime/bridge-session.js";
+import { resolveProviderConfig } from "./providers.js";
+import { loadConfig } from "./config.js";
+import { runDoctor } from "./commands/doctor.js";
+import { runSetup } from "./commands/setup.js";
+import { getLanIp } from "./utils/lan-ip.js";
+
+const config = loadConfig();
+const program = new Command();
+
+program
+  .name("linkshell")
+  .description(
+    "Bridge a local Claude/Codex terminal session to a remote gateway",
+  )
+  .version("0.1.0");
+
+program
+  .command("start")
+  .description("Start a bridge session")
+  .option("--gateway <url>", "Gateway websocket URL (omit to start built-in gateway)", config.gateway)
+  .option(
+    "--pairing-gateway <url-or-host>",
+    "Public HTTP gateway used in QR/deep link output",
+    config.pairingGateway,
+  )
+  .option("--port <port>", "Port for built-in gateway (default: 8787)", "8787")
+  .option("--session-id <id>", "Session identifier (auto-created if omitted)")
+  .option(
+    "--provider <provider>",
+    "claude | codex | custom",
+    config.provider ?? "claude",
+  )
+  .option("--command <command>", "Override provider executable", config.command)
+  .option(
+    "--client-name <name>",
+    "Display name for this CLI",
+    config.clientName ?? "local-cli",
+  )
+  .option(
+    "--cols <cols>",
+    "Initial terminal columns",
+    String(config.cols ?? 120),
+  )
+  .option("--rows <rows>", "Initial terminal rows", String(config.rows ?? 36))
+  .option("--verbose", "Enable verbose logging")
+  .allowUnknownOption(true)
+  .action(async (options, command) => {
+    const passthroughArgs = command.args.filter(
+      (value: string) => value !== "--",
+    );
+    const providerConfig = resolveProviderConfig({
+      provider: options.provider,
+      command: options.command,
+      args: passthroughArgs,
+    });
+
+    let gatewayUrl = options.gateway as string | undefined;
+    let gatewayHttpUrl: string;
+    let pairingGateway = options.pairingGateway as string | undefined;
+    let embeddedGatewayHandle: { close: () => Promise<void> } | undefined;
+
+    if (!gatewayUrl) {
+      // Start built-in gateway
+      const { startEmbeddedGateway } = await import("@linkshell/gateway/embedded");
+      const port = Number(options.port);
+      const gw = await startEmbeddedGateway({
+        port,
+        logLevel: options.verbose ? "debug" : "warn",
+        silent: false,
+      });
+      embeddedGatewayHandle = gw;
+      gatewayUrl = gw.wsUrl;
+      gatewayHttpUrl = gw.httpUrl;
+
+      // Auto-detect LAN IP for QR code
+      const lanIp = getLanIp();
+      if (!pairingGateway && lanIp !== "127.0.0.1") {
+        pairingGateway = `http://${lanIp}:${gw.port}`;
+      }
+
+      process.stderr.write(`\n  Built-in gateway started on port ${gw.port}\n`);
+      if (pairingGateway) {
+        process.stderr.write(`  LAN address: ${pairingGateway}\n`);
+      }
+      process.stderr.write("\n");
+    } else {
+      gatewayHttpUrl = gatewayUrl
+        .replace(/\/ws\/?$/, "")
+        .replace(/^wss:/, "https:")
+        .replace(/^ws:/, "http:");
+    }
+
+    const session = new BridgeSession({
+      gatewayUrl,
+      gatewayHttpUrl,
+      pairingGateway,
+      sessionId: options.sessionId,
+      cols: Number(options.cols),
+      rows: Number(options.rows),
+      clientName: options.clientName,
+      verbose: Boolean(options.verbose),
+      providerConfig,
+    });
+
+    // Clean up embedded gateway on exit
+    if (embeddedGatewayHandle) {
+      const cleanup = async () => {
+        await embeddedGatewayHandle!.close();
+      };
+      process.on("SIGINT", () => { cleanup().then(() => process.exit(0)); });
+      process.on("SIGTERM", () => { cleanup().then(() => process.exit(0)); });
+    }
+
+    await session.start();
+  });
+
+program
+  .command("doctor")
+  .description("Check your environment and connectivity")
+  .option("--gateway <url>", "Gateway URL to test", config.gateway)
+  .action(async (options) => {
+    await runDoctor(options.gateway);
+  });
+
+program
+  .command("setup")
+  .description("Interactive setup wizard")
+  .action(async () => {
+    await runSetup();
+  });
+
+program.parseAsync(process.argv).catch((error: unknown) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+});

package/src/providers.ts

@@ -0,0 +1,91 @@
+import { execSync } from "node:child_process";
+
+export type ProviderName = "claude" | "codex" | "custom";
+
+export interface ProviderConfig {
+  provider: ProviderName;
+  command: string;
+  args: string[];
+  env: NodeJS.ProcessEnv;
+}
+
+function which(bin: string): string | undefined {
+  try {
+    return execSync(`which ${bin}`, { encoding: "utf8" }).trim() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveClaudeProvider(input: {
+  command?: string;
+  args: string[];
+}): ProviderConfig {
+  const command = input.command ?? "claude";
+  const resolved = which(command);
+  if (!resolved) {
+    throw new Error(
+      `Claude CLI not found ("${command}"). Install it with: npm install -g @anthropic-ai/claude-code`,
+    );
+  }
+
+  // Claude starts an interactive REPL by default — that's exactly what we want in the PTY.
+  // Pass through any extra args the user provided.
+  return {
+    provider: "claude",
+    command: resolved,
+    args: input.args,
+    env: { ...process.env },
+  };
+}
+
+function resolveCodexProvider(input: {
+  command?: string;
+  args: string[];
+}): ProviderConfig {
+  const command = input.command ?? "codex";
+  const resolved = which(command);
+  if (!resolved) {
+    throw new Error(
+      `Codex CLI not found ("${command}"). Install it with: npm install -g @openai/codex`,
+    );
+  }
+
+  if (!process.env.OPENAI_API_KEY) {
+    process.stderr.write(
+      "[warn] OPENAI_API_KEY not set — Codex may fail to authenticate\n",
+    );
+  }
+
+  return {
+    provider: "codex",
+    command: resolved,
+    args: input.args,
+    env: { ...process.env },
+  };
+}
+
+export function resolveProviderConfig(input: {
+  provider: ProviderName;
+  command?: string;
+  args: string[];
+}): ProviderConfig {
+  switch (input.provider) {
+    case "claude":
+      return resolveClaudeProvider(input);
+    case "codex":
+      return resolveCodexProvider(input);
+    case "custom": {
+      if (!input.command) {
+        throw new Error("custom provider requires --command");
+      }
+      const resolved = which(input.command);
+      return {
+        provider: "custom",
+        command: resolved ?? input.command,
+        args: input.args,
+        env: { ...process.env },
+      };
+    }
+  }
+}