@mycadet/cli 0.0.1 → 0.12.6-dev.202610072225.d7acd73

package/src/lib/orphan-detection.ts

@@ -0,0 +1,222 @@
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+
+import {
+  getDaemonPidPath,
+  loadAllAssistantsAcrossEnvs,
+  type AssistantEntry,
+} from "./assistant-config.js";
+import { execOutput } from "./step-runner";
+
+export interface RemoteProcess {
+  pid: string;
+  ppid: string;
+  command: string;
+}
+
+const CADET_PROCESS_MARKER = /cadet|qdrant/;
+
+export function classifyProcess(command: string): string {
+  if (/qdrant/.test(command)) return "qdrant";
+  if (/cadet-gateway/.test(command)) return "gateway";
+  if (/cadet-daemon|[\\/]daemon[\\/]main/.test(command)) return "assistant";
+  if (/daemon\s+(start|restart)/.test(command)) return "assistant";
+  if (/(?:cadet)-cli|[\\/](?:cadet)(?:-cli)?\.exe/.test(command))
+    return "cadet";
+  // Exclude macOS desktop app processes — their path contains .app/Contents/MacOS/
+  // but they are not background service processes.
+  if (/\.app\/Contents\/MacOS\//.test(command)) return "unknown";
+  // Match cadet CLI commands (e.g. "cadet hatch", "cadet sleep") but NOT
+  // unrelated processes whose working directory or repo path happens to contain
+  // e.g. /Users/runner/work/mycadet/mycadet/... repo
+  // checkouts must not classify as the cadet CLI.
+  if (/(?:^|\/)cadet(?:\s|$)/.test(command)) return "cadet";
+  return "unknown";
+}
+
+/**
+ * True when the command line is a deliberate long-running interactive CLI
+ * session (e.g. a live `cadet tunnel` in someone's terminal). Such sessions
+ * have no PID-file registration, so `cadet clean` would otherwise kill them
+ * mid-session. The command line may be "bun /path/to/bin/cadet tunnel ...",
+ * so match the subcommand right after the cadet binary/script path (allowing
+ * only the known global flags in between; see GLOBAL_FLAGS in cli/src/index.ts).
+ * Later argv tokens (e.g. "cadet hatch --name logs") must not match.
+ *
+ * `detectOrphanedProcesses` consults this before classification so that
+ * service-like substrings in later argv (e.g. `cadet exec -it --service
+ * cadet-gateway -- /bin/sh`) cannot re-flag a live session, while
+ * `classifyProcess` stays a pure display label for `cadet ps`.
+ *
+ * Also spared: bare `cadet` (no subcommand launches the implicit TUI client
+ * via tryLaunchClient) and `cadet wake --foreground` (stays attached with
+ * logs in the terminal).
+ */
+export function isInteractiveCliSession(command: string): boolean {
+  const cadetToken =
+    /(?:^|[\\/])cadet(?:-cli)?(?:\.exe)?["']?(?:\s+--(?:no-color|plain))*/;
+  const interactiveSubcommand = new RegExp(
+    cadetToken.source +
+      String.raw`\s+(?:tunnel|events|logs|client|terminal|ssh|exec|message|workflows)\b`,
+  );
+  const implicitTuiClient = new RegExp(cadetToken.source + String.raw`\s*$`);
+  const foregroundWake = new RegExp(
+    cadetToken.source + String.raw`\s+wake\b(?:\s+\S+)*\s--foreground\b`,
+  );
+  return (
+    interactiveSubcommand.test(command) ||
+    implicitTuiClient.test(command) ||
+    foregroundWake.test(command)
+  );
+}
+
+export function parseRemotePs(output: string): RemoteProcess[] {
+  return output
+    .trim()
+    .split("\n")
+    .filter((line) => line.trim().length > 0)
+    .map((line) => {
+      const trimmed = line.trim();
+      const parts = trimmed.split(/\s+/);
+      const pid = parts[0];
+      const ppid = parts[1];
+      const command = parts.slice(2).join(" ");
+      return { pid, ppid, command };
+    });
+}
+
+export function readPidFile(pidFile: string): string | null {
+  if (!existsSync(pidFile)) return null;
+  const pid = readFileSync(pidFile, "utf-8").trim();
+  return pid || null;
+}
+
+export function isPidAlive(pid: string): boolean {
+  try {
+    process.kill(parseInt(pid, 10), 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export interface OrphanedProcess {
+  name: string;
+  pid: string;
+  source: string;
+}
+
+/**
+ * Collect PIDs that belong to a known assistant in any environment.
+ *
+ * For local entries this reads the daemon/gateway/qdrant/embed-worker PID
+ * files under each entry's `instanceDir`. For docker entries we include the
+ * `watcherPid` field when present (the file watcher runs as a host process,
+ * unlike the containers themselves). Other cloud topologies don't have
+ * host-side processes that show up in `ps ax`.
+ *
+ * This set is the basis for filtering the orphan list: if a running process
+ * matches a recorded PID for *any* env's assistant, it's not an orphan.
+ */
+export function getKnownPidsFromAssistants(
+  entries: AssistantEntry[],
+): Set<string> {
+  const pids = new Set<string>();
+  for (const entry of entries) {
+    if (entry.cloud === "local" && entry.resources) {
+      const legacyDir = join(entry.resources.instanceDir, ".cadet");
+      const candidates = [
+        getDaemonPidPath(entry.resources),
+        join(legacyDir, "gateway.pid"),
+        join(legacyDir, "workspace", "data", "qdrant", "qdrant.pid"),
+        join(legacyDir, "workspace", "embed-worker.pid"),
+      ];
+      for (const file of candidates) {
+        const pid = readPidFile(file);
+        if (pid) pids.add(pid);
+      }
+    }
+    if (typeof entry.watcherPid === "number") {
+      pids.add(String(entry.watcherPid));
+    }
+  }
+  return pids;
+}
+
+export interface DetectOrphansOptions {
+  /**
+   * Set of PIDs to treat as known and exclude from the orphan list. When
+   * omitted, defaults to the union of every env's recorded assistant PIDs
+   * via {@link loadAllAssistantsAcrossEnvs} +
+   * {@link getKnownPidsFromAssistants}. Tests can inject an explicit set to
+   * avoid touching the real on-host lockfiles.
+   */
+  excludePids?: Set<string>;
+  platform?: NodeJS.Platform;
+}
+
+const WINDOWS_PROCESS_LIST_SCRIPT =
+  'Get-CimInstance Win32_Process | ForEach-Object { "$($_.ProcessId) $($_.ParentProcessId) $($_.CommandLine)" }';
+
+export function processTableCommand(hostPlatform: NodeJS.Platform): {
+  command: string;
+  args: string[];
+} {
+  if (hostPlatform === "win32") {
+    return {
+      command: "powershell.exe",
+      args: [
+        "-NoProfile",
+        "-NonInteractive",
+        "-Command",
+        WINDOWS_PROCESS_LIST_SCRIPT,
+      ],
+    };
+  }
+  return { command: "ps", args: ["ax", "-o", "pid=,ppid=,args="] };
+}
+
+export async function detectOrphanedProcesses(
+  options: DetectOrphansOptions = {},
+): Promise<OrphanedProcess[]> {
+  const results: OrphanedProcess[] = [];
+  const seenPids = new Set<string>();
+
+  // PIDs that belong to a known assistant in *any* environment are not
+  // orphans. Without this filter, running `cadet ps` from an env that has
+  // no assistants — or `cadet clean` from any env — would flag (or kill)
+  // another env's healthy services as orphans.
+  const knownPids =
+    options.excludePids ??
+    getKnownPidsFromAssistants(loadAllAssistantsAcrossEnvs());
+
+  // Process table scan — discover orphaned processes by scanning the OS
+  // process table rather than reading PID files from the workspace.
+  try {
+    const table = processTableCommand(options.platform ?? process.platform);
+    const output = await execOutput(table.command, table.args, {
+      timeoutMs: 5_000,
+    });
+    const procs = parseRemotePs(output);
+    const ownPid = String(process.pid);
+
+    for (const p of procs) {
+      if (p.pid === ownPid || seenPids.has(p.pid)) continue;
+      if (knownPids.has(p.pid)) continue;
+      if (!CADET_PROCESS_MARKER.test(p.command)) continue;
+      // Live interactive sessions are spared before classification so that
+      // service substrings in their argv cannot mark them as orphans.
+      if (isInteractiveCliSession(p.command)) {
+        continue;
+      }
+      const type = classifyProcess(p.command);
+      if (type === "unknown") continue;
+      results.push({ name: type, pid: p.pid, source: "process table" });
+      seenPids.add(p.pid);
+    }
+  } catch {
+    // grep exits 1 when no matches found — ignore
+  }
+
+  return results;
+}

package/src/lib/pair.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+
+import { REMOTE_WEB_PAIRING_CODE_TTL_MS } from "@mycadet/service-contracts/remote-web-pairing";
+
+import { formatWebApproveFailure, parseGatewayErrorCode } from "./pair.js";
+
+const GATEWAY_URL = "http://127.0.0.1:20100";
+// Callers pass formatAssistantReference() output: display name plus stable ID.
+const ASSISTANT_REFERENCE = "example-assistant (asst_0123456789abcdef)";
+const ENV_NAME = "local";
+const TTL_NOTE = `expire after ${Math.round(REMOTE_WEB_PAIRING_CODE_TTL_MS / 60_000)} minutes`;
+
+describe("formatWebApproveFailure", () => {
+  test("INVALID_USER_CODE names the gateway, assistant reference, and environment", () => {
+    const message = formatWebApproveFailure(
+      GATEWAY_URL,
+      ASSISTANT_REFERENCE,
+      ENV_NAME,
+      "INVALID_USER_CODE",
+    );
+    expect(message).not.toBeNull();
+    expect(message).toContain(`No such pairing code on ${GATEWAY_URL}`);
+    expect(message).toContain(`assistant "${ASSISTANT_REFERENCE}"`);
+    expect(message).toContain("asst_0123456789abcdef");
+    expect(message).toContain(`environment "${ENV_NAME}"`);
+  });
+
+  test("INVALID_USER_CODE includes the TTL note and the cross-environment hint", () => {
+    const message = formatWebApproveFailure(
+      GATEWAY_URL,
+      ASSISTANT_REFERENCE,
+      ENV_NAME,
+      "INVALID_USER_CODE",
+    );
+    expect(message).toContain(TTL_NOTE);
+    expect(message).toContain("single-use");
+    expect(message).toContain("different assistant or environment");
+    expect(message).toContain("CADET_ENVIRONMENT");
+  });
+
+  test("EXPIRED_USER_CODE gets the same diagnostic with an expiry lead line", () => {
+    const message = formatWebApproveFailure(
+      GATEWAY_URL,
+      ASSISTANT_REFERENCE,
+      ENV_NAME,
+      "EXPIRED_USER_CODE",
+    );
+    expect(message).toContain(`Pairing code expired on ${GATEWAY_URL}`);
+    expect(message).toContain(TTL_NOTE);
+    expect(message).toContain("CADET_ENVIRONMENT");
+  });
+
+  test("unknown error codes return null so callers fall back to the generic HTTP error", () => {
+    for (const code of ["RATE_LIMITED", "BAD_REQUEST", "", null]) {
+      expect(
+        formatWebApproveFailure(
+          GATEWAY_URL,
+          ASSISTANT_REFERENCE,
+          ENV_NAME,
+          code,
+        ),
+      ).toBeNull();
+    }
+  });
+});
+
+describe("parseGatewayErrorCode", () => {
+  test("extracts the code from a gateway error envelope", () => {
+    const body = JSON.stringify({
+      error: { code: "INVALID_USER_CODE", message: "invalid pairing code" },
+    });
+    expect(parseGatewayErrorCode(body)).toBe("INVALID_USER_CODE");
+  });
+
+  test("returns null for non-JSON bodies", () => {
+    expect(parseGatewayErrorCode("Not Found")).toBeNull();
+    expect(parseGatewayErrorCode("")).toBeNull();
+  });
+
+  test("returns null when the envelope carries no string code", () => {
+    expect(parseGatewayErrorCode(JSON.stringify({ error: {} }))).toBeNull();
+    expect(
+      parseGatewayErrorCode(JSON.stringify({ error: { code: 404 } })),
+    ).toBeNull();
+    expect(parseGatewayErrorCode(JSON.stringify({}))).toBeNull();
+  });
+});

package/src/lib/pair.ts

@@ -0,0 +1,55 @@
+/**
+ * Pure helpers for `cadet pair`'s remote-web approval flow.
+ *
+ * Pairing challenge stores are in-memory per gateway process, so approving a
+ * code against a different assistant or environment than the one that served
+ * the pair page looks identical to a typo'd or expired code. These helpers
+ * turn the gateway's error envelope into a diagnostic that names the gateway
+ * actually asked.
+ */
+
+import { REMOTE_WEB_PAIRING_CODE_TTL_MS } from "@mycadet/service-contracts/remote-web-pairing";
+
+const CODE_TTL_MINUTES = Math.round(REMOTE_WEB_PAIRING_CODE_TTL_MS / 60_000);
+
+/**
+ * Extract the `error.code` from a gateway JSON error envelope
+ * (`{"error":{"code":...,"message":...}}`). Returns null when the body is not
+ * JSON or carries no string code.
+ */
+export function parseGatewayErrorCode(body: string): string | null {
+  try {
+    const parsed = JSON.parse(body) as { error?: { code?: unknown } };
+    return typeof parsed.error?.code === "string" ? parsed.error.code : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Diagnostic for a failed `--web-approve`, naming which gateway rejected the
+ * code and hinting at cross-assistant / cross-environment mismatches. Returns
+ * null for error codes this helper doesn't recognize, so the caller falls
+ * back to the generic HTTP error text. `assistantReference` should carry the
+ * stable assistant ID (see `formatAssistantReference`); `envName` should be
+ * the effective environment actually used (see `getCurrentEnvironment`).
+ */
+export function formatWebApproveFailure(
+  gatewayUrl: string,
+  assistantReference: string,
+  envName: string,
+  errorCode: string | null,
+): string | null {
+  if (errorCode !== "INVALID_USER_CODE" && errorCode !== "EXPIRED_USER_CODE") {
+    return null;
+  }
+  const rejection =
+    errorCode === "EXPIRED_USER_CODE"
+      ? "Pairing code expired on"
+      : "No such pairing code on";
+  return [
+    `${rejection} ${gatewayUrl} (assistant "${assistantReference}", environment "${envName}").`,
+    `Codes are minted by the gateway that serves the pair page, expire after ${CODE_TTL_MINUTES} minutes, and are single-use.`,
+    "If the pair page came from a different assistant or environment (e.g. the desktop app's), re-run with that environment's CADET_ENVIRONMENT and that assistant's name.",
+  ].join("\n");
+}

package/src/lib/pgrep.ts

@@ -0,0 +1,32 @@
+import { execOutput } from "./step-runner";
+import { executableName, parseTasklistCsv } from "./process.js";
+
+const PGREP_TIMEOUT_MS = 5_000;
+
+export async function pgrepExact(
+  name: string,
+  hostPlatform: NodeJS.Platform = process.platform,
+): Promise<string[]> {
+  try {
+    const command = hostPlatform === "win32" ? "tasklist.exe" : "pgrep";
+    const args =
+      hostPlatform === "win32"
+        ? [
+            "/FI",
+            `IMAGENAME eq ${executableName(name, hostPlatform)}`,
+            "/FO",
+            "CSV",
+            "/NH",
+          ]
+        : ["-x", name];
+    const output = await execOutput(command, args, {
+      timeoutMs: PGREP_TIMEOUT_MS,
+    });
+    if (hostPlatform === "win32") {
+      return parseTasklistCsv(output).map(({ pid }) => String(pid));
+    }
+    return output.trim().split("\n").filter(Boolean);
+  } catch {
+    return [];
+  }
+}