cursor-route 0.1.1

package/src/health.ts

@@ -0,0 +1,120 @@
+import { execSync } from "node:child_process";
+import { allAdapters } from "./adapters/index.ts";
+import { config } from "./config.ts";
+import { isTmuxAvailable } from "./tmux.ts";
+import { commandExists } from "./util.ts";
+
+export interface HealthReport {
+  ok: boolean;
+  product: string;
+  version: string;
+  checks: Array<{
+    name: string;
+    ok: boolean;
+    detail: string;
+  }>;
+}
+
+export function runHealth(): HealthReport {
+  const checks: HealthReport["checks"] = [];
+
+  const tmuxOk = isTmuxAvailable();
+  checks.push({
+    name: "tmux",
+    ok: tmuxOk,
+    detail: tmuxOk
+      ? "ok"
+      : "missing — install: brew install tmux (macOS) or apt install tmux (Linux)",
+  });
+
+  const bunOk = commandExists("bun");
+  const nodeOk = commandExists("node");
+  checks.push({
+    name: "runtime",
+    ok: bunOk || nodeOk,
+    detail: bunOk ? "bun ok" : nodeOk ? "node ok (tsx via npx for TS)" : "need bun or node 20+",
+  });
+
+  const scriptOk = (() => {
+    try {
+      execSync("command -v script", { stdio: "ignore" });
+      return true;
+    } catch {
+      return false;
+    }
+  })();
+  checks.push({
+    name: "script(1)",
+    ok: scriptOk,
+    detail: scriptOk ? "ok (tty log capture)" : "missing — needed for job logs on macOS/Linux",
+  });
+
+  for (const adapter of allAdapters()) {
+    const h = adapter.health();
+    checks.push({
+      name: `worker:${h.worker}`,
+      ok: h.ok,
+      detail: h.binary ? `${h.detail} @ ${h.binary}` : h.detail,
+    });
+  }
+
+  // Optional supervisor probe (v0 skill-only; Cursor CLI agent is informational)
+  const agentBin =
+    (commandExists("agent") && "agent") ||
+    (commandExists("cursor-agent") && "cursor-agent") ||
+    null;
+  checks.push({
+    name: "cursor_cli",
+    ok: true, // informational — does not fail health
+    detail: agentBin
+      ? `optional ok (${agentBin} on PATH) — v0 supervisor is Cursor skill, not CLI`
+      : "optional — Cursor CLI agent not on PATH (skill-only supervisor is fine for v0)",
+  });
+
+  // At least one worker must be healthy; tmux is hard-required for attach/send product path.
+  // Set CURSOR_ROUTE_RELAXED=1 to pass health without tmux (headless/--no-tmux CI).
+  const workerOk = checks.some((c) => c.name.startsWith("worker:") && c.ok);
+  const relaxed = process.env.CURSOR_ROUTE_RELAXED === "1";
+  const hardOk = (tmuxOk || relaxed) && (bunOk || nodeOk) && scriptOk;
+  const ok = hardOk && workerOk;
+
+  if (relaxed && !tmuxOk) {
+    checks.push({
+      name: "relaxed",
+      ok: true,
+      detail: "CURSOR_ROUTE_RELAXED=1 — tmux not required (headless only)",
+    });
+  }
+
+  checks.push({
+    name: "jobs_dir",
+    ok: true,
+    detail: config.jobsDir,
+  });
+
+  return {
+    ok,
+    product: config.product,
+    version: config.version,
+    checks,
+  };
+}
+
+export function printHealth(report: HealthReport, asJson: boolean): void {
+  if (asJson) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  console.log(`${report.product} v${report.version}`);
+  console.log(report.ok ? "health: OK" : "health: NEEDS SETUP");
+  console.log("");
+  for (const c of report.checks) {
+    const mark = c.ok ? "✓" : "✗";
+    console.log(`  ${mark} ${c.name.padEnd(16)} ${c.detail}`);
+  }
+  if (!report.ok) {
+    console.log("");
+    console.log("Fix the ✗ items, then re-run: cursor-route health");
+    console.log("Tip: start with one worker (grok OR claude-ds) before parallel demos.");
+  }
+}

