@bli-cockpit/cli 0.1.18 → 0.1.19

package/README.md

@@ -42,18 +42,23 @@ pairing. Already-onboarded users update with
 `cockpit sync --workspace "$PWD" --json`. `--repo <path>` remains supported
 for older prompts and the agent ticket-binding guardrail.
 
-On machines where Codex or Claude 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` 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 the managed block first, so current files are
-left unchanged and stale managed blocks are replaced.
+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

@@ -24,13 +24,17 @@ async function installAgentRulesForHost(host, options = {}) {
     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 agentRulesResult(host, rulesFile, "unchanged", block);
+        return agentRulesResult(host, rulesFile, "unchanged", block, prepared.state);
     }
     await mkdir(path.dirname(rulesFile), { recursive: true });
     await writeFile(rulesFile, next, "utf8");
-    return agentRulesResult(host, rulesFile, existed ? "updated" : "created", block);
+    return agentRulesResult(host, rulesFile, existed ? "updated" : "created", block, "managed", prepared.state === "stale");
 }
 export async function uninstallCodexAgentRules(options = {}) {
     return uninstallAgentRulesForHost("codex", options);
@@ -50,14 +54,14 @@ async function uninstallAgentRulesForHost(host, options = {}) {
         existing = await readFile(rulesFile, "utf8");
     }
     catch {
-        return agentRulesResult(host, rulesFile, "missing", block);
+        return agentRulesResult(host, rulesFile, "missing", block, "missing");
     }
     const next = removeManagedBlock(existing);
     if (next === existing) {
-        return agentRulesResult(host, rulesFile, "missing", block);
+        return agentRulesResult(host, rulesFile, "missing", block, "missing");
     }
     await writeFile(rulesFile, next, "utf8");
-    return agentRulesResult(host, rulesFile, "updated", block);
+    return agentRulesResult(host, rulesFile, "updated", block, "missing");
 }
 export async function inspectCodexAgentRules(options = {}) {
     return inspectAgentRulesForHost("codex", options);
@@ -80,11 +84,15 @@ async function inspectAgentRulesForHost(host, options = {}) {
         existing = await readFile(rulesFile, "utf8");
     }
     catch {
-        return { ...agentRulesResult(host, rulesFile, "missing", block), installed: false };
+        return {
+            ...agentRulesResult(host, rulesFile, "missing", block, "missing"),
+            installed: false,
+        };
     }
-    const installed = hasManagedBlock(existing);
+    const state = inspectAgentRulesContents(existing);
+    const installed = state === "managed" || state === "equivalent";
     return {
-        ...agentRulesResult(host, rulesFile, installed ? "unchanged" : "missing", block),
+        ...agentRulesResult(host, rulesFile, installed ? "unchanged" : "missing", block, state),
         installed,
     };
 }
@@ -118,19 +126,48 @@ export function removeManagedBlock(contents) {
         return contents;
     return contents.replace(managedBlockPattern(), "").replace(/\n{3,}/gu, "\n\n").trimEnd() + "\n";
 }
+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) {
+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) {
@@ -151,6 +188,62 @@ function aggregateAgentRulesResult(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.js

@@ -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.",
             ],
         ],
         [
@@ -310,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;
@@ -383,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({
@@ -449,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;
     }

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.18",
+  "version": "0.1.19",
   "private": false,
   "type": "module",
   "bin": {