@bli-cockpit/cli 0.1.8 → 0.1.9

package/dist/autostart.js

@@ -0,0 +1,154 @@
+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");
+    await mkdir(path.dirname(plistPath), { recursive: true });
+    await mkdir(paths.state_dir, { recursive: true });
+    await writeFile(plistPath, renderPlist({
+        workDir,
+        dashboardUrl,
+        intervalSeconds,
+        stdoutPath,
+        stderrPath,
+    }), "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,
+    };
+}
+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/>",
+        "  <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");
+}
+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.js

@@ -1,6 +1,8 @@
+import { execFile } from "node:child_process";
 import os from "node:os";
 import path from "node:path";
 import { createCollectorServer } from "../server.js";
+import { autostartStatus, installAutostartAgent, uninstallAutostartAgent, } from "../autostart.js";
 import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, inspectLocalCollectorStatus, installLocalCollector, logoutLocalCollector, pairLocalCollector, readLocalCollectorSessionFile, readLocalSessionReference, startLocalWorkContext, } from "../local-state.js";
 import { LocalUploadBlockedError, postCodexSessionReport, syncLocalAmbientEnvelope, } from "../upload.js";
 import { scanAndAttributeCodexSessions, } from "../adapters/codex-attribution.js";
@@ -21,6 +23,7 @@ export const rootCommandNames = new Set([
     "status",
     "sessions",
     "serve",
+    "autostart",
 ]);
 export async function runLocalCockpitCli(argv, io = defaultIo()) {
     if (isLocalHelpRequest(argv)) {
@@ -57,6 +60,8 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
                 return await runSessions(command, io);
             case "serve":
                 return await runServe(command, io);
+            case "autostart":
+                return await runAutostart(command, io);
         }
     }
     catch (error) {
@@ -78,6 +83,7 @@ export function localCommandHelp(command) {
         "  cockpit status [--repo <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit sessions [--source codex|claude] [--repo <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit serve [--port <port>] [--repo <path>]",
+        "  cockpit autostart [install|uninstall|status] [--repo <path>] [--dashboard-url <url>] [--interval-seconds <n>] [--json]",
     ].join("\n");
 }
 function localSubcommandHelp(command) {
@@ -169,6 +175,17 @@ function localSubcommandHelp(command) {
                 "Starts the local collector HTTP status server.",
             ],
         ],
+        [
+            "autostart",
+            [
+                "Usage: cockpit autostart [install|uninstall|status] [--repo <path>] [--dashboard-url <url>] [--interval-seconds <n>] [--json]",
+                "",
+                "Installs a macOS launchd LaunchAgent that runs `cockpit sync` at login and",
+                "every 30 min (default), surviving reboots — so machines never drift to Stale.",
+                "Action defaults to `install`. `--repo` is the parent work folder to sync.",
+                "macOS-only for now; see docs/runbooks/cockpit-launchd-sync.md.",
+            ],
+        ],
     ]);
     return (helpByCommand.get(command) ?? [localCommandHelp()]).join("\n");
 }