package/src/jobs.ts

@@ -0,0 +1,394 @@
+import {
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  readdirSync,
+  existsSync,
+  unlinkSync,
+  openSync,
+  closeSync,
+  chmodSync,
+} from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { dirname } from "node:path";
+import { config, sessionName, type Lane, type WorkerKind } from "./config.ts";
+import { getAdapter } from "./adapters/index.ts";
+import { spawn } from "node:child_process";
+import { spawnSync } from "node:child_process";
+import { createWorkerSession, sessionExists, killSession } from "./tmux.ts";
+import { newJobId, shellQuote } from "./util.ts";
+import { markCompleteInvoker } from "./runtime.ts";
+import { assertJobId, JOB_ID_RE } from "./secrets.ts";
+
+export type JobStatus = "pending" | "running" | "completed" | "failed" | "killed";
+
+export interface Job {
+  id: string;
+  schema: "cursor-route.job.v1";
+  status: JobStatus;
+  worker: WorkerKind;
+  lane?: Lane;
+  prompt: string;
+  cwd: string;
+  alwaysApprove: boolean;
+  tmuxSession: string;
+  /** Headless process id (process group leader). */
+  pid?: number;
+  createdAt: string;
+  startedAt?: string;
+  completedAt?: string;
+  error?: string;
+  logBytes?: number;
+  logTail?: string;
+  exitCode?: number;
+}
+
+function ensureJobsDir(): void {
+  mkdirSync(config.jobsDir, { recursive: true, mode: 0o700 });
+  try {
+    chmodSync(config.jobsDir, 0o700);
+  } catch {
+    /* ignore */
+  }
+}
+
+function writeSecure(path: string, data: string): void {
+  writeFileSync(path, data, { mode: 0o600 });
+}
+
+function underJobsDir(id: string, ext: string): string {
+  assertJobId(id);
+  const base = resolve(config.jobsDir);
+  const full = resolve(join(base, `${id}${ext}`));
+  if (!full.startsWith(base + "/") && full !== base) {
+    throw new Error("Job path escapes jobsDir");
+  }
+  return full;
+}
+
+export function jobPaths(id: string) {
+  ensureJobsDir();
+  return {
+    json: underJobsDir(id, ".json"),
+    prompt: underJobsDir(id, ".prompt"),
+    log: underJobsDir(id, ".log"),
+  };
+}
+
+export function readJob(id: string): Job | null {
+  try {
+    assertJobId(id);
+  } catch {
+    return null;
+  }
+  const p = jobPaths(id).json;
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, "utf8")) as Job;
+  } catch {
+    return null;
+  }
+}
+
+export function writeJob(job: Job): void {
+  writeSecure(jobPaths(job.id).json, JSON.stringify(job, null, 2));
+}
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function sleepMs(ms: number): void {
+  spawnSync("sleep", [String(ms / 1000)]);
+}
+
+function terminatePid(pid: number): boolean {
+  const trySignal = (sig: NodeJS.Signals | number, group: boolean) => {
+    try {
+      process.kill(group ? -pid : pid, sig);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  trySignal("SIGTERM", true);
+  trySignal("SIGTERM", false);
+  for (let i = 0; i < 10; i++) {
+    if (!pidAlive(pid)) return true;
+    sleepMs(100);
+  }
+  trySignal("SIGKILL", true);
+  trySignal("SIGKILL", false);
+  for (let i = 0; i < 10; i++) {
+    if (!pidAlive(pid)) return true;
+    sleepMs(100);
+  }
+  return !pidAlive(pid);
+}
+
+/** Refresh running jobs without inventing success from "session gone". */
+export function refreshStatus(job: Job): Job {
+  if (job.status !== "running") return job;
+
+  // Prefer completion-hook result if already written.
+  const fresh = readJob(job.id);
+  if (fresh && fresh.status !== "running") return fresh;
+
+  const headless = job.tmuxSession.startsWith("headless-");
+  if (headless) {
+    if (job.pid && pidAlive(job.pid)) return job;
+    if (job.pid && !pidAlive(job.pid)) {
+      // Process exited but hook may not have run — mark unknown failure, not success.
+      const again = readJob(job.id);
+      if (again && again.status !== "running") return again;
+      job.status = "failed";
+      job.error = job.error || "Headless worker exited without completion marker";
+      job.completedAt = new Date().toISOString();
+      writeJob(job);
+      return job;
+    }
+    // No pid recorded (legacy) — do not flip to completed.
+    return job;
+  }
+
+  // tmux path: session gone → re-read; if still running, mark failed (unknown), not completed.
+  if (!sessionExists(job.tmuxSession)) {
+    const again = readJob(job.id);
+    if (again && again.status !== "running") return again;
+    job.status = "failed";
+    job.error = job.error || "tmux session ended without completion marker";
+    job.completedAt = new Date().toISOString();
+    writeJob(job);
+  }
+  return job;
+}
+
+export function listJobs(limit = config.jobsListLimit): Job[] {
+  ensureJobsDir();
+  const files = readdirSync(config.jobsDir).filter(
+    (f) => f.endsWith(".json") && JOB_ID_RE.test(f.replace(/\.json$/, "")),
+  );
+  const jobs: Job[] = [];
+  for (const f of files) {
+    try {
+      const job = JSON.parse(readFileSync(join(config.jobsDir, f), "utf8")) as Job;
+      if (job?.schema === "cursor-route.job.v1") jobs.push(refreshStatus(job));
+    } catch {
+      /* skip */
+    }
+  }
+  jobs.sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1));
+  return jobs.slice(0, limit);
+}
+
+export interface StartOptions {
+  prompt: string;
+  worker?: WorkerKind;
+  lane?: Lane;
+  cwd?: string;
+  alwaysApprove?: boolean;
+  dryRun?: boolean;
+  noTmux?: boolean;
+}
+
+export function resolveWorker(opts: StartOptions): WorkerKind {
+  if (opts.worker) return opts.worker;
+  if (opts.lane) return config.laneWorkers[opts.lane];
+  return config.defaultWorker;
+}
+
+export function startJob(opts: StartOptions): {
+  ok: true;
+  job: Job;
+  dryRun?: boolean;
+  command?: string;
+} | { ok: false; error: string } {
+  const worker = resolveWorker(opts);
+  const cwd = opts.cwd || process.cwd();
+  const alwaysApprove =
+    opts.alwaysApprove !== false &&
+    process.env.CURSOR_ROUTE_ASK !== "1" &&
+    process.env.CLAUDE_DS_ASK !== "1";
+
+  // Preflight: requested worker must be healthy
+  const adapter = getAdapter(worker);
+  const health = adapter.health();
+  if (!health.ok && !opts.dryRun) {
+    return { ok: false, error: `Worker ${worker} unavailable: ${health.detail}` };
+  }
+
+  const id = newJobId();
+  const paths = jobPaths(id);
+  writeSecure(paths.prompt, opts.prompt);
+
+  let plan;
+  try {
+    plan = adapter.buildLaunch({
+      promptFile: paths.prompt,
+      cwd,
+      alwaysApprove,
+    });
+  } catch (e) {
+    return { ok: false, error: (e as Error).message };
+  }
+
+  const job: Job = {
+    id,
+    schema: "cursor-route.job.v1",
+    status: "pending",
+    worker,
+    lane: opts.lane,
+    prompt: opts.prompt,
+    cwd,
+    alwaysApprove: plan.alwaysApprove,
+    tmuxSession: opts.noTmux ? `headless-${id}` : sessionName(id),
+    createdAt: new Date().toISOString(),
+  };
+
+  if (opts.dryRun) {
+    // No durable prompt retention for dry-run
+    try {
+      unlinkSync(paths.prompt);
+    } catch {
+      /* ignore */
+    }
+    return { ok: true, job, dryRun: true, command: plan.command };
+  }
+
+  const here = dirname(fileURLToPath(import.meta.url));
+  const markComplete = join(here, "mark-complete.ts");
+  const invoker = markCompleteInvoker(markComplete);
+
+  // Persist running BEFORE launch so fast workers cannot race completion overwrite.
+  job.status = "running";
+  job.startedAt = new Date().toISOString();
+  writeJob(job);
+
+  if (opts.noTmux) {
+    const wrapped = [
+      plan.command,
+      `exit_code=$?`,
+      `${invoker} ${shellQuote(paths.json)} "$exit_code" ${shellQuote(paths.log)}`,
+      `exit $exit_code`,
+    ].join("; ");
+
+    let logFd: number | undefined;
+    try {
+      logFd = openSync(paths.log, "a", 0o600);
+    } catch (e) {
+      job.status = "failed";
+      job.error = `Cannot open log: ${(e as Error).message}`;
+      job.completedAt = new Date().toISOString();
+      writeJob(job);
+      return { ok: false, error: job.error };
+    }
+
+    const child = spawn("sh", ["-c", wrapped], {
+      cwd,
+      detached: true,
+      stdio: ["ignore", logFd, logFd],
+    });
+    try {
+      closeSync(logFd);
+    } catch {
+      /* ignore */
+    }
+
+    if (child.pid == null) {
+      job.status = "failed";
+      job.error = "Failed to spawn headless worker";
+      job.completedAt = new Date().toISOString();
+      writeJob(job);
+      return { ok: false, error: job.error };
+    }
+
+    job.pid = child.pid;
+    writeJob(job);
+    child.unref();
+    return { ok: true, job };
+  }
+
+  const created = createWorkerSession({
+    jobId: id,
+    cwd,
+    workerCmd: plan.command,
+    logFile: paths.log,
+    jobFile: paths.json,
+    markCompleteScript: markComplete,
+  });
+
+  if (!created.ok) {
+    job.status = "failed";
+    job.error = created.error;
+    job.completedAt = new Date().toISOString();
+    writeJob(job);
+    return { ok: false, error: created.error };
+  }
+
+  writeJob(job);
+  return { ok: true, job };
+}
+
+export function killJob(id: string): { ok: true; job: Job } | { ok: false; error: string } {
+  const job = readJob(id);
+  if (!job) return { ok: false, error: `Job not found: ${id}` };
+
+  if (job.tmuxSession.startsWith("headless-")) {
+    if (job.pid) {
+      const ok = terminatePid(job.pid);
+      if (!ok) {
+        return { ok: false, error: `Failed to kill pid ${job.pid}` };
+      }
+    } else {
+      return {
+        ok: false,
+        error: "Headless job has no pid — cannot kill (legacy job). Kill the worker process manually.",
+      };
+    }
+  } else {
+    const killed = killSession(job.tmuxSession);
+    if (!killed && sessionExists(job.tmuxSession)) {
+      return { ok: false, error: `Failed to kill tmux session ${job.tmuxSession}` };
+    }
+  }
+
+  job.status = "killed";
+  job.completedAt = new Date().toISOString();
+  writeJob(job);
+  return { ok: true, job };
+}
+
+export function cleanJobs(olderThanDays = 7): number {
+  ensureJobsDir();
+  const cutoff = Date.now() - olderThanDays * 86400000;
+  let n = 0;
+  for (const f of readdirSync(config.jobsDir)) {
+    if (!f.endsWith(".json")) continue;
+    const id = f.replace(/\.json$/, "");
+    if (!JOB_ID_RE.test(id)) continue;
+    try {
+      const job = JSON.parse(readFileSync(join(config.jobsDir, f), "utf8")) as Job;
+      const t = Date.parse(job.completedAt || job.createdAt);
+      if (
+        Number.isFinite(t) &&
+        t < cutoff &&
+        (job.status === "completed" || job.status === "failed" || job.status === "killed")
+      ) {
+        for (const ext of [".json", ".prompt", ".log"] as const) {
+          const fp = underJobsDir(id, ext);
+          if (existsSync(fp)) unlinkSync(fp);
+        }
+        n++;
+      }
+    } catch {
+      /* skip */
+    }
+  }
+  return n;
+}

