@principles/pd-cli 1.73.2 → 1.75.0

package/dist/services/console-launcher.d.ts

@@ -0,0 +1,110 @@
+/**
+ * PD Console Launcher — seed-friendly Console startup with port detection,
+ * reuse, and browser opening.
+ *
+ * PRI-300 MVP UX:
+ *   - Default port 3100; auto-falls back to next available if 3100 is busy
+ *   - Reuses a running Console if one is already serving on the chosen port
+ *   - Refuses non-loopback hosts (ERR-049 loopback safety)
+ *   - Opens the system browser on success (skipped under --json)
+ *   - Emits `reason` + `nextAction` for every failure
+ *
+ * Constraints (no daemonization, no public bind, no manual port):
+ *   - Does NOT start a background service
+ *   - Does NOT bind to non-loopback hosts
+ *   - Does NOT require user-configured ports (uses 3100 then 3101..)
+ */
+export type ConsoleStatus = 'reused' | 'started' | 'failed' | 'refused';
+export interface ConsoleLaunchResult {
+    status: ConsoleStatus;
+    url: string;
+    port: number;
+    host: string;
+    workspaceDir: string;
+    reason?: string;
+    nextAction?: string;
+    /** True when an existing console was detected and reused. */
+    reused: boolean;
+    /** True when a browser should/has been opened (skipped in --json mode). */
+    browserOpened: boolean;
+}
+export interface ConsoleLaunchOptions {
+    workspaceDir: string;
+    /** Preferred port. Defaults to 3100. */
+    preferredPort?: number;
+    /** Optional override host. Must be loopback; non-loopback is refused. */
+    host?: string;
+    /** When true, the launcher does not open the browser. */
+    skipBrowser?: boolean;
+    /** Timeout in ms to wait for a freshly-spawned console to become ready. */
+    readyTimeoutMs?: number;
+}
+/** Returns true if the host resolves to a loopback address. */
+export declare function isLoopbackHost(host: string): boolean;
+/**
+ * Normalize loopback host for safe use in listen/http.request.
+ * - [::1] → ::1 (strip brackets; Node net/http don't want brackets in host field)
+ * - localhost, 127.x.x.x, ::1 → pass through
+ * - non-loopback → return as-is (caller must reject via isLoopbackHost first)
+ */
+export declare function normalizeLoopbackHost(host: string): string;
+/**
+ * Build a valid Console URL from a normalized loopback host and port.
+ * - IPv6 ::1 → http://[::1]:port (brackets required for valid URL)
+ * - IPv4/localhost → http://host:port (unchanged)
+ */
+export declare function buildConsoleUrl(host: string, port: number): string;
+/** Returns true if the port on the given host accepts a TCP connection. */
+export declare function isPortInUse(host: string, port: number, timeoutMs?: number): Promise<boolean>;
+export interface HealthProbeOptions {
+    host: string;
+    port: number;
+    timeoutMs?: number;
+    /** Optional auth token (PD_CONSOLE_TOKEN) for authenticated health probes. */
+    token?: string;
+}
+/** Probe a port to see if it serves a healthy PD Console. */
+export declare function probeConsoleHealth(opts: HealthProbeOptions): Promise<{
+    healthy: boolean;
+    reason?: string;
+}>;
+/** Find the first available port in [preferred..preferred+limit]. */
+export declare function findAvailablePort(host: string, preferred: number, limit?: number): Promise<number | null>;
+/**
+ * Open the system browser. Best-effort — failures are reported but do not
+ * crash the launcher.
+ */
+export declare function openBrowser(url: string): Promise<{
+    opened: boolean;
+    reason?: string;
+    nextAction?: string;
+}>;
+/**
+ * Orchestrates the seed-friendly Console launch:
+ *   1. Validate the host is loopback (refuse otherwise)
+ *   2. If a healthy console is already running on the preferred port, reuse it
+ *   3. Otherwise find the next available port starting at the preferred one
+ *
+ * NOTE: This function does NOT spawn the server. The caller (CLI command) is
+ * responsible for actually launching the child process; the result returned
+ * here tells the caller which port to bind to and whether the existing port
+ * already serves a console.
+ */
+export interface OrchestratorResult {
+    status: ConsoleStatus;
+    url: string;
+    port: number;
+    host: string;
+    reused: boolean;
+    reason?: string;
+    nextAction?: string;
+}
+export interface OrchestratorInput {
+    workspaceDir: string;
+    preferredPort?: number;
+    host?: string;
+    /** Optional auth token for health probes (PD_CONSOLE_TOKEN). */
+    token?: string;
+}
+export declare function planConsoleLaunch(input: OrchestratorInput): Promise<OrchestratorResult>;
+//# sourceMappingURL=console-launcher.d.ts.map

