@gleapai/kai-bridge 0.10.2 → 0.12.0

package/src/deps.mjs

@@ -11,7 +11,7 @@
 // yet) we leave the directory absent and the install path takes over with
 // the lockfile-driven, cache-first command instead of a bare `npm install`.
 
-import { execFileSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, rmSync, statSync } from "node:fs";
 import { platform } from "node:os";
@@ -84,24 +84,45 @@ export function canSeedNodeModules({ primaryPath, cwd }) {
   return { ok: true, reason: "lockfile_match", pm: b.pm };
 }
 
+/**
+ * `cmd args` as a promise, output discarded (stderr's head kept for the
+ * reason). Asynchronous on purpose: cloning a big `node_modules` takes 30 s
+ * to 2.5 min (bridge.log: 144 s for the Gleap dashboard, 105 s for the
+ * Server), and a synchronous copy froze the daemon for all of it.
+ */
+function runQuiet(cmd, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { stdio: ["ignore", "ignore", "pipe"] });
+    let stderr = "";
+    child.stderr.on("data", (chunk) => {
+      if (stderr.length < 2000) stderr += chunk;
+    });
+    child.on("error", reject);
+    child.on("close", (code, signal) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${cmd} exited with ${code ?? signal}${stderr.trim() ? `: ${stderr.trim().slice(0, 500)}` : ""}`));
+    });
+  });
+}
+
 /**
  * Copy the primary checkout's `node_modules` into a fresh worktree when
- * the lockfiles match. Returns `{ seeded, reason, ms }`; never throws — a
+ * the lockfiles match. Resolves `{ seeded, reason, ms }`; never rejects — a
  * failed or partial copy is removed so the install path still runs.
  *
  * macOS `cp -c` clones via clonefile(2) and falls back to a plain copy on
  * filesystems without it; `-R` without `-L` keeps symlinks as symlinks
  * (`.bin` shims, pnpm's store links — all relative, so they stay valid).
  */
-export function seedNodeModules({ primaryPath, cwd, os = platform(), exec = execFileSync }) {
+export async function seedNodeModules({ primaryPath, cwd, os = platform(), exec = runQuiet }) {
   const started = Date.now();
   const check = canSeedNodeModules({ primaryPath, cwd });
   if (!check.ok) return { seeded: false, reason: check.reason, ms: 0 };
   const src = join(primaryPath, "node_modules");
   const dst = join(cwd, "node_modules");
   try {
-    if (os === "darwin") exec("cp", ["-c", "-R", src, dst], { stdio: "ignore" });
-    else if (os === "linux") exec("cp", ["-R", "--reflink=auto", src, dst], { stdio: "ignore" });
+    if (os === "darwin") await exec("cp", ["-c", "-R", src, dst]);
+    else if (os === "linux") await exec("cp", ["-R", "--reflink=auto", src, dst]);
     else return { seeded: false, reason: "unsupported_platform", ms: 0 };
     return { seeded: true, reason: check.reason, ms: Date.now() - started };
   } catch (err) {

package/src/help.mjs

@@ -0,0 +1,115 @@
+// The command reference: one table drives `kai-bridge help`, `help <command>`,
+// the "unknown command" hint and the usage lines the commands print themselves.
+
+import { palette } from "./tui.mjs";
+
+export const COMMANDS = [
+  // ── setup and account ──
+  { name: "setup", group: "Setup and account", usage: "setup", summary: "guided onboarding: pair, service, agent sign-ins",
+    details: ["Re-run it any time: it shows the machine's state and offers what is left to do."] },
+  { name: "login", group: "Setup and account", usage: "login [--name <device name>]", brief: "login [--name …]", summary: "pair this machine with your Gleap account",
+    details: ["Opens a link to approve in the dashboard. `--name` sets how the machine appears there."] },
+  { name: "logout", group: "Setup and account", usage: "logout", summary: "disconnect this machine, remove its service",
+    details: ["Your Claude Code / Codex / Cursor logins stay on the machine."] },
+  // ── service ──
+  { name: "service", group: "Background service", usage: "service install | uninstall | restart | status | logs [--lines <n>] [--follow]", brief: "service <action>",
+    summary: "the bridge that runs at login and restarts after crashes",
+    details: [
+      "install    add it (launchd on macOS, systemd --user on Linux, Task Scheduler on Windows) and start it",
+      "uninstall  stop and remove it",
+      "restart    reload it — after a manual `npm i -g`, or when it looks stuck",
+      "status     installed? running? since when? where are the logs?",
+      "logs       the last 50 lines of the bridge log; `--follow` keeps streaming, `--lines 200` shows more",
+    ],
+    examples: ["kai-bridge service logs --follow", "kai-bridge service restart"] },
+  { name: "start", group: "Background service", usage: "start", summary: "run in the foreground (what the service runs)",
+    details: ["Ctrl-C stops it. Only one bridge runs per machine: stop the service first, or use `kai-bridge service install`."] },
+  { name: "install", hidden: true, aliasOf: "service", usage: "install", summary: "same as `service install`" },
+  { name: "uninstall", hidden: true, aliasOf: "service", usage: "uninstall", summary: "same as `service uninstall`" },
+  // ── inspect ──
+  { name: "status", group: "Inspect", usage: "status", summary: "tools, device, service, agents, profiles, repos",
+    details: ["Node, git and agent binaries first, then the machine's pairing, service, sign-ins and the repos Kai can see."] },
+  { name: "ps", group: "Inspect", usage: "ps [--json]", summary: "running turns and dev servers, with links" },
+  { name: "doctor", hidden: true, aliasOf: "status", usage: "doctor", summary: "same as `status`" },
+  // ── agents ──
+  { name: "harness", group: "Coding agents", usage: "harness list | install <id> | update <id>", brief: "harness <action> [id]",
+    summary: "install or update Claude Code, Codex and Cursor",
+    details: ["<id> is claude, codex or cursor. Claude Code and Codex ship bundled; Cursor is downloaded on install.", "Signing in is `kai-bridge profile login <id>`."],
+    examples: ["kai-bridge harness update codex", "kai-bridge harness install cursor"] },
+  { name: "profile", group: "Coding agents", usage: "profile list | login <id> [--device-auth] | add <id> --harness <claude|codex|cursor> [--label …] | remove <id>", brief: "profile <action> [id]",
+    summary: "sign in to agents, and keep extra logins apart",
+    details: [
+      "`login claude` (or codex, cursor) signs in the machine's own agent. `--device-auth` uses a code instead of a browser (servers, SSH).",
+      "`add` creates a second, separate login — another Claude account, a shared team Codex — that sessions can pick.",
+    ],
+    examples: ["kai-bridge profile login codex --device-auth", "kai-bridge profile add work --harness claude --label \"Claude (work)\"", "kai-bridge profile login work"] },
+  // ── repos ──
+  { name: "repo", group: "Repositories", usage: "repo roots [add <dir> | remove <dir>] | primary <repoKey> <path>", brief: "repo <action> […]",
+    summary: "where Kai looks for checkouts, and the primary per repo",
+    details: ["Roots are scanned for git checkouts (`kai-bridge status` lists what was found). `primary` picks the checkout used when a repo appears more than once."],
+    examples: ["kai-bridge repo roots add ~/work", "kai-bridge repo primary github.com/acme/app ~/work/app"] },
+  // ── other ──
+  { name: "update", group: "Advanced", usage: "update", summary: "install the latest version now",
+    details: ["The background service updates itself; this forces it, also after a failed attempt."] },
+  { name: "help", group: "Advanced", usage: "help [command]", summary: "this list, or one command in detail" },
+  { name: "run", hidden: true, usage: "run --task \"…\" [--model <id>] [--profile <id>] [--cwd <dir>]", summary: "one local turn without the server (for development)",
+    examples: ["kai-bridge run --task \"Explain the auth flow\" --cwd ~/code/app"] },
+];
+
+export const findCommand = (name) => COMMANDS.find((c) => c.name === name) ?? null;
+
+/** `kai-bridge help` — grouped, one line per command. */
+export function renderHelp({ paint = palette(), version } = {}) {
+  const p = paint;
+  const lines = [`${p.bold("kai-bridge")}${version ? p.dim(` v${version}`) : ""} ${p.dim("— run Gleap Kai Code on this machine")}`, ""];
+  const shown = COMMANDS.filter((c) => !c.hidden);
+  const groups = [...new Set(shown.map((c) => c.group))];
+  const brief = (c) => c.brief ?? c.usage;
+  const w = Math.max(...shown.map((c) => brief(c).length)) + 2;
+  for (const g of groups) {
+    lines.push(p.dim(g));
+    for (const c of shown.filter((c) => c.group === g)) {
+      const args = brief(c).slice(c.name.length);
+      lines.push(`  ${p.magenta(c.name)}${p.dim(args)}${" ".repeat(w - brief(c).length)}${c.summary}`);
+    }
+    lines.push("");
+  }
+  lines.push(p.dim("kai-bridge help <command> shows details · --version prints the version"));
+  return lines;
+}
+
+/** `kai-bridge help <command>`. Null when the command does not exist. */
+export function renderCommandHelp(name, { paint = palette() } = {}) {
+  let c = findCommand(name);
+  if (!c) return null;
+  const p = paint;
+  const lines = [];
+  if (c.aliasOf) {
+    lines.push(p.dim(`\`kai-bridge ${c.usage}\` is ${c.summary.replace(/^same as /, "the same as ")}.`), "");
+    c = findCommand(c.aliasOf);
+  }
+  lines.push(`${p.bold(`kai-bridge ${c.usage}`)}`, "", `  ${c.summary}`);
+  if (c.details?.length) {
+    lines.push("");
+    for (const d of c.details) lines.push(`  ${d}`);
+  }
+  if (c.examples?.length) {
+    lines.push("", p.dim("  Examples"));
+    for (const e of c.examples) lines.push(`    ${e}`);
+  }
+  return lines;
+}
+
+/** The closest known command for a typo, or null when nothing is close. */
+export function suggestCommand(input) {
+  const s = String(input || "").toLowerCase();
+  if (!s) return null;
+  const dist = (a, b) => {
+    const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+    for (let j = 1; j <= b.length; j += 1) d[0][j] = j;
+    for (let i = 1; i <= a.length; i += 1) for (let j = 1; j <= b.length; j += 1) d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    return d[a.length][b.length];
+  };
+  const best = COMMANDS.filter((c) => !c.hidden).map((c) => ({ name: c.name, d: dist(s, c.name) })).sort((a, b) => a.d - b.d)[0];
+  return best && (best.d <= 2 || best.name.startsWith(s)) ? best.name : null;
+}

