@oss-autopilot/core 0.41.0 → 0.42.1

package/dist/commands/daily.js

@@ -6,31 +6,12 @@
  * Domain logic lives in src/core/daily-logic.ts; this file is a thin
  * orchestration layer that wires up the phases and handles I/O.
  */
-import { getStateManager, PRMonitor, IssueConversationMonitor, getGitHubToken, CRITICAL_STATUSES, computeRepoSignals, groupPRsByRepo, assessCapacity, collectActionableIssues, computeActionMenu, toShelvedPRRef, formatBriefSummary, formatSummary, printDigest, } from '../core/index.js';
-import { outputJson, outputJsonError, deduplicateDigest, compactActionableIssues, compactRepoGroups, } from '../formatters/json.js';
+import { getStateManager, PRMonitor, IssueConversationMonitor, requireGitHubToken, CRITICAL_STATUSES, computeRepoSignals, groupPRsByRepo, assessCapacity, collectActionableIssues, computeActionMenu, toShelvedPRRef, formatBriefSummary, formatSummary, } from '../core/index.js';
+import { errorMessage } from '../core/errors.js';
+import { deduplicateDigest, compactActionableIssues, compactRepoGroups, } from '../formatters/json.js';
 // Re-export domain functions so existing consumers (tests, dashboard, startup)
 // can continue importing from './daily.js' without changes.
 export { computeRepoSignals, groupPRsByRepo, assessCapacity, collectActionableIssues, computeActionMenu, toShelvedPRRef, formatBriefSummary, formatSummary, printDigest, CRITICAL_STATUSES, } from '../core/index.js';
-export async function runDaily(options) {
-    // Token is guaranteed by the preAction hook in cli.ts for non-LOCAL_ONLY_COMMANDS.
-    const token = getGitHubToken();
-    try {
-        await runDailyInner(token, options);
-    }
-    catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        if (options.json) {
-            outputJsonError(`Daily check failed: ${msg}`);
-        }
-        else {
-            console.error(`[FATAL] Daily check failed: ${msg}`);
-            if (error instanceof Error && error.stack) {
-                console.error(error.stack);
-            }
-        }
-        process.exit(1);
-    }
-}
 // ---------------------------------------------------------------------------
 // Phase functions
 // ---------------------------------------------------------------------------