package/dist/services/console-launcher.d.ts.map

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

package/dist/services/console-launcher.js

@@ -0,0 +1,282 @@
+/**
+ * PD Console Launcher — seed-friendly Console startup with port detection,
+ * reuse, and browser opening.
+ *
+ * PRI-300 MVP UX:
+ *   - Default port 3100; auto-falls back to next available if 3100 is busy
+ *   - Reuses a running Console if one is already serving on the chosen port
+ *   - Refuses non-loopback hosts (ERR-049 loopback safety)
+ *   - Opens the system browser on success (skipped under --json)
+ *   - Emits `reason` + `nextAction` for every failure
+ *
+ * Constraints (no daemonization, no public bind, no manual port):
+ *   - Does NOT start a background service
+ *   - Does NOT bind to non-loopback hosts
+ *   - Does NOT require user-configured ports (uses 3100 then 3101..)
+ */
+import * as net from 'net';
+import * as http from 'http';
+const DEFAULT_PORT = 3100;
+const DEFAULT_HOST = '127.0.0.1';
+const PORT_FALLBACK_LIMIT = 20; // try 3100..3119 before giving up
+// ─── Loopback safety (ERR-049) ──────────────────────────────────────────────
+/** Returns true if the host resolves to a loopback address. */
+export function isLoopbackHost(host) {
+    if (host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '[::1]')
+        return true;
+    // Reject any IPv4 host that doesn't start with 127.
+    if (/^127\./.test(host))
+        return true;
+    return false;
+}
+/**
+ * Normalize loopback host for safe use in listen/http.request.
+ * - [::1] → ::1 (strip brackets; Node net/http don't want brackets in host field)
+ * - localhost, 127.x.x.x, ::1 → pass through
+ * - non-loopback → return as-is (caller must reject via isLoopbackHost first)
+ */
+export function normalizeLoopbackHost(host) {
+    if (host === '[::1]')
+        return '::1';
+    return host;
+}
+/**
+ * Build a valid Console URL from a normalized loopback host and port.
+ * - IPv6 ::1 → http://[::1]:port (brackets required for valid URL)
+ * - IPv4/localhost → http://host:port (unchanged)
+ */
+export function buildConsoleUrl(host, port) {
+    if (host === '::1')
+        return `http://[::1]:${port}`;
+    return `http://${host}:${port}`;
+}
+// ─── Port detection (ERR-022: bounded) ───────────────────────────────────────
+/** Returns true if the port on the given host accepts a TCP connection. */
+export async function isPortInUse(host, port, timeoutMs = 800) {
+    if (Object.hasOwn(globalThis, '__mockIsPortInUse')) {
+        const mock = Reflect.get(globalThis, '__mockIsPortInUse');
+        return mock(host, port, timeoutMs);
+    }
+    return new Promise((resolve) => {
+        const socket = new net.Socket();
+        let settled = false;
+        const done = (inUse) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                socket.destroy();
+            }
+            catch { /* ignore */ }
+            resolve(inUse);
+        };
+        socket.setTimeout(timeoutMs);
+        socket.once('connect', () => done(true));
+        socket.once('timeout', () => done(false));
+        socket.once('error', (err) => {
+            // ECONNREFUSED → port is free; EHOSTUNREACH/ENETUNREACH → also free.
+            if (err.code === 'ECONNREFUSED' || err.code === 'EHOSTUNREACH' || err.code === 'ENETUNREACH') {
+                done(false);
+            }
+            else {
+                done(false);
+            }
+        });
+        try {
+            socket.connect(port, host);
+        }
+        catch {
+            done(false);
+        }
+    });
+}
+/** Probe a port to see if it serves a healthy PD Console. */
+export async function probeConsoleHealth(opts) {
+    const { host, port, timeoutMs = 1500, token } = opts;
+    if (Object.hasOwn(globalThis, '__mockProbeConsoleHealth')) {
+        const mock = Reflect.get(globalThis, '__mockProbeConsoleHealth');
+        return mock(opts);
+    }
+    return new Promise((resolve) => {
+        const headers = {};
+        if (token) {
+            headers.Authorization = `Bearer ${token}`;
+        }
+        const req = http.request({ host, port, path: '/api/health', method: 'GET', timeout: timeoutMs, headers }, (res) => {
+            // 401 means auth required — treat as unhealthy, not a generic error
+            if (res.statusCode === 401) {
+                resolve({ healthy: false, reason: 'console health endpoint returned 401 (unauthorized) — check PD_CONSOLE_TOKEN' });
+                return;
+            }
+            if (res.statusCode !== 200) {
+                resolve({ healthy: false, reason: `console health endpoint returned status ${res.statusCode ?? 'no-status'}` });
+                return;
+            }
+            let data = '';
+            res.on('data', (chunk) => {
+                data += chunk;
+            });
+            res.on('end', () => {
+                try {
+                    const body = JSON.parse(data);
+                    if (body && typeof body === 'object') {
+                        const isHealthy = (Object.hasOwn(body, 'healthy') && Reflect.get(body, 'healthy') === true) ||
+                            (Object.hasOwn(body, 'success') && Reflect.get(body, 'success') === true);
+                        if (isHealthy) {
+                            resolve({ healthy: true });
+                        }
+                        else {
+                            resolve({ healthy: false, reason: 'console health JSON was missing healthy/success markers' });
+                        }
+                    }
+                    else {
+                        resolve({ healthy: false, reason: 'console health endpoint returned non-object JSON' });
+                    }
+                }
+                catch (err) {
+                    resolve({ healthy: false, reason: `failed to parse console health JSON: ${err instanceof Error ? err.message : String(err)}` });
+                }
+            });
+        });
+        req.on('timeout', () => {
+            req.destroy();
+            resolve({ healthy: false, reason: 'console health probe timed out' });
+        });
+        req.on('error', (err) => {
+            resolve({ healthy: false, reason: `console health probe error: ${err.message}` });
+        });
+        req.end();
+    });
+}
+/** Find the first available port in [preferred..preferred+limit]. */
+export async function findAvailablePort(host, preferred, limit = PORT_FALLBACK_LIMIT) {
+    for (let i = 0; i < limit; i++) {
+        const candidate = preferred + i;
+        if (candidate > 65535 || candidate < 1) {
+            break;
+        }
+        if (!(await isPortInUse(host, candidate)))
+            return candidate;
+    }
+    return null;
+}
+// ─── Browser opener (best-effort, no throw) ──────────────────────────────────
+/**
+ * Open the system browser. Best-effort — failures are reported but do not
+ * crash the launcher.
+ */
+export async function openBrowser(url) {
+    const { spawn } = await import('child_process');
+    const { platform } = process;
+    let cmd;
+    let args;
+    if (platform === 'win32') {
+        cmd = 'cmd';
+        args = ['/c', 'start', '""', url];
+    }
+    else if (platform === 'darwin') {
+        cmd = 'open';
+        args = [url];
+    }
+    else {
+        cmd = 'xdg-open';
+        args = [url];
+    }
+    return new Promise((resolve) => {
+        try {
+            const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+            let resolved = false;
+            const timer = setTimeout(() => {
+                if (!resolved) {
+                    resolved = true;
+                    child.unref();
+                    resolve({ opened: true });
+                }
+            }, 100);
+            child.on('error', (err) => {
+                if (!resolved) {
+                    resolved = true;
+                    clearTimeout(timer);
+                    resolve({
+                        opened: false,
+                        reason: `Failed to spawn browser process: ${err.message}`,
+                        nextAction: `Ensure your system has '${cmd}' available in PATH or open the URL manually.`
+                    });
+                }
+            });
+        }
+        catch (err) {
+            resolve({
+                opened: false,
+                reason: err instanceof Error ? err.message : String(err),
+                nextAction: 'Ensure child_process is available or open the URL manually.'
+            });
+        }
+    });
+}
+export async function planConsoleLaunch(input) {
+    if (Object.hasOwn(globalThis, '__mockPlanConsoleLaunch')) {
+        const mock = Reflect.get(globalThis, '__mockPlanConsoleLaunch');
+        return mock(input);
+    }
+    const { token } = input;
+    const rawHost = input.host ?? DEFAULT_HOST;
+    const host = normalizeLoopbackHost(rawHost);
+    const preferredPort = input.preferredPort ?? DEFAULT_PORT;
+    if (!isLoopbackHost(host)) {
+        return {
+            status: 'refused',
+            url: '',
+            port: preferredPort,
+            host,
+            reused: false,
+            reason: `Non-loopback host refused: '${host}'. Only 127.0.0.1, ::1, and 'localhost' are allowed.`,
+            nextAction: 'Use the default loopback host (do not pass --host 0.0.0.0 or any LAN address).',
+        };
+    }
+    // Step 1: Is there already a healthy console on the preferred port?
+    const health = await probeConsoleHealth({ host, port: preferredPort, token });
+    if (health.healthy) {
+        return {
+            status: 'reused',
+            url: buildConsoleUrl(host, preferredPort),
+            port: preferredPort,
+            host,
+            reused: true,
+        };
+    }
+    // Step 2: Is the preferred port simply occupied by something else?
+    const preferredInUse = await isPortInUse(host, preferredPort);
+    if (preferredInUse) {
+        // Try to find a free port in the fallback range.
+        const freePort = await findAvailablePort(host, preferredPort + 1, PORT_FALLBACK_LIMIT - 1);
+        if (freePort === null) {
+            return {
+                status: 'failed',
+                url: '',
+                port: preferredPort,
+                host,
+                reused: false,
+                reason: `No available port in ${preferredPort + 1}..${preferredPort + PORT_FALLBACK_LIMIT}`,
+                nextAction: `Stop the process holding port ${preferredPort} (e.g., another Console instance), or free a port in the fallback range.`,
+            };
+        }
+        return {
+            status: 'started',
+            url: buildConsoleUrl(host, freePort),
+            port: freePort,
+            host,
+            reused: false,
+            reason: `Preferred port ${preferredPort} was busy; using ${freePort} instead`,
+        };
+    }
+    // Preferred port is free → bind there.
+    return {
+        status: 'started',
+        url: buildConsoleUrl(host, preferredPort),
+        port: preferredPort,
+        host,
+        reused: false,
+    };
+}
+//# sourceMappingURL=console-launcher.js.map

