@bli-cockpit/cli 0.1.14 → 0.1.16

package/README.md

@@ -41,6 +41,16 @@ pairing. Already-onboarded users update with
 `npm install -g @bli-cockpit/cli@latest`, then run
 `cockpit sync --repo "$PWD" --json`.
 
+On machines where Codex agents will do ticketed work, install the user-scope
+agent rule once:
+
+```bash
+cockpit agent-rules install
+```
+
+That updates `~/.codex/AGENTS.md` with the Cockpit rule to bind known Linear
+tickets before edits, or ask once when the ticket ID is missing.
+
 Parent mode scans child git repos/worktrees (3 folder levels deep, up to 50
 repos by default — tune with `--max-depth` / `--max-repos`; a warning prints
 if the repo cap truncates discovery), creates one stable work context per

package/dist/agent-rules.js

@@ -0,0 +1,97 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+const MANAGED_BLOCK_START = "<!-- BLI_COCKPIT_AGENT_RULES:START -->";
+const MANAGED_BLOCK_END = "<!-- BLI_COCKPIT_AGENT_RULES:END -->";
+export async function installCodexAgentRules(options = {}) {
+    const agentsFile = codexAgentsFile(options.homeDir);
+    const block = cockpitAgentRulesBlock();
+    let existing = "";
+    let existed = true;
+    try {
+        existing = await readFile(agentsFile, "utf8");
+    }
+    catch {
+        existed = false;
+    }
+    const next = upsertManagedBlock(existing, block);
+    if (next === existing) {
+        return { status: "unchanged", agents_file: agentsFile, block };
+    }
+    await mkdir(path.dirname(agentsFile), { recursive: true });
+    await writeFile(agentsFile, next, "utf8");
+    return { status: existed ? "updated" : "created", agents_file: agentsFile, block };
+}
+export async function uninstallCodexAgentRules(options = {}) {
+    const agentsFile = codexAgentsFile(options.homeDir);
+    const block = cockpitAgentRulesBlock();
+    let existing = "";
+    try {
+        existing = await readFile(agentsFile, "utf8");
+    }
+    catch {
+        return { status: "missing", agents_file: agentsFile, block };
+    }
+    const next = removeManagedBlock(existing);
+    if (next === existing) {
+        return { status: "missing", agents_file: agentsFile, block };
+    }
+    await writeFile(agentsFile, next, "utf8");
+    return { status: "updated", agents_file: agentsFile, block };
+}
+export async function inspectCodexAgentRules(options = {}) {
+    const agentsFile = codexAgentsFile(options.homeDir);
+    const block = cockpitAgentRulesBlock();
+    let existing = "";
+    try {
+        existing = await readFile(agentsFile, "utf8");
+    }
+    catch {
+        return { status: "missing", agents_file: agentsFile, block, installed: false };
+    }
+    return {
+        status: hasManagedBlock(existing) ? "unchanged" : "missing",
+        agents_file: agentsFile,
+        block,
+        installed: hasManagedBlock(existing),
+    };
+}
+export function cockpitAgentRulesBlock() {
+    return [
+        MANAGED_BLOCK_START,
+        "## Cockpit Ticket Binding",
+        "",
+        "- For implementation, debugging, review, PR, or ship work tied to a clear Linear ticket, run `cockpit start --ticket <ticket-id> --repo \"$PWD\"` before the first code edit or mutating tool call.",
+        "- Use `--ticket`; do not invent `--ticketId` or other flag shapes.",
+        "- If the user mentions ticketed work but no ticket ID is visible, ask once for the Linear ticket ID before editing. Agents cannot reliably infer it from context.",
+        "- If there is truly no ticket, state that the work remains in general ambient capture and do not invent a ticket.",
+        "- After the first meaningful checkpoint, run `cockpit sync --repo \"$PWD\" --json` so Cockpit has fresh ticket/session binding metadata.",
+        MANAGED_BLOCK_END,
+    ].join("\n");
+}
+export function hasManagedBlock(contents) {
+    return contents.includes(MANAGED_BLOCK_START) && contents.includes(MANAGED_BLOCK_END);
+}
+export function upsertManagedBlock(contents, block) {
+    if (!contents.trim())
+        return `${block}\n`;
+    if (!hasManagedBlock(contents)) {
+        return `${contents.replace(/\s+$/u, "")}\n\n${block}\n`;
+    }
+    const pattern = managedBlockPattern();
+    return contents.replace(pattern, block);
+}
+export function removeManagedBlock(contents) {
+    if (!hasManagedBlock(contents))
+        return contents;
+    return contents.replace(managedBlockPattern(), "").replace(/\n{3,}/gu, "\n\n").trimEnd() + "\n";
+}
+function codexAgentsFile(homeDir = os.homedir()) {
+    return path.join(homeDir, ".codex", "AGENTS.md");
+}
+function managedBlockPattern() {
+    return new RegExp(`${escapeRegExp(MANAGED_BLOCK_START)}[\\s\\S]*?${escapeRegExp(MANAGED_BLOCK_END)}`, "u");
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}

