cursor-route 0.1.1

package/src/adapters/grok.ts

@@ -0,0 +1,54 @@
+import { execSync } from "node:child_process";
+import type { Adapter, WorkerHealth } from "./types.ts";
+import { shellQuote } from "../util.ts";
+
+function findGrok(): string | null {
+  try {
+    return execSync("command -v grok", {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+export const grokAdapter: Adapter = {
+  kind: "grok",
+  label: "Grok CLI (xAI)",
+  health(): WorkerHealth {
+    const binary = findGrok();
+    if (!binary) {
+      return {
+        worker: "grok",
+        ok: false,
+        binary: null,
+        detail: "grok not on PATH — install from https://x.ai/cli then run: grok login",
+      };
+    }
+    return {
+      worker: "grok",
+      ok: true,
+      binary,
+      detail: "ok (auth checked at first start — run grok login if jobs fail)",
+    };
+  },
+  buildLaunch({ promptFile, cwd, alwaysApprove }) {
+    const parts = [
+      "grok",
+      "-p",
+      `"$(cat ${shellQuote(promptFile)})"`,
+      "--cwd",
+      shellQuote(cwd),
+      "--no-auto-update",
+      "--output-format",
+      "plain",
+    ];
+    if (alwaysApprove) parts.push("--always-approve");
+    return {
+      worker: "grok",
+      command: parts.join(" "),
+      alwaysApprove,
+    };
+  },
+};

package/src/adapters/index.ts

@@ -0,0 +1,21 @@
+import type { WorkerKind } from "../config.ts";
+import type { Adapter } from "./types.ts";
+import { grokAdapter } from "./grok.ts";
+import { claudeDsAdapter } from "./claude-ds.ts";
+
+const registry: Record<WorkerKind, Adapter> = {
+  grok: grokAdapter,
+  "claude-ds": claudeDsAdapter,
+};
+
+export function getAdapter(worker: WorkerKind): Adapter {
+  const a = registry[worker];
+  if (!a) throw new Error(`Unknown worker: ${worker}`);
+  return a;
+}
+
+export function allAdapters(): Adapter[] {
+  return Object.values(registry);
+}
+
+export type { Adapter, WorkerHealth, LaunchPlan } from "./types.ts";

package/src/adapters/types.ts

@@ -0,0 +1,26 @@
+import type { WorkerKind } from "../config.ts";
+
+export interface WorkerHealth {
+  worker: WorkerKind;
+  ok: boolean;
+  binary: string | null;
+  detail: string;
+}
+
+export interface LaunchPlan {
+  worker: WorkerKind;
+  /** Full shell command to run inside tmux (prompt already inlined via cat). */
+  command: string;
+  alwaysApprove: boolean;
+}
+
+export interface Adapter {
+  kind: WorkerKind;
+  label: string;
+  health(): WorkerHealth;
+  buildLaunch(opts: {
+    promptFile: string;
+    cwd: string;
+    alwaysApprove: boolean;
+  }): LaunchPlan;
+}

package/src/cli.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from "bun:test";
+import { resolveWorker } from "./jobs.ts";
+import { config } from "./config.ts";
+import { shellQuote, newJobId } from "./util.ts";
+import { runHealth } from "./health.ts";
+import { looksLikeSecretMaterial } from "./secrets.ts";
+import { isDeepSeekRouted } from "./adapters/claude-ds.ts";
+
+describe("resolveWorker", () => {
+  test("lane mid → claude-ds", () => {
+    expect(resolveWorker({ prompt: "x", lane: "mid" })).toBe("claude-ds");
+  });
+  test("lane hard → grok", () => {
+    expect(resolveWorker({ prompt: "x", lane: "hard" })).toBe("grok");
+  });
+  test("explicit worker wins", () => {
+    expect(resolveWorker({ prompt: "x", lane: "hard", worker: "claude-ds" })).toBe(
+      "claude-ds",
+    );
+  });
+  test("default worker", () => {
+    expect(resolveWorker({ prompt: "x" })).toBe(config.defaultWorker);
+  });
+});
+
+describe("util", () => {
+  test("shellQuote", () => {
+    expect(shellQuote("a b")).toBe("'a b'");
+    expect(shellQuote("it's")).toBe("'it'\\''s'");
+  });
+  test("newJobId length", () => {
+    expect(newJobId()).toHaveLength(8);
+  });
+});
+
+describe("secrets", () => {
+  test("allows discussing API keys in prose", () => {
+    expect(looksLikeSecretMaterial("load the API key from env")).toBe(false);
+  });
+  test("blocks sk- material", () => {
+    expect(looksLikeSecretMaterial("token sk-abcdefghijklmnopqrstuvwxyz1234")).toBe(true);
+  });
+  test("blocks ghp_ material", () => {
+    expect(looksLikeSecretMaterial("ghp_abcdefghijklmnopqrstuvwx")).toBe(true);
+  });
+});
+
+describe("deepseek routing", () => {
+  test("detects deepseek base url", () => {
+    const prev = process.env.ANTHROPIC_BASE_URL;
+    process.env.ANTHROPIC_BASE_URL = "https://api.deepseek.com/anthropic";
+    try {
+      expect(isDeepSeekRouted()).toBe(true);
+    } finally {
+      if (prev === undefined) delete process.env.ANTHROPIC_BASE_URL;
+      else process.env.ANTHROPIC_BASE_URL = prev;
+    }
+  });
+});
+
+describe("health", () => {
+  test("returns structured report", () => {
+    const r = runHealth();
+    expect(r.product).toBe("cursor-route");
+    expect(r.checks.length).toBeGreaterThan(3);
+    expect(r.checks.some((c) => c.name === "tmux")).toBe(true);
+    expect(r.checks.some((c) => c.name === "cursor_cli")).toBe(true);
+  });
+
+  test("relaxed env can pass without tmux", () => {
+    const prev = process.env.CURSOR_ROUTE_RELAXED;
+    process.env.CURSOR_ROUTE_RELAXED = "1";
+    try {
+      const r = runHealth();
+      const tmux = r.checks.find((c) => c.name === "tmux");
+      if (tmux && !tmux.ok) {
+        expect(r.ok).toBe(true);
+        expect(r.checks.some((c) => c.name === "relaxed")).toBe(true);
+      }
+    } finally {
+      if (prev === undefined) delete process.env.CURSOR_ROUTE_RELAXED;
+      else process.env.CURSOR_ROUTE_RELAXED = prev;
+    }
+  });
+});

package/src/cli.ts

@@ -0,0 +1,370 @@
+#!/usr/bin/env bun
+/**
+ * cursor-route CLI — Cursor brain, Grok + DeepSeek workers in tmux.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, basename } from "node:path";
+import { config, WORKERS, LANES, type WorkerKind, type Lane } from "./config.ts";
+import { runHealth, printHealth } from "./health.ts";
+import {
+  startJob,
+  listJobs,
+  readJob,
+  killJob,
+  cleanJobs,
+  jobPaths,
+  refreshStatus,
+} from "./jobs.ts";
+import {
+  capturePane,
+  sendKeys,
+  attachHint,
+  listManagedSessions,
+  sessionExists,
+} from "./tmux.ts";
+import { looksLikeSecretMaterial } from "./secrets.ts";
+
+function usage(exitCode = 0): never {
+  console.log(`cursor-route v${config.version}
+
+Cursor stays the brain. Grok CLI + DeepSeek (claude-ds) are the parallel army.
+
+Usage:
+  cursor-route --version
+  cursor-route health [--json]
+  cursor-route start <prompt> [options]
+  cursor-route start --prompt-file <path> [options]
+  cursor-route jobs [--json] [--limit N]
+  cursor-route status <jobId> [--json]
+  cursor-route capture <jobId> [lines]
+  cursor-route send <jobId> <message>
+  cursor-route attach <jobId>
+  cursor-route kill <jobId>
+  cursor-route sessions
+  cursor-route clean [--days N]
+
+Start options:
+  --worker <grok|claude-ds>   Worker adapter (default: grok)
+  --lane <mid|hard>           Lane → worker (mid=claude-ds, hard=grok)
+  --dir <path>                Working directory (default: cwd)
+  --ask                       Disable always-approve for this job
+  --dry-run                   Print launch command; do not start
+  --no-tmux                   Headless background process (no attach/send)
+  --json                      JSON output where supported
+
+Env:
+  CURSOR_ROUTE_ASK=1                 Opt out of always-approve
+  CURSOR_ROUTE_JOBS_DIR              Override jobs dir (default: ~/.local/share/cursor-route/jobs)
+  CURSOR_ROUTE_RELAXED=1             health OK without tmux (headless CI)
+  CURSOR_ROUTE_ALLOW_ANTHROPIC=1     Allow mid-lane on Anthropic Claude (expensive; not default)
+`);
+  process.exit(exitCode);
+}
+
+function parseArgs(argv: string[]) {
+  const flags: Record<string, string | boolean> = {};
+  const positional: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (
+      a === "--json" ||
+      a === "--ask" ||
+      a === "--dry-run" ||
+      a === "--no-tmux" ||
+      a === "-h" ||
+      a === "--help" ||
+      a === "--version" ||
+      a === "-V"
+    ) {
+      if (a === "-h" || a === "--help") flags.help = true;
+      if (a === "--version" || a === "-V") flags.version = true;
+      if (a === "--dry-run") flags.dryRun = true;
+      if (a === "--no-tmux") flags.noTmux = true;
+      if (a === "--ask") flags.ask = true;
+      if (a === "--json") flags.json = true;
+      continue;
+    }
+    if (a.startsWith("--")) {
+      let key = a.slice(2);
+      let val: string | boolean = true;
+      if (key.includes("=")) {
+        const eq = key.indexOf("=");
+        val = key.slice(eq + 1);
+        key = key.slice(0, eq);
+      } else {
+        const next = argv[i + 1];
+        if (next && !next.startsWith("--")) {
+          val = next;
+          i++;
+        }
+      }
+      flags[key] = val;
+      continue;
+    }
+    positional.push(a);
+  }
+  return { flags, positional };
+}
+
+function asWorker(v: unknown): WorkerKind | undefined {
+  if (typeof v !== "string") return undefined;
+  if ((WORKERS as string[]).includes(v)) return v as WorkerKind;
+  throw new Error(`Invalid --worker ${v}; expected ${WORKERS.join("|")}`);
+}
+
+function asLane(v: unknown): Lane | undefined {
+  if (typeof v !== "string") return undefined;
+  if ((LANES as string[]).includes(v)) return v as Lane;
+  throw new Error(`Invalid --lane ${v}; expected ${LANES.join("|")}`);
+}
+
+function refuseSecrets(text: string, context: string): void {
+  if (looksLikeSecretMaterial(text)) {
+    console.error(
+      `Refusing ${context}: looks like secret key material. Remove tokens/keys and retry.`,
+    );
+    process.exit(3);
+  }
+}
+
+function refuseDangerousPromptFile(path: string): void {
+  const base = basename(path);
+  const resolved = resolve(path);
+  if (
+    base.startsWith(".env") ||
+    resolved.includes("/.ssh/") ||
+    base === "id_rsa" ||
+    base === "id_ed25519" ||
+    base.endsWith(".pem")
+  ) {
+    console.error(`Refusing --prompt-file path that looks credential-related: ${path}`);
+    process.exit(3);
+  }
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0) usage(0);
+
+  if (argv[0] === "--version" || argv[0] === "-V") {
+    console.log(config.version);
+    return;
+  }
+  if (argv[0] === "-h" || argv[0] === "--help") usage(0);
+
+  const cmd = argv[0];
+  const { flags: f, positional: pos } = parseArgs(argv.slice(1));
+  const json = Boolean(f.json);
+
+  if (cmd === "health") {
+    const report = runHealth();
+    printHealth(report, json);
+    process.exit(report.ok ? 0 : 1);
+  }
+
+  if (cmd === "start") {
+    let prompt = "";
+    if (f["prompt-file"]) {
+      const p = resolve(String(f["prompt-file"]));
+      refuseDangerousPromptFile(p);
+      if (!existsSync(p)) {
+        console.error(`prompt file not found: ${p}`);
+        process.exit(2);
+      }
+      prompt = readFileSync(p, "utf8");
+    } else {
+      prompt = pos.join(" ").trim();
+    }
+    if (!prompt) {
+      console.error("start requires a prompt or --prompt-file");
+      process.exit(2);
+    }
+    refuseSecrets(prompt, "to start");
+
+    const result = startJob({
+      prompt,
+      worker: asWorker(f.worker),
+      lane: asLane(f.lane),
+      cwd: f.dir ? resolve(String(f.dir)) : process.cwd(),
+      alwaysApprove: !f.ask,
+      dryRun: Boolean(f.dryRun),
+      noTmux: Boolean(f.noTmux),
+    });
+
+    if (!result.ok) {
+      console.error(result.error);
+      process.exit(1);
+    }
+
+    if (json) {
+      console.log(JSON.stringify({ ...result.job, command: result.command }, null, 2));
+    } else if (result.dryRun) {
+      console.log(`dry-run job ${result.job.id}`);
+      console.log(`worker: ${result.job.worker}`);
+      console.log(`command: ${result.command}`);
+    } else {
+      console.log(`started ${result.job.id} (${result.job.worker})`);
+      console.log(`session: ${result.job.tmuxSession}`);
+      if (String(result.job.tmuxSession).startsWith("headless-")) {
+        console.log(`mode:    headless (--no-tmux); use capture/status (no attach/send)`);
+        if (result.job.pid) console.log(`pid:     ${result.job.pid}`);
+      } else {
+        console.log(`attach:  ${attachHint(result.job.id)}`);
+      }
+      console.log(`capture: cursor-route capture ${result.job.id}`);
+    }
+    return;
+  }
+
+  if (cmd === "jobs") {
+    const limit = f.limit ? Number(f.limit) : config.jobsListLimit;
+    const jobs = listJobs(limit);
+    if (json) {
+      console.log(JSON.stringify(jobs, null, 2));
+    } else if (jobs.length === 0) {
+      console.log('No jobs yet. Try: cursor-route start "say hello" --worker grok');
+    } else {
+      for (const j of jobs) {
+        const age = j.startedAt || j.createdAt;
+        console.log(
+          `${j.id}  ${j.status.padEnd(10)}  ${j.worker.padEnd(10)}  ${age}  ${j.prompt.slice(0, 48).replace(/\n/g, " ")}`,
+        );
+      }
+    }
+    return;
+  }
+
+  if (cmd === "status") {
+    const id = pos[0];
+    if (!id) {
+      console.error("status requires <jobId>");
+      process.exit(2);
+    }
+    let job = readJob(id);
+    if (!job) {
+      console.error(`Job not found: ${id}`);
+      process.exit(1);
+    }
+    job = refreshStatus(job);
+    const alive = job.tmuxSession.startsWith("headless-")
+      ? Boolean(job.pid && (() => {
+          try {
+            process.kill(job!.pid!, 0);
+            return true;
+          } catch {
+            return false;
+          }
+        })())
+      : sessionExists(job.tmuxSession);
+    const view = { ...job, sessionAlive: alive };
+    if (json) console.log(JSON.stringify(view, null, 2));
+    else {
+      console.log(`${job.id}  ${job.status}  worker=${job.worker}  sessionAlive=${alive}`);
+      if (job.error) console.log(`error: ${job.error}`);
+    }
+    return;
+  }
+
+  if (cmd === "capture") {
+    const id = pos[0];
+    const lines = pos[1] ? Number(pos[1]) : 50;
+    if (!id) {
+      console.error("capture requires <jobId>");
+      process.exit(2);
+    }
+    const job = readJob(id);
+    if (!job) {
+      console.error(`Job not found: ${id}`);
+      process.exit(1);
+    }
+    if (!job.tmuxSession.startsWith("headless-") && sessionExists(job.tmuxSession)) {
+      const out = capturePane(job.tmuxSession, lines);
+      if (out.trim()) {
+        process.stdout.write(out.endsWith("\n") ? out : out + "\n");
+        return;
+      }
+    }
+    const logPath = jobPaths(id).log;
+    if (existsSync(logPath)) {
+      const log = readFileSync(logPath, "utf8");
+      const parts = log.split("\n");
+      console.log(parts.slice(-lines).join("\n"));
+      return;
+    }
+    console.error("No live session or log for this job");
+    process.exit(1);
+  }
+
+  if (cmd === "send") {
+    const id = pos[0];
+    const message = pos.slice(1).join(" ").trim();
+    if (!id || !message) {
+      console.error('send requires <jobId> "<message>"');
+      process.exit(2);
+    }
+    refuseSecrets(message, "to send");
+    const job = readJob(id);
+    if (!job) {
+      console.error(`Job not found: ${id}`);
+      process.exit(1);
+    }
+    if (job.tmuxSession.startsWith("headless-")) {
+      console.error("send is not supported for --no-tmux jobs");
+      process.exit(1);
+    }
+    if (!sendKeys(job.tmuxSession, message)) {
+      console.error(`Failed to send — is session alive? ${attachHint(id)}`);
+      process.exit(1);
+    }
+    console.log(`sent to ${id}`);
+    return;
+  }
+
+  if (cmd === "attach") {
+    const id = pos[0];
+    if (!id) {
+      console.error("attach requires <jobId>");
+      process.exit(2);
+    }
+    console.log(attachHint(id));
+    return;
+  }
+
+  if (cmd === "kill") {
+    const id = pos[0];
+    if (!id) {
+      console.error("kill requires <jobId>");
+      process.exit(2);
+    }
+    const r = killJob(id);
+    if (!r.ok) {
+      console.error(r.error);
+      process.exit(1);
+    }
+    console.log(`killed ${id}`);
+    return;
+  }
+
+  if (cmd === "sessions") {
+    const sessions = listManagedSessions();
+    if (json) console.log(JSON.stringify(sessions, null, 2));
+    else if (sessions.length === 0) console.log("No active cursor-route tmux sessions");
+    else sessions.forEach((s) => console.log(s));
+    return;
+  }
+
+  if (cmd === "clean") {
+    const days = f.days ? Number(f.days) : 7;
+    const n = cleanJobs(days);
+    console.log(`cleaned ${n} job(s) older than ${days}d`);
+    return;
+  }
+
+  console.error(`Unknown command: ${cmd}`);
+  usage(2);
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/src/config.ts

@@ -0,0 +1,32 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { defaultJobsDir } from "./runtime.ts";
+
+export type WorkerKind = "grok" | "claude-ds";
+export type Lane = "mid" | "hard";
+
+export const WORKERS: WorkerKind[] = ["grok", "claude-ds"];
+export const LANES: Lane[] = ["mid", "hard"];
+
+export const config = {
+  product: "cursor-route",
+  version: "0.1.1",
+  jobsDir: defaultJobsDir(),
+  tmuxPrefix: "cursor-route",
+  defaultWorker: "grok" as WorkerKind,
+  /** Lane → default worker (Cemini /route public core). */
+  laneWorkers: {
+    mid: "claude-ds" as WorkerKind,
+    hard: "grok" as WorkerKind,
+  },
+  jobsListLimit: 20,
+};
+
+export function sessionName(jobId: string): string {
+  return `${config.tmuxPrefix}-${jobId}`;
+}
+
+/** Home for docs only — not used as jobsDir. */
+export function productHomeHint(): string {
+  return join(process.env.HOME || homedir(), ".cursor-route");
+}