debughub 1.0.0

package/README.md

@@ -0,0 +1,49 @@
+# DebugHub
+
+A cross-platform CLI tool providing a Cursor-like "Debug Mode" loop for any coding agent (Codex, Claude, etc.), without requiring MCP or complex remote execution setups.
+
+## Features
+- **Runtime Setup Guide**: See `docs/RUNTIME_PREREQS.md` for installing Java/Go/Python/Rust/PHP/.NET required by helper E2E tests.
+- **Agent-Agnostic**: Works with any coding assistant capable of modifying files and running basic OS commands.
+- **Vendored Runtime Helpers**: Small, standalone helpers for TypeScript/Node, Browser TS/JS, Java, Python, Rust, PHP, Go, and C# are installed in `.debughub/vendor`.
+- **Shared HTTP Contract**: All helpers follow one event contract (`.debughub/vendor/<version>/http/EVENT_CONTRACT.md` after `debughub install`) and submit best-effort HTTP events to the local collector.
+- **Deterministic**: A `MANIFEST.json` and strict integrity verification ensures files are not tampered with.
+- **Safe and Local**: By default, the collector server only binds to `127.0.0.1`.
+
+## Quick Start
+
+1. Install inside any repository:
+```bash
+npx debughub install
+```
+2. Start the local collector:
+```bash
+npx debughub start
+```
+3. Read the given `sessionId` and endpoint. Follow the instructions to configure your environment variables:
+   - `DEBUGHUB_ENABLED=1`
+   - `DEBUGHUB_SESSION=<sessionId>`
+   - `DEBUGHUB_ENDPOINT=http://127.0.0.1:<port>`
+
+4. Use the helper inside your app code (see `.debughub/vendor/<version>`).
+5. Run your app and reproduce the issue.
+6. Check logs:
+```bash
+npx debughub tail --n 50
+```
+
+## Security Model
+- No network traffic leaves your local machine.
+- No remote code is downloaded at runtime.
+- No `eval` or shell spawning in helpers.
+- The `debughub verify` command validates the helper code matches the official SHA-256 signatures.
+
+## Commands
+- `debughub install`: Installs support files to `.debughub/`.
+- `debughub start`: Starts the collector server in the background.
+- `debughub stop`: Stops the background collector.
+- `debughub tail`: Print the latest recorded events.
+- `debughub search "<query>"`: Search events by text or label.
+- `debughub clear`: Clears the output log file.
+- `debughub verify`: Verifies integrity of the vendor code in `.debughub/`.
+- `debughub doctor`: Checks installation and system status.

package/dist/cli.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const install_1 = require("./commands/install");
+const start_1 = require("./commands/start");
+const stop_1 = require("./commands/stop");
+const tail_1 = require("./commands/tail");
+const search_1 = require("./commands/search");
+const clear_1 = require("./commands/clear");
+const verify_1 = require("./commands/verify");
+const doctor_1 = require("./commands/doctor");
+const server_1 = require("./commands/server");
+const program = new commander_1.Command();
+const pkg = require('../package.json');
+program
+    .name('debughub')
+    .description('DebugHub: Agent-agnostic local debug loop')
+    .version(pkg.version);
+program.command('install')
+    .description('Installs vendored DebugHub runtime helpers into the current repo')
+    .action(install_1.install);
+program.command('start')
+    .description('Starts the local collector server')
+    .action(start_1.start);
+program.command('stop')
+    .description('Stops the local collector server')
+    .action(stop_1.stop);
+program.command('tail')
+    .description('Tails the last N events')
+    .option('-n, --n <number>', 'Number of events', '200')
+    .option('--session <id>', 'Session ID')
+    .option('--json', 'Print raw JSON instead of pretty output', false)
+    .action(tail_1.tail);
+program.command('search <query>')
+    .description('Searches the JSONL file for substring matches')
+    .option('--label <label>', 'Filter by label')
+    .option('--hypothesis <id>', 'Filter by hypothesisId')
+    .option('--level <level>', 'Filter by level')
+    .option('--session <id>', 'Session ID')
+    .action(search_1.search);
+program.command('clear')
+    .description('Clears the current session output file')
+    .option('--session <id>', 'Session ID')
+    .action(clear_1.clear);
+program.command('verify')
+    .description('Verifies integrity of installed vendor files')
+    .action(verify_1.verify);
+program.command('doctor')
+    .description('Prints quick diagnostics')
+    .action(doctor_1.doctor);
+program.command('_server <sessionId> <port>', { hidden: true })
+    .action(server_1._server);
+program.parse(process.argv);