package/src/mark-complete.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env bun
+/**
+ * Marks a job completed/failed after the worker process exits.
+ * Invoked from tmux / headless completion hooks — keep dep-free.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+
+const jobPath = process.argv[2];
+const exitCode = Number(process.argv[3] ?? "1");
+const logPath = process.argv[4];
+
+if (!jobPath) process.exit(0);
+
+try {
+  const job = JSON.parse(readFileSync(jobPath, "utf8")) as Record<string, unknown>;
+  if (job.status === "running" || job.status === "pending") {
+    job.status = exitCode === 0 ? "completed" : "failed";
+    job.exitCode = exitCode;
+    job.completedAt = new Date().toISOString();
+    if (exitCode !== 0 && !job.error) {
+      job.error = `Worker exited with code ${exitCode}`;
+    }
+    if (logPath) {
+      try {
+        const log = readFileSync(logPath, "utf8");
+        job.logBytes = Buffer.byteLength(log);
+        // Avoid retaining secret-looking tails in job metadata
+        const redacted = log
+          .replace(/\bsk-[a-zA-Z0-9]{20,}\b/g, "[REDACTED]")
+          .replace(/\bghp_[A-Za-z0-9]{20,}\b/g, "[REDACTED]")
+          .replace(/\bxox[baprs]-[A-Za-z0-9-]{10,}\b/gi, "[REDACTED]");
+        job.logTail = redacted.slice(-2000);
+      } catch {
+        /* ignore */
+      }
+    }
+    writeFileSync(jobPath, JSON.stringify(job, null, 2), { mode: 0o600 });
+  }
+} catch {
+  /* never fail the shell hook hard */
+}
+process.exit(0);