@@ -200,6 +217,8 @@ function parseLocalArgs(argv) {
             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 ?? ""}`);
     }
@@ -422,6 +441,34 @@ function parseServeArgs(args) {
         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);
@@ -473,17 +520,14 @@ function isInteractiveStdin(io) {
     return Boolean(io.stdin.isTTY);
 }
 /**
- * Reads one line from stdin so `cockpit onboard` (no flags) can ask for the
- * dashboard email instead of forcing a `--email` flag. Only called when stdin
- * is a TTY and we're not in --json mode, so headless / piped / spawned runs
- * never block on input — they keep the existing behaviour (email optional; the
- * approving admin's account owns the device). An empty answer or a non-email
- * skips rather than failing, matching `optionalEmail`'s leniency.
+ * Reads one line from stdin after writing a prompt. Shared by the onboard email
+ * prompt and the autostart prompt; callers gate on `isInteractiveStdin` first so
+ * headless / piped / spawned runs never block on input.
  */
-async function promptOnboardEmail(io) {
-    io.stdout.write("Dashboard email (press enter to skip): ");
+async function readLine(io, prompt) {
+    io.stdout.write(prompt);
     io.stdin.setEncoding("utf8");
-    const raw = await new Promise((resolve) => {
+    return new Promise((resolve) => {
         const onData = (chunk) => {
             io.stdin.removeListener("data", onData);
             io.stdin.pause();
@@ -492,6 +536,15 @@ async function promptOnboardEmail(io) {
         io.stdin.resume();
         io.stdin.on("data", onData);
     });
+}
+/**
+ * Asks for the dashboard email so `cockpit onboard` (no flags) need not force a
+ * `--email`. Only called when stdin is a TTY and not in --json mode. An empty
+ * answer or a non-email skips rather than failing, matching `optionalEmail`'s
+ * leniency (the approving admin's account then owns the device).
+ */
+async function promptOnboardEmail(io) {
+    const raw = await readLine(io, "Dashboard email (press enter to skip): ");
     const answer = raw.trim().toLowerCase();
     if (!answer)
         return undefined;
@@ -501,6 +554,38 @@ async function promptOnboardEmail(io) {
     }
     return answer;
 }
+/**
+ * After a successful onboard, offers to install the launchd autostart agent so a
+ * Mac mini keeps syncing without anyone re-running cockpit — this is the fix for
+ * interns drifting to Stale. Only in an interactive, non-JSON run with a real
+ * exec runner (`io.exec`): headless / piped / spawned onboards and tests that
+ * pass no exec skip it entirely. Declining leaves onboarding's success untouched.
+ */
+async function maybeOfferAutostart(command, io) {
+    if (command.json || !isInteractiveStdin(io) || !io.exec)
+        return;
+    const answer = (await readLine(io, "Keep Cockpit syncing in the background, even after restart? [Y/n] "))
+        .trim()
+        .toLowerCase();
+    if (answer === "n" || answer === "no") {
+        writeLine(io.stdout, "Skipped background autostart. Run `cockpit autostart install` anytime.");
+        return;
+    }
+    const result = await installAutostartAgent({
+        homeDir: command.homeDir,
+        repoRoot: command.repoRoot,
+        dashboardUrl: command.dashboardUrl,
+        exec: io.exec,
+    });
+    if (result.status === "unsupported") {
+        writeLine(io.stdout, `Background autostart unsupported: ${result.message}`);
+        return;
+    }
+    writeLine(io.stdout, result.loaded
+        ? "Background autostart installed; Cockpit syncs at login and every 30 min."
+        : "Background autostart installed, but launchctl load reported a problem; check `cockpit autostart status`.");
+    writeLine(io.stdout, `Plist: ${result.plist_path}`);
+}
 async function runOnboard(command, io) {
     let install = null;
     let pair = null;
@@ -574,6 +659,8 @@ async function runOnboard(command, io) {
                     codex_sessions: multi.codex_sessions,
                 }, null, 2));
             }
+            if (multi.ok)
+                await maybeOfferAutostart(command, io);
             return multi.ok ? 0 : 1;
         }
         const context = await startLocalWorkContext({
@@ -638,6 +725,7 @@ async function runOnboard(command, io) {
         writeLine(io.stdout, `Upload state: ${status.upload_state}`);
         writeLine(io.stdout, "PASS: Cockpit collector is ready for harvest.");
         writeLine(io.stdout, `Open: ${command.dashboardUrl}/my-work`);
+        await maybeOfferAutostart(command, io);
         return 0;
     }
     catch (error) {
@@ -1685,6 +1773,61 @@ async function runServe(command, io) {
     });
     return 0;
 }
+async function runAutostart(command, io) {
+    const exec = io.exec ?? defaultExec();
+    const result = command.action === "install"
+        ? await installAutostartAgent({
+            homeDir: command.homeDir,
+            repoRoot: command.repoRoot,
+            dashboardUrl: command.dashboardUrl,
+            intervalSeconds: command.intervalSeconds,
+            exec,
+        })
+        : command.action === "uninstall"
+            ? await uninstallAutostartAgent({ homeDir: command.homeDir, exec })
+            : await autostartStatus({ homeDir: command.homeDir, exec });
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify(result, null, 2));
+        return result.status === "unsupported" ? 1 : 0;
+    }
+    writeAutostartResult(io, result);
+    return result.status === "unsupported" ? 1 : 0;
+}
+function writeAutostartResult(io, result) {
+    switch (result.status) {
+        case "installed":
+            writeLine(io.stdout, result.loaded
+                ? "Cockpit autostart installed and loaded."
+                : "Cockpit autostart installed (launchctl load reported a problem).");
+            writeLine(io.stdout, `Label: ${result.label}`);
+            writeLine(io.stdout, `Plist: ${result.plist_path}`);
+            writeLine(io.stdout, `Interval: every ${result.interval_seconds}s`);
+            writeLine(io.stdout, `Repo: ${result.work_dir}`);
+            writeLine(io.stdout, `Dashboard: ${result.dashboard_url}`);
+            if (!result.loaded && result.message)
+                writeLine(io.stderr, result.message);
+            return;
+        case "uninstalled":
+            writeLine(io.stdout, "Cockpit autostart removed.");
+            writeLine(io.stdout, `Plist: ${result.plist_path}`);
+            return;
+        case "absent":
+            writeLine(io.stdout, "Cockpit autostart is not installed.");
+            writeLine(io.stdout, `Plist: ${result.plist_path}`);
+            return;
+        case "loaded":
+            writeLine(io.stdout, "Cockpit autostart is installed and loaded.");
+            writeLine(io.stdout, `Plist: ${result.plist_path}`);
+            return;
+        case "not_loaded":
+            writeLine(io.stdout, "Cockpit autostart plist exists but is not loaded; run `cockpit autostart install` to reload.");
+            writeLine(io.stdout, `Plist: ${result.plist_path}`);
+            return;
+        case "unsupported":
+            writeLine(io.stderr, `Autostart unsupported: ${result.message}`);
+            return;
+    }
+}
 function assertNoPositionals(positionals, command) {
     if (positionals.length > 0) {
         throw new Error(`${command} does not accept positional arguments.`);
@@ -1754,6 +1897,16 @@ function base64UrlToBase64(value) {
     const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
     return `${normalized}${"=".repeat((4 - (normalized.length % 4)) % 4)}`;
 }
+function defaultExec() {
+    return (cmd, args) => new Promise((resolve) => {
+        execFile(cmd, args, { encoding: "utf8" }, (err, stdout, stderr) => {
+            // execFile's error `.code` is the exit code when numeric, but a string
+            // (e.g. "ENOENT") for spawn failures — treat those as a generic 1.
+            const code = err == null ? 0 : typeof err.code === "number" ? err.code : 1;
+            resolve({ code, stdout: stdout ?? "", stderr: stderr ?? "" });
+        });
+    });
+}
 function defaultIo() {
     if (!globalThis.fetch) {
         throw new Error("global fetch is unavailable; use Node.js 20 or newer.");
@@ -1764,6 +1917,7 @@ function defaultIo() {
         stderr: process.stderr,
         env: process.env,
         fetch: globalThis.fetch.bind(globalThis),
+        exec: defaultExec(),
     };
 }
 function writeLine(stream, text) {

package/dist/local-state.js

@@ -5,7 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import { resolveRepoWorktreeIdentity, } from "./repo-identity.js";
 import { summarizeLocalUploadSpool } from "./spool/local-spool.js";
-export const LOCAL_COLLECTOR_VERSION = "0.1.8";
+export const LOCAL_COLLECTOR_VERSION = "0.1.9";
 export const DEFAULT_DASHBOARD_URL = "https://bli-cockpit-dashboard.vercel.app";
 export function getCollectorRuntimePaths(homeDir = os.homedir()) {
     const paths = getUserLocalCockpitPaths(homeDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "private": false,
   "type": "module",
   "bin": {