package/dist/commands/clear.js

@@ -0,0 +1,65 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clear = clear;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function clear(options) {
+    const cwd = process.cwd();
+    const debughubDir = path.join(cwd, '.debughub');
+    let sessionId = options.session;
+    if (!sessionId) {
+        const stateFile = path.join(debughubDir, 'state.json');
+        if (fs.existsSync(stateFile)) {
+            try {
+                const state = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+                sessionId = state.session;
+            }
+            catch (e) { }
+        }
+    }
+    if (!sessionId) {
+        console.error('Could not determine active session ID.');
+        process.exit(1);
+    }
+    const outFile = path.join(debughubDir, 'out', `${sessionId}.jsonl`);
+    if (fs.existsSync(outFile)) {
+        fs.truncateSync(outFile, 0);
+        console.log(`Cleared log file for session ${sessionId}`);
+    }
+    else {
+        console.log(`Session ${sessionId} has no log file yet.`);
+    }
+}

package/dist/commands/doctor.js

@@ -0,0 +1,96 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.doctor = doctor;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const http = __importStar(require("http"));
+function doctor() {
+    const cwd = process.cwd();
+    const debughubDir = path.join(cwd, '.debughub');
+    const stateFile = path.join(debughubDir, 'state.json');
+    const currentLink = path.join(debughubDir, 'vendor', 'current');
+    console.log('🩺 DebugHub Doctor');
+    console.log('==================');
+    // Check 1: Installation
+    const installed = fs.existsSync(currentLink);
+    console.log(`[${installed ? 'x' : ' '}] Installation: .debughub/vendor directory exists`);
+    if (installed) {
+        const version = fs.readFileSync(currentLink, 'utf-8').trim();
+        console.log(`    Version linked: ${version}`);
+    }
+    // Check 2: Collector status
+    const isRunning = fs.existsSync(stateFile);
+    console.log(`[${isRunning ? 'x' : ' '}] Collector   : Running state found`);
+    if (isRunning) {
+        try {
+            const state = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+            console.log(`    Session ID: ${state.session}`);
+            console.log(`    PID       : ${state.pid}`);
+            console.log(`    Port      : ${state.port}`);
+            // Check writable output
+            const outFile = path.join(debughubDir, 'out', `${state.session}.jsonl`);
+            try {
+                fs.accessSync(path.dirname(outFile), fs.constants.W_OK);
+                console.log(`[x] Output Path : ${outFile} is reachable/writable`);
+            }
+            catch (e) {
+                console.log(`[ ] Output Path : ${outFile} is NOT writable`);
+            }
+            // Check Reachability
+            const req = http.request({
+                hostname: '127.0.0.1',
+                port: state.port,
+                path: '/event',
+                method: 'OPTIONS',
+            }, (res) => {
+                if (res.statusCode === 204) {
+                    console.log(`[x] Reachability: Endpoint http://127.0.0.1:${state.port}/event is responding`);
+                }
+                else {
+                    console.log(`[ ] Reachability: Endpoint responded with ${res.statusCode}`);
+                }
+            });
+            req.on('error', (e) => {
+                console.log(`[ ] Reachability: Error connecting to endpoint: ${e.message}`);
+            });
+            req.end();
+            return;
+        }
+        catch (e) {
+            console.log(`    State file is unreadable or corrupt.`);
+        }
+    }
+}

package/dist/commands/install.js

