@bli-cockpit/cli 0.1.17 → 0.1.19

package/README.md

@@ -40,17 +40,25 @@ staging, a custom dashboard, or deliberately forcing a different dashboard
 pairing. Already-onboarded users update with
 `npm install -g @bli-cockpit/cli@latest`, then run
 `cockpit sync --workspace "$PWD" --json`. `--repo <path>` remains supported
-for older prompts and the Codex ticket-binding guardrail.
+for older prompts and the agent ticket-binding guardrail.
 
-On machines where Codex agents will do ticketed work, install the user-scope
-agent rule once:
+On machines where Codex or Claude agents will do ticketed work, interactive
+`cockpit onboard` checks `~/.codex/AGENTS.md` and `~/.claude/CLAUDE.md` after
+harvest proof. If equivalent Cockpit ticket-binding guidance already exists, it
+leaves the files alone. If guidance is missing or clearly stale, it asks whether
+to install or replace it.
 
 ```bash
+# Repair/manual path, or headless/json onboarding where Cockpit cannot prompt.
 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.
+The direct command updates `~/.codex/AGENTS.md` and `~/.claude/CLAUDE.md` with
+the Cockpit rule to bind known Linear tickets before edits, or ask once when
+the ticket ID is missing. That binding starts attributing the session's work to
+the specific ticket in Cockpit. It checks for managed or equivalent guidance
+first, so current files are left unchanged and stale Cockpit ticket-binding
+sections are replaced.
 
 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

package/dist/agent-rules.js

@@ -4,56 +4,96 @@ 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);
+    return installAgentRulesForHost("codex", options);
+}
+export async function installClaudeAgentRules(options = {}) {
+    return installAgentRulesForHost("claude", options);
+}
+export async function installAgentRules(options = {}) {
+    const targets = await Promise.all(targetHosts(options.hosts).map((host) => installAgentRulesForHost(host, options)));
+    return aggregateAgentRulesResult(targets);
+}
+async function installAgentRulesForHost(host, options = {}) {
+    const rulesFile = agentRulesFile(host, options.homeDir);
     const block = cockpitAgentRulesBlock();
     let existing = "";
     let existed = true;
     try {
-        existing = await readFile(agentsFile, "utf8");
+        existing = await readFile(rulesFile, "utf8");
     }
     catch {
         existed = false;
     }
-    const next = upsertManagedBlock(existing, block);
+    const prepared = prepareManagedBlockInstall(existing, block);
+    if (!prepared.next) {
+        return agentRulesResult(host, rulesFile, "unchanged", block, prepared.state);
+    }
+    const next = prepared.next;
     if (next === existing) {
-        return { status: "unchanged", agents_file: agentsFile, block };
+        return agentRulesResult(host, rulesFile, "unchanged", block, prepared.state);
     }
-    await mkdir(path.dirname(agentsFile), { recursive: true });
-    await writeFile(agentsFile, next, "utf8");
-    return { status: existed ? "updated" : "created", agents_file: agentsFile, block };
+    await mkdir(path.dirname(rulesFile), { recursive: true });
+    await writeFile(rulesFile, next, "utf8");
+    return agentRulesResult(host, rulesFile, existed ? "updated" : "created", block, "managed", prepared.state === "stale");
 }
 export async function uninstallCodexAgentRules(options = {}) {
-    const agentsFile = codexAgentsFile(options.homeDir);
+    return uninstallAgentRulesForHost("codex", options);
+}
+export async function uninstallClaudeAgentRules(options = {}) {
+    return uninstallAgentRulesForHost("claude", options);
+}
+export async function uninstallAgentRules(options = {}) {
+    const targets = await Promise.all(targetHosts(options.hosts).map((host) => uninstallAgentRulesForHost(host, options)));
+    return aggregateAgentRulesResult(targets);
+}
+async function uninstallAgentRulesForHost(host, options = {}) {
+    const rulesFile = agentRulesFile(host, options.homeDir);
     const block = cockpitAgentRulesBlock();
     let existing = "";
     try {
-        existing = await readFile(agentsFile, "utf8");
+        existing = await readFile(rulesFile, "utf8");
     }
     catch {
-        return { status: "missing", agents_file: agentsFile, block };
+        return agentRulesResult(host, rulesFile, "missing", block, "missing");
     }
     const next = removeManagedBlock(existing);
     if (next === existing) {
-        return { status: "missing", agents_file: agentsFile, block };
+        return agentRulesResult(host, rulesFile, "missing", block, "missing");
     }
-    await writeFile(agentsFile, next, "utf8");
-    return { status: "updated", agents_file: agentsFile, block };
+    await writeFile(rulesFile, next, "utf8");
+    return agentRulesResult(host, rulesFile, "updated", block, "missing");
 }
 export async function inspectCodexAgentRules(options = {}) {
-    const agentsFile = codexAgentsFile(options.homeDir);
+    return inspectAgentRulesForHost("codex", options);
+}
+export async function inspectClaudeAgentRules(options = {}) {
+    return inspectAgentRulesForHost("claude", options);
+}
+export async function inspectAgentRules(options = {}) {
+    const targets = await Promise.all(targetHosts(options.hosts).map((host) => inspectAgentRulesForHost(host, options)));
+    return {
+        ...aggregateAgentRulesResult(targets),
+        installed: targets.every((target) => target.installed),
+    };
+}
+async function inspectAgentRulesForHost(host, options = {}) {
+    const rulesFile = agentRulesFile(host, options.homeDir);
     const block = cockpitAgentRulesBlock();
     let existing = "";
     try {
-        existing = await readFile(agentsFile, "utf8");
+        existing = await readFile(rulesFile, "utf8");
     }
     catch {
-        return { status: "missing", agents_file: agentsFile, block, installed: false };
+        return {
+            ...agentRulesResult(host, rulesFile, "missing", block, "missing"),
+            installed: false,
+        };
     }
+    const state = inspectAgentRulesContents(existing);
+    const installed = state === "managed" || state === "equivalent";
     return {
-        status: hasManagedBlock(existing) ? "unchanged" : "missing",
-        agents_file: agentsFile,
-        block,
-        installed: hasManagedBlock(existing),
+        ...agentRulesResult(host, rulesFile, installed ? "unchanged" : "missing", block, state),
+        installed,
     };
 }
 export function cockpitAgentRulesBlock() {
@@ -61,7 +101,7 @@ export function cockpitAgentRulesBlock() {
         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.",
+        "- 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. This starts attributing the session's work to that specific ticket in Cockpit.",
         "- 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.",
@@ -86,12 +126,124 @@ export function removeManagedBlock(contents) {
         return contents;
     return contents.replace(managedBlockPattern(), "").replace(/\n{3,}/gu, "\n\n").trimEnd() + "\n";
 }
-function codexAgentsFile(homeDir = os.homedir()) {
+function prepareManagedBlockInstall(contents, block) {
+    if (!contents.trim())
+        return { next: `${block}\n`, state: "missing" };
+    if (hasManagedBlock(contents)) {
+        return { next: upsertManagedBlock(contents, block), state: "managed" };
+    }
+    if (hasEquivalentUnmanagedTicketBinding(contents)) {
+        return { next: null, state: "equivalent" };
+    }
+    const staleBlock = findStaleUnmanagedTicketBindingBlock(contents);
+    if (staleBlock) {
+        return {
+            next: replaceLineSpan(contents, staleBlock.startLine, staleBlock.endLine, block),
+            state: "stale",
+        };
+    }
+    return { next: `${contents.replace(/\s+$/u, "")}\n\n${block}\n`, state: "missing" };
+}
+function inspectAgentRulesContents(contents) {
+    if (hasManagedBlock(contents))
+        return "managed";
+    if (hasEquivalentUnmanagedTicketBinding(contents))
+        return "equivalent";
+    if (findStaleUnmanagedTicketBindingBlock(contents))
+        return "stale";
+    return "missing";
+}
+function agentRulesFile(host, homeDir = os.homedir()) {
+    if (host === "claude") {
+        return path.join(homeDir, ".claude", "CLAUDE.md");
+    }
     return path.join(homeDir, ".codex", "AGENTS.md");
 }
+function agentRulesResult(host, rulesFile, status, block, state, staleBlockReplaced = false) {
+    return {
+        host,
+        status,
+        rules_file: rulesFile,
+        agents_file: rulesFile,
+        block,
+        state,
+        ...(staleBlockReplaced ? { stale_block_replaced: true } : {}),
+    };
+}
+function targetHosts(hosts) {
+    return hosts && hosts.length > 0 ? hosts : ["codex", "claude"];
+}
+function aggregateAgentRulesResult(targets) {
+    if (targets.every((target) => target.status === "unchanged")) {
+        return { status: "unchanged", targets };
+    }
+    if (targets.every((target) => target.status === "missing")) {
+        return { status: "missing", targets };
+    }
+    if (targets.every((target) => target.status === "created")) {
+        return { status: "created", targets };
+    }
+    return { status: "updated", targets };
+}
 function managedBlockPattern() {
     return new RegExp(`${escapeRegExp(MANAGED_BLOCK_START)}[\\s\\S]*?${escapeRegExp(MANAGED_BLOCK_END)}`, "u");
 }
+function hasEquivalentUnmanagedTicketBinding(contents) {
+    const text = normalizeRuleText(contents);
+    if (!hasTicketBindingCues(text))
+        return false;
+    const signals = [
+        /cockpit\s+start\s+--ticket\b/u,
+        /before\s+(?:the\s+)?first\s+code\s+edit|before\s+ticketed\s+implementation/u,
+        /ticket\s+id\s+(?:is\s+)?(?:missing|visible)|ask\s+once/u,
+        /general\s+ambient/u,
+        /cockpit\s+sync\s+--repo|fresh\s+ticket\/session\s+binding\s+metadata/u,
+        /use\s+--ticket|do\s+not\s+invent\s+--ticketid/u,
+    ];
+    const score = signals.filter((signal) => signal.test(text)).length;
+    return score >= 5;
+}
+function findStaleUnmanagedTicketBindingBlock(contents) {
+    const lines = contents.split("\n");
+    for (let index = 0; index < lines.length; index += 1) {
+        if (!/^#{1,6}\s+.*(?:cockpit\s+)?ticket\s+binding\b/iu.test(lines[index] ?? "")) {
+            continue;
+        }
+        let endLine = lines.length;
+        for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+            if (/^#{1,6}\s+\S/u.test(lines[cursor] ?? "")) {
+                endLine = cursor;
+                break;
+            }
+        }
+        const candidate = lines.slice(index, endLine).join("\n");
+        const normalized = normalizeRuleText(candidate);
+        if (hasTicketBindingCues(normalized) && !hasEquivalentUnmanagedTicketBinding(candidate)) {
+            return { startLine: index, endLine };
+        }
+    }
+    return null;
+}
+function replaceLineSpan(contents, startLine, endLine, replacement) {
+    const lines = contents.split("\n");
+    const before = lines.slice(0, startLine).join("\n").trimEnd();
+    const after = lines.slice(endLine).join("\n").trimStart();
+    return [before, replacement, after]
+        .filter((part) => part.trim().length > 0)
+        .join("\n\n")
+        .replace(/\n{3,}/gu, "\n\n")
+        .trimEnd() + "\n";
+}
+function hasTicketBindingCues(text) {
+    return /\bcockpit\b/u.test(text) && /\bticket\b/u.test(text) && /binding|agent|linear/u.test(text);
+}
+function normalizeRuleText(contents) {
+    return contents
+        .toLowerCase()
+        .replace(/[`"'<>]/gu, "")
+        .replace(/\s+/gu, " ")
+        .trim();
+}
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }

