@bli-cockpit/cli 0.2.27 → 0.2.29

package/dist/commands/local-help.js

@@ -0,0 +1,281 @@
+/**
+ * What `cockpit --help` and `cockpit <command> --help` print, plus the set of
+ * command names the top-level router recognises.
+ *
+ * Pure text and one lookup table — no filesystem, no network, no process. Split
+ * out of commands/local.ts (BLI-3104) with every string moved verbatim: help
+ * output is what an intern pastes back when something breaks, so it is a
+ * user-visible contract like any other.
+ */
+import { DEFAULT_DASHBOARD_URL } from "../local-state.js";
+export const rootCommandNames = new Set([
+    "onboard",
+    "update",
+    "upgrade",
+    "do-everything",
+    "fix",
+    "install",
+    "login",
+    "pair",
+    "logout",
+    "start",
+    "sync",
+    "analyze",
+    "backfill",
+    "status",
+    "sessions",
+    "serve",
+    "autostart",
+    "agent-rules",
+    "release",
+]);
+export function localCommandHelp(command) {
+    if (command)
+        return localSubcommandHelp(command);
+    return [
+        "  cockpit onboard [--ticket <id>] [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--branch <name>] [--no-auth] [--max-depth <n>] [--max-repos <n>] [--json]",
+        "  cockpit update [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--no-auth] [--json]",
+        "  cockpit upgrade [same flags as update]",
+        "  cockpit do-everything [--workspace <path>] [--dashboard-url <url>] [--update-tag <tag>] [--dry-run] [--json]",
+        "  cockpit fix [same flags as do-everything]",
+        "  cockpit install [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--json]",
+        "  cockpit login [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--no-auth] [--json]",
+        "  cockpit pair [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--no-auth] [--json]",
+        "  cockpit logout",
+        "  cockpit start [--ticket <id>|--clear-ticket] [--topic <label>] [--intent <intent>] [--phase <phase>] [--workspace <path>] [--branch <name>] [--max-depth <n>] [--max-repos <n>] [--json]",
+        "  cockpit sync [--workspace <path>] [--dashboard-url <url>] [--max-depth <n>] [--max-repos <n>] [--json]",
+        "  cockpit analyze [--workspace <path>] [--dashboard-url <url>] [--max-depth <n>] [--max-repos <n>] [--json]",
+        "  cockpit backfill (--since-days <n>|--all) [--source codex|claude] [--dry-run] [--max-files <n>] [--max-depth <n>] [--max-repos <n>] [--yes] [--workspace <path>] [--json]",
+        "  cockpit status [--workspace <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
+        "  cockpit sessions [--source codex|claude] [--since-days <n>|--all] [--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] [--host codex|claude|all] [--workspace <path>] [--json]",
+        "  cockpit release [--dry-run] [--skip-checks] [--tag <tag>] [--access <public|restricted>] [--otp <code>]",
+        "",
+        `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");
+}
+function localSubcommandHelp(command) {
+    const helpByCommand = new Map([
+        [
+            "onboard",
+            [
+                "Usage: cockpit onboard [--ticket <id>] [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--branch <name>] [--no-auth] [--max-depth <n>] [--max-repos <n>] [--json]",
+                "",
+                "Installs, pairs, starts work context(s), syncs once, completes all-history",
+                "Codex and Claude backfill for the saved roots, and then prints readiness proof.",
+                "If --workspace is a parent folder, scans child git repos/worktrees and rolls them up by repo.",
+                "`--repo <path>` remains supported as a backward-compatible alias.",
+                `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 and OTP code; pass --email to skip the email prompt. Use --no-auth to force the manual approval fallback.",
+                "Interactive runs also offer to add Cockpit ticket-binding rules to AGENTS.md and CLAUDE.md after readiness proof.",
+            ],
+        ],
+        [
+            "install",
+            [
+                "Usage: cockpit install [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--json]",
+                "",
+                "Writes local collector config. Pair with `cockpit login`, then run `cockpit start` when work begins.",
+                "`--repo <path>` remains supported as a backward-compatible alias.",
+                "Omit --dashboard-url for the production dashboard; pass it only for staging/custom dashboards.",
+            ],
+        ],
+        [
+            "update",
+            [
+                "Usage: cockpit update [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--no-auth] [--json]",
+                "",
+                "Updates the global public CLI from npm, then reruns `cockpit onboard`",
+                "with the same setup flags so pairing, saved roots, all-history backfill,",
+                "agent rules, autostart, and the initial sync are refreshed in one command.",
+                "`cockpit upgrade` is an alias.",
+            ],
+        ],
+        [
+            "upgrade",
+            [
+                "Usage: cockpit upgrade [same flags as cockpit update]",
+                "",
+                "Alias for `cockpit update`.",
+            ],
+        ],
+        [
+            "do-everything",
+            [
+                "Usage: cockpit do-everything [--workspace <path>] [--dashboard-url <url>] [--update-tag <tag>] [--dry-run] [--json]",
+                "",
+                "Converges a blank, existing, or reused intern machine: latest CLI, interactive auth and collection-root recovery when needed, saved roots, autostart, all-history backfill, raw-evidence GC, and sync freshness.",
+                "`cockpit fix` is an alias.",
+                "Maintainer canary: use `--update-tag next` so self-update and re-exec stay on the prerelease candidate.",
+                "--dry-run prints the checks and would-fix steps without writing config, plists, cursors, or install telemetry.",
+            ],
+        ],
+        [
+            "fix",
+            [
+                "Usage: cockpit fix [same flags as cockpit do-everything]",
+                "",
+                "Alias for `cockpit do-everything`.",
+            ],
+        ],
+        [
+            "login",
+            [
+                "Usage: cockpit login [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--no-auth] [--json]",
+                "",
+                "Signs in with an email OTP when interactive, starts dashboard device pairing, and stores the approved local session.",
+                "Omit --dashboard-url for the production dashboard; pass it only for staging/custom dashboards.",
+            ],
+        ],
+        [
+            "pair",
+            [
+                "Usage: cockpit pair [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--no-auth] [--json]",
+                "",
+                "Alias for `cockpit login`.",
+            ],
+        ],
+        ["logout", ["Usage: cockpit logout [--json]", "", "Removes the local device session."]],
+        [
+            "start",
+            [
+                "Usage: cockpit start [--ticket <id>|--clear-ticket] [--topic <label>] [--topic-summary <summary>] [--intent <intent>] [--phase <phase>] [--intent-confidence <0..1>] [--workspace <path>] [--branch <name>] [--json]",
+                "",
+                "Starts local ambient capture. Parent folders start each child git worktree.",
+                "Add --ticket only when the work already has a visible ticket; omit it to preserve an existing binding.",
+                "Use --clear-ticket to intentionally return the context to general ambient capture.",
+                "Use --topic/--intent/--phase for planning, discovery, and learning work that has no ticket yet.",
+                "Supported intents: implementation, bug_fix, root_cause_analysis, planning, discovery, review, testing, documentation, release, learning, coordination, maintenance, analysis, unknown, other.",
+                "Supported phases: planning, discovery, implementation, debugging, review, testing, documentation, release, handoff, analysis, unknown, other.",
+                "`--repo <path>` remains supported as a backward-compatible alias; use --workspace in agent guidance.",
+            ],
+        ],
+        [
+            "sync",
+            [
+                "Usage: cockpit sync [--workspace <path>] [--dashboard-url <url>] [--json]",
+                "",
+                "Uploads latest local ambient envelope(s), or spools safe retries if blocked.",
+                "Omit --dashboard-url for normal production sync; pass it only for staging/custom dashboards or forced re-pairing.",
+                "`--repo <path>` remains supported as a backward-compatible alias.",
+                "Parent folders sync each child git worktree; Codex AND Claude Code JSONL",
+                "transcripts (and Claude subagent sidecars) are attributed to repos",
+                "deterministically and ambiguous transcripts are retained as unattributed",
+                "instead of being duplicated across repos. Use `cockpit sessions` to see why",
+                "a session is or is not collected.",
+                "Newly discovered repos get a general ambient work context automatically.",
+                "Discovery scans 3 folder levels and up to 50 repos by default; tune with",
+                "--max-depth and --max-repos.",
+                "Also self-updates the CLI from npm latest once per day, strictly after",
+                "collection finishes; set COCKPIT_DISABLE_AUTO_UPDATE=1 to freeze the",
+                "installed version during incident triage.",
+            ],
+        ],
+        [
+            "analyze",
+            [
+                "Usage: cockpit analyze [--workspace <path>] [--dashboard-url <url>] [--json]",
+                "",
+                "Uploads the latest local ambient evidence, then queues one analysis job.",
+                "The command returns after the batch is queued; view status and results in My Work.",
+                "Omit --dashboard-url for production; pass it only for staging/custom dashboards.",
+                "`--repo <path>` remains supported as a backward-compatible alias.",
+            ],
+        ],
+        [
+            "backfill",
+            [
+                "Usage: cockpit backfill (--since-days <n>|--all) [--source codex|claude] [--dry-run] [--max-files <n>] [--max-depth <n>] [--max-repos <n>] [--yes] [--workspace <path>] [--json]",
+                "",
+                "Backfills historical Codex and Claude Code session evidence using the saved collection roots from local config when --workspace is omitted.",
+                "Omit --source to scan both sources; there is no --source all literal.",
+                "The non-all window is capped at the collector session paired_at timestamp.",
+                "--all requires a dry-run review and TTY confirmation; pass --yes for headless agent runs.",
+                "Repo discovery scans 3 folder levels and up to 50 repos by default.",
+                "Raise --max-depth or --max-repos when a partial result reports a discovery cap.",
+                "--dry-run validates the paired collector and dashboard reachability, prints the same summary tables, and writes nothing.",
+            ],
+        ],
+        [
+            "status",
+            [
+                "Usage: cockpit status [--workspace <path>] [--json]",
+                "",
+                "Prints install, pairing, active work, upload, and retry state.",
+                "`--repo <path>` remains supported as a backward-compatible alias.",
+            ],
+        ],
+        [
+            "sessions",
+            [
+                "Usage: cockpit sessions [--source codex|claude] [--since-days <n>|--all] [--workspace <path>] [--json]",
+                "",
+                "Read-only: re-runs Codex + Claude session attribution and prints each",
+                "session's id, source, state, reason, scores, signals, and per-sidecar",
+                "skip reasons. No upload, no cursor writes. Answers \"why is session X",
+                "missing?\" locally — counts and labels only, never paths or content.",
+                "--since-days uses the same paired_at cap as `cockpit backfill`; --all scans the full local history.",
+                "`--repo <path>` remains supported as a backward-compatible alias.",
+            ],
+        ],
+        [
+            "serve",
+            [
+                "Usage: cockpit serve [--port <port>] [--workspace <path>]",
+                "",
+                "Starts the local collector HTTP status server.",
+                "`--repo <path>` remains supported as a backward-compatible alias.",
+            ],
+        ],
+        [
+            "autostart",
+            [
+                "Usage: cockpit autostart [install|uninstall|status] [--workspace <path>] [--dashboard-url <url>] [--interval-seconds <n>] [--json]",
+                "",
+                "Installs background sync through launchd on Apple Silicon macOS or a",
+                "per-user Task Scheduler task on native Windows.",
+                "Runs `cockpit sync` every 15 min by default and survives reboots;",
+                "the Windows task runs while the user is signed in.",
+                "Action defaults to `install`. `--workspace` is the parent work folder to sync.",
+                "`--repo <path>` remains supported as a backward-compatible alias.",
+                "Omit --dashboard-url for production; pass it only for staging/custom dashboards.",
+                "See docs/runbooks/cockpit-launchd-sync.md and",
+                "docs/runbooks/cockpit-windows-task-scheduler-sync.md.",
+            ],
+        ],
+        [
+            "agent-rules",
+            [
+                "Usage: cockpit agent-rules [install|uninstall|status] [--host codex|claude|all] [--workspace <path>] [--json]",
+                "",
+                "Installs a managed Cockpit Ticket Binding block into ~/.codex/AGENTS.md",
+                "and ~/.claude/CLAUDE.md by default. Pass --host to manage only one.",
+                "The block is scoped to --workspace, or the current directory when omitted,",
+                "so Codex and Claude only run Cockpit ticket binding inside that onboarded folder.",
+                "Action defaults to `install`.",
+            ],
+        ],
+        [
+            "release",
+            [
+                "Usage: cockpit release [--dry-run] [--skip-checks] [--tag <tag>] [--access <public|restricted>] [--otp <code>]",
+                "",
+                "Maintainer-only helper. Run from inside the bli-cockpit repo checkout.",
+                "Requires a clean `main` branch and runs `git pull --ff-only` before publishing.",
+                "Delegates to `npm run publish:public -- ...` so public packages are",
+                "built, checked, and published in the safe telemetry-core then CLI order.",
+            ],
+        ],
+    ]);
+    return (helpByCommand.get(command) ?? [localCommandHelp()]).join("\n");
+}
+/** `cockpit <command> --help` — the command name alone, with only the help flag. */
+export function isLocalHelpRequest(argv) {
+    const command = argv[0];
+    if (!command || !rootCommandNames.has(command))
+        return false;
+    return argv.length === 2 && (argv[1] === "--help" || argv[1] === "-h");
+}