claw-design 1.0.1

package/dist/cli/utils/port-detect.js

@@ -0,0 +1,95 @@
+import { createConnection } from 'node:net';
+import { execFileSync } from 'node:child_process';
+/**
+ * Ordered patterns for extracting port numbers from dev server stdout.
+ * Most specific first to avoid false positives (Pitfall 4 from research).
+ */
+export const PORT_PATTERNS = [
+    // Full URL: http://localhost:3000, https://127.0.0.1:8080, http://0.0.0.0:4321, http://[::]:3000
+    /https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::\]):(\d+)/,
+    // "listening on port 3000", "running at port 8080", "started server on 0.0.0.0:3000"
+    /(?:listening|running|started\s+server)\s+(?:on|at)\s+(?:(?:\S+:)?(?:port\s+)?)?(\d+)/i,
+    // "port: 3000", "Port 3000", "PORT=3000"
+    /\b(?:port|Port|PORT)\s*[:=]?\s*(\d+)/,
+    // Fallback: any :NNNNN (4-5 digit port after colon) -- most generic, last resort
+    /:(\d{4,5})\b/,
+];
+/**
+ * Lines containing these phrases are error messages about ports, not actual
+ * listening announcements. Filter them out to avoid false positives like
+ * "Port 3016 is already in use" being detected as the dev server port.
+ */
+const PORT_ERROR_PHRASES = /(?:in use|EADDRINUSE|already|error|failed|unavailable)/i;
+/**
+ * Extract a port number from dev server output text.
+ * Tests patterns from most specific (URL) to least specific (colon:digits).
+ * Filters out error lines to avoid false positives from port-in-use messages.
+ * Returns null if no valid port found.
+ */
+export function extractPortFromOutput(output) {
+    // Filter out lines that mention port errors before matching
+    const cleanedOutput = output
+        .split('\n')
+        .filter(line => !PORT_ERROR_PHRASES.test(line))
+        .join('\n');
+    for (const pattern of PORT_PATTERNS) {
+        const match = cleanedOutput.match(pattern);
+        if (match) {
+            const port = parseInt(match[1], 10);
+            if (port > 0 && port <= 65535)
+                return port;
+        }
+    }
+    return null;
+}
+/**
+ * Poll a TCP port until it accepts connections or timeout expires.
+ * Default timeout: 30s (per D-09). Default poll interval: 250ms.
+ */
+export function waitForPort(port, opts) {
+    const timeout = opts?.timeout ?? 30_000;
+    const interval = opts?.interval ?? 250;
+    return new Promise((resolve, reject) => {
+        const startTime = Date.now();
+        function attempt() {
+            if (Date.now() - startTime > timeout) {
+                reject(new Error(`Timeout: port ${port} not ready after ${timeout / 1000}s`));
+                return;
+            }
+            const socket = createConnection({ port, host: '127.0.0.1' });
+            socket.once('connect', () => {
+                socket.destroy();
+                resolve();
+            });
+            socket.once('error', () => {
+                socket.destroy();
+                setTimeout(attempt, interval);
+            });
+        }
+        attempt();
+    });
+}
+/**
+ * Attempt to identify which process is listening on a given port.
+ * Best-effort -- returns null if lsof/ps unavailable or port is free.
+ * Used for D-14: port-in-use diagnostics.
+ */
+export function getProcessOnPort(port) {
+    try {
+        const pidStr = execFileSync('lsof', ['-i', `:${port}`, '-t'], {
+            encoding: 'utf-8',
+        }).trim();
+        // lsof may return multiple PIDs (one per line); take the first
+        const pid = parseInt(pidStr.split('\n')[0], 10);
+        if (Number.isNaN(pid))
+            return null;
+        const name = execFileSync('ps', ['-p', String(pid), '-o', 'comm='], {
+            encoding: 'utf-8',
+        }).trim();
+        return { pid, name };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=port-detect.js.map

package/dist/cli/utils/port-detect.js.map

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

package/dist/cli/utils/preflight.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Parse Node.js version string to major version number.
+ * Exported for testability.
+ */
+export declare function parseNodeMajor(versionString: string): number;
+/**
+ * Check if the running Node.js version meets the minimum requirement (>= 20).
+ * Per D-14: fast pre-flight check before any async work.
+ */
+export declare function checkNodeVersion(): {
+    ok: boolean;
+    version: string;
+};
+/**
+ * Check if the Electron binary is installed and accessible.
+ * Uses the same resolution pattern as electron.ts:spawnElectron().
+ * Per D-14: catches missing electron after npm install failures.
+ */
+export declare function checkElectronBinary(): boolean;
+//# sourceMappingURL=preflight.d.ts.map

package/dist/cli/utils/preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/preflight.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAGnE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAQ7C"}

package/dist/cli/utils/preflight.js

@@ -0,0 +1,33 @@
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+/**
+ * Parse Node.js version string to major version number.
+ * Exported for testability.
+ */
+export function parseNodeMajor(versionString) {
+    return parseInt(versionString.split('.')[0], 10);
+}
+/**
+ * Check if the running Node.js version meets the minimum requirement (>= 20).
+ * Per D-14: fast pre-flight check before any async work.
+ */
+export function checkNodeVersion() {
+    const major = parseNodeMajor(process.versions.node);
+    return { ok: major >= 20, version: process.versions.node };
+}
+/**
+ * Check if the Electron binary is installed and accessible.
+ * Uses the same resolution pattern as electron.ts:spawnElectron().
+ * Per D-14: catches missing electron after npm install failures.
+ */
+export function checkElectronBinary() {
+    try {
+        const require = createRequire(import.meta.url);
+        const electronPath = require('electron');
+        return typeof electronPath === 'string' && existsSync(electronPath);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=preflight.js.map

package/dist/cli/utils/preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.js","sourceRoot":"","sources":["../../../src/cli/utils/preflight.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,aAAqB;IAClD,OAAO,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACnD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACpD,OAAO,EAAE,EAAE,EAAE,KAAK,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;AAC7D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB;IACjC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC/C,MAAM,YAAY,GAAG,OAAO,CAAC,UAAU,CAAsB,CAAC;QAC9D,OAAO,OAAO,YAAY,KAAK,QAAQ,IAAI,UAAU,CAAC,YAAY,CAAC,CAAC;IACtE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/cli/utils/process.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Processes managed by the shutdown coordinator.
+ * Each field is optional -- only populated when the process has been spawned.
+ */
+export interface ManagedProcesses {
+    devServer?: {
+        pid: number;
+    };
+    electronProcess?: {
+        pid: number;
+    };
+}
+/**
+ * Register signal handlers for graceful shutdown of all managed processes.
+ * Coordinates ordered teardown: Claude session, Electron, dev server.
+ * Idempotent -- second shutdown call is a no-op.
+ */
+export declare function registerShutdownHandlers(processes: ManagedProcesses): void;
+/**
+ * Reset shutdown state for testing. Removes registered signal listeners.
+ */
+export declare function resetShutdownState(): void;
+//# sourceMappingURL=process.d.ts.map

package/dist/cli/utils/process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/process.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5B,eAAe,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CACnC;AAKD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,gBAAgB,GAAG,IAAI,CA+C1E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAMzC"}

package/dist/cli/utils/process.js

@@ -0,0 +1,57 @@
+import kill from 'tree-kill';
+import pc from 'picocolors';
+let shuttingDown = false;
+const registeredListeners = [];
+/**
+ * Register signal handlers for graceful shutdown of all managed processes.
+ * Coordinates ordered teardown: Claude session, Electron, dev server.
+ * Idempotent -- second shutdown call is a no-op.
+ */
+export function registerShutdownHandlers(processes) {
+    function shutdown(signal) {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        console.log(pc.dim(`\n  Shutting down (${signal})...`));
+        // Force exit after 5s if kills hang
+        setTimeout(() => process.exit(1), 5000).unref();
+        // Step 2: Kill process trees, wait for completion before exiting
+        let pending = 0;
+        function onKilled() {
+            pending--;
+            if (pending === 0)
+                process.exit(0);
+        }
+        if (processes.electronProcess?.pid) {
+            pending++;
+            kill(processes.electronProcess.pid, 'SIGTERM', onKilled);
+        }
+        if (processes.devServer?.pid) {
+            pending++;
+            kill(processes.devServer.pid, 'SIGTERM', onKilled);
+        }
+        if (pending === 0)
+            process.exit(0);
+    }
+    const sigintHandler = () => shutdown('SIGINT');
+    const sigtermHandler = () => shutdown('SIGTERM');
+    const uncaughtHandler = (err) => {
+        console.error('Uncaught exception:', err);
+        shutdown('uncaughtException');
+    };
+    process.on('SIGINT', sigintHandler);
+    process.on('SIGTERM', sigtermHandler);
+    process.on('uncaughtException', uncaughtHandler);
+    registeredListeners.push({ event: 'SIGINT', handler: sigintHandler }, { event: 'SIGTERM', handler: sigtermHandler }, { event: 'uncaughtException', handler: uncaughtHandler });
+}
+/**
+ * Reset shutdown state for testing. Removes registered signal listeners.
+ */
+export function resetShutdownState() {
+    shuttingDown = false;
+    for (const { event, handler } of registeredListeners) {
+        process.removeListener(event, handler);
+    }
+    registeredListeners.length = 0;
+}
+//# sourceMappingURL=process.js.map

package/dist/cli/utils/process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.js","sourceRoot":"","sources":["../../../src/cli/utils/process.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,YAAY,CAAC;AAW5B,IAAI,YAAY,GAAG,KAAK,CAAC;AACzB,MAAM,mBAAmB,GAAgE,EAAE,CAAC;AAE5F;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,SAA2B;IAClE,SAAS,QAAQ,CAAC,MAAc;QAC9B,IAAI,YAAY;YAAE,OAAO;QACzB,YAAY,GAAG,IAAI,CAAC;QAEpB,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,sBAAsB,MAAM,MAAM,CAAC,CAAC,CAAC;QAExD,oCAAoC;QACpC,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;QAEhD,iEAAiE;QACjE,IAAI,OAAO,GAAG,CAAC,CAAC;QAEhB,SAAS,QAAQ;YACf,OAAO,EAAE,CAAC;YACV,IAAI,OAAO,KAAK,CAAC;gBAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACrC,CAAC;QAED,IAAI,SAAS,CAAC,eAAe,EAAE,GAAG,EAAE,CAAC;YACnC,OAAO,EAAE,CAAC;YACV,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,GAAG,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;QAC3D,CAAC;QAED,IAAI,SAAS,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC;YAC7B,OAAO,EAAE,CAAC;YACV,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,GAAG,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;QACrD,CAAC;QAED,IAAI,OAAO,KAAK,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACrC,CAAC;IAED,MAAM,aAAa,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC/C,MAAM,cAAc,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IACjD,MAAM,eAAe,GAAG,CAAC,GAAU,EAAE,EAAE;QACrC,OAAO,CAAC,KAAK,CAAC,qBAAqB,EAAE,GAAG,CAAC,CAAC;QAC1C,QAAQ,CAAC,mBAAmB,CAAC,CAAC;IAChC,CAAC,CAAC;IAEF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;IACpC,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;IACtC,OAAO,CAAC,EAAE,CAAC,mBAAmB,EAAE,eAAe,CAAC,CAAC;IAEjD,mBAAmB,CAAC,IAAI,CACtB,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,EAAE,EAC3C,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,EAAE,EAC7C,EAAE,KAAK,EAAE,mBAAmB,EAAE,OAAO,EAAE,eAAe,EAAE,CACzD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAChC,YAAY,GAAG,KAAK,CAAC;IACrB,KAAK,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,mBAAmB,EAAE,CAAC;QACrD,OAAO,CAAC,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACzC,CAAC;IACD,mBAAmB,CAAC,MAAM,GAAG,CAAC,CAAC;AACjC,CAAC"}