package/src/runtime.ts

@@ -0,0 +1,23 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { commandExists, shellQuote } from "./util.ts";
+
+/**
+ * Resolve how to re-invoke TypeScript helpers (mark-complete) from shell hooks.
+ * Prefer bun; else pinned npx tsx — never bare network-unpinned without note.
+ */
+export function markCompleteInvoker(scriptPath: string): string {
+  if (commandExists("bun")) {
+    return `bun ${shellQuote(scriptPath)}`;
+  }
+  // Pin tsx major for supply-chain predictability on Node-only hosts
+  return `npx --yes tsx@4.19.4 ${shellQuote(scriptPath)}`;
+}
+
+/** XDG-ish default away from git-clone install dir (~/.cursor-route). */
+export function defaultJobsDir(): string {
+  if (process.env.CURSOR_ROUTE_JOBS_DIR) return process.env.CURSOR_ROUTE_JOBS_DIR;
+  const home = process.env.HOME || homedir();
+  const xdg = process.env.XDG_DATA_HOME || join(home, ".local", "share");
+  return join(xdg, "cursor-route", "jobs");
+}

package/src/secrets.ts

@@ -0,0 +1,26 @@
+/**
+ * Secret material detectors — match key *contents*, not the phrase "API key".
+ * Applied to `start` and `send`.
+ */
+const PATTERNS: RegExp[] = [
+  /\bsk-[a-zA-Z0-9]{20,}\b/,
+  /\bghp_[A-Za-z0-9]{20,}\b/,
+  /\bgho_[A-Za-z0-9]{20,}\b/,
+  /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/i,
+  /\bAIza[0-9A-Za-z_-]{20,}\b/,
+  /-----BEGIN (?:RSA |EC |OPENSSH |PGP )?PRIVATE KEY-----/,
+  /\bAKIA[0-9A-Z]{16}\b/,
+];
+
+export function looksLikeSecretMaterial(text: string): boolean {
+  return PATTERNS.some((re) => re.test(text));
+}
+
+export const JOB_ID_RE = /^[a-f0-9]{8}$/;
+
+export function assertJobId(id: string): string {
+  if (!JOB_ID_RE.test(id)) {
+    throw new Error(`Invalid job id: ${id} (expected 8 hex chars)`);
+  }
+  return id;
+}