@productbrain/cli 0.1.0-beta.5 → 0.1.0-beta.5060

package/dist/commands/constellation.js

@@ -0,0 +1,33 @@
+/**
+ * pb constellation <entry-id> — compound view: entry + grouped relations.
+ * BET-181 Slice 3: agents can assess a shaped bet from this single output.
+ *
+ * Chain: DEC-299 (agent-native, JSON-default), STD-65 (structured, parseable, minimal),
+ * ARCH-25 (orient view model pattern), DEC-99 (ALLOWED_RELATION_TYPES as SSOT)
+ */
+import { getConfigOrGuide } from '../lib/config.js';
+import { kernelCall } from '../lib/client.js';
+import { runCliCommand } from '../lib/runner.js';
+import { formatConstellation } from '../formatters/constellation.js';
+import { CLIError, ErrorCode } from '../lib/errors.js';
+export async function runConstellation(options) {
+    const config = await getConfigOrGuide(() => runConstellation(options));
+    if (!config)
+        return;
+    await runCliCommand({
+        fn: () => kernelCall('chain.getConstellation', {
+            entryId: options.entryId,
+        }),
+        formatPretty: (result) => {
+            if (!result?.entry) {
+                throw new CLIError(`Entry "${options.entryId}" not found.`, {
+                    code: ErrorCode.VALIDATION_FAILED,
+                    category: 'validation',
+                    guidance: 'Check the entry ID and try again. Use `pb search` to find entries.',
+                });
+            }
+            return formatConstellation(result);
+        },
+    });
+}
+//# sourceMappingURL=constellation.js.map

package/dist/commands/constellation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constellation.js","sourceRoot":"","sources":["../../src/commands/constellation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAA4B,MAAM,gCAAgC,CAAC;AAC/F,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAEvD,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,OAA4B;IACjE,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,GAAG,EAAE,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC;IACvE,IAAI,CAAC,MAAM;QAAE,OAAO;IAEpB,MAAM,aAAa,CAAsB;QACvC,EAAE,EAAE,GAAG,EAAE,CACP,UAAU,CAAqD,wBAAwB,EAAE;YACvF,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAC;QACJ,YAAY,EAAE,CAAC,MAAM,EAAE,EAAE;YACvB,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC;gBACnB,MAAM,IAAI,QAAQ,CAAC,UAAU,OAAO,CAAC,OAAO,cAAc,EAAE;oBAC1D,IAAI,EAAE,SAAS,CAAC,iBAAiB;oBACjC,QAAQ,EAAE,YAAY;oBACtB,QAAQ,EAAE,oEAAoE;iBAC/E,CAAC,CAAC;YACL,CAAC;YACD,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC;QACrC,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/commands/context.d.ts