@@ -0,0 +1,88 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.install = install;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const verify_1 = require("./verify");
+function install() {
+    const pkg = require('../../package.json');
+    const version = pkg.version;
+    const cwd = process.cwd();
+    const debughubDir = path.join(cwd, '.debughub');
+    const targetVendorDir = path.join(debughubDir, 'vendor', version);
+    const currentLinkFile = path.join(debughubDir, 'vendor', 'current');
+    // Find source bundle
+    const distVendorPath = path.resolve(__dirname, '..', 'vendor', version);
+    if (!fs.existsSync(distVendorPath)) {
+        console.error(`Error: Cannot find DebugHub distribution bundle for v${version} at ${distVendorPath}`);
+        process.exit(1);
+    }
+    // Create target structure
+    fs.mkdirSync(targetVendorDir, { recursive: true });
+    fs.mkdirSync(path.join(debughubDir, 'out'), { recursive: true });
+    // Copy files
+    copyRecursiveSync(distVendorPath, targetVendorDir);
+    // Update "current" pointer (use a text file to avoid symlink issues on windows)
+    fs.writeFileSync(currentLinkFile, version, 'utf-8');
+    // Write default config
+    const configFile = path.join(debughubDir, 'debughub.json');
+    if (!fs.existsSync(configFile)) {
+        fs.writeFileSync(configFile, JSON.stringify({
+            bindHost: "127.0.0.1",
+            allowRemote: false
+        }, null, 2), 'utf-8');
+    }
+    console.log(`DebugHub v${version} vendor files installed to .debughub/vendor/${version}`);
+    console.log(`Verifying installation...`);
+    const isValid = (0, verify_1.verifyVendorFiles)(cwd);
+    if (!isValid) {
+        console.error('Verify failed immediately after install. Installation might be corrupted.');
+        process.exit(1);
+    }
+    console.log('Installation verified successfully ✨');
+}
+function copyRecursiveSync(src, dest) {
+    const stat = fs.statSync(src);
+    if (stat.isDirectory()) {
+        fs.mkdirSync(dest, { recursive: true });
+        for (const child of fs.readdirSync(src)) {
+            copyRecursiveSync(path.join(src, child), path.join(dest, child));
+        }
+    }
+    else {
+        fs.copyFileSync(src, dest);
+    }
+}

package/dist/commands/search.js

@@ -0,0 +1,106 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.search = search;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function search(query, options) {
+    const cwd = process.cwd();
+    const debughubDir = path.join(cwd, '.debughub');
+    let sessionId = options.session;
+    if (!sessionId) {
+        const stateFile = path.join(debughubDir, 'state.json');
+        if (fs.existsSync(stateFile)) {
+            try {
+                const state = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+                sessionId = state.session;
+            }
+            catch (e) { }
+        }
+    }
+    if (!sessionId) {
+        console.error('Could not determine active session ID. Provide --session or run `debughub start`.');
+        process.exit(1);
+    }
+    const outFile = path.join(debughubDir, 'out', `${sessionId}.jsonl`);
+    if (!fs.existsSync(outFile)) {
+        console.log(`No events yet in session ${sessionId}`);
+        return;
+    }
+    const content = fs.readFileSync(outFile, 'utf-8');
+    const lines = content.trim().split('\n').filter(Boolean);
+    let matches = 0;
+    for (const l of lines) {
+        try {
+            const parsed = JSON.parse(l);
+            // Filters
+            if (options.label && parsed.label !== options.label)
+                continue;
+            if (options.hypothesis && parsed.hypothesisId !== options.hypothesis)
+                continue;
+            if (options.level && parsed.level !== options.level)
+                continue;
+            // Substring match
+            if (query && !l.includes(query))
+                continue;
+            matches++;
+            const ts = new Date(parsed.ts).toLocaleTimeString();
+            const levelColorStr = parsed.level === 'error' ? '\x1b[31m[ERROR]\x1b[0m' :
+                parsed.level === 'warn' ? '\x1b[33m[WARN]\x1b[0m' :
+                    '\x1b[36m[INFO]\x1b[0m';
+            let meta = '';
+            if (parsed.hypothesisId)
+                meta += ` [H:${parsed.hypothesisId}]`;
+            if (parsed.loc)
+                meta += ` [L:${parsed.loc}]`;
+            console.log(`[${ts}] ${levelColorStr} ${parsed.label}${meta}`);
+            if (parsed.data !== null) {
+                console.dir(parsed.data, { depth: 4, colors: true });
+            }
+        }
+        catch (e) {
+            if (query && l.includes(query)) {
+                matches++;
+                console.log(l);
+            }
+        }
+    }
+    if (matches === 0) {
+        console.log(`No matches found for query: "${query}"`);
+    }
+    else {
+        console.log(`\nFound ${matches} match(es).`);
+    }
+}

package/dist/commands/server.js