package/dist/services/console-launcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-launcher.js","sourceRoot":"","sources":["../../src/services/console-launcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,GAAG,MAAM,KAAK,CAAC;AAC3B,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAgC7B,MAAM,YAAY,GAAG,IAAI,CAAC;AAC1B,MAAM,YAAY,GAAG,WAAW,CAAC;AACjC,MAAM,mBAAmB,GAAG,EAAE,CAAC,CAAC,kCAAkC;AAElE,+EAA+E;AAE/E,+DAA+D;AAC/D,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,IAAI,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IACpG,oDAAoD;IACpD,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,IAAI,IAAI,KAAK,OAAO;QAAE,OAAO,KAAK,CAAC;IACnC,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,IAAY;IACxD,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,gBAAgB,IAAI,EAAE,CAAC;IAClD,OAAO,UAAU,IAAI,IAAI,IAAI,EAAE,CAAC;AAClC,CAAC;AAED,gFAAgF;AAEhF,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAY,EAAE,IAAY,EAAE,SAAS,GAAG,GAAG;IAC3E,IAAI,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,mBAAmB,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,mBAAmB,CAInC,CAAC;QACtB,OAAO,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QAChC,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,IAAI,GAAG,CAAC,KAAc,EAAE,EAAE;YAC9B,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,IAAI,CAAC;gBAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;YAChD,OAAO,CAAC,KAAK,CAAC,CAAC;QACjB,CAAC,CAAC;QACF,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;QAC7B,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACzC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAC1C,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,GAAwC,EAAE,EAAE;YAChE,qEAAqE;YACrE,IAAI,GAAG,CAAC,IAAI,KAAK,cAAc,IAAI,GAAG,CAAC,IAAI,KAAK,cAAc,IAAI,GAAG,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;gBAC7F,IAAI,CAAC,KAAK,CAAC,CAAC;YACd,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,KAAK,CAAC,CAAC;YACd,CAAC;QACH,CAAC,CAAC,CAAC;QACH,IAAI,CAAC;YACH,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,KAAK,CAAC,CAAC;QACd,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAUD,6DAA6D;AAC7D,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAAwB;IAC/D,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;IAErD,IAAI,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,0BAA0B,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,0BAA0B,CAEZ,CAAC;QACpD,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC;IACD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,OAAO,GAA2B,EAAE,CAAC;QAC3C,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,CAAC,aAAa,GAAG,UAAU,KAAK,EAAE,CAAC;QAC5C,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CACtB,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,EAC/E,CAAC,GAAG,EAAE,EAAE;YACN,oEAAoE;YACpE,IAAI,GAAG,CAAC,UAAU,KAAK,GAAG,EAAE,CAAC;gBAC3B,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,8EAA8E,EAAE,CAAC,CAAC;gBACpH,OAAO;YACT,CAAC;YACD,IAAI,GAAG,CAAC,UAAU,KAAK,GAAG,EAAE,CAAC;gBAC3B,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,2CAA2C,GAAG,CAAC,UAAU,IAAI,WAAW,EAAE,EAAE,CAAC,CAAC;gBAChH,OAAO;YACT,CAAC;YACD,IAAI,IAAI,GAAG,EAAE,CAAC;YACd,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;gBAC/B,IAAI,IAAI,KAAK,CAAC;YAChB,CAAC,CAAC,CAAC;YACH,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;gBACjB,IAAI,CAAC;oBACH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;oBACzC,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;wBACrC,MAAM,SAAS,GACb,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,KAAK,IAAI,CAAC;4BACzE,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,KAAK,IAAI,CAAC,CAAC;wBAC5E,IAAI,SAAS,EAAE,CAAC;4BACd,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;wBAC7B,CAAC;6BAAM,CAAC;4BACN,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,yDAAyD,EAAE,CAAC,CAAC;wBACjG,CAAC;oBACH,CAAC;yBAAM,CAAC;wBACN,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,kDAAkD,EAAE,CAAC,CAAC;oBAC1F,CAAC;gBACH,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,wCAAwC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;gBAClI,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC,CACF,CAAC;QACF,GAAG,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;YACrB,GAAG,CAAC,OAAO,EAAE,CAAC;YACd,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,gCAAgC,EAAE,CAAC,CAAC;QACxE,CAAC,CAAC,CAAC;QACH,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAU,EAAE,EAAE;YAC7B,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,+BAA+B,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACpF,CAAC,CAAC,CAAC;QACH,GAAG,CAAC,GAAG,EAAE,CAAC;IACZ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,qEAAqE;AACrE,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,IAAY,EACZ,SAAiB,EACjB,KAAK,GAAG,mBAAmB;IAE3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,MAAM,SAAS,GAAG,SAAS,GAAG,CAAC,CAAC;QAChC,IAAI,SAAS,GAAG,KAAK,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;YACvC,MAAM;QACR,CAAC;QACD,IAAI,CAAC,CAAC,MAAM,WAAW,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YAAE,OAAO,SAAS,CAAC;IAC9D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAW;IAC3C,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,CAAC;IAChD,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAE7B,IAAI,GAAW,CAAC;IAChB,IAAI,IAAc,CAAC;IAEnB,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QACzB,GAAG,GAAG,KAAK,CAAC;QACZ,IAAI,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IACpC,CAAC;SAAM,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjC,GAAG,GAAG,MAAM,CAAC;QACb,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACf,CAAC;SAAM,CAAC;QACN,GAAG,GAAG,UAAU,CAAC;QACjB,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACf,CAAC;IAED,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;YAEpE,IAAI,QAAQ,GAAG,KAAK,CAAC;YACrB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC5B,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACd,QAAQ,GAAG,IAAI,CAAC;oBAChB,KAAK,CAAC,KAAK,EAAE,CAAC;oBACd,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC5B,CAAC;YACH,CAAC,EAAE,GAAG,CAAC,CAAC;YAER,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;gBACxB,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACd,QAAQ,GAAG,IAAI,CAAC;oBAChB,YAAY,CAAC,KAAK,CAAC,CAAC;oBACpB,OAAO,CAAC;wBACN,MAAM,EAAE,KAAK;wBACb,MAAM,EAAE,oCAAoC,GAAG,CAAC,OAAO,EAAE;wBACzD,UAAU,EAAE,2BAA2B,GAAG,+CAA+C;qBAC1F,CAAC,CAAC;gBACL,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC;gBACN,MAAM,EAAE,KAAK;gBACb,MAAM,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;gBACxD,UAAU,EAAE,6DAA6D;aAC1E,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAiCD,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,KAAwB;IAC9D,IAAI,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,yBAAyB,CAAC,EAAE,CAAC;QACzD,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,yBAAyB,CAE9B,CAAC;QACjC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;IACD,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;IACxB,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,IAAI,YAAY,CAAC;IAC3C,MAAM,IAAI,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,aAAa,GAAG,KAAK,CAAC,aAAa,IAAI,YAAY,CAAC;IAE1D,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,OAAO;YACL,MAAM,EAAE,SAAS;YACjB,GAAG,EAAE,EAAE;YACP,IAAI,EAAE,aAAa;YACnB,IAAI;YACJ,MAAM,EAAE,KAAK;YACb,MAAM,EAAE,+BAA+B,IAAI,sDAAsD;YACjG,UAAU,EAAE,gFAAgF;SAC7F,CAAC;IACJ,CAAC;IAED,oEAAoE;IACpE,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC,CAAC;IAC9E,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO;YACL,MAAM,EAAE,QAAQ;YAChB,GAAG,EAAE,eAAe,CAAC,IAAI,EAAE,aAAa,CAAC;YACzC,IAAI,EAAE,aAAa;YACnB,IAAI;YACJ,MAAM,EAAE,IAAI;SACb,CAAC;IACJ,CAAC;IAED,mEAAmE;IACnE,MAAM,cAAc,GAAG,MAAM,WAAW,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IAE9D,IAAI,cAAc,EAAE,CAAC;QACnB,iDAAiD;QACjD,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,IAAI,EAAE,aAAa,GAAG,CAAC,EAAE,mBAAmB,GAAG,CAAC,CAAC,CAAC;QAC3F,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,OAAO;gBACL,MAAM,EAAE,QAAQ;gBAChB,GAAG,EAAE,EAAE;gBACP,IAAI,EAAE,aAAa;gBACnB,IAAI;gBACJ,MAAM,EAAE,KAAK;gBACb,MAAM,EAAE,wBAAwB,aAAa,GAAG,CAAC,KAAK,aAAa,GAAG,mBAAmB,EAAE;gBAC3F,UAAU,EAAE,iCAAiC,aAAa,0EAA0E;aACrI,CAAC;QACJ,CAAC;QACD,OAAO;YACL,MAAM,EAAE,SAAS;YACjB,GAAG,EAAE,eAAe,CAAC,IAAI,EAAE,QAAQ,CAAC;YACpC,IAAI,EAAE,QAAQ;YACd,IAAI;YACJ,MAAM,EAAE,KAAK;YACb,MAAM,EAAE,kBAAkB,aAAa,oBAAoB,QAAQ,UAAU;SAC9E,CAAC;IACJ,CAAC;IAED,uCAAuC;IACvC,OAAO;QACL,MAAM,EAAE,SAAS;QACjB,GAAG,EAAE,eAAe,CAAC,IAAI,EAAE,aAAa,CAAC;QACzC,IAAI,EAAE,aAAa;QACnB,IAAI;QACJ,MAAM,EAAE,KAAK;KACd,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principles/pd-cli",
-  "version": "1.73.2",
+  "version": "1.75.0",
   "description": "PD CLI — Pain recording, sample management, and evolution tasks",
   "type": "module",
   "bin": {
@@ -15,9 +15,11 @@
   "dependencies": {
     "@principles/core": "^1.73.0",
     "commander": "^12.0.0",
-    "js-yaml": "^4.1.1"
+    "js-yaml": "^4.1.1",
+    "better-sqlite3": "^12.9.0"
   },
   "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.6.2",
     "typescript": "^6.0.3",

package/src/commands/config-doctor.ts

@@ -0,0 +1,158 @@
+/**
+ * pd config doctor — Discover and explain PD / OpenClaw configuration state.
+ *
+ * PRI-299 MVP UX:
+ *   - Reports workspace + OpenClaw config paths and existence
+ *   - Lists effective feature flags and enabled MVP channels
+ *   - Classifies provider/model/auth connectivity (healthy, auth_missing, rate_limit, etc.)
+ *   - Emits `reason` + `nextActions` for failures
+ *   - NEVER leaks tokens, env var values, or raw config bytes
+ *
+ * Usage:
+ *   pd config doctor [--workspace <path>] [--json]
+ */
+
+import * as path from 'path';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+import { buildDoctorOutput, type DoctorOutput } from '../services/config-doctor.js';
+
+interface DoctorOptions {
+  workspace?: string;
+  json?: boolean;
+}
+
+function formatTextOutput(output: DoctorOutput): string {
+  const lines: string[] = [];
+  const statusIcon = output.status === 'ok' ? '✓' : output.status === 'degraded' ? '⚠' : '✗';
+
+  lines.push('PD Config Doctor');
+  lines.push(`status: ${statusIcon} ${output.status.toUpperCase()}`);
+  lines.push(`workspace: ${output.workspaceDir}`);
+  lines.push('');
+
+  lines.push('PD config paths:');
+  for (const [k, v] of Object.entries(output.pdConfigPaths)) {
+    const exists = v.exists ? '[exists]' : '[missing]';
+    lines.push(`  ${k.padEnd(16)} ${exists.padEnd(10)} ${v.path}`);
+  }
+  lines.push('');
+
+  lines.push('OpenClaw paths:');
+  for (const [k, v] of Object.entries(output.openclawConfigPaths)) {
+    const exists = v.exists ? '[exists]' : '[missing]';
+    lines.push(`  ${k.padEnd(16)} ${exists.padEnd(10)} ${v.path}`);
+  }
+  lines.push('');
+
+  lines.push(`Feature flags: source=${output.featureFlags.source}`);
+  lines.push(`  enabled MVP channels: ${output.featureFlags.enabledMvpChannels.length === 0 ? '(none)' : output.featureFlags.enabledMvpChannels.join(', ')}`);
+  if (output.featureFlags.disabledFlags.length > 0) {
+    lines.push(`  disabled: ${output.featureFlags.disabledFlags.join(', ')}`);
+  }
+  if (output.featureFlags.warnings.length > 0) {
+    lines.push(`  warnings: ${output.featureFlags.warnings.length}`);
+  }
+  lines.push('');
+
+  lines.push('Provider health:');
+  if (output.providerHealth.length === 0) {
+    lines.push('  (no providers discovered)');
+  } else {
+    for (const p of output.providerHealth) {
+      const cls = p.classification.toUpperCase();
+      const provider = p.provider ?? '(unset)';
+      const model = p.model ?? '(unset)';
+      const apiKeyEnv = p.apiKeyEnv ?? '(unset)';
+      const apiKeyState = p.apiKeyPresent ? 'present' : 'absent';
+      lines.push(`  [${cls}] ${provider} / ${model}`);
+      lines.push(`    apiKeyEnv:   ${apiKeyEnv} (${apiKeyState})`);
+      lines.push(`    source:      ${p.source}`);
+      lines.push(`    reason:      ${p.reason}`);
+      lines.push(`    nextAction:  ${p.nextAction}`);
+    }
+  }
+  lines.push('');
+
+  lines.push('Internal agents:');
+  if (output.internalAgents && output.internalAgents.correctionObserver) {
+    const co = output.internalAgents.correctionObserver;
+    const coStatus = co.status.toUpperCase();
+    const coProvider = co.provider ?? '(unset)';
+    const coModel = co.model ?? '(unset)';
+    const coApiKeyEnv = co.apiKeyEnv ?? '(unset)';
+    const coApiKeyState = co.apiKeyPresent ? 'present' : 'absent';
+    lines.push(`  correctionObserver: [${coStatus}]`);
+    lines.push(`    enabled:     ${co.enabled}`);
+    lines.push(`    flagSource:  ${co.flagSource}`);
+    lines.push(`    configSource:${co.configSource}`);
+    if (co.provider || co.model) {
+      lines.push(`    provider:    ${coProvider} / ${coModel}`);
+    }
+    lines.push(`    apiKeyEnv:   ${coApiKeyEnv} (${coApiKeyState})`);
+    lines.push(`    reason:      ${co.reason}`);
+    lines.push(`    nextAction:  ${co.nextAction}`);
+  } else {
+    lines.push('  (no internal agents diagnosed)');
+  }
+  lines.push('');
+
+  if (output.warnings.length > 0) {
+    lines.push('Warnings:');
+    for (const w of output.warnings) {
+      lines.push(`  [!] ${w}`);
+    }
+    lines.push('');
+  }
+
+  if (output.reason) {
+    lines.push(`Reason: ${output.reason}`);
+    lines.push('');
+  }
+
+  if (output.nextActions.length > 0) {
+    lines.push('Next actions:');
+    for (const a of output.nextActions) {
+      lines.push(`  → ${a}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+export async function handleConfigDoctor(opts: DoctorOptions): Promise<void> {
+  let workspaceDir: string;
+  try {
+    workspaceDir = opts.workspace ? path.resolve(opts.workspace) : resolveWorkspaceDir();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const output = {
+      status: 'failed' as const,
+      reason: 'workspace_resolution_failed',
+      message,
+      nextActions: ['Pass --workspace <path> explicitly, or set PD_WORKSPACE_DIR environment variable'],
+    };
+    if (opts.json) {
+      console.log(JSON.stringify(output, null, 2));
+    } else {
+      console.error(`error: ${message}`);
+    }
+    process.exit(1);
+    return;
+  }
+
+  const output = await buildDoctorOutput({ workspaceDir });
+
+  if (opts.json) {
+    // JSON mode: single parseable object on stdout.
+    console.log(JSON.stringify(output, null, 2));
+  } else {
+    console.log(formatTextOutput(output));
+  }
+
+  if (output.status === 'failed') {
+    process.exitCode = 1;
+  } else if (output.status === 'degraded') {
+    // degraded: do not exit 1, but emit a hint to stderr for the operator.
+    console.error(`\nNote: doctor status is degraded. Inspect warnings + nextActions.`);
+  }
+}