@seanpropapp/cli 0.1.0-beta.1

package/dist/commands/connect.js

@@ -0,0 +1,213 @@
+import openImport from "open";
+import { ClaudeProvider } from "../providers/claude.js";
+import { CodexProvider } from "../providers/codex.js";
+import { detectAllProviders } from "../providers/index.js";
+import { startServer } from "../http/server.js";
+import { updateConfig, loadConfig } from "../config.js";
+import { generatePairToken, osc8Link, pairUrl, } from "./pair-url.js";
+import { planClaudeInstall, runInstall } from "./install-claude.js";
+import { confirm } from "./prompt.js";
+import { spawnBackgroundBridge } from "./bridge.js";
+import { emitConnectStart } from "../telemetry.js";
+const HANDSHAKE_TIMEOUT_MS = 60_000;
+const HANDSHAKE_POLL_MS = 1_000;
+const SAMPLE_URL = "https://prop.seanoneill.com/workspace?sample=true";
+function fmtSeconds(ms) {
+    return (ms / 1000).toFixed(1);
+}
+/**
+ * Persona A entry point. Runs the full first-time flow:
+ *  1. Detect Claude CLI; inline-guide install if missing.
+ *  2. Generate pair token.
+ *  3. Start bridge (background by default).
+ *  4. Print clickable + plain-text pair URL (TX13).
+ *  5. Open browser.
+ *  6. Poll config for paired_at (set by bridge once /pair confirms).
+ *  7. Print elapsed time + sample-analysis CTA on success (TX6).
+ */
+export async function runConnect(opts = {}) {
+    const out = opts.stdout ?? ((s) => process.stdout.write(s));
+    const err = opts.stderr ?? ((s) => process.stderr.write(s));
+    const t0 = Date.now();
+    // Fire-and-forget telemetry. Swallowed silently if disabled or offline.
+    void emitConnectStart({
+        ...(opts.configDir !== undefined ? { configDir: opts.configDir } : {}),
+        ...(opts.noTelemetry ? { forceDisable: true } : {}),
+    });
+    // 1. Detect Claude CLI.
+    out("Looking for Claude CLI on your system...\n");
+    const claude = opts.providers?.claude ?? new ClaudeProvider();
+    const codex = opts.providers?.codex ?? new CodexProvider();
+    let detected;
+    if (opts.providers) {
+        detected = {
+            claude: await claude.detect(),
+            codex: await codex.detect(),
+        };
+    }
+    else {
+        const all = await detectAllProviders();
+        detected = { claude: all.claude, codex: all.codex };
+    }
+    if (!detected.claude.installed && !detected.codex.installed) {
+        out("\n  Claude CLI not found.\n\n");
+        out("  SeanPropApp uses your Claude Pro subscription via the official Claude CLI.\n");
+        out("  You need to install it once.\n\n");
+        const plan = await planClaudeInstall();
+        if (plan.autoCommand && !opts.skipInstallPrompt) {
+            out(`    ${plan.autoCommand.label}\n\n`);
+            const yes = await confirm("  Install now? [Y/n] ");
+            if (yes) {
+                out("\n");
+                const code = await runInstall(plan.autoCommand.binary, plan.autoCommand.args);
+                if (code !== 0) {
+                    err(`\n  Install failed (exit ${code ?? "unknown"}). See the output above and re-run \`seanpropapp connect\`.\n`);
+                    return {
+                        success: false,
+                        elapsedSeconds: (Date.now() - t0) / 1000,
+                        reason: "install_failed",
+                    };
+                }
+                // Re-detect.
+                const after = await claude.detect();
+                detected.claude = after;
+            }
+            else {
+                out(`\n  ${plan.manualMessage}\n`);
+                out("  Re-run `seanpropapp connect` once Claude CLI is installed.\n");
+                return {
+                    success: false,
+                    elapsedSeconds: (Date.now() - t0) / 1000,
+                    reason: "user_declined_install",
+                };
+            }
+        }
+        else {
+            out(`  ${plan.manualMessage}\n`);
+            out("  Re-run `seanpropapp connect` once Claude CLI is installed.\n");
+            return {
+                success: false,
+                elapsedSeconds: (Date.now() - t0) / 1000,
+                reason: "manual_install_required",
+            };
+        }
+    }
+    if (detected.claude.installed) {
+        const v = detected.claude.version ? ` (${detected.claude.version})` : "";
+        out(`  Claude CLI detected${v}\n`);
+    }
+    if (detected.codex.installed) {
+        const v = detected.codex.version ? ` (${detected.codex.version})` : "";
+        out(`  Codex CLI detected${v}\n`);
+    }
+    // 2. Generate pair token.
+    const token = generatePairToken();
+    // 3. Start bridge (background by default).
+    let bridgePort;
+    let stopInlineBridge;
+    if (opts.noBridgeFork) {
+        const running = await startServer({
+            token,
+            port: opts.port,
+            pairedAt: async () => {
+                const cfg = await loadConfig(opts.configDir);
+                return cfg.paired_at ?? null;
+            },
+        });
+        bridgePort = running.port;
+        stopInlineBridge = () => running.close();
+    }
+    else {
+        // Detached child. We still need to know what port it bound. Quick approach
+        // for v1.4.0: bind here just long enough to claim the port, then close
+        // and hand the port over to the child. This avoids a stdio handshake.
+        const probe = await startServer({
+            token,
+            port: opts.port,
+            pairedAt: () => null,
+        });
+        bridgePort = probe.port;
+        await probe.close();
+        await spawnBackgroundBridge({
+            port: bridgePort,
+            token,
+            ...(opts.configDir ? { configDir: opts.configDir } : {}),
+            ...(opts.skipBridgeHealthcheck ? { skipHealthcheck: true } : {}),
+        });
+    }
+    await updateConfig({
+        pair_token: token,
+        bridge_port: bridgePort,
+        bridge_url: `http://127.0.0.1:${bridgePort}`,
+    }, opts.configDir);
+    out(`  Bridge ready on port ${bridgePort}\n`);
+    // 4. Print pair URL: clickable + plain (TX13).
+    const url = pairUrl(token);
+    out(`\n  Pair URL: ${osc8Link(url, url)}\n`);
+    out(`  Or paste in browser: ${url}\n`);
+    // 5. Open browser.
+    if (!opts.skipBrowserOpen) {
+        try {
+            // `open` is a default-export ESM module.
+            await openImport(url);
+        }
+        catch {
+            // Non-fatal: the user can still paste the plain URL.
+        }
+    }
+    out("\n  Waiting for you to confirm pairing in the browser...\n");
+    // 6. Poll for paired_at.
+    let paired = false;
+    if (opts.fakePairedAt) {
+        await updateConfig({ paired_at: opts.fakePairedAt }, opts.configDir);
+        paired = true;
+    }
+    else {
+        const deadline = Date.now() + HANDSHAKE_TIMEOUT_MS;
+        while (Date.now() < deadline) {
+            const cfg = await loadConfig(opts.configDir);
+            if (cfg.paired_at) {
+                paired = true;
+                break;
+            }
+            await new Promise((r) => setTimeout(r, HANDSHAKE_POLL_MS));
+        }
+    }
+    if (!paired) {
+        if (stopInlineBridge)
+            await stopInlineBridge();
+        err("\n  Timed out waiting for pairing (60s).\n" +
+            "  Either re-run `seanpropapp connect` or click the pair URL again.\n");
+        return {
+            success: false,
+            elapsedSeconds: (Date.now() - t0) / 1000,
+            reason: "pair_timeout",
+            bridgePort,
+            pairUrl: url,
+        };
+    }
+    // 7. Success.
+    const elapsedMs = Date.now() - t0;
+    out(`\n  Connected in ${fmtSeconds(elapsedMs)}s! Run a sample analysis at:\n` +
+        `    ${SAMPLE_URL}\n\n` +
+        "  Next time, just run `npx @seanpropapp/cli connect` to reconnect.\n");
+    // When in --no-bridge-fork mode, hand control to the inline server so it
+    // keeps running until the user kills the process.
+    if (stopInlineBridge) {
+        await new Promise((resolve) => {
+            const shutdown = async () => {
+                await stopInlineBridge();
+                resolve();
+            };
+            process.once("SIGINT", shutdown);
+            process.once("SIGTERM", shutdown);
+        });
+    }
+    return {
+        success: true,
+        elapsedSeconds: elapsedMs / 1000,
+        bridgePort,
+        pairUrl: url,
+    };
+}
+//# sourceMappingURL=connect.js.map

