@seanpropapp/cli 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sean O'Neill
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# @seanpropapp/cli
+
+Run [SeanPropApp](https://prop.seanoneill.com) proposition analyses on your existing Claude Pro or ChatGPT Plus subscription. No API key, no extra cost.
+
+## Quick start
+
+```sh
+npx @seanpropapp/cli connect
+```
+
+That's it. Click the link that appears, confirm the device in your browser, and your SeanPropApp workspace is now powered by your AI subscription.
+
+Time to hello world: about 3 minutes on a fresh machine (Claude CLI install included). Reconnects on a paired machine take a couple of seconds.
+
+## What this is
+
+A small open-source CLI that runs locally on your computer and lets the SeanPropApp browser app send LLM requests to your Claude or ChatGPT subscription without an API key. Your prompts and your provider responses stay between your computer and your AI provider; this repo only ships the bridge code.
+
+## What you need
+
+- Node 18 or later (run `node --version`).
+- A Claude Pro subscription OR a ChatGPT Plus subscription.
+- The Claude CLI or Codex CLI installed. `connect` will guide you through this on first run.
+
+## Commands
+
+| Command             | What it does                                                |
+|---------------------|-------------------------------------------------------------|
+| `connect`           | Start everything and pair with your browser. Use this first.|
+| `bridge`            | Run the bridge server explicitly.                           |
+| `pair`              | Generate a new pair URL.                                    |
+| `mcp`               | Run as an MCP stdio server (Claude Desktop, Cursor).        |
+| `doctor`            | Self-diagnostic with actionable suggestions.                |
+| `autostart install` | Install an OS-native supervisor so the bridge starts at login. See [docs/autostart-macos.md](./docs/autostart-macos.md), [docs/autostart-linux.md](./docs/autostart-linux.md), [docs/autostart-windows.md](./docs/autostart-windows.md). |
+| `telemetry`         | `enable`, `disable`, or `status`. Default is off.           |
+
+Global flags: `--config <path>`, `--quiet`, `--json`, `--verbose`, `--no-telemetry`.
+
+## How it works
+
+The CLI runs a small HTTP server on `127.0.0.1` (default port `17492`, falling back through `17500`). The SeanPropApp browser workspace sends LLM requests to that local URL, attaching a Bearer pair token that lives only on your machine. The CLI in turn shells out to your installed Claude CLI or Codex CLI, which runs against your subscription.
+
+The bridge accepts requests only from `https://prop.seanoneill.com` (and `http://localhost:3000` for development); every other Origin is rejected with 403.
+
+## Trust signals
+
+- **Source code:** 100% in this repository. Review the bridge HTTP server, providers, and command code before installing.
+- **License:** MIT.
+- **npm provenance:** every release is published with `--provenance` (see [.github/workflows/publish.yml](./.github/workflows/publish.yml)).
+- **Telemetry:** opt-in only. See [TELEMETRY.md](./TELEMETRY.md).
+- **Security disclosure:** [SECURITY.md](./SECURITY.md) (mailto: security@seanoneill.com).
+- **Files in the npm package:** run `npm pack --dry-run` to see exactly what we ship. Currently `dist/`, `README.md`, `LICENSE`.
+
+## Status
+
+v0.1.0-beta.1. The connect/bridge/pair/mcp/doctor/autostart/telemetry commands are live. CI + npm-provenance publish are set up. The workspace-side TTHW dashboard (TX8) ships with v1.4.0 of the proposition-app workspace; until then, telemetry events land but are not visualized in-app.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md). Issues and pull requests welcome at [github.com/seanomich/seanpropapp-cli](https://github.com/seanomich/seanpropapp-cli).
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/commands/autostart.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `seanpropapp autostart install|uninstall`.
+ *
+ * macOS: writes a LaunchAgent plist + bootstraps it via `launchctl`.
+ * Linux: writes a user systemd unit + enables it via `systemctl --user`.
+ * Windows: prints the schtasks command (full Task Scheduler XML is deferred
+ *          to v1.4.1; the printed command works for users who run it themselves).
+ *
+ * The command targets `seanpropapp bridge --foreground` so the OS supervisor
+ * keeps the bridge alive across crashes / reboots.
+ */
+import { spawn } from "node:child_process";
+import { promises as fs } from "node:fs";
+export interface AutostartOptions {
+    /** macOS / Linux / Windows; defaults to process.platform. */
+    platform?: NodeJS.Platform;
+    /** Override the binary the supervisor invokes (used by tests). */
+    binPath?: string;
+    /** Override fs write/read (used by tests). */
+    fsImpl?: typeof fs;
+    /** Override spawn (used by tests). */
+    spawnFn?: typeof spawn;
+    /** Override stdout writer (used by tests). */
+    stdout?: (line: string) => void;
+    /** Override stderr writer (used by tests). */
+    stderr?: (line: string) => void;
+    /** Override $HOME (used by tests). */
+    home?: string;
+    /** Skip the launchctl / systemctl subprocess; useful in tests + dry-run. */
+    dryRun?: boolean;
+}
+export type AutostartResult = {
+    ok: true;
+    action: "install" | "uninstall";
+    path?: string;
+    manual?: string[];
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function installAutostart(opts?: AutostartOptions): Promise<AutostartResult>;
+export declare function uninstallAutostart(opts?: AutostartOptions): Promise<AutostartResult>;

package/dist/commands/autostart.js

@@ -0,0 +1,195 @@
+/**
+ * `seanpropapp autostart install|uninstall`.
+ *
+ * macOS: writes a LaunchAgent plist + bootstraps it via `launchctl`.
+ * Linux: writes a user systemd unit + enables it via `systemctl --user`.
+ * Windows: prints the schtasks command (full Task Scheduler XML is deferred
+ *          to v1.4.1; the printed command works for users who run it themselves).
+ *
+ * The command targets `seanpropapp bridge --foreground` so the OS supervisor
+ * keeps the bridge alive across crashes / reboots.
+ */
+import { spawn } from "node:child_process";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const LAUNCHD_LABEL = "com.seanpropapp.bridge";
+const SYSTEMD_UNIT = "seanpropapp-bridge.service";
+function resolveBinPath(opts) {
+    if (opts.binPath)
+        return opts.binPath;
+    // Default: try to find seanpropapp on PATH. Fall back to a placeholder the
+    // user must edit (this happens when someone runs autostart from a dev
+    // checkout that hasn't been npm-linked).
+    return "seanpropapp";
+}
+function macPlist(binPath) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LAUNCHD_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${binPath}</string>
+    <string>bridge</string>
+    <string>--foreground</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>/tmp/seanpropapp-bridge.out.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/seanpropapp-bridge.err.log</string>
+</dict>
+</plist>
+`;
+}
+function systemdUnit(binPath) {
+    return `[Unit]
+Description=SeanPropApp local bridge
+After=network.target
+
+[Service]
+ExecStart=${binPath} bridge --foreground
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+`;
+}
+async function runCmd(bin, args, spawnFn) {
+    return new Promise((resolve) => {
+        const child = spawnFn(bin, args, { stdio: ["ignore", "pipe", "pipe"] });
+        let stderr = "";
+        child.stderr?.on("data", (chunk) => {
+            stderr += typeof chunk === "string" ? chunk : chunk.toString();
+        });
+        child.once("close", (code) => resolve({ code, stderr }));
+        child.once("error", (err) => resolve({ code: -1, stderr: err.message }));
+    });
+}
+export async function installAutostart(opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const fsImpl = opts.fsImpl ?? fs;
+    const spawnFn = opts.spawnFn ?? spawn;
+    const out = opts.stdout ?? ((s) => process.stdout.write(s));
+    const err = opts.stderr ?? ((s) => process.stderr.write(s));
+    const home = opts.home ?? os.homedir();
+    const bin = resolveBinPath(opts);
+    if (platform === "darwin") {
+        const plistDir = path.join(home, "Library", "LaunchAgents");
+        const plistPath = path.join(plistDir, `${LAUNCHD_LABEL}.plist`);
+        try {
+            await fsImpl.mkdir(plistDir, { recursive: true });
+            await fsImpl.writeFile(plistPath, macPlist(bin), { mode: 0o644 });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            err(`Could not write ${plistPath}: ${msg}\n`);
+            return { ok: false, reason: msg };
+        }
+        out(`Wrote LaunchAgent: ${plistPath}\n`);
+        if (opts.dryRun) {
+            return { ok: true, action: "install", path: plistPath };
+        }
+        const uid = process.getuid?.() ?? 0;
+        const cmd = await runCmd("launchctl", ["bootstrap", `gui/${uid}`, plistPath], spawnFn);
+        if (cmd.code !== 0) {
+            err(`launchctl bootstrap exited ${cmd.code}: ${cmd.stderr.trim() || "(no stderr)"}\n` +
+                `If you see "service already loaded", run \`seanpropapp autostart uninstall\` first.\n`);
+            return { ok: false, reason: cmd.stderr || `exit ${cmd.code}` };
+        }
+        out(`Bootstrapped LaunchAgent ${LAUNCHD_LABEL}.\n`);
+        return { ok: true, action: "install", path: plistPath };
+    }
+    if (platform === "linux") {
+        const unitDir = path.join(home, ".config", "systemd", "user");
+        const unitPath = path.join(unitDir, SYSTEMD_UNIT);
+        try {
+            await fsImpl.mkdir(unitDir, { recursive: true });
+            await fsImpl.writeFile(unitPath, systemdUnit(bin), { mode: 0o644 });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            err(`Could not write ${unitPath}: ${msg}\n`);
+            return { ok: false, reason: msg };
+        }
+        out(`Wrote systemd unit: ${unitPath}\n`);
+        if (opts.dryRun) {
+            return { ok: true, action: "install", path: unitPath };
+        }
+        const enable = await runCmd("systemctl", ["--user", "enable", "--now", SYSTEMD_UNIT], spawnFn);
+        if (enable.code !== 0) {
+            err(`systemctl --user exited ${enable.code}: ${enable.stderr.trim() || "(no stderr)"}\n` +
+                `If you're on a server without lingering enabled, run: \`sudo loginctl enable-linger $USER\`\n`);
+            return { ok: false, reason: enable.stderr || `exit ${enable.code}` };
+        }
+        out(`Enabled ${SYSTEMD_UNIT}.\n`);
+        return { ok: true, action: "install", path: unitPath };
+    }
+    if (platform === "win32") {
+        // TODO v1.4.1: emit a Task Scheduler XML and import it via `schtasks /create /XML`.
+        const cmd = `schtasks /create /SC ONLOGON /RL HIGHEST /TN "SeanPropApp Bridge" /TR "${bin} bridge --foreground"`;
+        out("Windows full auto-install is deferred to v1.4.1. Run this once to register the task:\n\n  " +
+            cmd +
+            "\n\nOr open Task Scheduler and create a new task pointing at the same command.\n");
+        return { ok: true, action: "install", manual: [cmd] };
+    }
+    err(`Unsupported platform: ${platform}\n`);
+    return { ok: false, reason: `unsupported platform ${platform}` };
+}
+export async function uninstallAutostart(opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const fsImpl = opts.fsImpl ?? fs;
+    const spawnFn = opts.spawnFn ?? spawn;
+    const out = opts.stdout ?? ((s) => process.stdout.write(s));
+    const err = opts.stderr ?? ((s) => process.stderr.write(s));
+    const home = opts.home ?? os.homedir();
+    if (platform === "darwin") {
+        const plistPath = path.join(home, "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
+        if (!opts.dryRun) {
+            const uid = process.getuid?.() ?? 0;
+            const cmd = await runCmd("launchctl", ["bootout", `gui/${uid}/${LAUNCHD_LABEL}`], spawnFn);
+            if (cmd.code !== 0 && !/No such process/i.test(cmd.stderr)) {
+                err(`launchctl bootout warning (continuing): ${cmd.stderr.trim()}\n`);
+            }
+        }
+        try {
+            await fsImpl.unlink(plistPath);
+            out(`Removed ${plistPath}\n`);
+        }
+        catch {
+            out(`No plist at ${plistPath}; nothing to remove.\n`);
+        }
+        return { ok: true, action: "uninstall", path: plistPath };
+    }
+    if (platform === "linux") {
+        const unitPath = path.join(home, ".config", "systemd", "user", SYSTEMD_UNIT);
+        if (!opts.dryRun) {
+            await runCmd("systemctl", ["--user", "disable", "--now", SYSTEMD_UNIT], spawnFn);
+        }
+        try {
+            await fsImpl.unlink(unitPath);
+            out(`Removed ${unitPath}\n`);
+        }
+        catch {
+            out(`No unit at ${unitPath}; nothing to remove.\n`);
+        }
+        return { ok: true, action: "uninstall", path: unitPath };
+    }
+    if (platform === "win32") {
+        const cmd = 'schtasks /delete /TN "SeanPropApp Bridge" /F';
+        out("Windows uninstall is deferred to v1.4.1. Run this once to remove the task:\n\n  " +
+            cmd +
+            "\n");
+        return { ok: true, action: "uninstall", manual: [cmd] };
+    }
+    err(`Unsupported platform: ${platform}\n`);
+    return { ok: false, reason: `unsupported platform ${platform}` };
+}
+//# sourceMappingURL=autostart.js.map

package/dist/commands/autostart.js.map

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

package/dist/commands/bridge.d.ts

@@ -0,0 +1,54 @@
+export interface BridgeRunOptions {
+    port?: number;
+    foreground?: boolean;
+    /** When true (the default), reuse a token from config; otherwise generate. */
+    reuseToken?: boolean;
+    /** Override config dir (used by tests). */
+    configDir?: string;
+    /** Pre-supplied token (used by `connect` which generates it first). */
+    token?: string;
+}
+/**
+ * Foreground bridge: bind the HTTP server and stay alive until interrupted.
+ *
+ * Listens for SIGHUP and reloads the pair token from disk so `seanpropapp pair`
+ * can rotate the token without restarting the bridge. SIGINT / SIGTERM trigger
+ * a clean shutdown.
+ */
+export declare function runBridgeForeground(opts: BridgeRunOptions): Promise<void>;
+/**
+ * Poll the bridge until it responds, or the timeout elapses. Returns true
+ * when reachable.
+ */
+export declare function waitForBridge(port: number, token: string, opts?: {
+    timeoutMs?: number;
+    pollMs?: number;
+    fetchImpl?: typeof fetch;
+    nowFn?: () => number;
+    sleepFn?: (ms: number) => Promise<void>;
+}): Promise<boolean>;
+/**
+ * Spawn the current CLI binary in foreground mode as a detached child so the
+ * parent process can return immediately. Used by `connect`.
+ *
+ * After spawning, polls /v1/handshake every 100ms for up to 3s to confirm
+ * the child actually bound the port. Lane C-Core's probe-bind-close-then-spawn
+ * dance has a sub-second race window we close here.
+ *
+ * Returns the child's PID + whether the post-spawn handshake succeeded.
+ * If `requireHealthy` is true (the default), throws when the handshake never
+ * comes up so the caller can fail fast with a clear error.
+ */
+export declare function spawnBackgroundBridge(opts: {
+    port?: number;
+    token: string;
+    configDir?: string;
+    requireHealthy?: boolean;
+    /** Test seam: skip the post-spawn poll entirely. */
+    skipHealthcheck?: boolean;
+    /** Test seam: override fetch used by the post-spawn poll. */
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    pid: number | undefined;
+    healthy: boolean;
+}>;

package/dist/commands/bridge.js

@@ -0,0 +1,145 @@
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { startServer } from "../http/server.js";
+import { generatePairToken } from "./pair-url.js";
+import { loadConfig, updateConfig, getConfigPath } from "../config.js";
+const HEALTHCHECK_TIMEOUT_MS = 3_000;
+const HEALTHCHECK_POLL_MS = 100;
+/**
+ * Foreground bridge: bind the HTTP server and stay alive until interrupted.
+ *
+ * Listens for SIGHUP and reloads the pair token from disk so `seanpropapp pair`
+ * can rotate the token without restarting the bridge. SIGINT / SIGTERM trigger
+ * a clean shutdown.
+ */
+export async function runBridgeForeground(opts) {
+    const cfg = await loadConfig(opts.configDir);
+    let currentToken = opts.token ??
+        (opts.reuseToken && cfg.pair_token ? cfg.pair_token : generatePairToken());
+    let currentPairedAt = cfg.paired_at ?? null;
+    const running = await startServer({
+        token: () => currentToken,
+        port: opts.port,
+        pairedAt: () => currentPairedAt,
+    });
+    await updateConfig({
+        pair_token: currentToken,
+        bridge_url: running.url,
+        bridge_port: running.port,
+    }, opts.configDir);
+    process.stdout.write(`Bridge ready on port ${running.port}\n`);
+    process.stdout.write(`URL: ${running.url}\n`);
+    process.stdout.write(`Config: ${getConfigPath(opts.configDir)}\n`);
+    process.stdout.write("Press Ctrl-C to stop.\n");
+    const reloadOnSighup = async () => {
+        try {
+            const next = await loadConfig(opts.configDir);
+            if (next.pair_token && next.pair_token !== currentToken) {
+                currentToken = next.pair_token;
+                process.stdout.write("SIGHUP: reloaded pair token from config.\n");
+            }
+            else {
+                process.stdout.write("SIGHUP: no token change in config; bridge token unchanged.\n");
+            }
+            if (next.paired_at && next.paired_at !== currentPairedAt) {
+                currentPairedAt = next.paired_at;
+            }
+        }
+        catch (err) {
+            process.stderr.write(`SIGHUP: failed to reload config: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    };
+    process.on("SIGHUP", reloadOnSighup);
+    // Keep alive until SIGINT / SIGTERM.
+    await new Promise((resolve) => {
+        const shutdown = async () => {
+            process.off("SIGHUP", reloadOnSighup);
+            await running.close();
+            resolve();
+        };
+        process.once("SIGINT", shutdown);
+        process.once("SIGTERM", shutdown);
+    });
+}
+/**
+ * Probe the bridge's /v1/handshake endpoint, returning true if the server
+ * is reachable. Used by the post-spawn health check.
+ */
+async function pingHandshake(port, token, fetchImpl = fetch) {
+    try {
+        const res = await fetchImpl(`http://127.0.0.1:${port}/v1/handshake`, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        return res.ok || res.status === 401; // 401 still means "server is up".
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Poll the bridge until it responds, or the timeout elapses. Returns true
+ * when reachable.
+ */
+export async function waitForBridge(port, token, opts = {}) {
+    const now = opts.nowFn ?? (() => Date.now());
+    const sleep = opts.sleepFn ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const timeout = opts.timeoutMs ?? HEALTHCHECK_TIMEOUT_MS;
+    const poll = opts.pollMs ?? HEALTHCHECK_POLL_MS;
+    const deadline = now() + timeout;
+    while (now() < deadline) {
+        if (await pingHandshake(port, token, fetchImpl))
+            return true;
+        await sleep(poll);
+    }
+    return false;
+}
+/**
+ * Spawn the current CLI binary in foreground mode as a detached child so the
+ * parent process can return immediately. Used by `connect`.
+ *
+ * After spawning, polls /v1/handshake every 100ms for up to 3s to confirm
+ * the child actually bound the port. Lane C-Core's probe-bind-close-then-spawn
+ * dance has a sub-second race window we close here.
+ *
+ * Returns the child's PID + whether the post-spawn handshake succeeded.
+ * If `requireHealthy` is true (the default), throws when the handshake never
+ * comes up so the caller can fail fast with a clear error.
+ */
+export async function spawnBackgroundBridge(opts) {
+    // Resolve the path to our own CLI entrypoint. When installed via npm, this
+    // file lives at dist/commands/bridge.js, and the entry binary is dist/index.js.
+    const here = fileURLToPath(import.meta.url);
+    const entry = path.resolve(path.dirname(here), "..", "index.js");
+    const args = ["bridge", "--foreground", "--no-token-rotation"];
+    if (opts.port)
+        args.push("--port", String(opts.port));
+    if (opts.configDir)
+        args.push("--config", opts.configDir);
+    const child = spawn(process.execPath, [entry, ...args], {
+        detached: true,
+        stdio: "ignore",
+        env: {
+            ...process.env,
+            SEANPROPAPP_PRESEED_TOKEN: opts.token,
+        },
+    });
+    child.unref();
+    if (opts.skipHealthcheck || !opts.port) {
+        // Without a known port, the parent can't probe; the caller (connect.ts)
+        // bound + closed the port itself, so it can fall back to its own check.
+        return { pid: child.pid, healthy: false };
+    }
+    const healthOpts = {};
+    if (opts.fetchImpl)
+        healthOpts.fetchImpl = opts.fetchImpl;
+    const healthy = await waitForBridge(opts.port, opts.token, healthOpts);
+    if (!healthy && opts.requireHealthy !== false) {
+        throw new Error(`Bridge process spawned (pid ${child.pid ?? "unknown"}) but did not become reachable on port ${opts.port} within ${HEALTHCHECK_TIMEOUT_MS}ms. ` +
+            "Run `seanpropapp doctor` to inspect, or try `seanpropapp bridge --foreground` to see the bridge's own stderr.");
+    }
+    return { pid: child.pid, healthy };
+}
+//# sourceMappingURL=bridge.js.map

package/dist/commands/bridge.js.map

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

package/dist/commands/connect.d.ts

@@ -0,0 +1,56 @@
+import type { Provider } from "../providers/base.js";
+export interface ConnectOptions {
+    /** When true, the bridge runs in this process instead of being detached. */
+    noBridgeFork?: boolean;
+    /** Override the requested initial port. */
+    port?: number;
+    /** Override config dir. */
+    configDir?: string;
+    /**
+     * Test seam: skip Y/N prompt + install. Always treats Claude as detected.
+     * Tests use this so they don't depend on terminal input.
+     */
+    skipInstallPrompt?: boolean;
+    /** Test seam: skip the browser launch. */
+    skipBrowserOpen?: boolean;
+    /** Test seam: provider override for detection in unit tests. */
+    providers?: {
+        claude?: Provider;
+        codex?: Provider;
+    };
+    /** Stdout writer override for tests. */
+    stdout?: (line: string) => void;
+    /** Stderr writer override for tests. */
+    stderr?: (line: string) => void;
+    /**
+     * Test seam: skip the handshake wait loop and pretend the user paired
+     * immediately at this timestamp.
+     */
+    fakePairedAt?: string;
+    /** When true, suppress telemetry emit for this run (--no-telemetry). */
+    noTelemetry?: boolean;
+    /**
+     * Test seam: skip the post-spawn bridge healthcheck. Production code never
+     * sets this; only the connect.test.ts happy-path test does so it can run
+     * without an actual `dist/` build to spawn.
+     */
+    skipBridgeHealthcheck?: boolean;
+}
+export interface ConnectResult {
+    success: boolean;
+    elapsedSeconds: number;
+    bridgePort?: number;
+    pairUrl?: string;
+    reason?: string;
+}
+/**
+ * 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 declare function runConnect(opts?: ConnectOptions): Promise<ConnectResult>;