@bli-cockpit/cli 0.2.8 → 0.2.10

package/dist/commands/backfill.js

@@ -19,19 +19,21 @@ const BACKFILL_MAX_CONSECUTIVE_FAILURES = 3;
 const ALL_BACKFILL_SINCE_MINUTES = 20 * 365 * 24 * 60;
 const DEFAULT_DISCOVERY_MAX_DEPTH = 3;
 const DEFAULT_DISCOVERY_MAX_REPOS = 50;
+// Window a bare `cockpit backfill` uses. Wide enough to cover a new machine's
+// recent history and an intern who went quiet for a few weeks, narrow enough
+// that it is not the whole-history scan `--all` deliberately gates.
+export const DEFAULT_BACKFILL_SINCE_DAYS = 30;
 export async function runBackfillCommand(command, io) {
+    // A bare `cockpit backfill` used to refuse and print three lines telling the
+    // operator to pick a window. That put a mandatory flag on the command that
+    // matters most for coverage, so the honest default is to run the common case
+    // and say plainly which window was chosen. `--all` stays explicit because it
+    // is the expensive, whole-history scan.
+    let effective = command;
     if (!command.all && command.sinceDays === undefined) {
-        const message = bareBackfillMessage();
-        const retryCommand = backfillRetryCommand(command);
-        writeLine(io.stderr, message);
-        if (command.json) {
-            writeLine(io.stdout, JSON.stringify({
-                status: "blocked",
-                reason: "missing_window",
-                retry_command: retryCommand,
-            }, null, 2));
-        }
-        return 1;
+        effective = { ...command, sinceDays: DEFAULT_BACKFILL_SINCE_DAYS };
+        const notice = defaultBackfillWindowNotice();
+        writeLine(command.json ? io.stderr : io.stdout, notice);
     }
     if (command.all && !command.yes && !isInteractiveStdin(io)) {
         const message = "--all requires TTY confirmation; pass --yes for agent runs.";
@@ -46,8 +48,8 @@ export async function runBackfillCommand(command, io) {
         }
         return 1;
     }
-    const result = await runBackfill(command, io);
-    if (command.json) {
+    const result = await runBackfill(effective, io);
+    if (effective.json) {
         writeLine(io.stdout, JSON.stringify(result, null, 2));
         return result.status === "complete" ? 0 : 1;
     }
@@ -508,11 +510,11 @@ export async function runBackfill(command, io) {
         await lock.handle.release();
     }
 }
-function bareBackfillMessage() {
+function defaultBackfillWindowNotice() {
     return [
-        "cockpit backfill needs an explicit window.",
-        "Use `cockpit backfill --since-days N` for post-pairing history; the effective start is capped at the collector paired_at timestamp.",
-        "Use `cockpit backfill --all` only after reviewing a dry-run; on headless agent runs add `--yes`.",
+        `No window given — backfilling the last ${DEFAULT_BACKFILL_SINCE_DAYS} days.`,
+        "The effective start is capped at the collector paired_at timestamp.",
+        "Use `cockpit backfill --since-days N` for a different window, or `cockpit backfill --all` for the full local history (review a dry-run first; add `--yes` on headless agent runs).",
     ].join("\n");
 }
 /**

package/dist/commands/local-args.js

@@ -7,6 +7,18 @@ import { DEFAULT_DASHBOARD_URL } from "../local-state.js";
 import { DEFAULT_AUTOSTART_INTERVAL_SECONDS } from "../autostart.js";
 import { IntentSourceSchema, WorkIntentSchema, WorkPhaseSchema, } from "@bli-cockpit/telemetry-core";
 const WORK_ROOT_FLAGS = ["--repo", "--workspace"];
+// The six human "set my machine up" doors. They are one thing wearing six
+// hats, so they all run the convergence command — but they keep accepting the
+// flags they always accepted, because DMs, runbooks and AGENTS.md rules across
+// the fleet still spell them out.
+export const DOCTOR_SETUP_ALIASES = [
+    "install",
+    "onboard",
+    "login",
+    "pair",
+    "update",
+    "upgrade",
+];
 export function parseLocalArgs(argv) {
     const command = argv[0];
     switch (command) {
@@ -15,6 +27,10 @@ export function parseLocalArgs(argv) {
         case "update":
         case "upgrade":
             return parseUpdateArgs(command, argv.slice(1));
+        // NOT yet aliased to the convergence command. `onboard --ticket <id>` binds
+        // work to a ticket, and routing it here would accept the flag and drop the
+        // binding with no error — the silent breakage BLI-2490 explicitly forbids.
+        // Aliasing lands once the convergence run honours --ticket. See BLI-2494.
         case "do-everything":
         case "fix":
             return parseDoctorArgs(command, argv.slice(1));
@@ -114,15 +130,46 @@ function parseUpdateArgs(alias, args) {
     };
 }
 function parseDoctorArgs(alias, args) {
+    // The allowed set is the UNION of what the six setup doors used to accept.
+    // An alias that silently rejected a flag its own docs told people to pass
+    // would be a worse dead end than the one we are removing.
     const values = parseNamedArgs(args, {
         allowedFlags: [
+            "--home",
+            "--repo",
             "--workspace",
             "--dashboard-url",
             "--update-tag",
             "--dry-run",
             "--json",
+            "--allow-home-root",
+            "--max-depth",
+            "--max-repos",
+            // Accepted and ignored: the convergence run works these out itself.
+            // Rejecting them would break existing DMs and runbooks for no gain.
+            "--email",
+            "--device-name",
+            "--ticket",
+            "--branch",
+            "--no-auth",
+            "--poll-interval-ms",
+            "--timeout-ms",
+        ],
+        valueFlags: [
+            "--home",
+            "--repo",
+            "--workspace",
+            "--dashboard-url",
+            "--update-tag",
+            "--max-depth",
+            "--max-repos",
+            "--email",
+            "--device-name",
+            "--ticket",
+            "--branch",
+            "--poll-interval-ms",
+            "--timeout-ms",
         ],
-        valueFlags: ["--workspace", "--dashboard-url", "--update-tag"],
     });
     assertNoPositionals(values.positionals, alias);
     const updateTag = optionalNonEmpty(values.flags.get("--update-tag"));
@@ -132,11 +179,16 @@ function parseDoctorArgs(alias, args) {
     return {
         kind: "doctor",
         alias,
-        repoRoot: optionalNonEmpty(values.flags.get("--workspace")),
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        repoRoot: optionalNonEmpty(workRootFlagValue(values)),
+        collectionRoots: optionalNonEmptyList(workRootFlagValues(values)),
         dashboardUrl: normalizeUrl(values.flags.get("--dashboard-url") ?? DEFAULT_DASHBOARD_URL),
         updateTag,
         dryRun: values.booleans.has("--dry-run"),
         json: values.booleans.has("--json"),
+        allowHomeRoot: values.booleans.has("--allow-home-root"),
+        maxDepth: optionalPositiveInteger(values.flags.get("--max-depth"), "--max-depth"),
+        maxRepos: optionalPositiveInteger(values.flags.get("--max-repos"), "--max-repos"),
     };
 }
 function parseInstallArgs(args) {

package/dist/commands/local.js

@@ -10,6 +10,7 @@ import { inspectBackfillLock } from "../backfill-lock.js";
 import { parseLocalArgs, normalizeUrl } from "./local-args.js";
 import { autostartStatus, installAutostartAgent, uninstallAutostartAgent, } from "../autostart.js";
 import { DEFAULT_DASHBOARD_URL, ensureLocalCollectorConfig, getCollectorRuntimePaths, inspectLocalCollectorStatus, installLocalCollector, logoutLocalCollector, pairLocalCollector, LOCAL_COLLECTOR_VERSION, readLocalCollectorConfig, readLocalCollectorSessionFile, readLocalSessionReference, startLocalWorkContext, } from "../local-state.js";
+import { redactSecretLikeContent, } from "@bli-cockpit/telemetry-core";
 import { CODEX_ATTRIBUTION_SCAN_WINDOW_SESSION_LIMIT, CODEX_ATTRIBUTION_SCAN_WINDOW_MINUTES, defaultCodexSessionDirs, scanAndAttributeCodexSessions, } from "../adapters/codex-attribution.js";
 import { scanAndAttributeClaudeSessions } from "../adapters/claude-attribution.js";
 import { backfillCompletionCovers, emptyBackfillCursorState, prepareBackfillCursorForScope, readBackfillCompletionMarker, readBackfillCursor, } from "../cursors/backfill-cursor.js";
@@ -367,6 +368,9 @@ async function runInstall(command, io) {
         addInstallEvent(installEvents, "home_root_optin", "ok");
     }
     const result = await installLocalCollector(resolved.command);
+    // Same invariant as the onboarding path: never report a successful install
+    // over a config that saved no usable collection root.
+    await assertCollectionRootPersisted(resolved.command.homeDir);
     addInstallEvent(installEvents, "install", "ok");
     if (command.json) {
         writeLine(io.stdout, JSON.stringify(result, null, 2));
@@ -707,6 +711,15 @@ export async function reportInstallEventsBestEffort(options) {
                 ...(event.error_code
                     ? { error_code: sanitizeInstallErrorCode(event.error_code) }
                     : {}),
+                // Already redacted and capped at the point it was produced; bounded
+                // again here because this mapping is what the server contract sees.
+                ...(event.error_detail
+                    ? {
+                        error_detail: event.error_detail
+                            .trim()
+                            .slice(0, SYNC_ERROR_DETAIL_MAX_CHARS),
+                    }
+                    : {}),
                 ...(event.at ? { at: event.at } : {}),
             })),
         });
@@ -1199,7 +1212,7 @@ async function resolveOnboardingRootsForCommand(command, io) {
     };
 }
 async function persistOnboardingRootConfig(command, resolution) {
-    return installLocalCollector({
+    const result = await installLocalCollector({
         homeDir: command.homeDir,
         repoRoot: resolution.primaryRoot,
         repoRoots: resolution.collectionRoots,
@@ -1207,6 +1220,88 @@ async function persistOnboardingRootConfig(command, resolution) {
         dashboardUrl: command.dashboardUrl,
         deviceName: command.deviceName,
     });
+    await assertCollectionRootPersisted(command.homeDir);
+    return result;
+}
+/**
+ * Setup does not get to claim success on its own say-so.
+ *
+ * Onboarding used to write the config and report success without ever reading
+ * it back. Savina's onboard did exactly that, persisted nothing, and every
+ * scheduled sync afterwards threw `collection_root_required` into a log nobody
+ * reads — twelve consecutive failures, six days at 3 uploaded of 195, found
+ * only by hand-querying the database. BLI-1986 fixed one path into that state;
+ * this closes the state itself.
+ *
+ * So we read the config back through the SAME resolution the scheduled sync
+ * will use, and fail here — in front of a human who can still fix it — rather
+ * than silently handing back a machine that will never collect.
+ */
+export async function assertCollectionRootPersisted(homeDir) {
+    const config = await readLocalCollectorConfig(getCollectorRuntimePaths(homeDir)).catch(() => null);
+    const saved = normalizeCollectionRoots(config?.default_repo_paths ?? []);
+    if (saved.length === 0) {
+        throw new Error(`${COLLECTION_ROOT_REQUIRED}: ${collectionRootNotPersistedMessage(homeDir)}`);
+    }
+    // Present in the file is not the same as usable. A root that no longer
+    // exists on disk resolves to nothing at sync time, which is the same silent
+    // dead end arriving one step later.
+    const usable = [];
+    for (const root of saved) {
+        if (await directoryExists(root))
+            usable.push(root);
+    }
+    if (usable.length === 0) {
+        throw new Error(`${COLLECTION_ROOT_REQUIRED}: ${collectionRootMissingOnDiskMessage(saved, homeDir)}`);
+    }
+    return usable;
+}
+// Placeholders like <path-to-your-work-folder> make a person stop and think.
+// These print real, paste-able commands with this machine's actual paths in
+// them, so the fix is a copy away rather than a puzzle.
+function collectionRootNotPersistedMessage(homeDir) {
+    const home = path.resolve(homeDir ?? os.homedir());
+    return [
+        "Setup finished without saving a collection root, so this machine would never collect anything.",
+        "Nothing was saved, so nothing is broken — setup just did not finish.",
+        "",
+        "Fix it by running ONE of these:",
+        "",
+        "  # Sync everything on this machine (what most people want on a work laptop)",
+        "  cockpit do-everything --allow-home-root",
+        "",
+        "  # Or sync one folder — replace the path with where your projects live",
+        `  cockpit do-everything --workspace ${path.join(home, "BLI")}`,
+        "",
+        "  # Or answer the folder question interactively",
+        "  cockpit do-everything",
+        "",
+        "Then check it worked:",
+        "  cockpit status",
+    ].join("\n");
+}
+function collectionRootMissingOnDiskMessage(saved, homeDir) {
+    const home = path.resolve(homeDir ?? os.homedir());
+    return [
+        "Cockpit is set up to collect from a folder that is not on this machine:",
+        ...saved.map((root) => `  ${root}`),
+        "",
+        "That usually means the folder was renamed, moved, or deleted since setup.",
+        "",
+        "Fix it by running ONE of these:",
+        "",
+        "  # Point Cockpit at where your projects actually live now",
+        `  cockpit do-everything --workspace ${path.join(home, "BLI")}`,
+        "",
+        "  # Or sync everything on this machine and stop worrying about the path",
+        "  cockpit do-everything --allow-home-root",
+        "",
+        "Not sure where your projects are? This lists the folders Cockpit can see:",
+        "  cockpit status",
+    ].join("\n");
+}
+async function directoryExists(dir) {
+    return stat(dir).then((stats) => stats.isDirectory(), () => false);
 }
 async function runDoctorLogin(command, io) {
     return runLogin({
@@ -1218,9 +1313,15 @@ async function runDoctorLogin(command, io) {
 }
 async function resolveAndSaveDoctorRoots(command, io) {
     const rootCommand = {
+        homeDir: command.homeDir,
         repoRoot: command.repoRoot,
+        collectionRoots: command.collectionRoots,
         dashboardUrl: command.dashboardUrl,
         json: command.json,
+        // Interactively this is not needed — the convergence run reaches the
+        // home-folder consent prompt and Enter accepts it. The flag is the
+        // headless equivalent for scripted and scheduled runs.
+        allowHomeRoot: command.allowHomeRoot,
     };
     const resolution = await resolveOnboardingRootsForCommand(rootCommand, io);
     await persistOnboardingRootConfig(rootCommand, resolution);
@@ -1974,6 +2075,7 @@ async function runSync(command, io) {
                     step: "sync_complete",
                     status: "fail",
                     error_code: classifySyncHealthError(error),
+                    error_detail: redactedSyncErrorDetail(error),
                 },
             ],
             json: command.json,
@@ -2048,7 +2150,7 @@ async function runSyncWithHealthReceipt(command, io) {
         await lock.handle.release();
     }
 }
-function classifySyncHealthError(error) {
+export function classifySyncHealthError(error) {
     const message = errorMessage(error);
     if (/auth|token|session|unauthorized|forbidden|401|403/iu.test(message)) {
         return "auth_failed";
@@ -2056,11 +2158,33 @@ function classifySyncHealthError(error) {
     if (/fetch|network|enotfound|econnrefused|timeout/iu.test(message)) {
         return "network_failed";
     }
-    if (/collection.root|workspace|repo|worktree/iu.test(message)) {
+    // Anchored on the code the collector actually throws rather than on loose
+    // vocabulary. The old test matched /collection.root|workspace|repo|worktree/
+    // against the message, so any failure that merely mentioned a repo was filed
+    // as a collection-root failure and the real reason was lost (BLI-2492).
+    if (message.includes(COLLECTION_ROOT_REQUIRED) ||
+        /collection root/iu.test(message)) {
         return "collection_root_failed";
     }
     return "sync_failed";
 }
+// The bucket above is for aggregation. This is the reason — the actual message,
+// redacted on the machine that produced it, before it ever leaves.
+//
+// Error text can carry absolute paths and, on some auth failures, token-shaped
+// fragments. It goes through the same deterministic redaction the collector
+// already applies to evidence, and is capped so one pathological stack trace
+// cannot dominate a health receipt.
+export const SYNC_ERROR_DETAIL_MAX_CHARS = 600;
+export function redactedSyncErrorDetail(error) {
+    const message = errorMessage(error).replace(/\s+/gu, " ").trim();
+    const { text } = redactSecretLikeContent(message, {
+        appliedBy: "local_collector",
+    });
+    return text.length > SYNC_ERROR_DETAIL_MAX_CHARS
+        ? `${text.slice(0, SYNC_ERROR_DETAIL_MAX_CHARS - 1)}…`
+        : text;
+}
 async function runSyncLocked(command, io) {
     const collectionRoots = await resolveSyncCollectionRoots(command);
     const worktrees = await discoverCommandWorktrees(collectionRoots, {

package/dist/commands/public-root.js

@@ -2,13 +2,20 @@ import { localCommandHelp, runLocalCockpitCli, rootCommandNames } from "./local.
 
 export async function runCockpitCli(argv, io) {
   const command = argv[0];
-  if (!command || command === "--help" || command === "-h") {
+  // Bare `cockpit` runs the convergence command instead of printing a
+  // usage wall (BLI-2490). This file is GENERATED and does not import
+  // commands/root.ts, so the routing has to be mirrored here or the fix
+  // ships to nobody.
+  if (!command) {
+    return runLocalCockpitCli(["do-everything"], io);
+  }
+  if (command === "--help" || command === "-h") {
     writeLine(io?.stdout ?? process.stdout, cockpitHelp());
     return 0;
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.8");
+    writeLine(io?.stdout ?? process.stdout, "0.2.10");
     return 0;
   }
 
@@ -24,6 +31,11 @@ export async function runCockpitCli(argv, io) {
 
 function cockpitHelp() {
   return [
+    "Just run `cockpit do-everything` — it takes this machine from nothing to collecting and asks you anything it needs.",
+    "(Running plain `cockpit` does the same thing.)",
+    "",
+    "Everything below is for scripting and agents.",
+    "",
     "Usage:",
     localCommandHelp(),
     "",

package/dist/onboarding-roots.js

@@ -6,7 +6,7 @@ import { isSamePath, normalizeCollectionRoots, } from "./root-normalization.js";
 export const COLLECTION_ROOT_REQUIRED = "collection_root_required";
 export function homeRootConsentPrompt(homeDirInput) {
     const homeDir = path.resolve(homeDirInput ?? os.homedir());
-    return `You're in your home folder (${homeDir}).\n  Sync ALL projects on this machine? Every git repo under here gets captured now and in the future.\n  This is a work machine — exclude personal projects yourself if needed.  [y/N]: `;
+    return `You're in your home folder (${homeDir}).\n  Sync ALL projects on this machine? Every git repo under here gets captured now and in the future.\n  This is a work machine — exclude personal projects yourself if needed.\n  Press Enter to sync everything, or answer n to name one folder instead.  [Y/n]: `;
 }
 export const HOME_ROOT_DECLINE_PATH_PROMPT = "Okay — which folder should I sync? Enter the full path to your work directory: ";
 export const HOME_ROOT_NO_FOLDER_CHOSEN_MESSAGE = "No folder chosen. Re-run: cockpit onboard --workspace <path-to-your-work-folder>";
@@ -223,9 +223,20 @@ async function promptForHomeRootOptIn(options, rejections) {
     }
     return promptForDeclinedHomeRoot(options, homeDir);
 }
+// Bare Enter is the answer most people give, so it has to mean the thing that
+// collects. It used to mean decline, and the decline path then asks for a
+// folder that is not home — which a person who keeps every project directly in
+// their home folder cannot answer. They finished onboarding with zero roots and
+// every session on the machine was legitimately out of scope forever after.
+// Anything that isn't recognisably yes still routes to the decline prompt,
+// where a typed path is recoverable rather than lost.
 function isHomeRootYes(raw) {
     const answer = raw.trim().split(/\s+/u)[0]?.toLowerCase() ?? "";
-    return answer === "y" || answer === "yes";
+    if (answer === "")
+        return true;
+    if (answer.startsWith("n"))
+        return false;
+    return answer.startsWith("y");
 }
 async function promptForDeclinedHomeRoot(options, homeDir) {
     const prompt = requirePrompt(options);

package/dist/spool/install-event-outbox.js

@@ -23,6 +23,11 @@ export async function enqueueInstallEventEntry(paths, options) {
             step: event.step,
             status: event.status,
             ...(event.error_code ? { error_code: event.error_code } : {}),
+            // Spooling must not quietly downgrade a receipt. This mapping copies
+            // named fields, so a new one has to be added here too — otherwise a
+            // failure that could not be delivered immediately loses its reason on
+            // the way to disk and replays as a bare bucket (BLI-2492).
+            ...(event.error_detail ? { error_detail: event.error_detail } : {}),
             at: event.at ?? createdAt,
         })),
     };
@@ -157,6 +162,9 @@ function parseEvent(value) {
         ...(stringValue(record["error_code"])
             ? { error_code: stringValue(record["error_code"]) }
             : {}),
+        ...(stringValue(record["error_detail"])
+            ? { error_detail: stringValue(record["error_detail"]) }
+            : {}),
         at,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "private": false,
   "type": "module",
   "bin": {
@@ -23,9 +23,9 @@
     "pretypecheck": "npm run build",
     "typecheck": "node -e \"await import('./dist/commands/public-root.js')\"",
     "pretest": "npm run build",
-    "test": "node dist/cli.js --help && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
+    "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
   },
   "dependencies": {
-    "@bli-cockpit/telemetry-core": "0.1.14"
+    "@bli-cockpit/telemetry-core": "0.1.15"
   }
 }