package/dist/commands/connect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.js","sourceRoot":"","sources":["../../src/commands/connect.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,MAAM,CAAC;AAC9B,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EACL,iBAAiB,EACjB,QAAQ,EACR,OAAO,GACR,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD,MAAM,oBAAoB,GAAG,MAAM,CAAC;AACpC,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAChC,MAAM,UAAU,GAAG,mDAAmD,CAAC;AA6CvE,SAAS,UAAU,CAAC,EAAU;IAC5B,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,OAAuB,EAAE;IAEzB,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAEtB,wEAAwE;IACxE,KAAK,gBAAgB,CAAC;QACpB,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtE,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpD,CAAC,CAAC;IAEH,wBAAwB;IACxB,GAAG,CAAC,4CAA4C,CAAC,CAAC;IAElD,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,MAAM,IAAI,IAAI,cAAc,EAAE,CAAC;IAC9D,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,EAAE,KAAK,IAAI,IAAI,aAAa,EAAE,CAAC;IAC3D,IAAI,QAAuE,CAAC;IAC5E,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QACnB,QAAQ,GAAG;YACT,MAAM,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE;YAC7B,KAAK,EAAE,MAAM,KAAK,CAAC,MAAM,EAAE;SAC5B,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,MAAM,GAAG,GAAG,MAAM,kBAAkB,EAAE,CAAC;QACvC,QAAQ,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC;IACtD,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;QAC5D,GAAG,CAAC,+BAA+B,CAAC,CAAC;QACrC,GAAG,CACD,gFAAgF,CACjF,CAAC;QACF,GAAG,CAAC,oCAAoC,CAAC,CAAC;QAE1C,MAAM,IAAI,GAAG,MAAM,iBAAiB,EAAE,CAAC;QACvC,IAAI,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAAC;YAChD,GAAG,CAAC,OAAO,IAAI,CAAC,WAAW,CAAC,KAAK,MAAM,CAAC,CAAC;YACzC,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,uBAAuB,CAAC,CAAC;YACnD,IAAI,GAAG,EAAE,CAAC;gBACR,GAAG,CAAC,IAAI,CAAC,CAAC;gBACV,MAAM,IAAI,GAAG,MAAM,UAAU,CAC3B,IAAI,CAAC,WAAW,CAAC,MAAM,EACvB,IAAI,CAAC,WAAW,CAAC,IAAI,CACtB,CAAC;gBACF,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;oBACf,GAAG,CACD,4BAA4B,IAAI,IAAI,SAAS,+DAA+D,CAC7G,CAAC;oBACF,OAAO;wBACL,OAAO,EAAE,KAAK;wBACd,cAAc,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,GAAG,IAAI;wBACxC,MAAM,EAAE,gBAAgB;qBACzB,CAAC;gBACJ,CAAC;gBACD,aAAa;gBACb,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC;gBACpC,QAAQ,CAAC,MAAM,GAAG,KAAK,CAAC;YAC1B,CAAC;iBAAM,CAAC;gBACN,GAAG,CAAC,OAAO,IAAI,CAAC,aAAa,IAAI,CAAC,CAAC;gBACnC,GAAG,CAAC,gEAAgE,CAAC,CAAC;gBACtE,OAAO;oBACL,OAAO,EAAE,KAAK;oBACd,cAAc,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,GAAG,IAAI;oBACxC,MAAM,EAAE,uBAAuB;iBAChC,CAAC;YACJ,CAAC;QACH,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,KAAK,IAAI,CAAC,aAAa,IAAI,CAAC,CAAC;YACjC,GAAG,CAAC,gEAAgE,CAAC,CAAC;YACtE,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,cAAc,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,GAAG,IAAI;gBACxC,MAAM,EAAE,yBAAyB;aAClC,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;QAC9B,MAAM,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACzE,GAAG,CAAC,wBAAwB,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;IACD,IAAI,QAAQ,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;QAC7B,MAAM,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACvE,GAAG,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,0BAA0B;IAC1B,MAAM,KAAK,GAAG,iBAAiB,EAAE,CAAC;IAElC,2CAA2C;IAC3C,IAAI,UAAkB,CAAC;IACvB,IAAI,gBAAmD,CAAC;IAExD,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;QACtB,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC;YAChC,KAAK;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,QAAQ,EAAE,KAAK,IAAI,EAAE;gBACnB,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;gBAC7C,OAAO,GAAG,CAAC,SAAS,IAAI,IAAI,CAAC;YAC/B,CAAC;SACO,CAAC,CAAC;QACZ,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;QAC1B,gBAAgB,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IAC3C,CAAC;SAAM,CAAC;QACN,2EAA2E;QAC3E,uEAAuE;QACvE,sEAAsE;QACtE,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC;YAC9B,KAAK;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI;SACrB,CAAC,CAAC;QACH,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC;QACxB,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;QACpB,MAAM,qBAAqB,CAAC;YAC1B,IAAI,EAAE,UAAU;YAChB,KAAK;YACL,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxD,GAAG,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACjE,CAAC,CAAC;IACL,CAAC;IAED,MAAM,YAAY,CAChB;QACE,UAAU,EAAE,KAAK;QACjB,WAAW,EAAE,UAAU;QACvB,UAAU,EAAE,oBAAoB,UAAU,EAAE;KAC7C,EACD,IAAI,CAAC,SAAS,CACf,CAAC;IAEF,GAAG,CAAC,0BAA0B,UAAU,IAAI,CAAC,CAAC;IAE9C,+CAA+C;IAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3B,GAAG,CAAC,iBAAiB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;IAC7C,GAAG,CAAC,0BAA0B,GAAG,IAAI,CAAC,CAAC;IAEvC,mBAAmB;IACnB,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;QAC1B,IAAI,CAAC;YACH,yCAAyC;YACzC,MAAO,UAA8D,CAAC,GAAG,CAAC,CAAC;QAC7E,CAAC;QAAC,MAAM,CAAC;YACP,qDAAqD;QACvD,CAAC;IACH,CAAC;IAED,GAAG,CAAC,4DAA4D,CAAC,CAAC;IAElE,yBAAyB;IACzB,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;QACtB,MAAM,YAAY,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,YAAY,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACrE,MAAM,GAAG,IAAI,CAAC;IAChB,CAAC;SAAM,CAAC;QACN,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,oBAAoB,CAAC;QACnD,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;YAC7B,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC7C,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;gBAClB,MAAM,GAAG,IAAI,CAAC;gBACd,MAAM;YACR,CAAC;YACD,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;IAED,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,IAAI,gBAAgB;YAAE,MAAM,gBAAgB,EAAE,CAAC;QAC/C,GAAG,CACD,4CAA4C;YAC1C,sEAAsE,CACzE,CAAC;QACF,OAAO;YACL,OAAO,EAAE,KAAK;YACd,cAAc,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,GAAG,IAAI;YACxC,MAAM,EAAE,cAAc;YACtB,UAAU;YACV,OAAO,EAAE,GAAG;SACb,CAAC;IACJ,CAAC;IAED,cAAc;IACd,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;IAClC,GAAG,CACD,oBAAoB,UAAU,CAAC,SAAS,CAAC,gCAAgC;QACvE,OAAO,UAAU,MAAM;QACvB,sEAAsE,CACzE,CAAC;IAEF,yEAAyE;IACzE,kDAAkD;IAClD,IAAI,gBAAgB,EAAE,CAAC;QACrB,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAClC,MAAM,QAAQ,GAAG,KAAK,IAAI,EAAE;gBAC1B,MAAM,gBAAiB,EAAE,CAAC;gBAC1B,OAAO,EAAE,CAAC;YACZ,CAAC,CAAC;YACF,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;YACjC,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QACpC,CAAC,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,OAAO,EAAE,IAAI;QACb,cAAc,EAAE,SAAS,GAAG,IAAI;QAChC,UAAU;QACV,OAAO,EAAE,GAAG;KACb,CAAC;AACJ,CAAC"}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,24 @@
+import { detectAllProviders } from "../providers/index.js";
+export interface DoctorOptions {
+    configDir?: string;
+    /** Override fetch (used by tests). */
+    fetchImpl?: typeof fetch;
+    /** Override stdout writer (used by tests). */
+    stdout?: (line: string) => void;
+    /** Override provider detection (used by tests). */
+    detectFn?: typeof detectAllProviders;
+    /** Override the port-probe function (used by tests). */
+    probePortFn?: (port: number) => Promise<boolean>;
+    /** When true, emit a single JSON envelope instead of human-readable sections. */
+    json?: boolean;
+}
+export interface DoctorResult {
+    ok: boolean;
+    sections: Record<string, string[]>;
+}
+/**
+ * Returns true if the given local port can be bound (i.e., is free).
+ * Honors a short timeout so the doctor doesn't stall.
+ */
+export declare function probePortAvailable(port: number): Promise<boolean>;
+export declare function runDoctor(opts?: DoctorOptions): Promise<DoctorResult>;