@@ -0,0 +1,94 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._server = _server;
+const http = __importStar(require("http"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function _server(sessionId, portStr) {
+    const cwd = process.cwd();
+    const stateFile = path.join(cwd, '.debughub', 'state.json');
+    const outFile = path.join(cwd, '.debughub', 'out', `${sessionId}.jsonl`);
+    const server = http.createServer((req, res) => {
+        // Basic CORS
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        if (req.method === 'POST' && req.url === '/event') {
+            let body = '';
+            req.on('data', chunk => {
+                body += chunk.toString();
+            });
+            req.on('end', () => {
+                try {
+                    fs.appendFileSync(outFile, body + '\n', 'utf-8');
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: true }));
+                }
+                catch (e) {
+                    res.writeHead(500);
+                    res.end();
+                }
+            });
+        }
+        else {
+            res.writeHead(404);
+            res.end();
+        }
+    });
+    server.listen(parseInt(portStr, 10), '127.0.0.1', () => {
+        const address = server.address();
+        const port = address.port;
+        fs.writeFileSync(stateFile, JSON.stringify({
+            pid: process.pid,
+            session: sessionId,
+            port: port
+        }, null, 2));
+        // Cleanup on exit
+        const cleanup = () => {
+            if (fs.existsSync(stateFile)) {
+                fs.unlinkSync(stateFile);
+            }
+            process.exit();
+        };
+        process.on('SIGINT', cleanup);
+        process.on('SIGTERM', cleanup);
+    });
+}

package/dist/commands/start.js

@@ -0,0 +1,123 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.start = start;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const child_process_1 = require("child_process");
+function start() {
+    const cwd = process.cwd();
+    const debughubDir = path.join(cwd, '.debughub');
+    const stateFile = path.join(debughubDir, 'state.json');
+    if (!fs.existsSync(debughubDir)) {
+        console.error('Error: .debughub directory not found. Did you run `debughub install`?');
+        process.exit(1);
+    }
+    // Check if already running
+    if (fs.existsSync(stateFile)) {
+        let state = null;
+        try {
+            state = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+        }
+        catch (e) { }
+        if (state?.pid) {
+            let isRunning = false;
+            try {
+                process.kill(state.pid, 0); // test if running
+                isRunning = true;
+            }
+            catch (e) {
+                // Process not actually running, clear state
+                fs.unlinkSync(stateFile);
+            }
+            if (isRunning) {
+                console.error(`Collector is already running with PID ${state.pid} (Session: ${state.session})`);
+                console.error(`Run \`debughub stop\` to stop it first.`);
+                process.exit(1);
+            }
+        }
+    }
+    const sessionId = crypto.randomUUID();
+    const outDir = path.join(debughubDir, 'out');
+    fs.mkdirSync(outDir, { recursive: true });
+    const port = process.env.DEBUGHUB_PORT ? parseInt(process.env.DEBUGHUB_PORT, 10) : 0; // 0 means pick random
+    // Spawn the server in detached mode
+    const cliPath = path.resolve(__dirname, '..', 'cli.js');
+    const outLog = fs.openSync(path.join(debughubDir, 'server.log'), 'a');
+    const errLog = fs.openSync(path.join(debughubDir, 'error.log'), 'a');
+    const child = (0, child_process_1.spawn)(process.execPath, [cliPath, '_server', sessionId, port.toString()], {
+        detached: true,
+        stdio: ['ignore', outLog, errLog]
+    });
+    child.unref();
+    // We need to wait a tiny bit to read the port from state file that the child writes,
+    // or the child can write it and we just tell the user to check `.debughub/state.json`.
+    // To be user-friendly, let's wait up to 2 seconds for state.json to appear with our sessionId
+    let attempts = 0;
+    let finalPort = port;
+    while (attempts < 20) {
+        if (fs.existsSync(stateFile)) {
+            try {
+                const state = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+                if (state.session === sessionId && state.port) {
+                    finalPort = state.port;
+                    break;
+                }
+            }
+            catch (e) { }
+        }
+        // sleep
+        const startTm = Date.now();
+        while (Date.now() - startTm < 100) {
+            // intentional busy-wait to keep implementation synchronous
+        }
+        attempts++;
+    }
+    if (finalPort === 0) {
+        console.log("Started collector but couldn't confirm port. Check .debughub/state.json");
+        // Fallback display
+    }
+    else {
+        console.log(`\nDebugHub Collector Started!`);
+        console.log(`Session ID   : ${sessionId}`);
+        console.log(`Endpoint     : http://127.0.0.1:${finalPort}/event`);
+        console.log(`Output File  : .debughub/out/${sessionId}.jsonl`);
+        console.log(`\nEnvironment variables to set:`);
+        console.log(`  DEBUGHUB_ENABLED=1`);
+        console.log(`  DEBUGHUB_SESSION=${sessionId}`);
+        console.log(`  DEBUGHUB_ENDPOINT=http://127.0.0.1:${finalPort}\n`);
+    }
+}