@@ -1,6 +1,7 @@
 /**
  * pb context <entry-id> — gather and display constellation context.
- * Pipe-friendly: when stdout is not a TTY, output clean markdown (no ANSI codes).
+ * BET-181 Slice 0: routes through runCliCommand for JSON-default output.
+ * Previously: pipe-friendly via process.stdout.isTTY — now delegated to runner.
  */
 export declare function runContext(options: {
     entryId: string;

package/dist/commands/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/commands/context.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,wBAAsB,UAAU,CAAC,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAe5E"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/commands/context.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,wBAAsB,UAAU,CAAC,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB5E"}

package/dist/commands/context.js

@@ -1,22 +1,33 @@
 /**
  * pb context <entry-id> — gather and display constellation context.
- * Pipe-friendly: when stdout is not a TTY, output clean markdown (no ANSI codes).
+ * BET-181 Slice 0: routes through runCliCommand for JSON-default output.
+ * Previously: pipe-friendly via process.stdout.isTTY — now delegated to runner.
  */
 import { getConfigOrGuide } from '../lib/config.js';
-import { mcpCall } from '../lib/client.js';
+import { kernelCall } from '../lib/client.js';
+import { runCliCommand, isJsonMode } from '../lib/runner.js';
 import { formatContext } from '../formatters/context.js';
+import { CLIError, ErrorCode } from '../lib/errors.js';
 export async function runContext(options) {
     const config = await getConfigOrGuide(() => runContext(options));
     if (!config)
         return;
-    const result = await mcpCall('chain.gatherContext', {
-        entryId: options.entryId,
-        maxHops: 2,
+    await runCliCommand({
+        fn: () => kernelCall('chain.gatherContext', {
+            entryId: options.entryId,
+            maxHops: 2,
+        }),
+        formatPretty: (result) => {
+            if (!result?.root) {
+                throw new CLIError(`Entry "${options.entryId}" not found.`, {
+                    code: ErrorCode.VALIDATION_FAILED,
+                    category: 'validation',
+                    guidance: 'Check the entry ID and try again. Use `pb search` to find entries.',
+                });
+            }
+            // In pretty mode, use tty: true for rich terminal output
+            return formatContext(result, { tty: !isJsonMode() });
+        },
     });
-    if (!result?.root) {
-        throw new Error(`Entry "${options.entryId}" not found.`);
-    }
-    const tty = Boolean(process.stdout.isTTY);
-    console.log(formatContext(result, { tty }));
 }
 //# sourceMappingURL=context.js.map

package/dist/commands/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/commands/context.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAsB,MAAM,0BAA0B,CAAC;AAE7E,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,OAA4B;IAC3D,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC;IACjE,IAAI,CAAC,MAAM;QAAE,OAAO;IAEpB,MAAM,MAAM,GAAG,MAAM,OAAO,CAAgB,qBAAqB,EAAE;QACjE,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,OAAO,EAAE,CAAC;KACX,CAAC,CAAC;IAEH,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,UAAU,OAAO,CAAC,OAAO,cAAc,CAAC,CAAC;IAC3D,CAAC;IAED,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC1C,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;AAC9C,CAAC"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/commands/context.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAsB,MAAM,0BAA0B,CAAC;AAC7E,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAEvD,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,OAA4B;IAC3D,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC;IACjE,IAAI,CAAC,MAAM;QAAE,OAAO;IAEpB,MAAM,aAAa,CAAgB;QACjC,EAAE,EAAE,GAAG,EAAE,CAAC,UAAU,CAAkD,qBAAqB,EAAE;YAC3F,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,OAAO,EAAE,CAAC;SACX,CAAC;QACF,YAAY,EAAE,CAAC,MAAM,EAAE,EAAE;YACvB,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC;gBAClB,MAAM,IAAI,QAAQ,CAAC,UAAU,OAAO,CAAC,OAAO,cAAc,EAAE;oBAC1D,IAAI,EAAE,SAAS,CAAC,iBAAiB;oBACjC,QAAQ,EAAE,YAAY;oBACtB,QAAQ,EAAE,oEAAoE;iBAC/E,CAAC,CAAC;YACL,CAAC;YACD,yDAAyD;YACzD,OAAO,aAAa,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QACvD,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/commands/cross-cut.d.ts

@@ -0,0 +1,11 @@
+/**
+ * pb cross-cut --type <relation-type> — structural aggregation across the workspace.
+ * BET-239 Slice 3: cross-cutting relation view.
+ *
+ * Shows all relations of a given type grouped by source collection.
+ * Chain: DEC-299 (agent-native, JSON-default), STD-65 (structured, parseable, minimal)
+ */
+export declare function runCrossCut(options: {
+    type: string;
+}): Promise<void>;
+//# sourceMappingURL=cross-cut.d.ts.map

package/dist/commands/cross-cut.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-cut.d.ts","sourceRoot":"","sources":["../../src/commands/cross-cut.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,wBAAsB,WAAW,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAW1E"}

package/dist/commands/cross-cut.js

@@ -0,0 +1,23 @@
+/**
+ * pb cross-cut --type <relation-type> — structural aggregation across the workspace.
+ * BET-239 Slice 3: cross-cutting relation view.
+ *
+ * Shows all relations of a given type grouped by source collection.
+ * Chain: DEC-299 (agent-native, JSON-default), STD-65 (structured, parseable, minimal)
+ */
+import { getConfigOrGuide } from '../lib/config.js';
+import { kernelCall } from '../lib/client.js';
+import { runCliCommand } from '../lib/runner.js';
+import { formatCrossCut } from '../formatters/cross-cut.js';
+export async function runCrossCut(options) {
+    const config = await getConfigOrGuide(() => runCrossCut(options));
+    if (!config)
+        return;
+    await runCliCommand({
+        fn: () => kernelCall('chain.structuralAggregation', {
+            relationType: options.type,
+        }),
+        formatPretty: (result) => formatCrossCut(result, options.type),
+    });
+}
+//# sourceMappingURL=cross-cut.js.map

package/dist/commands/cross-cut.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-cut.js","sourceRoot":"","sources":["../../src/commands/cross-cut.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAuB,MAAM,4BAA4B,CAAC;AAEjF,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAAyB;IACzD,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;IAClE,IAAI,CAAC,MAAM;QAAE,OAAO;IAEpB,MAAM,aAAa,CAAiB;QAClC,EAAE,EAAE,GAAG,EAAE,CACP,UAAU,CAA0D,6BAA6B,EAAE;YACjG,YAAY,EAAE,OAAO,CAAC,IAAI;SAC3B,CAAC;QACJ,YAAY,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC;KAC/D,CAAC,CAAC;AACL,CAAC"}

package/dist/commands/direction.d.ts

@@ -0,0 +1,10 @@
+import { Command } from 'commander';
+export declare function runDirectionList(options: {
+    all?: boolean;
+}): Promise<void>;
+export declare function runDirectionRefresh(): Promise<void>;
+export declare function runDirectionDefer(entryId: string, options: {
+    reason: string;
+}): Promise<void>;
+export declare function createDirectionCommand(): Command;
+//# sourceMappingURL=direction.d.ts.map

package/dist/commands/direction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"direction.d.ts","sourceRoot":"","sources":["../../src/commands/direction.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgCpC,wBAAsB,gBAAgB,CAAC,OAAO,EAAE;IAAE,GAAG,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhF;AAED,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAQzD;AAED,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBnG;AAED,wBAAgB,sBAAsB,IAAI,OAAO,CAkBhD"}

package/dist/commands/direction.js

@@ -0,0 +1,79 @@
+import { Command } from 'commander';
+import { getConfigOrGuide } from '../lib/config.js';
+import { kernelCall, kernelCallWithSession } from '../lib/client.js';
+import { CLIError, ErrorCode } from '../lib/errors.js';
+import { runCliCommand } from '../lib/runner.js';
+import { readSession } from '../lib/session.js';
+import { formatDirectionList, formatDirectionRefresh, formatDirectionDefer, } from '../formatters/direction.js';
+/**
+ * `pb direction` — the upward direction trace, first strategy-level signal for bets (WP-582 B1,
+ * FEAT-1403, advisory only). Structurally mirrors packages/cli/src/commands/conflicts.ts: `list`
+ * is a plain read (kernelCall, no session); `refresh`/`defer` are session-attributed writes
+ * (kernelCallWithSession), same shape as conflicts' resolve verb.
+ */
+function requireDirectionSession() {
+    const session = readSession();
+    if (!session) {
+        throw new CLIError('No active session.', {
+            code: ErrorCode.SESSION_REQUIRED,
+            category: 'session',
+            guidance: 'Run `pb session start` before refreshing or deferring a direction-trace finding.',
+        });
+    }
+    return session;
+}
+export async function runDirectionList(options) {
+    const config = await getConfigOrGuide(() => runDirectionList(options));
+    if (!config)
+        return;
+    await runCliCommand({
+        fn: () => kernelCall('direction.list', {}),
+        formatPretty: (value) => formatDirectionList(value, { all: options.all }),
+    });
+}
+export async function runDirectionRefresh() {
+    const config = await getConfigOrGuide(() => runDirectionRefresh());
+    if (!config)
+        return;
+    requireDirectionSession();
+    await runCliCommand({
+        fn: () => kernelCallWithSession('direction.refresh', {}),
+        formatPretty: (value) => formatDirectionRefresh(value),
+    });
+}
+export async function runDirectionDefer(entryId, options) {
+    const config = await getConfigOrGuide(() => runDirectionDefer(entryId, options));
+    if (!config)
+        return;
+    if (!options.reason || options.reason.trim().length === 0) {
+        throw new CLIError('`--reason` is required.', {
+            code: ErrorCode.VALIDATION_FAILED,
+            category: 'validation',
+            guidance: 'Usage: pb direction defer <work-package-id> --reason "<why deferring>"',
+        });
+    }
+    requireDirectionSession();
+    await runCliCommand({
+        fn: () => kernelCallWithSession('direction.defer', {
+            entryId,
+            reason: options.reason,
+        }),
+        formatPretty: (value) => formatDirectionDefer(value),
+    });
+}
+export function createDirectionCommand() {
+    const command = new Command('direction').description('The upward direction trace — first strategy-level signal for work packages (advisory, WP-582)');
+    command.command('list')
+        .description('Read the latest direction-trace snapshot (top 5 challenged work packages, most-recently-updated first)')
+        .option('--all', 'Show every challenged work package, not just the top 5')
+        .action(runDirectionList);
+    command.command('refresh')
+        .description('Recompute the workspace-wide direction trace and store a fresh snapshot')
+        .action(runDirectionRefresh);
+    command.command('defer <work-package-id>')
+        .description('Record a bounded, logged deferral for a challenged work package (never an ack, never auto-related)')
+        .requiredOption('--reason <reason>', 'Why this work package is being deferred')
+        .action(runDirectionDefer);
+    return command;
+}
+//# sourceMappingURL=direction.js.map

package/dist/commands/direction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"direction.js","sourceRoot":"","sources":["../../src/commands/direction.ts"],"names":[],"mappings":"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"}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,18 @@
+/**
+ * pb doctor — health check for CLI configuration and connectivity.
+ *
+ * Runs a series of diagnostic checks (config file, API key, environment,
+ * server reachability, Node version, CLI version) and prints a summary.
+ * Does NOT require an active session — this is a diagnostic tool.
+ *
+ * --fix: auto-repair common configuration issues.
+ * --dry-run: preview what --fix would do without changing anything.
+ *
+ * WP-301 Slice 2 (base), WP-302 Slice 3 (--fix / --dry-run).
+ */
+export interface DoctorOptions {
+    fix?: boolean;
+    dryRun?: boolean;
+}
+export declare function runDoctor(opts?: DoctorOptions): Promise<void>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/commands/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAwUH,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,SAAS,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4FvE"}

package/dist/commands/doctor.js

@@ -0,0 +1,367 @@
+/**
+ * pb doctor — health check for CLI configuration and connectivity.
+ *
+ * Runs a series of diagnostic checks (config file, API key, environment,
+ * server reachability, Node version, CLI version) and prints a summary.
+ * Does NOT require an active session — this is a diagnostic tool.
+ *
+ * --fix: auto-repair common configuration issues.
+ * --dry-run: preview what --fix would do without changing anything.
+ *
+ * WP-301 Slice 2 (base), WP-302 Slice 3 (--fix / --dry-run).
+ */
+import { existsSync, writeFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { HOME_ENV_PATH, getConfigSafe, getPreviewBinding, readLocalProjectConfig, } from '../lib/config.js';
+import { DEFAULT_SITE_URL, isDevMode, resolveConnectRedeemUrl } from '../lib/constants.js';
+import { listProfiles, PROFILES_DIR } from '../lib/profiles.js';
+import { isInteractive } from '../lib/prompts.js';
+import { banner, formatCheck, cyan, yellow } from '../lib/style.js';
+import { isNewer, resolveLatestVersion, reportVersionSkewIfNew } from '../lib/update-check.js';
+import { trackEvent } from '../lib/telemetry.js';
+import { runUpgrade } from './upgrade.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * How .productbrain/config.local.json is configuring the CLI, or null when it is not.
+ *
+ * Ordered to match the resolution cascade (direct binding before profile pin) so the line doctor
+ * prints is the one that actually supplied the credential. Only `getPreviewBinding()` — the same
+ * predicate the PREVIEW banner uses — may call it a preview binding: a marker-less pair binds
+ * identically but gets no banner, so saying "preview" would promise a warning that never fires.
+ */
+function describeLocalBinding(localConfig) {
+    const file = '.productbrain/config.local.json';
+    // An exported PRODUCTBRAIN_API_KEY wins step 1 of the cascade, so loadEnv() reads no binding out
+    // of this file at all. Describing it as the binding names the wrong tenant, and on a
+    // `preview: true` file it asserts "no preview marker" — getPreviewBinding() returns null under an
+    // env override, so the marker-less branch below would claim a marker that is sitting right there.
+    // Only report the shadowing when the file declares something; with nothing declared there is no
+    // binding to shadow, and the profiles-dir / legacy / not-found chain below must run untouched.
+    if (process.env.PRODUCTBRAIN_API_KEY && (localConfig?.apiKey || localConfig?.preview || localConfig?.profile)) {
+        return `${file} (overridden by PRODUCTBRAIN_API_KEY)`;
+    }
+    if (getPreviewBinding())
+        return `${file} (preview binding)`;
+    if (localConfig?.apiKey)
+        return `${file} (direct binding, no preview marker)`;
+    if (localConfig?.profile)
+        return `${file} (profile "${localConfig.profile}")`;
+    return null;
+}
+/** Check 1: Config file existence (profile-aware) */
+function checkConfigFile(configResult) {
+    // When resolution refused the local file, that file IS the fault under diagnosis — report the
+    // refusal rather than passing on the raw marker, which would green-light the broken binding on
+    // doctor's first line while the key check below fails for the very same reason.
+    if (!configResult.ok && (configResult.kind === 'preview-binding' || configResult.kind === 'profile-pin' || configResult.kind === 'missing-pin')) {
+        return {
+            status: 'fail',
+            label: 'Config file',
+            // The reason names its own offending file already, and they are not all the same file —
+            // `missing-pin` faults the committed config.json that declared the project. A hardcoded
+            // `.productbrain/config.local.json —` prefix printed that path twice and misattributed
+            // this kind, so let the resolver's message speak (it is the SSOT for the copy).
+            detail: configResult.reason,
+            nextCommand: configResult.nextCommand,
+            fix: {
+                description: configResult.guidance,
+                action: () => {
+                    console.log(`  Run: ${configResult.nextCommand}`);
+                },
+            },
+        };
+    }
+    const localBinding = describeLocalBinding(readLocalProjectConfig());
+    if (localBinding) {
+        return { status: 'pass', label: 'Config file', detail: localBinding };
+    }
+    // Profile system takes precedence over legacy .env
+    const profiles = listProfiles();
+    if (profiles.length > 0) {
+        return {
+            status: 'pass',
+            label: 'Config file',
+            detail: `${PROFILES_DIR} (${profiles.length} profile${profiles.length === 1 ? '' : 's'})`,
+        };
+    }
+    // Fall back to legacy .env check
+    const legacyExists = existsSync(HOME_ENV_PATH);
+    if (legacyExists) {
+        return {
+            status: 'pass',
+            label: 'Config file',
+            detail: HOME_ENV_PATH,
+        };
+    }
+    // Neither profiles nor legacy config found
+    return {
+        status: 'fail',
+        label: 'Config file',
+        detail: `No profiles in ${PROFILES_DIR} and no legacy config at ${HOME_ENV_PATH}`,
+        fix: {
+            description: 'Run `pb login` to create a profile with your API key',
+            action: () => {
+                console.log('  Run: pb login');
+            },
+        },
+    };
+}
+/**
+ * Check 2: API key presence and format.
+ *
+ * A `ConfigResult` that is `ok` has already cleared both the presence and the prefix bar, so this
+ * check reads the resolver's verdict rather than re-deriving one — the failure copy lives in
+ * `configResult.ts` alone and cannot drift from what every other surface reports.
+ */
+function checkApiKey(configResult) {
+    if (configResult.ok) {
+        return { status: 'pass', label: 'API key', detail: configResult.apiKey.slice(0, 8) + '****' };
+    }
+    // An unusable gateway URL is not a key fault: the key resolved fine and only the site URL failed
+    // the HTTPS bar. Reporting `fail` here would call a valid key broken and offer `pb doctor` as
+    // doctor's own fix; the Environment check below owns and repairs this one.
+    if (configResult.kind === 'invalid-url') {
+        return {
+            status: 'warn',
+            label: 'API key',
+            detail: 'Not verified — resolution stopped at the site URL (see Environment)',
+        };
+    }
+    return {
+        status: 'fail',
+        label: 'API key',
+        detail: `${configResult.reason} ${configResult.guidance}`,
+        nextCommand: configResult.nextCommand,
+        fix: {
+            description: configResult.guidance,
+            action: () => {
+                // Cannot auto-fix: every credential repair needs user input. Print the command instead.
+                console.log(`  Run: ${configResult.nextCommand}`);
+            },
+        },
+    };
+}
+/** Check 3: Environment and resolved URLs */
+function checkEnvironment(resolvedSiteUrl, configResult) {
+    const env = process.env.PB_ENV || 'production (default)';
+    // The URL that failed the HTTPS bar never reaches `resolvedSiteUrl` (that is only set when
+    // resolution succeeded), so take the reason from the resolver instead of re-inspecting a
+    // fallback URL that may not be the offending one.
+    if (!configResult.ok && configResult.kind === 'invalid-url') {
+        return {
+            status: 'fail',
+            label: 'Environment',
+            detail: `${env} \u2014 ${configResult.reason}`,
+            nextCommand: configResult.nextCommand,
+            fix: {
+                // The repair depends on which source supplied the URL, so print the resolver's own
+                // guidance rather than a hardcoded instruction that only fits the environment case.
+                description: configResult.guidance,
+                action: () => {
+                    console.log(`  ${configResult.guidance} (default: ${DEFAULT_SITE_URL})`);
+                },
+            },
+        };
+    }
+    const siteUrl = resolvedSiteUrl ?? (process.env.CONVEX_SITE_URL ?? DEFAULT_SITE_URL).replace(/\/$/, '');
+    // Validate URL format
+    const allowHttp = isDevMode() && siteUrl.startsWith('http://localhost');
+    if (!siteUrl.startsWith('https://') && !allowHttp) {
+        return {
+            status: 'fail',
+            label: 'Environment',
+            detail: `Invalid URL: ${siteUrl} (must be HTTPS)`,
+            fix: {
+                description: `Reset CONVEX_SITE_URL to default (${DEFAULT_SITE_URL}) in ${HOME_ENV_PATH}`,
+                action: () => {
+                    if (existsSync(HOME_ENV_PATH)) {
+                        const content = readFileSync(HOME_ENV_PATH, 'utf8');
+                        const updated = content.replace(/^CONVEX_SITE_URL=.*$/m, `CONVEX_SITE_URL=${DEFAULT_SITE_URL}`);
+                        // If no existing line, append it
+                        const final = updated.includes('CONVEX_SITE_URL=')
+                            ? updated
+                            : updated.trimEnd() + `\nCONVEX_SITE_URL=${DEFAULT_SITE_URL}\n`;
+                        writeFileSync(HOME_ENV_PATH, final, { mode: 0o600 });
+                    }
+                },
+            },
+        };
+    }
+    const connectRedeem = resolveConnectRedeemUrl();
+    return {
+        status: 'pass',
+        label: 'Environment',
+        detail: `${env} \u2192 API ${siteUrl} · connect redeem ${connectRedeem}`,
+    };
+}
+/** Check 4: Server reachability via kernelCall */
+async function checkReachability() {
+    try {
+        // Dynamic import to avoid module-load side effects when testing
+        const { kernelCall } = await import('../lib/client.js');
+        const start = Date.now();
+        await kernelCall('chain.getOrientView', { tier: 'summary' });
+        const elapsed = Date.now() - start;
+        return {
+            status: 'pass',
+            label: 'Reachability',
+            detail: `OK (${elapsed}ms)`,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // Truncate long error messages for readability
+        const short = msg.length > 80 ? msg.slice(0, 77) + '...' : msg;
+        return { status: 'fail', label: 'Reachability', detail: short };
+    }
+}
+/** Check 5: Node.js version */
+function checkNodeVersion() {
+    return { status: 'pass', label: 'Node', detail: process.version };
+}
+/** Check 6: CLI version from package.json */
+function checkCliVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf8'));
+        return { status: 'pass', label: 'CLI', detail: pkg.version };
+    }
+    catch {
+        return { status: 'warn', label: 'CLI', detail: 'Unable to read package.json' };
+    }
+}
+async function checkCliFreshness(currentVersion) {
+    const latest = await resolveLatestVersion(currentVersion);
+    if (!latest || !isNewer(currentVersion, latest)) {
+        return { status: 'pass', label: 'CLI freshness', detail: latest ? `Current (${currentVersion})` : 'No newer version detected' };
+    }
+    // Skew is observable from doctor too — reuse the once-per-process guard so we don't double-fire.
+    reportVersionSkewIfNew(latest, currentVersion);
+    return {
+        status: 'fail',
+        label: 'CLI freshness',
+        detail: `${currentVersion} -> ${latest}  [u] upgrade`,
+        hotkey: 'u',
+        nextCommand: 'pb upgrade',
+    };
+}
+async function maybeRunUpgradeHotkey(currentVersion, results) {
+    const stale = results.find((r) => r.hotkey === 'u');
+    const canPrompt = isInteractive() && process.env.CI !== 'true' && !process.env.PB_NO_INTERACTIVE;
+    if (!stale || !canPrompt)
+        return { upgraded: false };
+    const { render, Box, Text, useInput } = await import('ink');
+    const React = await import('react');
+    function UpgradePrompt({ onExit }) {
+        useInput((input, key) => {
+            if (input === 'u')
+                onExit(true);
+            if (input === 'q' || key.escape)
+                onExit(false);
+        });
+        return React.default.createElement(Box, { marginTop: 1 }, React.default.createElement(Text, { color: 'yellow' }, 'Press u to upgrade, q to quit'));
+    }
+    let shouldUpgrade = false;
+    // Hoist unmount: render() may invoke onExit synchronously (mocked or otherwise),
+    // which would hit a TDZ error if we read unmount from the destructure on the same line.
+    let unmount;
+    const { waitUntilExit, unmount: realUnmount } = render(React.default.createElement(UpgradePrompt, {
+        onExit: (upgrade) => {
+            shouldUpgrade = upgrade;
+            // Emit the dismissed event from the onExit consumer so it fires whether the user
+            // pressed q/Esc (real input) or the prompt resolves false through any other path.
+            if (!upgrade)
+                trackEvent('cli.upgrade.dismissed', { source: 'doctor' });
+            unmount?.();
+        },
+    }));
+    unmount = realUnmount;
+    await waitUntilExit();
+    if (shouldUpgrade) {
+        await runUpgrade({ currentVersion });
+        return { upgraded: true };
+    }
+    return { upgraded: false };
+}
+export async function runDoctor(opts = {}) {
+    const { fix = false, dryRun = false } = opts;
+    // Resolve config via getConfigSafe() so loadEnv() runs and profile files are read
+    // before any check inspects process.env. Without this, checkApiKey() sees an empty
+    // PRODUCTBRAIN_API_KEY even when a named profile has a valid key (TEN-1332).
+    const configResult = getConfigSafe();
+    const resolvedSiteUrl = configResult.ok ? configResult.siteUrl : undefined;
+    const results = [];
+    // Synchronous checks
+    results.push(checkConfigFile(configResult));
+    results.push(checkApiKey(configResult));
+    results.push(checkEnvironment(resolvedSiteUrl, configResult));
+    // Async check — server reachability
+    results.push(await checkReachability());
+    // More synchronous checks
+    results.push(checkNodeVersion());
+    const cliVersion = checkCliVersion();
+    results.push(cliVersion);
+    if (cliVersion.status === 'pass') {
+        results.push(await checkCliFreshness(cliVersion.detail));
+    }
+    // Print results
+    banner('Doctor');
+    for (const r of results) {
+        console.log(formatCheck(r.status, r.label, r.detail));
+    }
+    console.log('');
+    const upgradeResult = await maybeRunUpgradeHotkey(cliVersion.detail, results);
+    // If the user just upgraded in-doctor, don't fail the run for the (now-resolved) freshness check.
+    const failed = results
+        .filter((r) => r.status === 'fail')
+        .filter((r) => !(r.label === 'CLI freshness' && upgradeResult.upgraded));
+    const fixable = failed.filter((r) => r.fix);
+    // --dry-run: show what would be fixed
+    if (dryRun && fixable.length > 0) {
+        console.log(cyan('Dry run — the following fixes would be applied:\n'));
+        for (const r of fixable) {
+            console.log(`  ${yellow('\u2192')} ${r.label}: ${r.fix.description}`);
+        }
+        console.log('');
+        process.exit(failed.length > 0 ? 1 : 0);
+        return;
+    }
+    // --fix: apply fixes and re-check
+    if (fix && fixable.length > 0) {
+        console.log(cyan('Applying fixes...\n'));
+        for (const r of fixable) {
+            console.log(`  ${yellow('\u2192')} ${r.label}: ${r.fix.description}`);
+            r.fix.action();
+        }
+        // Re-run checks to confirm fixes — re-resolve config in case --fix wrote a key
+        const recheckConfig = getConfigSafe();
+        const recheckSiteUrl = recheckConfig.ok ? recheckConfig.siteUrl : undefined;
+        console.log('\nRe-checking...\n');
+        const recheck = [];
+        recheck.push(checkConfigFile(recheckConfig));
+        recheck.push(checkApiKey(recheckConfig));
+        recheck.push(checkEnvironment(recheckSiteUrl, recheckConfig));
+        recheck.push(await checkReachability());
+        recheck.push(checkNodeVersion());
+        recheck.push(checkCliVersion());
+        for (const r of recheck) {
+            console.log(formatCheck(r.status, r.label, r.detail));
+        }
+        console.log('');
+        const stillFailing = recheck.some((r) => r.status === 'fail');
+        if (stillFailing) {
+            process.exit(1);
+        }
+        return;
+    }
+    // Normal mode — exit with non-zero if any check failed
+    if (failed.length > 0) {
+        if (fixable.length > 0) {
+            console.log(`${fixable.length} issue(s) may be auto-fixable. Run: pb doctor --fix`);
+            console.log('Preview first with: pb doctor --dry-run\n');
+        }
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=doctor.js.map