package/dist/commands/doctor.js

@@ -0,0 +1,200 @@
+/**
+ * `seanpropapp doctor`: self-diagnostic for the bridge + provider stack.
+ *
+ * Output is plain text with simple section headings, no emojis. Every WARN
+ * or FAIL line is followed by an actionable suggestion. The check ordering
+ * matches the typical first-run failure mode (no Claude CLI -> port taken ->
+ * not paired yet).
+ *
+ * No secrets are ever printed; we only report token PRESENCE.
+ */
+import net from "node:net";
+import os from "node:os";
+import { detectAllProviders } from "../providers/index.js";
+import { loadConfig, getConfigPath, } from "../config.js";
+import { DEFAULT_BRIDGE_PORT, MAX_PORT_FALLBACK, } from "../http/server.js";
+import { CLI_VERSION } from "../version.js";
+/**
+ * Returns true if the given local port can be bound (i.e., is free).
+ * Honors a short timeout so the doctor doesn't stall.
+ */
+export function probePortAvailable(port) {
+    return new Promise((resolve) => {
+        const srv = net.createServer();
+        let settled = false;
+        const cleanup = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            srv.removeAllListeners();
+            srv.close(() => resolve(ok));
+        };
+        srv.once("error", () => cleanup(false));
+        srv.once("listening", () => cleanup(true));
+        try {
+            srv.listen(port, "127.0.0.1");
+        }
+        catch {
+            cleanup(false);
+        }
+        setTimeout(() => cleanup(false), 500);
+    });
+}
+/**
+ * Pretty-print a number as `Xm Ys` for paired_at deltas.
+ */
+function fmtAge(ms) {
+    if (ms < 0)
+        return "in the future";
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}s ago`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m ${s % 60}s ago`;
+    const h = Math.floor(m / 60);
+    return `${h}h ${m % 60}m ago`;
+}
+export async function runDoctor(opts = {}) {
+    const out = opts.stdout ?? ((s) => process.stdout.write(s));
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const detectFn = opts.detectFn ?? detectAllProviders;
+    const probePort = opts.probePortFn ?? probePortAvailable;
+    const sections = {};
+    let ok = true;
+    function section(name, lines) {
+        sections[name] = lines;
+        out(`\n${name}\n`);
+        for (const line of lines)
+            out(`  ${line}\n`);
+    }
+    // 1. CLI + system.
+    section("System", [
+        `seanpropapp v${CLI_VERSION}`,
+        `Node ${process.version} (${process.platform}/${process.arch})`,
+        `Host: ${os.hostname()}`,
+    ]);
+    // 2. Providers.
+    const providerLines = [];
+    const detected = await detectFn();
+    if (detected.claude.installed) {
+        providerLines.push(`Claude CLI: detected${detected.claude.version ? ` (${detected.claude.version})` : ""}`);
+    }
+    else {
+        providerLines.push(`Claude CLI: NOT FOUND. Install with: brew install anthropic/claude/claude (macOS) or see https://claude.ai/cli`);
+        ok = false;
+    }
+    if (detected.codex.installed) {
+        providerLines.push(`Codex CLI: detected${detected.codex.version ? ` (${detected.codex.version})` : ""}`);
+    }
+    else {
+        providerLines.push(`Codex CLI: not detected (optional)`);
+    }
+    if (!detected.gemini.installed) {
+        providerLines.push(`Gemini CLI: not yet supported`);
+    }
+    section("Providers", providerLines);
+    // 3. Port availability.
+    const portLines = [];
+    let firstFreePort = null;
+    for (let p = DEFAULT_BRIDGE_PORT; p <= MAX_PORT_FALLBACK; p++) {
+        const free = await probePort(p);
+        portLines.push(`Port ${p}: ${free ? "free" : "in use"}`);
+        if (free && firstFreePort === null)
+            firstFreePort = p;
+    }
+    if (firstFreePort === null) {
+        portLines.push(`WARN: every port in ${DEFAULT_BRIDGE_PORT}-${MAX_PORT_FALLBACK} is taken. Stop another process or pass --port to seanpropapp bridge.`);
+        ok = false;
+    }
+    else {
+        portLines.push(`Next free port: ${firstFreePort}`);
+    }
+    section("Bridge ports", portLines);
+    // 4. Config + pairing.
+    const cfg = await loadConfig(opts.configDir);
+    const configPath = getConfigPath(opts.configDir);
+    const configLines = [`Config: ${configPath}`];
+    if (cfg.pair_token) {
+        configLines.push("Pair token: present (value redacted)");
+    }
+    else {
+        configLines.push("Pair token: MISSING. Run `seanpropapp connect` to generate one.");
+        ok = false;
+    }
+    if (cfg.mcp_token) {
+        configLines.push("MCP token: present (value redacted)");
+    }
+    else {
+        configLines.push("MCP token: missing (only needed for `seanpropapp mcp`)");
+    }
+    if (cfg.paired_at) {
+        const parsed = Date.parse(cfg.paired_at);
+        if (Number.isFinite(parsed)) {
+            configLines.push(`Paired at: ${cfg.paired_at} (${fmtAge(Date.now() - parsed)})`);
+        }
+        else {
+            configLines.push(`Paired at: ${cfg.paired_at}`);
+        }
+    }
+    else {
+        configLines.push("Paired at: never. Complete pairing in the browser via `seanpropapp connect`.");
+    }
+    if (cfg.bridge_url) {
+        configLines.push(`Bridge URL: ${cfg.bridge_url}`);
+    }
+    if (cfg.bridge_port) {
+        configLines.push(`Bridge port: ${cfg.bridge_port}`);
+    }
+    if (cfg.telemetry_enabled === undefined ||
+        cfg.telemetry_enabled === false) {
+        configLines.push("Telemetry: opt-in (off)");
+    }
+    else {
+        configLines.push("Telemetry: opt-in (on)");
+    }
+    section("Config", configLines);
+    // 5. Bridge health check.
+    const healthLines = [];
+    if (cfg.bridge_url && cfg.pair_token) {
+        try {
+            const url = `${cfg.bridge_url.replace(/\/$/, "")}/v1/handshake`;
+            const res = await fetchImpl(url, {
+                method: "GET",
+                headers: { Authorization: `Bearer ${cfg.pair_token}` },
+            });
+            if (res.ok) {
+                healthLines.push(`Bridge reachable at ${url} (HTTP ${res.status})`);
+            }
+            else if (res.status === 401) {
+                healthLines.push(`Bridge reachable but rejected the saved pair token (HTTP 401). Re-pair with: \`seanpropapp connect\``);
+                ok = false;
+            }
+            else {
+                healthLines.push(`Bridge returned HTTP ${res.status} for ${url}. Restart with: \`seanpropapp connect\``);
+                ok = false;
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            healthLines.push(`Bridge not reachable at ${cfg.bridge_url}: ${msg}. Try: \`seanpropapp connect\``);
+            ok = false;
+        }
+    }
+    else {
+        healthLines.push("Bridge not configured. Run `seanpropapp connect` to start the bridge.");
+    }
+    section("Bridge health", healthLines);
+    // 6. Summary.
+    if (opts.json) {
+        // Drain anything we accumulated by replaying as a JSON envelope.
+        // (We still printed the human sections above so JSON consumers piping
+        // through `tee` see both; clean callers should pipe stdout-only.)
+        out(`${JSON.stringify({ ok, sections })}\n`);
+    }
+    else {
+        out(`\n${ok ? "All checks passed." : "Some checks failed. See suggestions above."}\n`);
+    }
+    return { ok, sections };
+}
+//# sourceMappingURL=doctor.js.map

package/dist/commands/doctor.js.map

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

package/dist/commands/install-claude.d.ts

@@ -0,0 +1,22 @@
+export interface InstallGuidance {
+    platform: NodeJS.Platform;
+    /** Shell command we can run for an automated install (macOS Homebrew). */
+    autoCommand?: {
+        binary: string;
+        args: string[];
+        label: string;
+    };
+    /** Human-readable instructions to print when we can't or won't auto-install. */
+    manualMessage: string;
+}
+/**
+ * Produce OS-aware install guidance for Claude CLI. Persona A typically has
+ * Claude Pro via the web app but not the CLI; this is the inline guided
+ * install hook called by `connect`.
+ */
+export declare function planClaudeInstall(): Promise<InstallGuidance>;
+/**
+ * Spawn an interactive install command, piping its stdout/stderr to the
+ * user's terminal. Resolves with the exit code.
+ */
+export declare function runInstall(binary: string, args: string[]): Promise<number | null>;

package/dist/commands/install-claude.js

@@ -0,0 +1,56 @@
+import { spawn } from "node:child_process";
+import { which } from "../providers/detect-util.js";
+/**
+ * Produce OS-aware install guidance for Claude CLI. Persona A typically has
+ * Claude Pro via the web app but not the CLI; this is the inline guided
+ * install hook called by `connect`.
+ */
+export async function planClaudeInstall() {
+    if (process.platform === "darwin") {
+        const brew = await which("brew");
+        if (brew) {
+            return {
+                platform: "darwin",
+                autoCommand: {
+                    binary: brew,
+                    args: ["install", "anthropic-ai/claude/claude"],
+                    label: "brew install anthropic-ai/claude/claude",
+                },
+                manualMessage: "Install Claude CLI via Homebrew: brew install anthropic-ai/claude/claude",
+            };
+        }
+        return {
+            platform: "darwin",
+            manualMessage: "Install Homebrew (https://brew.sh) then run: brew install anthropic-ai/claude/claude",
+        };
+    }
+    if (process.platform === "linux") {
+        return {
+            platform: "linux",
+            manualMessage: "See https://claude.ai/cli for the install command for your distro " +
+                "(apt, pacman, or curl-bash).",
+        };
+    }
+    if (process.platform === "win32") {
+        return {
+            platform: "win32",
+            manualMessage: "Install Claude CLI from https://claude.ai/cli, then re-run `seanpropapp connect`.",
+        };
+    }
+    return {
+        platform: process.platform,
+        manualMessage: "See https://claude.ai/cli for install instructions on your platform.",
+    };
+}
+/**
+ * Spawn an interactive install command, piping its stdout/stderr to the
+ * user's terminal. Resolves with the exit code.
+ */
+export function runInstall(binary, args) {
+    return new Promise((resolve) => {
+        const child = spawn(binary, args, { stdio: "inherit" });
+        child.on("error", () => resolve(null));
+        child.on("close", (code) => resolve(code));
+    });
+}
+//# sourceMappingURL=install-claude.js.map

package/dist/commands/install-claude.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-claude.js","sourceRoot":"","sources":["../../src/commands/install-claude.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAUpD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB;IACrC,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,CAAC;QACjC,IAAI,IAAI,EAAE,CAAC;YACT,OAAO;gBACL,QAAQ,EAAE,QAAQ;gBAClB,WAAW,EAAE;oBACX,MAAM,EAAE,IAAI;oBACZ,IAAI,EAAE,CAAC,SAAS,EAAE,4BAA4B,CAAC;oBAC/C,KAAK,EAAE,yCAAyC;iBACjD;gBACD,aAAa,EACX,0EAA0E;aAC7E,CAAC;QACJ,CAAC;QACD,OAAO;YACL,QAAQ,EAAE,QAAQ;YAClB,aAAa,EACX,sFAAsF;SACzF,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,OAAO;YACL,QAAQ,EAAE,OAAO;YACjB,aAAa,EACX,oEAAoE;gBACpE,8BAA8B;SACjC,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,OAAO;YACL,QAAQ,EAAE,OAAO;YACjB,aAAa,EACX,mFAAmF;SACtF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,aAAa,EACX,sEAAsE;KACzE,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CACxB,MAAc,EACd,IAAc;IAEd,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;QACxD,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QACvC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/commands/mcp.d.ts

@@ -0,0 +1,5 @@
+export interface McpCommandOptions {
+    configDir?: string;
+    baseUrl?: string;
+}
+export declare function runMcpCommand(opts?: McpCommandOptions): Promise<void>;

package/dist/commands/mcp.js

@@ -0,0 +1,23 @@
+/**
+ * `seanpropapp mcp` subcommand: launch the stdio MCP server.
+ *
+ * v0.1.0-alpha: minimal feature parity with the existing `@seanpropapp/mcp`
+ * package. The full migration (streaming + caching + telemetry) is the v1.4.0
+ * deliverable tracked in proposition-app#341.
+ */
+import { runMcpServer } from "../mcp/server.js";
+export async function runMcpCommand(opts = {}) {
+    const serverOpts = {};
+    if (opts.configDir !== undefined)
+        serverOpts.configDir = opts.configDir;
+    if (opts.baseUrl !== undefined)
+        serverOpts.baseUrl = opts.baseUrl;
+    try {
+        await runMcpServer(serverOpts);
+    }
+    catch (err) {
+        process.stderr.write(`mcp: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=mcp.js.map

package/dist/commands/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../src/commands/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,YAAY,EAAyB,MAAM,kBAAkB,CAAC;AAOvE,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAA0B,EAAE;IAE5B,MAAM,UAAU,GAAqB,EAAE,CAAC;IACxC,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;QAAE,UAAU,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IACxE,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;QAAE,UAAU,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAClE,IAAI,CAAC;QACH,MAAM,YAAY,CAAC,UAAU,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,QAAQ,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAC7D,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC"}

package/dist/commands/pair-url.d.ts

@@ -0,0 +1,12 @@
+export declare const PAIR_BASE_URL = "https://prop.seanoneill.com/pair";
+/** Generate a 32-byte hex pair token (64 hex chars). */
+export declare function generatePairToken(): string;
+/** Build the pair URL with token in the URL fragment (#t=...). */
+export declare function pairUrl(token: string): string;
+/**
+ * Wrap a URL in an OSC 8 hyperlink escape so supporting terminals render it
+ * clickable. Non-supporting terminals fall back to plain text (the label).
+ *
+ * Sequence shape: ESC ] 8 ; ; URL ESC \  LABEL  ESC ] 8 ; ; ESC \
+ */
+export declare function osc8Link(url: string, label: string): string;

package/dist/commands/pair-url.js

@@ -0,0 +1,23 @@
+import { randomBytes } from "node:crypto";
+export const PAIR_BASE_URL = "https://prop.seanoneill.com/pair";
+/** Generate a 32-byte hex pair token (64 hex chars). */
+export function generatePairToken() {
+    return randomBytes(32).toString("hex");
+}
+/** Build the pair URL with token in the URL fragment (#t=...). */
+export function pairUrl(token) {
+    return `${PAIR_BASE_URL}#t=${token}`;
+}
+const ESC = String.fromCharCode(0x1b);
+/**
+ * Wrap a URL in an OSC 8 hyperlink escape so supporting terminals render it
+ * clickable. Non-supporting terminals fall back to plain text (the label).
+ *
+ * Sequence shape: ESC ] 8 ; ; URL ESC \  LABEL  ESC ] 8 ; ; ESC \
+ */
+export function osc8Link(url, label) {
+    const OSC = `${ESC}]8;;`;
+    const ST = `${ESC}\\`;
+    return `${OSC}${url}${ST}${label}${OSC}${ST}`;
+}
+//# sourceMappingURL=pair-url.js.map

package/dist/commands/pair-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pair-url.js","sourceRoot":"","sources":["../../src/commands/pair-url.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,CAAC,MAAM,aAAa,GAAG,kCAAkC,CAAC;AAEhE,wDAAwD;AACxD,MAAM,UAAU,iBAAiB;IAC/B,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,OAAO,GAAG,aAAa,MAAM,KAAK,EAAE,CAAC;AACvC,CAAC;AAED,MAAM,GAAG,GAAG,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;AAEtC;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW,EAAE,KAAa;IACjD,MAAM,GAAG,GAAG,GAAG,GAAG,MAAM,CAAC;IACzB,MAAM,EAAE,GAAG,GAAG,GAAG,IAAI,CAAC;IACtB,OAAO,GAAG,GAAG,GAAG,GAAG,GAAG,EAAE,GAAG,KAAK,GAAG,GAAG,GAAG,EAAE,EAAE,CAAC;AAChD,CAAC"}

package/dist/commands/pair.d.ts

@@ -0,0 +1,12 @@
+export interface PairOptions {
+    configDir?: string;
+}
+/**
+ * Escape-hatch: generate a fresh pair URL without starting a bridge.
+ * Assumes the bridge is already running and will pick up the new token
+ * from the shared config on its next handshake.
+ *
+ * NOTE: in v1.4.0 the bridge holds tokens in-memory at start; a fully live
+ * rotation flow is a v1.4.x follow-up (see Lane C-Polish doctor).
+ */
+export declare function runPair(opts?: PairOptions): Promise<void>;