@@ -53,15 +34,15 @@ async function fetchPRData(prMonitor, token) {
         prMonitor.fetchUserMergedPRCounts(),
         prMonitor.fetchUserClosedPRCounts(),
         prMonitor.fetchRecentlyClosedPRs().catch((err) => {
-            console.error(`Warning: Failed to fetch recently closed PRs: ${err instanceof Error ? err.message : err}`);
+            console.error(`Warning: Failed to fetch recently closed PRs: ${errorMessage(err)}`);
             return [];
         }),
         prMonitor.fetchRecentlyMergedPRs().catch((err) => {
-            console.error(`Warning: Failed to fetch recently merged PRs: ${err instanceof Error ? err.message : err}`);
+            console.error(`Warning: Failed to fetch recently merged PRs: ${errorMessage(err)}`);
             return [];
         }),
         issueMonitor.fetchCommentedIssues().catch((error) => {
-            const msg = error instanceof Error ? error.message : String(error);
+            const msg = errorMessage(error);
             if (msg.includes('No GitHub username configured')) {
                 console.error(`[DAILY] Issue conversation tracking requires setup: ${msg}`);
             }
@@ -123,7 +104,7 @@ async function updateRepoScores(prMonitor, prs, mergedCounts, closedCounts) {
         }
         catch (error) {
             mergedCountFailures++;
-            console.error(`[DAILY] Failed to update merged count for ${repo}:`, error instanceof Error ? error.message : error);
+            console.error(`[DAILY] Failed to update merged count for ${repo}:`, errorMessage(error));
         }
     }
     if (mergedCountFailures === mergedCounts.size && mergedCounts.size > 0) {
@@ -143,7 +124,7 @@ async function updateRepoScores(prMonitor, prs, mergedCounts, closedCounts) {
         }
         catch (error) {
             closedCountFailures++;
-            console.error(`[DAILY] Failed to update closed count for ${repo}:`, error instanceof Error ? error.message : error);
+            console.error(`[DAILY] Failed to update closed count for ${repo}:`, errorMessage(error));
         }
     }
     if (closedCountFailures === closedCounts.size && closedCounts.size > 0) {
@@ -162,7 +143,7 @@ async function updateRepoScores(prMonitor, prs, mergedCounts, closedCounts) {
         }
         catch (error) {
             signalUpdateFailures++;
-            console.error(`[DAILY] Failed to update signals for ${repo}:`, error instanceof Error ? error.message : error);
+            console.error(`[DAILY] Failed to update signals for ${repo}:`, errorMessage(error));
         }
     }
     if (signalUpdateFailures === repoSignals.size && repoSignals.size > 0) {
@@ -175,7 +156,7 @@ async function updateRepoScores(prMonitor, prs, mergedCounts, closedCounts) {
         starCounts = await prMonitor.fetchRepoStarCounts(allRepos);
     }
     catch (error) {
-        console.error('[DAILY] Failed to fetch repo star counts:', error instanceof Error ? error.message : error);
+        console.error('[DAILY] Failed to fetch repo star counts:', errorMessage(error));
         console.error('[DAILY] Dashboard minStars filter will use cached star counts (or be skipped for repos without cached data).');
         starCounts = new Map();
     }
@@ -186,7 +167,7 @@ async function updateRepoScores(prMonitor, prs, mergedCounts, closedCounts) {
         }
         catch (error) {
             starUpdateFailures++;
-            console.error(`[DAILY] Failed to update star count for ${repo}:`, error instanceof Error ? error.message : error);
+            console.error(`[DAILY] Failed to update star count for ${repo}:`, errorMessage(error));
         }
     }
     if (starUpdateFailures === starCounts.size && starCounts.size > 0) {
@@ -200,7 +181,7 @@ async function updateRepoScores(prMonitor, prs, mergedCounts, closedCounts) {
         }
         catch (error) {
             trustSyncFailures++;
-            console.error(`[DAILY] Failed to sync trusted project ${repo}:`, error instanceof Error ? error.message : error);
+            console.error(`[DAILY] Failed to sync trusted project ${repo}:`, errorMessage(error));
         }
     }
     if (trustSyncFailures === mergedCounts.size && mergedCounts.size > 0) {
@@ -219,13 +200,13 @@ function updateAnalytics(prs, monthlyCounts, monthlyClosedCounts, openedFromMerg
         stateManager.setMonthlyMergedCounts(monthlyCounts);
     }
     catch (error) {
-        console.error('[DAILY] Failed to store monthly merged counts:', error instanceof Error ? error.message : error);
+        console.error('[DAILY] Failed to store monthly merged counts:', errorMessage(error));
     }
     try {
         stateManager.setMonthlyClosedCounts(monthlyClosedCounts);
     }
     catch (error) {
-        console.error('[DAILY] Failed to store monthly closed counts:', error instanceof Error ? error.message : error);
+        console.error('[DAILY] Failed to store monthly closed counts:', errorMessage(error));
     }
     try {
         // Build combined monthly opened counts from merged + closed + currently-open PRs
@@ -243,7 +224,7 @@ function updateAnalytics(prs, monthlyCounts, monthlyClosedCounts, openedFromMerg
         stateManager.setMonthlyOpenedCounts(combinedOpenedCounts);
     }
     catch (error) {
-        console.error('[DAILY] Failed to compute/store monthly opened counts:', error instanceof Error ? error.message : error);
+        console.error('[DAILY] Failed to compute/store monthly opened counts:', errorMessage(error));
     }
 }
 /**
@@ -266,7 +247,7 @@ function partitionPRs(prMonitor, prs, recentlyClosedPRs, recentlyMergedPRs) {
         }
     }
     catch (error) {
-        console.error('[DAILY] Failed to expire/persist snoozes:', error instanceof Error ? error.message : error);
+        console.error('[DAILY] Failed to expire/persist snoozes:', errorMessage(error));
     }
     // Partition PRs into active vs shelved, auto-unshelving when maintainers engage
     const shelvedPRs = [];
@@ -406,7 +387,7 @@ export async function executeDailyCheck(token) {
 }
 /**
  * Internal daily check returning full (non-deduplicated) result.
- * Used by runDailyInner for text-mode output where full PR objects are needed.
+ * Used by runDaily for text-mode output where full PR objects are needed.
  */
 async function executeDailyCheckInternal(token) {
     const prMonitor = new PRMonitor(token);
@@ -421,13 +402,20 @@ async function executeDailyCheckInternal(token) {
     // Phase 5: Build structured output (capacity, dismiss filter, action menu)
     return generateDigestOutput(digest, activePRs, shelvedPRs, commentedIssues, failures);
 }
-async function runDailyInner(token, options) {
-    if (options.json) {
-        const result = await executeDailyCheck(token);
-        outputJson(result);
-    }
-    else {
-        const result = await executeDailyCheckInternal(token);
-        printDigest(result.digest, result.capacity, result.commentedIssues);
-    }
+/**
+ * Run the daily check and return deduplicated DailyOutput.
+ * Errors propagate to the caller.
+ */
+export async function runDaily() {
+    // Token is guaranteed by the preAction hook in cli.ts for non-LOCAL_ONLY_COMMANDS.
+    const token = requireGitHubToken();
+    return executeDailyCheck(token);
+}
+/**
+ * Run the daily check and return the full (non-deduplicated) result.
+ * Used by CLI text mode where printDigest() needs full PR objects.
+ */
+export async function runDailyForDisplay() {
+    const token = requireGitHubToken();
+    return executeDailyCheckInternal(token);
 }

package/dist/commands/dashboard-data.js

@@ -4,6 +4,7 @@
  * Separates data concerns from template generation and command orchestration.
  */
 import { getStateManager, PRMonitor, IssueConversationMonitor } from '../core/index.js';
+import { errorMessage } from '../core/errors.js';
 import { toShelvedPRRef } from './daily.js';
 /**
  * Fetch fresh dashboard data from GitHub.
@@ -17,17 +18,17 @@ export async function fetchDashboardData(token) {
     const [{ prs, failures }, recentlyClosedPRs, recentlyMergedPRs, mergedResult, closedResult, fetchedIssues] = await Promise.all([
         prMonitor.fetchUserOpenPRs(),
         prMonitor.fetchRecentlyClosedPRs().catch((err) => {
-            console.error(`Warning: Failed to fetch recently closed PRs: ${err instanceof Error ? err.message : err}`);
+            console.error(`Warning: Failed to fetch recently closed PRs: ${errorMessage(err)}`);
             return [];
         }),
         prMonitor.fetchRecentlyMergedPRs().catch((err) => {
-            console.error(`Warning: Failed to fetch recently merged PRs: ${err instanceof Error ? err.message : err}`);
+            console.error(`Warning: Failed to fetch recently merged PRs: ${errorMessage(err)}`);
             return [];
         }),
         prMonitor.fetchUserMergedPRCounts(),
         prMonitor.fetchUserClosedPRCounts(),
         issueMonitor.fetchCommentedIssues().catch((error) => {
-            const msg = error instanceof Error ? error.message : String(error);
+            const msg = errorMessage(error);
             if (msg.includes('No GitHub username configured')) {
                 console.error(`[DASHBOARD] Issue conversation tracking requires setup: ${msg}`);
             }
@@ -54,13 +55,13 @@ export async function fetchDashboardData(token) {
         stateManager.setMonthlyMergedCounts(monthlyCounts);
     }
     catch (error) {
-        console.error('[DASHBOARD] Failed to store monthly merged counts:', error instanceof Error ? error.message : error);
+        console.error('[DASHBOARD] Failed to store monthly merged counts:', errorMessage(error));
     }
     try {
         stateManager.setMonthlyClosedCounts(monthlyClosedCounts);
     }
     catch (error) {
-        console.error('[DASHBOARD] Failed to store monthly closed counts:', error instanceof Error ? error.message : error);
+        console.error('[DASHBOARD] Failed to store monthly closed counts:', errorMessage(error));
     }
     try {
         const combinedOpenedCounts = { ...openedFromMerged };
@@ -76,7 +77,7 @@ export async function fetchDashboardData(token) {
         stateManager.setMonthlyOpenedCounts(combinedOpenedCounts);
     }
     catch (error) {
-        console.error('[DASHBOARD] Failed to store monthly opened counts:', error instanceof Error ? error.message : error);
+        console.error('[DASHBOARD] Failed to store monthly opened counts:', errorMessage(error));
     }
     const digest = prMonitor.generateDigest(prs, recentlyClosedPRs, recentlyMergedPRs);
     // Apply shelve partitioning for display (auto-unshelve only runs in daily check)

package/dist/commands/dashboard-server.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Dashboard HTTP server.
+ * Serves the Preact SPA from packages/dashboard/dist/ and provides API endpoints
+ * for live data fetching and state mutations (shelve, snooze, etc.).
+ *
+ * Uses Node's built-in http module — no Express/Fastify.
+ */
+export interface DashboardServerOptions {
+    port: number;
+    assetsDir: string;
+    token: string | null;
+    open: boolean;
+}
+export declare function startDashboardServer(options: DashboardServerOptions): Promise<void>;

package/dist/commands/dashboard-server.js

@@ -0,0 +1,362 @@
+/**
+ * Dashboard HTTP server.
+ * Serves the Preact SPA from packages/dashboard/dist/ and provides API endpoints
+ * for live data fetching and state mutations (shelve, snooze, etc.).
+ *
+ * Uses Node's built-in http module — no Express/Fastify.
+ */
+import * as http from 'http';
+import * as fs from 'fs';
+import * as path from 'path';
+import { getStateManager, getGitHubToken } from '../core/index.js';
+import { errorMessage } from '../core/errors.js';
+import { fetchDashboardData, computePRsByRepo, computeTopRepos, getMonthlyData } from './dashboard-data.js';
+import { buildDashboardStats } from './dashboard-templates.js';
+// ── Constants ────────────────────────────────────────────────────────────────
+const VALID_ACTIONS = new Set(['shelve', 'unshelve', 'snooze', 'unsnooze']);
+const MAX_BODY_BYTES = 10_240;
+const MIME_TYPES = {
+    '.html': 'text/html',
+    '.js': 'application/javascript',
+    '.css': 'text/css',
+    '.svg': 'image/svg+xml',
+    '.json': 'application/json',
+    '.png': 'image/png',
+    '.ico': 'image/x-icon',
+};
+// ── Helpers ────────────────────────────────────────────────────────────────────
+/**
+ * Build the JSON payload that the SPA expects from GET /api/data.
+ * Same shape as the existing `dashboard --json` output.
+ */
+function buildDashboardJson(digest, state, commentedIssues) {
+    const prsByRepo = computePRsByRepo(digest, state);
+    const topRepos = computeTopRepos(prsByRepo);
+    const { monthlyMerged } = getMonthlyData(state);
+    const stats = buildDashboardStats(digest, state);
+    const issueResponses = commentedIssues.filter((i) => i.status === 'new_response');
+    return {
+        stats,
+        prsByRepo,
+        topRepos: topRepos.map(([repo, data]) => ({ repo, ...data })),
+        monthlyMerged,
+        activePRs: digest.openPRs || [],
+        shelvedPRUrls: state.config.shelvedPRUrls || [],
+        commentedIssues,
+        issueResponses,
+    };
+}
+/**
+ * Read the full request body as a UTF-8 string, with a size limit.
+ */
+function readBody(req, maxBytes = MAX_BODY_BYTES) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let totalLength = 0;
+        let aborted = false;
+        req.on('data', (chunk) => {
+            if (aborted)
+                return;
+            totalLength += chunk.length;
+            if (totalLength > maxBytes) {
+                aborted = true;
+                req.destroy();
+                reject(new Error('Body too large'));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => {
+            if (!aborted)
+                resolve(Buffer.concat(chunks).toString('utf-8'));
+        });
+        req.on('error', (err) => {
+            if (!aborted)
+                reject(err);
+        });
+    });
+}
+/**
+ * Send a JSON response.
+ */
+function sendJson(res, statusCode, data) {
+    const body = JSON.stringify(data);
+    res.writeHead(statusCode, {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+    });
+    res.end(body);
+}
+/**
+ * Send an error JSON response.
+ */
+function sendError(res, statusCode, message) {
+    sendJson(res, statusCode, { error: message });
+}
+// ── Server ─────────────────────────────────────────────────────────────────────
+export async function startDashboardServer(options) {
+    const { port: requestedPort, assetsDir, token, open } = options;
+    const stateManager = getStateManager();
+    const resolvedAssetsDir = path.resolve(assetsDir);
+    // ── Cached data ──────────────────────────────────────────────────────────
+    let cachedDigest;
+    let cachedCommentedIssues = [];
+    // Fetch initial data
+    if (token) {
+        try {
+            console.error('Fetching dashboard data from GitHub...');
+            const result = await fetchDashboardData(token);
+            cachedDigest = result.digest;
+            cachedCommentedIssues = result.commentedIssues;
+        }
+        catch (error) {
+            console.error('Failed to fetch data from GitHub:', error);
+            console.error('Falling back to cached data...');
+            cachedDigest = stateManager.getState().lastDigest;
+        }
+    }
+    else {
+        cachedDigest = stateManager.getState().lastDigest;
+    }
+    if (!cachedDigest) {
+        console.error('No dashboard data available. Run the daily check first:');
+        console.error('  GITHUB_TOKEN=$(gh auth token) npm start -- daily');
+        process.exit(1);
+    }
+    // ── Build cached JSON response ───────────────────────────────────────────
+    let cachedJsonData;
+    try {
+        cachedJsonData = buildDashboardJson(cachedDigest, stateManager.getState(), cachedCommentedIssues);
+    }
+    catch (error) {
+        console.error('Failed to build dashboard data from cached digest:', error);
+        console.error('Your state data may be corrupted. Try running: daily --json');
+        process.exit(1);
+    }
+    // ── Request handler ──────────────────────────────────────────────────────
+    const server = http.createServer(async (req, res) => {
+        const method = req.method || 'GET';
+        const url = req.url || '/';
+        try {
+            // ── API routes ─────────────────────────────────────────────────────
+            if (url === '/api/data' && method === 'GET') {
+                sendJson(res, 200, cachedJsonData);
+                return;
+            }
+            if (url === '/api/action' && method === 'POST') {
+                await handleAction(req, res);
+                return;
+            }
+            if (url === '/api/refresh' && method === 'POST') {
+                await handleRefresh(req, res);
+                return;
+            }
+            // ── Static file serving ────────────────────────────────────────────
+            if (method === 'GET') {
+                serveStaticFile(url, res);
+                return;
+            }
+            sendError(res, 405, 'Method not allowed');
+        }
+        catch (error) {
+            console.error('Unhandled request error:', method, url, error);
+            if (!res.headersSent) {
+                sendError(res, 500, 'Internal server error');
+            }
+        }
+    });
+    // ── POST /api/action handler ─────────────────────────────────────────────
+    async function handleAction(req, res) {
+        let body;
+        try {
+            const raw = await readBody(req);
+            body = JSON.parse(raw);
+        }
+        catch (e) {
+            const isBodyTooLarge = e instanceof Error && e.message === 'Body too large';
+            sendError(res, isBodyTooLarge ? 413 : 400, isBodyTooLarge ? 'Request body too large' : 'Invalid JSON body');
+            return;
+        }
+        if (!body.action || !VALID_ACTIONS.has(body.action)) {
+            sendError(res, 400, `Invalid action. Must be one of: ${[...VALID_ACTIONS].join(', ')}`);
+            return;
+        }
+        if (!body.url || typeof body.url !== 'string') {
+            sendError(res, 400, 'Missing or invalid "url" field');
+            return;
+        }
+        try {
+            switch (body.action) {
+                case 'shelve':
+                    stateManager.shelvePR(body.url);
+                    break;
+                case 'unshelve':
+                    stateManager.unshelvePR(body.url);
+                    break;
+                case 'snooze':
+                    stateManager.snoozePR(body.url, body.reason || 'Snoozed via dashboard', body.days || 7);
+                    break;
+                case 'unsnooze':
+                    stateManager.unsnoozePR(body.url);
+                    break;
+            }
+            stateManager.save();
+        }
+        catch (error) {
+            console.error('Action failed:', body.action, body.url, error);
+            sendError(res, 500, `Action failed: ${errorMessage(error)}`);
+            return;
+        }
+        // Rebuild dashboard data from cached digest + updated state
+        if (cachedDigest) {
+            cachedJsonData = buildDashboardJson(cachedDigest, stateManager.getState(), cachedCommentedIssues);
+        }
+        sendJson(res, 200, cachedJsonData);
+    }
+    // ── POST /api/refresh handler ────────────────────────────────────────────
+    async function handleRefresh(_req, res) {
+        const currentToken = token || getGitHubToken();
+        if (!currentToken) {
+            sendError(res, 401, 'No GitHub token available. Cannot refresh data.');
+            return;
+        }
+        try {
+            console.error('Refreshing dashboard data from GitHub...');
+            const result = await fetchDashboardData(currentToken);
+            cachedDigest = result.digest;
+            cachedCommentedIssues = result.commentedIssues;
+            cachedJsonData = buildDashboardJson(cachedDigest, stateManager.getState(), cachedCommentedIssues);
+            sendJson(res, 200, cachedJsonData);
+        }
+        catch (error) {
+            console.error('Dashboard refresh failed:', error);
+            sendError(res, 500, `Refresh failed: ${errorMessage(error)}`);
+        }
+    }
+    // ── Static file serving ──────────────────────────────────────────────────
+    function serveStaticFile(requestUrl, res) {
+        // Decode URL, handling malformed percent-encoding
+        let urlPath;
+        try {
+            urlPath = decodeURIComponent(requestUrl.split('?')[0]);
+        }
+        catch (err) {
+            console.error('Malformed URL received:', requestUrl, err);
+            sendError(res, 400, 'Malformed URL');
+            return;
+        }
+        // Security: reject paths with parent directory references
+        if (urlPath.includes('..')) {
+            sendError(res, 403, 'Forbidden');
+            return;
+        }
+        // Resolve the file path from sanitized URL
+        const relativePath = urlPath === '/' ? 'index.html' : urlPath.replace(/^\/+/, '');
+        let filePath = path.join(resolvedAssetsDir, relativePath);
+        // Belt-and-suspenders: ensure resolved path is within assets directory
+        if (!filePath.startsWith(resolvedAssetsDir + path.sep) && filePath !== resolvedAssetsDir) {
+            sendError(res, 403, 'Forbidden');
+            return;
+        }
+        // If file doesn't exist or is a directory, serve index.html for SPA routing
+        try {
+            const stat = fs.statSync(filePath);
+            if (stat.isDirectory()) {
+                filePath = path.join(resolvedAssetsDir, 'index.html');
+            }
+        }
+        catch (err) {
+            const nodeErr = err;
+            if (nodeErr.code === 'ENOENT') {
+                filePath = path.join(resolvedAssetsDir, 'index.html');
+            }
+            else {
+                console.error('Failed to stat file:', filePath, err);
+                sendError(res, 500, 'Internal server error');
+                return;
+            }
+        }
+        const ext = path.extname(filePath).toLowerCase();
+        const contentType = MIME_TYPES[ext] || 'application/octet-stream';
+        try {
+            const content = fs.readFileSync(filePath);
+            res.writeHead(200, {
+                'Content-Type': contentType,
+                'Content-Length': content.length,
+            });
+            res.end(content);
+        }
+        catch (error) {
+            const nodeErr = error;
+            if (nodeErr.code === 'ENOENT') {
+                sendError(res, 404, 'Not found');
+            }
+            else {
+                console.error('Failed to serve static file:', filePath, error);
+                sendError(res, 500, 'Failed to read file');
+            }
+        }
+    }
+    // ── Start server with port retry ─────────────────────────────────────────
+    const MAX_PORT_ATTEMPTS = 10;
+    let actualPort = requestedPort;
+    for (let attempt = 0; attempt < MAX_PORT_ATTEMPTS; attempt++) {
+        try {
+            await new Promise((resolve, reject) => {
+                server.once('error', reject);
+                server.listen(actualPort, '127.0.0.1', () => resolve());
+            });
+            // Success — break out of retry loop
+            break;
+        }
+        catch (err) {
+            const nodeErr = err;
+            if (nodeErr.code === 'EADDRINUSE' && attempt < MAX_PORT_ATTEMPTS - 1) {
+                console.error(`Port ${actualPort} is in use, trying ${actualPort + 1}...`);
+                actualPort++;
+                continue;
+            }
+            console.error(`Failed to start server: ${nodeErr.message}`);
+            process.exit(1);
+        }
+    }
+    const serverUrl = `http://localhost:${actualPort}`;
+    console.error(`Dashboard server running at ${serverUrl}`);
+    // ── Open browser ─────────────────────────────────────────────────────────
+    if (open) {
+        const { execFile } = await import('child_process');
+        let openCmd;
+        let args;
+        switch (process.platform) {
+            case 'darwin':
+                openCmd = 'open';
+                args = [serverUrl];
+                break;
+            case 'win32':
+                openCmd = 'cmd';
+                args = ['/c', 'start', '', serverUrl];
+                break;
+            default:
+                openCmd = 'xdg-open';
+                args = [serverUrl];
+                break;
+        }
+        execFile(openCmd, args, (error) => {
+            if (error) {
+                console.error('Failed to open browser:', error.message);
+                console.error(`Open manually: ${serverUrl}`);
+            }
+        });
+    }
+    // ── Clean shutdown ───────────────────────────────────────────────────────
+    const shutdown = () => {
+        console.error('\nShutting down dashboard server...');
+        server.close(() => {
+            process.exit(0);
+        });
+        // Force exit after 3 seconds if server doesn't close cleanly
+        setTimeout(() => process.exit(0), 3000).unref();
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}

package/dist/commands/dashboard.d.ts

@@ -15,4 +15,9 @@ export declare function runDashboard(options: DashboardOptions): Promise<void>;
  * Returns the path to the generated dashboard HTML file.
  */
 export declare function writeDashboardFromState(): string;
+interface ServeOptions {
+    port: number;
+    open: boolean;
+}
+export declare function serveDashboard(options: ServeOptions): Promise<void>;
 export {};