package/dist/commands/local-args.js

@@ -345,8 +345,8 @@ function parseAutostartArgs(args) {
 }
 function parseAgentRulesArgs(args) {
     const values = parseNamedArgs(args, {
-        allowedFlags: ["--home", "--json"],
-        valueFlags: ["--home"],
+        allowedFlags: ["--home", "--host", "--json"],
+        valueFlags: ["--home", "--host"],
     });
     if (values.positionals.length > 1) {
         throw new Error("agent-rules accepts at most one action (install|uninstall|status).");
@@ -358,10 +358,17 @@ function parseAgentRulesArgs(args) {
     return {
         kind: "agent-rules",
         action,
+        host: parseAgentRulesHost(values.flags.get("--host")),
         homeDir: optionalNonEmpty(values.flags.get("--home")),
         json: values.booleans.has("--json"),
     };
 }
+function parseAgentRulesHost(value) {
+    const host = value?.trim().toLowerCase() || "all";
+    if (host === "codex" || host === "claude" || host === "all")
+        return host;
+    throw new Error("agent-rules --host must be codex, claude, or all.");
+}
 function parseNamedArgs(args, options) {
     const allowed = new Set(options.allowedFlags);
     const valueFlags = new Set(options.valueFlags);

package/dist/commands/local.js

@@ -2,7 +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 { inspectAgentRules, installAgentRules, uninstallAgentRules, } 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";
@@ -86,7 +86,7 @@ export function localCommandHelp(command) {
         "  cockpit sessions [--source codex|claude] [--workspace <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit serve [--port <port>] [--workspace <path>]",
         "  cockpit autostart [install|uninstall|status] [--workspace <path>] [--dashboard-url <url>] [--interval-seconds <n>] [--json]",
-        "  cockpit agent-rules [install|uninstall|status] [--json]",
+        "  cockpit agent-rules [install|uninstall|status] [--host codex|claude|all] [--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");
@@ -104,6 +104,7 @@ function localSubcommandHelp(command) {
                 `Omit --dashboard-url for normal production setup (${DEFAULT_DASHBOARD_URL}).`,
                 "Pass --dashboard-url only for staging/custom dashboards or to force a different pairing.",
                 "Run with no flags in a terminal and it prompts for the dashboard email; pass --email to skip the prompt (and on shared/reused machines, where mismatched sessions are re-paired).",
+                "Interactive runs also offer to add Cockpit ticket-binding rules to AGENTS.md and CLAUDE.md after readiness proof.",
             ],
         ],
         [
@@ -208,11 +209,13 @@ function localSubcommandHelp(command) {
         [
             "agent-rules",
             [
-                "Usage: cockpit agent-rules [install|uninstall|status] [--json]",
+                "Usage: cockpit agent-rules [install|uninstall|status] [--host codex|claude|all] [--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.",
+                "Installs a managed Cockpit Ticket Binding block into ~/.codex/AGENTS.md",
+                "and ~/.claude/CLAUDE.md by default. Pass --host to manage only one.",
+                "This gives Codex and Claude 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`.",
             ],
         ],
@@ -308,6 +311,48 @@ async function maybeOfferAutostart(command, io) {
         : "Background autostart installed, but launchctl load reported a problem; check `cockpit autostart status`.");
     writeLine(io.stdout, `Plist: ${result.plist_path}`);
 }
+async function maybeOfferAgentRules(command, io) {
+    if (command.json || !isInteractiveStdin(io))
+        return;
+    const current = await inspectAgentRules({ homeDir: command.homeDir });
+    if (current.installed) {
+        writeLine(io.stdout, onboardAgentRulesAlreadyInstalledLine(current));
+        return;
+    }
+    const answer = (await readLine(io, "Add Cockpit ticket-binding rules to AGENTS.md and CLAUDE.md? [Y/n] "))
+        .trim()
+        .toLowerCase();
+    if (answer === "n" || answer === "no") {
+        writeLine(io.stdout, "Skipped agent rules. Run `cockpit agent-rules install` anytime.");
+        return;
+    }
+    const result = await installAgentRules({ homeDir: command.homeDir });
+    writeLine(io.stdout, `Agent rules: ${onboardAgentRulesInstallLine(result)}`);
+    for (const target of result.targets) {
+        writeLine(io.stdout, `${agentRuleHostLabel(target.host)}: ${target.rules_file}`);
+    }
+}
+function onboardAgentRulesAlreadyInstalledLine(result) {
+    const hasEquivalent = result.targets.some((target) => target.state === "equivalent");
+    return hasEquivalent
+        ? "Agent rules: matching Cockpit ticket-binding guidance already exists."
+        : "Agent rules: already current in AGENTS.md and CLAUDE.md.";
+}
+function onboardAgentRulesInstallLine(result) {
+    if (result.targets.some((target) => target.stale_block_replaced)) {
+        return "updated; replaced stale Cockpit ticket-binding guidance.";
+    }
+    switch (result.status) {
+        case "created":
+            return "installed.";
+        case "updated":
+            return "updated.";
+        case "unchanged":
+            return "already current.";
+        case "missing":
+            return "not installed.";
+    }
+}
 async function runOnboard(command, io) {
     let install = null;
     let pair = null;
@@ -381,8 +426,10 @@ async function runOnboard(command, io) {
                     codex_sessions: multi.codex_sessions,
                 }, null, 2));
             }
-            if (multi.ok)
+            if (multi.ok) {
+                await maybeOfferAgentRules(command, io);
                 await maybeOfferAutostart(command, io);
+            }
             return multi.ok ? 0 : 1;
         }
         const context = await startLocalWorkContext({
@@ -447,6 +494,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 maybeOfferAgentRules(command, io);
         await maybeOfferAutostart(command, io);
         return 0;
     }
@@ -1032,39 +1080,47 @@ async function runAutostart(command, io) {
     return result.status === "unsupported" ? 1 : 0;
 }
 async function runAgentRules(command, io) {
+    const hosts = agentRuleHosts(command.host);
     const result = command.action === "install"
-        ? await installCodexAgentRules({ homeDir: command.homeDir })
+        ? await installAgentRules({ homeDir: command.homeDir, hosts })
         : command.action === "uninstall"
-            ? await uninstallCodexAgentRules({ homeDir: command.homeDir })
-            : await inspectCodexAgentRules({ homeDir: command.homeDir });
+            ? await uninstallAgentRules({ homeDir: command.homeDir, hosts })
+            : await inspectAgentRules({ homeDir: command.homeDir, hosts });
     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.");
+            ? "Cockpit agent rules are installed."
+            : "Cockpit 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, agentRulesStatusLine(result));
+    }
+    for (const target of result.targets) {
+        writeLine(io.stdout, `${agentRuleHostLabel(target.host)}: ${target.rules_file}`);
     }
-    writeLine(io.stdout, `AGENTS.md: ${result.agents_file}`);
     return 0;
 }
+function agentRuleHosts(host) {
+    return host === "all" ? ["codex", "claude"] : [host];
+}
+function agentRulesStatusLine(result) {
+    switch (result.status) {
+        case "created":
+            return "Cockpit agent rules installed.";
+        case "updated":
+            return "Cockpit agent rules updated.";
+        case "unchanged":
+            return "Cockpit agent rules already current.";
+        case "missing":
+            return "Cockpit agent rules were not installed.";
+    }
+}
+function agentRuleHostLabel(host) {
+    return host === "claude" ? "CLAUDE.md" : "AGENTS.md";
+}
 function writeAutostartResult(io, result) {
     switch (result.status) {
         case "installed":

package/dist/commands/public-root.js

@@ -25,7 +25,7 @@ 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 --workspace \"$PWD\" --json`.",
-    "Agent setup: run `cockpit agent-rules install` so Codex asks for or binds Linear tickets before edits.",
+    "Agent setup: interactive `cockpit onboard` offers AGENTS.md/CLAUDE.md rules; use `cockpit agent-rules install` for repair/headless setup.",
     "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`, `agent-rules`.",
   ].join("\n");

package/package.json

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