@bli-cockpit/cli 0.1.8 → 0.1.11

package/dist/autostart.js

@@ -0,0 +1,197 @@
+import { mkdir, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths } from "./local-state.js";
+/** launchd LaunchAgent label; matches docs/runbooks/cockpit-launchd-sync.md. */
+export const AUTOSTART_LABEL = "com.bli.cockpit.sync";
+const DEFAULT_INTERVAL_SECONDS = 1800;
+const UNSUPPORTED_MESSAGE = "macOS-only for now; see docs/runbooks/cockpit-launchd-sync.md";
+function plistPathFor(homeDir) {
+    return path.join(homeDir, "Library", "LaunchAgents", `${AUTOSTART_LABEL}.plist`);
+}
+function unsupportedResult(homeDir) {
+    return {
+        status: "unsupported",
+        label: AUTOSTART_LABEL,
+        plist_path: plistPathFor(homeDir ?? os.homedir()),
+        message: UNSUPPORTED_MESSAGE,
+    };
+}
+/**
+ * Installs (or refreshes) the launchd LaunchAgent that keeps `cockpit sync`
+ * running at login and every `intervalSeconds`. Mirrors the plist in
+ * docs/runbooks/cockpit-launchd-sync.md exactly, but writes resolved absolute
+ * log paths (launchd does not expand `$HOME`). The unload before load makes the
+ * install idempotent — re-running picks up a changed repo/url/interval.
+ */
+export async function installAutostartAgent(options) {
+    const platform = options.platform ?? process.platform;
+    if (platform !== "darwin")
+        return unsupportedResult(options.homeDir);
+    const homeDir = options.homeDir ?? os.homedir();
+    const workDir = path.resolve(options.repoRoot ?? process.cwd());
+    const dashboardUrl = options.dashboardUrl ?? DEFAULT_DASHBOARD_URL;
+    const intervalSeconds = options.intervalSeconds ?? DEFAULT_INTERVAL_SECONDS;
+    const paths = getCollectorRuntimePaths(homeDir);
+    const plistPath = plistPathFor(homeDir);
+    const stdoutPath = path.join(paths.state_dir, "sync.log");
+    const stderrPath = path.join(paths.state_dir, "sync.err.log");
+    // launchd will not reliably watch a path that does not exist at load time, so
+    // only feed it the transcript dirs that are present right now. A missing dir
+    // is fine — the StartInterval floor still covers it.
+    const watchPaths = await existingWatchPaths(homeDir);
+    await mkdir(path.dirname(plistPath), { recursive: true });
+    await mkdir(paths.state_dir, { recursive: true });
+    await writeFile(plistPath, renderPlist({
+        workDir,
+        dashboardUrl,
+        intervalSeconds,
+        stdoutPath,
+        stderrPath,
+        watchPaths,
+    }), "utf8");
+    // Unload first so a changed plist is actually picked up; a not-yet-loaded
+    // agent makes unload fail harmlessly, so the error is ignored.
+    await options.exec("launchctl", ["unload", plistPath]).catch(() => undefined);
+    const load = await options.exec("launchctl", ["load", plistPath]);
+    const loaded = load.code === 0;
+    return {
+        status: "installed",
+        label: AUTOSTART_LABEL,
+        plist_path: plistPath,
+        loaded,
+        interval_seconds: intervalSeconds,
+        work_dir: workDir,
+        dashboard_url: dashboardUrl,
+        ...(loaded
+            ? {}
+            : {
+                message: `launchctl load exited ${load.code}: ${load.stderr.trim() || "unknown error"}`,
+            }),
+    };
+}
+/**
+ * Removes the LaunchAgent. Reports `absent` when there was nothing to remove so
+ * the command is safe to run repeatedly.
+ */
+export async function uninstallAutostartAgent(options) {
+    const platform = options.platform ?? process.platform;
+    if (platform !== "darwin")
+        return unsupportedResult(options.homeDir);
+    const homeDir = options.homeDir ?? os.homedir();
+    const plistPath = plistPathFor(homeDir);
+    if (!(await fileExists(plistPath))) {
+        return { status: "absent", label: AUTOSTART_LABEL, plist_path: plistPath };
+    }
+    await options.exec("launchctl", ["unload", plistPath]).catch(() => undefined);
+    await rm(plistPath, { force: true });
+    return { status: "uninstalled", label: AUTOSTART_LABEL, plist_path: plistPath };
+}
+/**
+ * Reports whether the agent is installed and loaded. `absent` when no plist
+ * exists; otherwise `launchctl list <label>` exit code distinguishes `loaded`
+ * (0) from `not_loaded` (non-zero).
+ */
+export async function autostartStatus(options) {
+    const platform = options.platform ?? process.platform;
+    if (platform !== "darwin")
+        return unsupportedResult(options.homeDir);
+    const homeDir = options.homeDir ?? os.homedir();
+    const plistPath = plistPathFor(homeDir);
+    if (!(await fileExists(plistPath))) {
+        return { status: "absent", label: AUTOSTART_LABEL, plist_path: plistPath };
+    }
+    const list = await options.exec("launchctl", ["list", AUTOSTART_LABEL]);
+    return {
+        status: list.code === 0 ? "loaded" : "not_loaded",
+        label: AUTOSTART_LABEL,
+        plist_path: plistPath,
+    };
+}
+/**
+ * The transcript directories whose changes should re-trigger a sync, in the
+ * order they appear in WatchPaths. Resolved from the same homeDir as the plist
+ * and log paths so `--home` redirects them together.
+ */
+function watchPathCandidates(homeDir) {
+    return [
+        path.join(homeDir, ".claude", "projects"),
+        path.join(homeDir, ".codex", "sessions"),
+    ];
+}
+/** Subset of the transcript dirs that exist now (see the WatchPaths comment). */
+async function existingWatchPaths(homeDir) {
+    const candidates = watchPathCandidates(homeDir);
+    const present = await Promise.all(candidates.map((dir) => fileExists(dir)));
+    return candidates.filter((_, i) => present[i]);
+}
+function renderPlist(options) {
+    // The repo path is shell-quoted because it lands inside a `/bin/zsh -lc "…"`
+    // command string; the whole command is then XML-escaped for the <string>.
+    const command = `npm exec --yes --package=@bli-cockpit/cli@latest -- cockpit sync --repo ${shellQuote(options.workDir)} --dashboard-url ${shellQuote(options.dashboardUrl)} --json`;
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+        '<plist version="1.0">',
+        "<dict>",
+        "  <key>Label</key>",
+        `  <string>${xmlEscape(AUTOSTART_LABEL)}</string>`,
+        "  <key>ProgramArguments</key>",
+        "  <array>",
+        "    <string>/bin/zsh</string>",
+        "    <string>-lc</string>",
+        `    <string>${xmlEscape(command)}</string>`,
+        "  </array>",
+        "  <key>StartInterval</key>",
+        `  <integer>${options.intervalSeconds}</integer>`,
+        "  <key>RunAtLoad</key>",
+        "  <true/>",
+        // WatchPaths makes a transcript write fire `cockpit sync` within seconds, so
+        // captures land near-real-time; StartInterval above is the safety-net floor.
+        // It fires often, but launchd single-flights the job, sync holds its own
+        // lock, and growing-transcript re-upload is damped — so cost stays bounded
+        // and no extra debounce is needed.
+        ...watchPathsBlock(options.watchPaths),
+        "  <key>EnvironmentVariables</key>",
+        "  <dict>",
+        "    <key>PATH</key>",
+        "    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>",
+        "  </dict>",
+        "  <key>StandardOutPath</key>",
+        `  <string>${xmlEscape(options.stdoutPath)}</string>`,
+        "  <key>StandardErrorPath</key>",
+        `  <string>${xmlEscape(options.stderrPath)}</string>`,
+        "</dict>",
+        "</plist>",
+        "",
+    ].join("\n");
+}
+/**
+ * Renders the `<key>WatchPaths</key><array>…</array>` lines, or nothing when no
+ * transcript dir exists yet (an empty array would tell launchd to watch
+ * everything-and-nothing; omitting the key leaves StartInterval as the floor).
+ */
+function watchPathsBlock(watchPaths) {
+    if (watchPaths.length === 0)
+        return [];
+    return [
+        "  <key>WatchPaths</key>",
+        "  <array>",
+        ...watchPaths.map((dir) => `    <string>${xmlEscape(dir)}</string>`),
+        "  </array>",
+    ];
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function xmlEscape(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+async function fileExists(filePath) {
+    return stat(filePath).then(() => true, () => false);
+}

package/dist/commands/local-args.js

@@ -0,0 +1,383 @@
+// CLI argument parsing for the local cockpit collector. Split out of
+// commands/local.ts so the command runners read as a table of contents and
+// the parser (pure, independently testable) can change at its own rate.
+//
+// Behavior-preserving extraction: functions moved verbatim, no logic change.
+import { DEFAULT_DASHBOARD_URL } from "../local-state.js";
+export function parseLocalArgs(argv) {
+    const command = argv[0];
+    switch (command) {
+        case "onboard":
+            return parseOnboardArgs(argv.slice(1));
+        case "install":
+            return parseInstallArgs(argv.slice(1));
+        case "login":
+        case "pair":
+            return parseLoginArgs(argv.slice(1));
+        case "logout":
+            return parseLogoutArgs(argv.slice(1));
+        case "start":
+            return parseStartArgs(argv.slice(1));
+        case "sync":
+            return parseSyncArgs(argv.slice(1));
+        case "status":
+            return parseStatusArgs(argv.slice(1));
+        case "sessions":
+            return parseSessionsArgs(argv.slice(1));
+        case "serve":
+            return parseServeArgs(argv.slice(1));
+        case "autostart":
+            return parseAutostartArgs(argv.slice(1));
+        default:
+            throw new Error(`Unknown local command: ${command ?? ""}`);
+    }
+}
+function parseOnboardArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [
+            "--home",
+            "--repo",
+            "--dashboard-url",
+            "--email",
+            "--device-name",
+            "--ticket",
+            "--branch",
+            "--json",
+            "--poll-interval-ms",
+            "--timeout-ms",
+            "--max-depth",
+            "--max-repos",
+        ],
+        valueFlags: [
+            "--home",
+            "--repo",
+            "--dashboard-url",
+            "--email",
+            "--device-name",
+            "--ticket",
+            "--branch",
+            "--poll-interval-ms",
+            "--timeout-ms",
+            "--max-depth",
+            "--max-repos",
+        ],
+    });
+    assertNoPositionals(values.positionals, "onboard");
+    return {
+        kind: "onboard",
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        repoRoot: optionalNonEmpty(values.flags.get("--repo")),
+        dashboardUrl: normalizeUrl(values.flags.get("--dashboard-url") ?? DEFAULT_DASHBOARD_URL),
+        claimedOwnerEmail: optionalEmail(values.flags.get("--email")),
+        deviceName: optionalNonEmpty(values.flags.get("--device-name")),
+        activeTicketId: optionalNonEmpty(values.flags.get("--ticket")),
+        branch: optionalNonEmpty(values.flags.get("--branch")),
+        json: values.booleans.has("--json"),
+        pollIntervalMs: optionalPositiveInteger(values.flags.get("--poll-interval-ms"), "--poll-interval-ms"),
+        timeoutMs: optionalPositiveInteger(values.flags.get("--timeout-ms"), "--timeout-ms"),
+        maxDepth: optionalPositiveInteger(values.flags.get("--max-depth"), "--max-depth"),
+        maxRepos: optionalPositiveInteger(values.flags.get("--max-repos"), "--max-repos"),
+    };
+}
+function parseInstallArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [
+            "--home",
+            "--repo",
+            "--dashboard-url",
+            "--supabase-url",
+            "--json",
+        ],
+        valueFlags: ["--home", "--repo", "--dashboard-url", "--supabase-url"],
+    });
+    assertNoPositionals(values.positionals, "install");
+    return {
+        kind: "install",
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        repoRoot: optionalNonEmpty(values.flags.get("--repo")),
+        dashboardUrl: normalizeUrl(values.flags.get("--dashboard-url") ?? DEFAULT_DASHBOARD_URL),
+        supabaseUrl: optionalNonEmpty(values.flags.get("--supabase-url")),
+        json: values.booleans.has("--json"),
+    };
+}
+function parseLoginArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [
+            "--home",
+            "--dashboard-url",
+            "--email",
+            "--device-name",
+            "--json",
+            "--poll-interval-ms",
+            "--timeout-ms",
+        ],
+        valueFlags: [
+            "--home",
+            "--dashboard-url",
+            "--email",
+            "--device-name",
+            "--poll-interval-ms",
+            "--timeout-ms",
+        ],
+    });
+    assertNoPositionals(values.positionals, "login");
+    return {
+        kind: "login",
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        claimedOwnerEmail: optionalEmail(values.flags.get("--email")),
+        deviceName: optionalNonEmpty(values.flags.get("--device-name")),
+        json: values.booleans.has("--json"),
+        pollIntervalMs: optionalPositiveInteger(values.flags.get("--poll-interval-ms"), "--poll-interval-ms"),
+        timeoutMs: optionalPositiveInteger(values.flags.get("--timeout-ms"), "--timeout-ms"),
+    };
+}
+function parseLogoutArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: ["--home", "--json"],
+        valueFlags: ["--home"],
+    });
+    assertNoPositionals(values.positionals, "logout");
+    return {
+        kind: "logout",
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        json: values.booleans.has("--json"),
+    };
+}
+function parseStartArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [
+            "--home",
+            "--repo",
+            "--branch",
+            "--ticket",
+            "--operator-id",
+            "--session-id",
+            "--json",
+            "--max-depth",
+            "--max-repos",
+        ],
+        valueFlags: [
+            "--home",
+            "--repo",
+            "--branch",
+            "--ticket",
+            "--operator-id",
+            "--session-id",
+            "--max-depth",
+            "--max-repos",
+        ],
+    });
+    assertNoPositionals(values.positionals, "start");
+    return {
+        kind: "start",
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        repoRoot: optionalNonEmpty(values.flags.get("--repo")),
+        branch: optionalNonEmpty(values.flags.get("--branch")),
+        activeTicketId: optionalNonEmpty(values.flags.get("--ticket")),
+        operatorId: optionalNonEmpty(values.flags.get("--operator-id")),
+        sessionId: optionalNonEmpty(values.flags.get("--session-id")),
+        json: values.booleans.has("--json"),
+        maxDepth: optionalPositiveInteger(values.flags.get("--max-depth"), "--max-depth"),
+        maxRepos: optionalPositiveInteger(values.flags.get("--max-repos"), "--max-repos"),
+    };
+}
+function parseSyncArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: ["--home", "--repo", "--dashboard-url", "--json", "--max-depth", "--max-repos"],
+        valueFlags: ["--home", "--repo", "--dashboard-url", "--max-depth", "--max-repos"],
+    });
+    assertNoPositionals(values.positionals, "sync");
+    return {
+        kind: "sync",
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        repoRoot: optionalNonEmpty(values.flags.get("--repo")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        json: values.booleans.has("--json"),
+        maxDepth: optionalPositiveInteger(values.flags.get("--max-depth"), "--max-depth"),
+        maxRepos: optionalPositiveInteger(values.flags.get("--max-repos"), "--max-repos"),
+    };
+}
+function parseStatusArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: ["--home", "--repo", "--json", "--max-depth", "--max-repos"],
+        valueFlags: ["--home", "--repo", "--max-depth", "--max-repos"],
+    });
+    assertNoPositionals(values.positionals, "status");
+    return {
+        kind: "status",
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        repoRoot: optionalNonEmpty(values.flags.get("--repo")),
+        json: values.booleans.has("--json"),
+        maxDepth: optionalPositiveInteger(values.flags.get("--max-depth"), "--max-depth"),
+        maxRepos: optionalPositiveInteger(values.flags.get("--max-repos"), "--max-repos"),
+    };
+}
+function parseSessionsArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: ["--home", "--repo", "--source", "--json", "--max-depth", "--max-repos"],
+        valueFlags: ["--home", "--repo", "--source", "--max-depth", "--max-repos"],
+    });
+    assertNoPositionals(values.positionals, "sessions");
+    const source = values.flags.get("--source");
+    if (source !== undefined && source !== "codex" && source !== "claude") {
+        throw new Error("--source must be 'codex' or 'claude'.");
+    }
+    return {
+        kind: "sessions",
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        repoRoot: optionalNonEmpty(values.flags.get("--repo")),
+        source,
+        json: values.booleans.has("--json"),
+        maxDepth: optionalPositiveInteger(values.flags.get("--max-depth"), "--max-depth"),
+        maxRepos: optionalPositiveInteger(values.flags.get("--max-repos"), "--max-repos"),
+    };
+}
+function parseServeArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: ["--home", "--repo", "--port"],
+        valueFlags: ["--home", "--repo", "--port"],
+    });
+    assertNoPositionals(values.positionals, "serve");
+    const port = Number(values.flags.get("--port") ?? "4174");
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error("--port must be a TCP port between 1 and 65535.");
+    }
+    return {
+        kind: "serve",
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        repoRoot: optionalNonEmpty(values.flags.get("--repo")),
+        port,
+    };
+}
+function parseAutostartArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [
+            "--home",
+            "--repo",
+            "--dashboard-url",
+            "--interval-seconds",
+            "--json",
+        ],
+        valueFlags: ["--home", "--repo", "--dashboard-url", "--interval-seconds"],
+    });
+    if (values.positionals.length > 1) {
+        throw new Error("autostart accepts at most one action (install|uninstall|status).");
+    }
+    const action = values.positionals[0] ?? "install";
+    if (action !== "install" && action !== "uninstall" && action !== "status") {
+        throw new Error("autostart action must be install, uninstall, or status.");
+    }
+    return {
+        kind: "autostart",
+        action,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        repoRoot: optionalNonEmpty(values.flags.get("--repo")),
+        dashboardUrl: normalizeUrl(values.flags.get("--dashboard-url") ?? DEFAULT_DASHBOARD_URL),
+        intervalSeconds: optionalPositiveInteger(values.flags.get("--interval-seconds"), "--interval-seconds") ?? 1800,
+        json: values.booleans.has("--json"),
+    };
+}
+function parseNamedArgs(args, options) {
+    const allowed = new Set(options.allowedFlags);
+    const valueFlags = new Set(options.valueFlags);
+    const flags = new Map();
+    const booleans = new Set();
+    const positionals = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index] ?? "";
+        rejectServiceRoleLikeArgument(arg);
+        if (!arg.startsWith("--")) {
+            positionals.push(arg);
+            continue;
+        }
+        const [flag, inlineValue] = arg.split("=", 2);
+        if (!allowed.has(flag))
+            throw new Error(`Unknown flag: ${flag}`);
+        if (valueFlags.has(flag)) {
+            const value = inlineValue ?? args[index + 1];
+            if (!value || value.startsWith("--")) {
+                throw new Error(`${flag} requires a value.`);
+            }
+            rejectServiceRoleLikeArgument(value);
+            flags.set(flag, value);
+            if (inlineValue === undefined)
+                index += 1;
+        }
+        else {
+            if (inlineValue !== undefined)
+                throw new Error(`${flag} does not accept a value.`);
+            booleans.add(flag);
+        }
+    }
+    return { flags, booleans, positionals };
+}
+function assertNoPositionals(positionals, command) {
+    if (positionals.length > 0) {
+        throw new Error(`${command} does not accept positional arguments.`);
+    }
+}
+function optionalNonEmpty(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+function optionalUrl(value) {
+    return value === undefined ? undefined : normalizeUrl(value);
+}
+function optionalEmail(value) {
+    const trimmed = value?.trim().toLowerCase();
+    if (!trimmed)
+        return undefined;
+    if (!trimmed.includes("@")) {
+        throw new Error("--email must be a valid email address.");
+    }
+    return trimmed;
+}
+function optionalPositiveInteger(value, flag) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        throw new Error(`${flag} must be a positive integer.`);
+    }
+    return parsed;
+}
+export function normalizeUrl(value) {
+    const trimmed = value.trim().replace(/\/+$/, "");
+    if (!trimmed)
+        throw new Error("URL value cannot be empty.");
+    return trimmed;
+}
+function rejectServiceRoleLikeArgument(value) {
+    if (!looksLikeServiceRoleSecret(value))
+        return;
+    throw new Error("Service-role credentials are not accepted by local collector commands.");
+}
+function looksLikeServiceRoleSecret(value) {
+    if (serviceCredentialNamePattern().test(value))
+        return true;
+    const parts = value.split(".");
+    if (parts.length !== 3)
+        return false;
+    try {
+        const payload = Buffer.from(base64UrlToBase64(parts[1] ?? ""), "base64").toString("utf8");
+        return serviceCredentialPayloadPattern().test(payload);
+    }
+    catch {
+        return false;
+    }
+}
+function serviceCredentialNamePattern() {
+    return new RegExp([
+        ["SUPABASE", "SERVICE", "ROLE", "KEY"].join("[_-]?"),
+        ["service", "role"].join("[_-]?"),
+    ].join("|"), "i");
+}
+function serviceCredentialPayloadPattern() {
+    const privilegedRole = ["service", "role"].join("_");
+    return new RegExp(`"role"\\s*:\\s*"${privilegedRole}"`);
+}
+function base64UrlToBase64(value) {
+    const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+    return `${normalized}${"=".repeat((4 - (normalized.length % 4)) % 4)}`;
+}