package/src/logs.mjs

@@ -0,0 +1,62 @@
+// `kai-bridge service logs`: the last lines of a log file, optionally
+// followed. Plain fs — the daemon appends lines, nothing rotates them.
+
+import { closeSync, existsSync, openSync, readSync, statSync, watchFile, unwatchFile } from "node:fs";
+
+/** The last `lines` lines of `path` ("" when the file is missing or empty). */
+export function tailFile(path, lines = 50) {
+  if (!existsSync(path)) return "";
+  const size = statSync(path).size;
+  if (size === 0) return "";
+  const fd = openSync(path, "r");
+  try {
+    // Read backwards in chunks until enough newlines are in hand.
+    const chunk = 64 * 1024;
+    let pos = size;
+    let buf = "";
+    while (pos > 0 && buf.split("\n").length <= lines + 1) {
+      const len = Math.min(chunk, pos);
+      pos -= len;
+      const b = Buffer.alloc(len);
+      readSync(fd, b, 0, len, pos);
+      buf = b.toString("utf8") + buf;
+    }
+    const all = buf.replace(/\n$/, "").split("\n");
+    return all.slice(-lines).join("\n");
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Print `path` as it grows. Resolves only when `signal` aborts (Ctrl-C).
+ * Polls via fs.watchFile: works on every platform and for files that do
+ * not exist yet (the daemon may start after `logs --follow`).
+ */
+export function followFile(path, { write = (s) => process.stdout.write(s), signal, intervalMs = 500 } = {}) {
+  let pos = existsSync(path) ? statSync(path).size : 0;
+  const drain = () => {
+    if (!existsSync(path)) return;
+    const size = statSync(path).size;
+    if (size < pos) pos = 0; // truncated or replaced
+    if (size === pos) return;
+    const fd = openSync(path, "r");
+    try {
+      const b = Buffer.alloc(size - pos);
+      readSync(fd, b, 0, b.length, pos);
+      write(b.toString("utf8"));
+      pos = size;
+    } finally {
+      closeSync(fd);
+    }
+  };
+  return new Promise((resolve) => {
+    watchFile(path, { interval: intervalMs }, drain);
+    const stop = () => {
+      unwatchFile(path, drain);
+      resolve();
+    };
+    if (signal?.aborted) stop();
+    else signal?.addEventListener("abort", stop, { once: true });
+  });
+}

package/src/ps.mjs

@@ -133,7 +133,7 @@ export function formatProcessList(list, { now = Date.now() } = {}) {
   lines.push(
     d.running
       ? `daemon:   running · pid ${d.pid}${d.version ? ` · v${d.version}` : ""} · up ${formatUptime(d.startedAt, now)}`
-      : `daemon:   not running${d.pid ? ` (stale lock, pid ${d.pid})` : ""} — run \`kai-bridge start\` or \`kai-bridge install\``,
+      : `daemon:   not running${d.pid ? ` (stale lock, pid ${d.pid})` : ""} — run \`kai-bridge start\` or \`kai-bridge service install\``,
   );
   if (!list.sessions.length) {
     lines.push("", "nothing running on this machine");

package/src/service.mjs

@@ -1,6 +1,6 @@
 // Login-item service: launchd (macOS) / systemd --user (Linux) /
 // Task Scheduler (Windows). Runs `kai-bridge start` at login, restarts
-// on crash, logs under ~/.kai/logs. `kai-bridge install` / `uninstall`.
+// on crash, logs under ~/.kai/logs. `kai-bridge service install|uninstall|restart|status|logs`.
 
 import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";