package/dist/autostart.js

@@ -4,7 +4,7 @@ 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;
+export const DEFAULT_AUTOSTART_INTERVAL_SECONDS = 15 * 60;
 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`);
@@ -31,7 +31,7 @@ export async function installAutostartAgent(options) {
     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 intervalSeconds = options.intervalSeconds ?? DEFAULT_AUTOSTART_INTERVAL_SECONDS;
     const paths = getCollectorRuntimePaths(homeDir);
     const plistPath = plistPathFor(homeDir);
     const stdoutPath = path.join(paths.state_dir, "sync.log");

package/dist/commands/local-args.js

@@ -4,6 +4,7 @@
 //
 // Behavior-preserving extraction: functions moved verbatim, no logic change.
 import { DEFAULT_DASHBOARD_URL } from "../local-state.js";
+import { DEFAULT_AUTOSTART_INTERVAL_SECONDS } from "../autostart.js";
 export function parseLocalArgs(argv) {
     const command = argv[0];
     switch (command) {
@@ -28,6 +29,8 @@ export function parseLocalArgs(argv) {
             return parseServeArgs(argv.slice(1));
         case "autostart":
             return parseAutostartArgs(argv.slice(1));
+        case "agent-rules":
+            return parseAgentRulesArgs(argv.slice(1));
         default:
             throw new Error(`Unknown local command: ${command ?? ""}`);
     }
@@ -274,7 +277,26 @@ function parseAutostartArgs(args) {
         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,
+        intervalSeconds: optionalPositiveInteger(values.flags.get("--interval-seconds"), "--interval-seconds") ?? DEFAULT_AUTOSTART_INTERVAL_SECONDS,
+        json: values.booleans.has("--json"),
+    };
+}
+function parseAgentRulesArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: ["--home", "--json"],
+        valueFlags: ["--home"],
+    });
+    if (values.positionals.length > 1) {
+        throw new Error("agent-rules accepts at most one action (install|uninstall|status).");
+    }
+    const action = values.positionals[0] ?? "install";
+    if (action !== "install" && action !== "uninstall" && action !== "status") {
+        throw new Error("agent-rules action must be install, uninstall, or status.");
+    }
+    return {
+        kind: "agent-rules",
+        action,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
         json: values.booleans.has("--json"),
     };
 }

package/dist/commands/local.js

@@ -2,6 +2,7 @@ import { execFile } from "node:child_process";
 import os from "node:os";
 import path from "node:path";
 import { createCollectorServer } from "../server.js";
+import { inspectCodexAgentRules, installCodexAgentRules, uninstallCodexAgentRules, } from "../agent-rules.js";
 import { parseLocalArgs, normalizeUrl } from "./local-args.js";
 import { autostartStatus, installAutostartAgent, uninstallAutostartAgent } from "../autostart.js";
 import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, inspectLocalCollectorStatus, installLocalCollector, logoutLocalCollector, pairLocalCollector, readLocalCollectorSessionFile, readLocalSessionReference, startLocalWorkContext } from "../local-state.js";
@@ -22,6 +23,7 @@ export const rootCommandNames = new Set([
     "sessions",
     "serve",
     "autostart",
+    "agent-rules",
 ]);
 export async function runLocalCockpitCli(argv, io = defaultIo()) {
     if (isLocalHelpRequest(argv)) {
@@ -60,6 +62,8 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
                 return await runServe(command, io);
             case "autostart":
                 return await runAutostart(command, io);
+            case "agent-rules":
+                return await runAgentRules(command, io);
         }
     }
     catch (error) {
@@ -82,6 +86,7 @@ export function localCommandHelp(command) {
         "  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]",
+        "  cockpit agent-rules [install|uninstall|status] [--json]",
         "",
         `Default dashboard: ${DEFAULT_DASHBOARD_URL}. Omit --dashboard-url for normal production use; pass it only for staging/custom dashboards or to force a different pairing.`,
     ].join("\n");
@@ -186,12 +191,23 @@ function localSubcommandHelp(command) {
                 "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.",
+                "every 15 min (default), surviving reboots — so machines never drift to Stale.",
                 "Action defaults to `install`. `--repo` is the parent work folder to sync.",
                 "Omit --dashboard-url for production; pass it only for staging/custom dashboards.",
                 "macOS-only for now; see docs/runbooks/cockpit-launchd-sync.md.",
             ],
         ],
+        [
+            "agent-rules",
+            [
+                "Usage: cockpit agent-rules [install|uninstall|status] [--json]",
+                "",
+                "Installs a managed Cockpit Ticket Binding block into ~/.codex/AGENTS.md.",
+                "This gives Codex agents a user-scope rule to run `cockpit start --ticket <id>`",
+                "before ticketed implementation work, or ask once when the ticket ID is missing.",
+                "Action defaults to `install`.",
+            ],
+        ],
     ]);
     return (helpByCommand.get(command) ?? [localCommandHelp()]).join("\n");
 }
@@ -280,7 +296,7 @@ async function maybeOfferAutostart(command, io) {
         return;
     }
     writeLine(io.stdout, result.loaded
-        ? "Background autostart installed; Cockpit syncs at login and every 30 min."
+        ? "Background autostart installed; Cockpit syncs at login and every 15 min."
         : "Background autostart installed, but launchctl load reported a problem; check `cockpit autostart status`.");
     writeLine(io.stdout, `Plist: ${result.plist_path}`);
 }
@@ -1007,6 +1023,40 @@ async function runAutostart(command, io) {
     writeAutostartResult(io, result);
     return result.status === "unsupported" ? 1 : 0;
 }
+async function runAgentRules(command, io) {
+    const result = command.action === "install"
+        ? await installCodexAgentRules({ homeDir: command.homeDir })
+        : command.action === "uninstall"
+            ? await uninstallCodexAgentRules({ homeDir: command.homeDir })
+            : await inspectCodexAgentRules({ homeDir: command.homeDir });
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify(result, null, 2));
+        return 0;
+    }
+    if ("installed" in result) {
+        writeLine(io.stdout, result.installed
+            ? "Cockpit Codex agent rules are installed."
+            : "Cockpit Codex agent rules are not installed.");
+    }
+    else {
+        switch (result.status) {
+            case "created":
+                writeLine(io.stdout, "Cockpit Codex agent rules installed.");
+                break;
+            case "updated":
+                writeLine(io.stdout, "Cockpit Codex agent rules updated.");
+                break;
+            case "unchanged":
+                writeLine(io.stdout, "Cockpit Codex agent rules already current.");
+                break;
+            case "missing":
+                writeLine(io.stdout, "Cockpit Codex agent rules were not installed.");
+                break;
+        }
+    }
+    writeLine(io.stdout, `AGENTS.md: ${result.agents_file}`);
+    return 0;
+}
 function writeAutostartResult(io, result) {
     switch (result.status) {
         case "installed":

package/dist/commands/public-root.js

@@ -25,8 +25,9 @@ function cockpitHelp() {
     "Install/update: `npm install -g @bli-cockpit/cli@latest`.",
     "Intern path: run `cockpit onboard` from the repo root; add `--ticket <id>` only when work already has a ticket.",
     "Already onboarded: run `cockpit sync --repo \"$PWD\" --json`.",
+    "Agent setup: run `cockpit agent-rules install` so Codex asks for or binds Linear tickets before edits.",
     "Dashboard URL is optional for normal production use; pass `--dashboard-url` only for staging/custom dashboards or forced re-pairing.",
-    "Manual collector path: `install`, `login`, `start [--ticket <id>]`, `sync`, `status`.",
+    "Manual collector path: `install`, `login`, `start [--ticket <id>]`, `sync`, `status`, `agent-rules`.",
   ].join("\n");
 }
 

package/package.json

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