specsmd 0.1.66 → 0.1.68

package/lib/dashboard/web/server.js

@@ -0,0 +1,376 @@
+const fs = require('fs');
+const http = require('http');
+const path = require('path');
+const { URL } = require('url');
+const { spawn } = require('child_process');
+const crypto = require('crypto');
+const { createWatchRuntime } = require('../runtime/watch-runtime');
+const { detectFlow } = require('../flow-detect');
+const { loadWebDashboardData } = require('./snapshot');
+
+const PUBLIC_DIR = path.join(__dirname, 'public');
+const TOKEN_COOKIE = 'specsmd_dashboard_token';
+
+function parsePort(raw) {
+  const parsed = Number.parseInt(String(raw || '0'), 10);
+  if (Number.isNaN(parsed) || parsed < 0 || parsed > 65535) {
+    return 0;
+  }
+  return parsed;
+}
+
+function sendJson(res, statusCode, payload) {
+  const body = JSON.stringify(payload);
+  res.writeHead(statusCode, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'content-length': Buffer.byteLength(body)
+  });
+  res.end(body);
+}
+
+function sendText(res, statusCode, body, contentType = 'text/plain; charset=utf-8') {
+  res.writeHead(statusCode, {
+    'content-type': contentType,
+    'cache-control': 'no-store',
+    'content-length': Buffer.byteLength(body)
+  });
+  res.end(body);
+}
+
+function sendHtml(res, body, token) {
+  res.writeHead(200, {
+    'content-type': 'text/html; charset=utf-8',
+    'cache-control': 'no-store',
+    'set-cookie': `${TOKEN_COOKIE}=${token}; Path=/; SameSite=Strict`,
+    'content-length': Buffer.byteLength(body)
+  });
+  res.end(body);
+}
+
+function contentTypeFor(filePath) {
+  if (filePath.endsWith('.html')) return 'text/html; charset=utf-8';
+  if (filePath.endsWith('.js')) return 'text/javascript; charset=utf-8';
+  if (filePath.endsWith('.css')) return 'text/css; charset=utf-8';
+  if (filePath.endsWith('.svg')) return 'image/svg+xml';
+  if (filePath.endsWith('.png')) return 'image/png';
+  return 'application/octet-stream';
+}
+
+function safeStaticPath(requestPath) {
+  const pathname = requestPath === '/' ? '/index.html' : requestPath;
+  const normalized = path.normalize(pathname).replace(/^(\.\.[/\\])+/, '');
+  const filePath = path.join(PUBLIC_DIR, normalized);
+  if (!filePath.startsWith(PUBLIC_DIR)) {
+    return null;
+  }
+  return filePath;
+}
+
+function readRequestBody(req) {
+  return new Promise((resolve, reject) => {
+    let body = '';
+    req.setEncoding('utf8');
+    req.on('data', (chunk) => {
+      body += chunk;
+      if (body.length > 1024 * 1024) {
+        reject(new Error('Request body too large.'));
+        req.destroy();
+      }
+    });
+    req.on('end', () => resolve(body));
+    req.on('error', reject);
+  });
+}
+
+function parseCookies(req) {
+  return String(req.headers.cookie || '')
+    .split(';')
+    .map((cookie) => cookie.trim())
+    .filter(Boolean)
+    .reduce((cookies, cookie) => {
+      const separator = cookie.indexOf('=');
+      if (separator === -1) return cookies;
+      cookies[cookie.slice(0, separator)] = decodeURIComponent(cookie.slice(separator + 1));
+      return cookies;
+    }, {});
+}
+
+function hasValidCommandToken(req, token) {
+  const headerToken = req.headers['x-specsmd-dashboard-token'];
+  const cookies = parseCookies(req);
+  return headerToken === token || cookies[TOKEN_COOKIE] === token;
+}
+
+function isAllowedCommandRequest(req, host, port, token) {
+  if (!hasValidCommandToken(req, token)) {
+    return false;
+  }
+
+  const origin = req.headers.origin;
+  if (!origin) {
+    return true;
+  }
+
+  try {
+    const parsed = new URL(origin);
+    const expectedPort = String(port);
+    const requestHost = req.headers.host || `${host}:${expectedPort}`;
+    return parsed.protocol === 'http:'
+      && parsed.host === requestHost;
+  } catch {
+    return false;
+  }
+}
+
+function isSafeWorkspacePath(workspacePath, candidatePath) {
+  if (typeof candidatePath !== 'string' || candidatePath.trim() === '') {
+    return false;
+  }
+  try {
+    const resolvedWorkspace = fs.realpathSync.native(workspacePath);
+    const resolvedCandidate = fs.realpathSync.native(candidatePath);
+    const stat = fs.statSync(resolvedCandidate);
+    return stat.isFile()
+      && (resolvedCandidate === resolvedWorkspace || resolvedCandidate.startsWith(`${resolvedWorkspace}${path.sep}`));
+  } catch {
+    return false;
+  }
+}
+
+function openExternal(url) {
+  if (typeof url !== 'string' || !/^https?:\/\//i.test(url)) {
+    return false;
+  }
+  const opener = process.platform === 'darwin'
+    ? 'open'
+    : (process.platform === 'win32' ? 'cmd' : 'xdg-open');
+  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+  const child = spawn(opener, args, { detached: true, stdio: 'ignore' });
+  child.unref();
+  return true;
+}
+
+function openLocalFile(filePath) {
+  const opener = process.platform === 'darwin'
+    ? 'open'
+    : (process.platform === 'win32' ? 'cmd' : 'xdg-open');
+  const args = process.platform === 'win32' ? ['/c', 'start', '', filePath] : [filePath];
+  const child = spawn(opener, args, { detached: true, stdio: 'ignore' });
+  child.unref();
+}
+
+function buildWatchRoots(workspacePath, flow) {
+  const normalizedFlow = String(flow || '').toLowerCase();
+  if (normalizedFlow === 'aidlc') {
+    return [path.join(workspacePath, 'memory-bank')];
+  }
+  if (normalizedFlow === 'simple') {
+    return [path.join(workspacePath, 'specs')];
+  }
+  return [path.join(workspacePath, '.specs-fire')];
+}
+
+async function startDashboardWeb(options = {}) {
+  const workspacePath = path.resolve(options.path || options.workspacePath || process.cwd());
+  const host = options.host || '127.0.0.1';
+  const port = parsePort(options.port);
+  const commandToken = crypto.randomBytes(24).toString('base64url');
+  const clients = new Set();
+  let watcher = null;
+  let lastData = null;
+
+  async function loadAndBroadcast() {
+    lastData = await loadWebDashboardData({ workspacePath, flow: options.flow });
+    const message = lastData.webviewMessage || lastData;
+    const payload = `event: message\ndata: ${JSON.stringify(message)}\n\n`;
+    for (const client of clients) {
+      client.write(payload);
+    }
+    return lastData;
+  }
+
+  const server = http.createServer(async (req, res) => {
+    try {
+      const requestUrl = new URL(req.url || '/', `http://${host}`);
+
+      if (req.method === 'GET' && requestUrl.pathname === '/api/snapshot') {
+        const data = await loadAndBroadcast();
+        sendJson(res, data.ok ? 200 : 400, data);
+        return;
+      }
+
+      if (req.method === 'POST' && requestUrl.pathname === '/api/message') {
+        if (!isAllowedCommandRequest(req, host, actualPort, commandToken)) {
+          sendJson(res, 403, {
+            ok: false,
+            error: {
+              code: 'FORBIDDEN_ORIGIN',
+              message: 'Dashboard commands must originate from the local dashboard page.'
+            }
+          });
+          return;
+        }
+        const rawBody = await readRequestBody(req);
+        const message = rawBody ? JSON.parse(rawBody) : {};
+        if (message.type === 'refresh' || message.type === 'ready') {
+          const data = await loadAndBroadcast();
+          sendJson(res, 200, { ok: true, data });
+          return;
+        }
+        if (message.type === 'openExternal') {
+          const opened = openExternal(message.url);
+          sendJson(res, opened ? 200 : 400, opened
+            ? { ok: true }
+            : { ok: false, error: { code: 'INVALID_URL', message: 'Only http(s) URLs can be opened.' } });
+          return;
+        }
+        if (message.type === 'openArtifact' && isSafeWorkspacePath(workspacePath, message.path)) {
+          openLocalFile(message.path);
+          sendJson(res, 200, { ok: true });
+          return;
+        }
+        sendJson(res, 202, { ok: true, ignored: true });
+        return;
+      }
+
+      if (req.method === 'GET' && requestUrl.pathname === '/events') {
+        if (!isAllowedCommandRequest(req, host, actualPort, commandToken)) {
+          sendJson(res, 403, {
+            ok: false,
+            error: {
+              code: 'FORBIDDEN_ORIGIN',
+              message: 'Dashboard event streams must originate from the local dashboard page.'
+            }
+          });
+          return;
+        }
+        res.writeHead(200, {
+          'content-type': 'text/event-stream; charset=utf-8',
+          'cache-control': 'no-cache, no-transform',
+          connection: 'keep-alive'
+        });
+        res.write('\n');
+        clients.add(res);
+        if (lastData) {
+          const message = lastData.webviewMessage || lastData;
+          res.write(`event: message\ndata: ${JSON.stringify(message)}\n\n`);
+        }
+        req.on('close', () => {
+          clients.delete(res);
+        });
+        return;
+      }
+
+      if (req.method === 'GET') {
+        const filePath = safeStaticPath(requestUrl.pathname);
+        if (!filePath || !fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
+          sendText(res, 404, 'Not found');
+          return;
+        }
+        const body = fs.readFileSync(filePath);
+        if (filePath.endsWith('.html')) {
+          sendHtml(res, body, commandToken);
+          return;
+        }
+        res.writeHead(200, {
+          'content-type': contentTypeFor(filePath),
+          'cache-control': filePath.endsWith('.html') ? 'no-store' : 'public, max-age=60',
+          'content-length': body.length
+        });
+        res.end(body);
+        return;
+      }
+
+      sendText(res, 405, 'Method not allowed');
+    } catch (error) {
+      sendJson(res, 500, {
+        ok: false,
+        error: {
+          code: 'SERVER_ERROR',
+          message: error?.message || String(error)
+        }
+      });
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, () => {
+      server.off('error', reject);
+      resolve();
+    });
+  });
+
+  const address = server.address();
+  const actualPort = typeof address === 'object' && address ? address.port : port;
+  const url = `http://${host}:${actualPort}/`;
+
+  const initialData = await loadAndBroadcast();
+  if (options.watch !== false && initialData.flow) {
+    let detection = null;
+    try {
+      detection = detectFlow(workspacePath, options.flow);
+    } catch {
+      detection = null;
+    }
+    const flow = detection?.flow || initialData.flow;
+    const roots = buildWatchRoots(workspacePath, flow).filter((root) => fs.existsSync(root));
+    if (roots.length > 0) {
+      watcher = createWatchRuntime({
+        rootPaths: roots,
+        onRefresh: () => {
+          loadAndBroadcast().catch(() => {});
+        }
+      });
+      watcher.start();
+    }
+  }
+
+  async function close() {
+    if (watcher) {
+      await watcher.close();
+      watcher = null;
+    }
+    for (const client of clients) {
+      client.end();
+    }
+    clients.clear();
+    await new Promise((resolve) => server.close(resolve));
+  }
+
+  return {
+    server,
+    url,
+    host,
+    port: actualPort,
+    workspacePath,
+    close,
+    getLastData: () => lastData
+  };
+}
+
+async function run(options = {}) {
+  const handle = await startDashboardWeb(options);
+  console.log(`specsmd dashboard web: ${handle.url}`);
+  console.log(`workspace: ${handle.workspacePath}`);
+  console.log('Press Ctrl+C to stop.');
+
+  if (options.open !== false) {
+    openExternal(handle.url);
+  }
+
+  const shutdown = async () => {
+    await handle.close();
+    process.exit(0);
+  };
+  process.once('SIGINT', shutdown);
+  process.once('SIGTERM', shutdown);
+}
+
+module.exports = {
+  startDashboardWeb,
+  run,
+  parsePort,
+  buildWatchRoots
+};

package/lib/dashboard/web/snapshot.js

@@ -0,0 +1,299 @@
+const path = require('path');
+const { detectFlow } = require('../flow-detect');
+const { parseFireDashboard } = require('../fire/parser');
+const { parseAidlcDashboard } = require('../aidlc/parser');
+const { parseSimpleDashboard } = require('../simple/parser');
+const { listGitChanges } = require('../git/changes');
+const { createSetDataMessage } = require('./extension-adapter');
+
+const FLOW_PARSERS = {
+  fire: parseFireDashboard,
+  aidlc: parseAidlcDashboard,
+  simple: parseSimpleDashboard
+};
+
+function normalizeFlow(flow) {
+  return String(flow || '').trim().toLowerCase();
+}
+
+function compactError(error) {
+  if (!error) {
+    return {
+      code: 'UNKNOWN_ERROR',
+      message: 'Unknown dashboard error.'
+    };
+  }
+
+  return {
+    code: error.code || 'DASHBOARD_ERROR',
+    message: error.message || String(error),
+    hint: error.hint,
+    details: error.details,
+    path: error.path
+  };
+}
+
+function createCard(label, value, detail) {
+  return {
+    label,
+    value: String(value ?? 0),
+    detail: detail || ''
+  };
+}
+
+function summarizeAidlc(snapshot) {
+  const stats = snapshot?.stats || {};
+  const activeBolts = Array.isArray(snapshot?.activeBolts) ? snapshot.activeBolts : [];
+  const pendingBolts = Array.isArray(snapshot?.pendingBolts) ? snapshot.pendingBolts : [];
+  const completedBolts = Array.isArray(snapshot?.completedBolts) ? snapshot.completedBolts : [];
+  const intents = Array.isArray(snapshot?.intents) ? snapshot.intents : [];
+
+  return {
+    cards: [
+      createCard('Intents', stats.totalIntents, `${stats.completedIntents || 0} complete`),
+      createCard('Stories', stats.totalStories, `${stats.completedStories || 0} complete`),
+      createCard('Bolts', stats.totalBolts, `${stats.activeBoltsCount || 0} active`),
+      createCard('Progress', `${stats.progressPercent || 0}%`, 'story completion')
+    ],
+    sections: [
+      {
+        title: 'Active Bolts',
+        empty: 'No active bolts.',
+        items: activeBolts.map((bolt) => ({
+          title: bolt.id,
+          meta: `${bolt.intent || 'unknown intent'} / ${bolt.unit || 'unknown unit'}`,
+          status: bolt.currentStage || bolt.status,
+          path: bolt.filePath
+        }))
+      },
+      {
+        title: 'Queued Bolts',
+        empty: 'No queued bolts.',
+        items: pendingBolts.slice(0, 12).map((bolt) => ({
+          title: bolt.id,
+          meta: `${bolt.intent || 'unknown intent'} / ${bolt.unit || 'unknown unit'}`,
+          status: bolt.isBlocked ? 'blocked' : bolt.status,
+          path: bolt.filePath
+        }))
+      },
+      {
+        title: 'Recent Completed Bolts',
+        empty: 'No completed bolts.',
+        items: completedBolts.slice(0, 12).map((bolt) => ({
+          title: bolt.id,
+          meta: `${bolt.intent || 'unknown intent'} / ${bolt.unit || 'unknown unit'}`,
+          status: bolt.completedAt || 'completed',
+          path: bolt.filePath
+        }))
+      },
+      {
+        title: 'Intents',
+        empty: 'No intents found.',
+        items: intents.map((intent) => ({
+          title: intent.title || intent.id,
+          meta: `${intent.unitCount || 0} units / ${intent.storyCount || 0} stories`,
+          status: intent.status,
+          path: intent.path
+        }))
+      }
+    ],
+    primaryItems: intents.map((intent) => ({
+      title: intent.title || intent.id,
+      status: intent.status,
+      path: intent.path
+    }))
+  };
+}
+
+function summarizeFire(snapshot) {
+  const stats = snapshot?.stats || {};
+  const activeRuns = Array.isArray(snapshot?.activeRuns) ? snapshot.activeRuns : [];
+  const pendingItems = Array.isArray(snapshot?.pendingItems) ? snapshot.pendingItems : [];
+  const completedRuns = Array.isArray(snapshot?.completedRuns) ? snapshot.completedRuns : [];
+  const intents = Array.isArray(snapshot?.intents) ? snapshot.intents : [];
+
+  return {
+    cards: [
+      createCard('Intents', stats.totalIntents, `${stats.completedIntents || 0} complete`),
+      createCard('Work Items', stats.totalWorkItems, `${stats.completedWorkItems || 0} complete`),
+      createCard('Runs', stats.totalRuns, `${stats.activeRunsCount || 0} active`),
+      createCard('Standards', Array.isArray(snapshot?.standards) ? snapshot.standards.length : 0, 'configured')
+    ],
+    sections: [
+      {
+        title: 'Active Runs',
+        empty: 'No active runs.',
+        items: activeRuns.map((run) => ({
+          title: run.id,
+          meta: `${run.scope || 'single'} / ${run.workItems?.length || 0} work items`,
+          status: run.currentItem || 'active',
+          path: run.folderPath
+        }))
+      },
+      {
+        title: 'Pending Work Items',
+        empty: 'No pending work items.',
+        items: pendingItems.slice(0, 12).map((item) => ({
+          title: item.title || item.id,
+          meta: item.intentTitle || item.intentId || '',
+          status: `${item.mode || 'confirm'} / ${item.complexity || 'medium'}`,
+          path: item.filePath
+        }))
+      },
+      {
+        title: 'Completed Runs',
+        empty: 'No completed runs.',
+        items: completedRuns.slice(0, 12).map((run) => ({
+          title: run.id,
+          meta: `${run.scope || 'single'} / ${run.workItems?.length || 0} work items`,
+          status: run.completedAt || 'completed',
+          path: run.folderPath
+        }))
+      },
+      {
+        title: 'Intents',
+        empty: 'No intents found.',
+        items: intents.map((intent) => ({
+          title: intent.title || intent.id,
+          meta: `${intent.workItems?.length || 0} work items`,
+          status: intent.status,
+          path: intent.filePath
+        }))
+      }
+    ],
+    primaryItems: intents.map((intent) => ({
+      title: intent.title || intent.id,
+      status: intent.status,
+      path: intent.filePath
+    }))
+  };
+}
+
+function summarizeSimple(snapshot) {
+  const stats = snapshot?.stats || {};
+  const activeSpecs = Array.isArray(snapshot?.activeSpecs) ? snapshot.activeSpecs : [];
+  const completedSpecs = Array.isArray(snapshot?.completedSpecs) ? snapshot.completedSpecs : [];
+
+  return {
+    cards: [
+      createCard('Specs', stats.totalSpecs, `${stats.completedSpecs || 0} complete`),
+      createCard('Tasks', stats.totalTasks, `${stats.completedTasks || 0} complete`),
+      createCard('Ready', stats.readySpecs, 'specs'),
+      createCard('Progress', `${stats.progressPercent || 0}%`, 'task completion')
+    ],
+    sections: [
+      {
+        title: 'Active Specs',
+        empty: 'No active specs.',
+        items: activeSpecs.map((spec) => ({
+          title: spec.name,
+          meta: `${spec.tasksCompleted || 0}/${spec.tasksTotal || 0} tasks`,
+          status: spec.state,
+          path: spec.path
+        }))
+      },
+      {
+        title: 'Completed Specs',
+        empty: 'No completed specs.',
+        items: completedSpecs.slice(0, 12).map((spec) => ({
+          title: spec.name,
+          meta: `${spec.tasksCompleted || 0}/${spec.tasksTotal || 0} tasks`,
+          status: spec.updatedAt || 'completed',
+          path: spec.path
+        }))
+      }
+    ],
+    primaryItems: activeSpecs.map((spec) => ({
+      title: spec.name,
+      status: spec.state,
+      path: spec.path
+    }))
+  };
+}
+
+function summarizeSnapshot(flow, snapshot) {
+  if (flow === 'fire') {
+    return summarizeFire(snapshot);
+  }
+  if (flow === 'simple') {
+    return summarizeSimple(snapshot);
+  }
+  return summarizeAidlc(snapshot);
+}
+
+async function loadWebDashboardData(options = {}) {
+  const workspacePath = path.resolve(options.workspacePath || options.path || process.cwd());
+  let detection;
+
+  try {
+    detection = detectFlow(workspacePath, options.flow);
+  } catch (error) {
+    return {
+      ok: false,
+      flow: normalizeFlow(options.flow) || null,
+      workspacePath,
+      error: compactError(error)
+    };
+  }
+
+  if (!detection.flow) {
+    return {
+      ok: false,
+      flow: null,
+      workspacePath,
+      availableFlows: detection.availableFlows || [],
+      error: {
+        code: 'NO_SUPPORTED_FLOW',
+        message: 'No supported flow detected. Expected one of: .specs-fire, memory-bank, specs'
+      }
+    };
+  }
+
+  const parser = FLOW_PARSERS[detection.flow];
+  if (!parser) {
+    return {
+      ok: false,
+      flow: detection.flow,
+      workspacePath,
+      availableFlows: detection.availableFlows || [],
+      error: {
+        code: 'UNSUPPORTED_FLOW',
+        message: `Flow "${detection.flow}" is not supported by the web dashboard.`
+      }
+    };
+  }
+
+  const result = await parser(workspacePath);
+  if (!result.ok) {
+    return {
+      ok: false,
+      flow: detection.flow,
+      workspacePath,
+      availableFlows: detection.availableFlows || [],
+      error: compactError(result.error)
+    };
+  }
+
+  const snapshot = {
+    ...result.snapshot,
+    gitChanges: listGitChanges(workspacePath)
+  };
+
+  const data = {
+    ok: true,
+    flow: detection.flow,
+    availableFlows: detection.availableFlows || [detection.flow],
+    workspacePath,
+    snapshot,
+    summary: summarizeSnapshot(detection.flow, snapshot),
+    warnings: Array.isArray(snapshot.warnings) ? snapshot.warnings : [],
+    generatedAt: snapshot.generatedAt || new Date().toISOString()
+  };
+  data.webviewMessage = createSetDataMessage(data);
+  return data;
+}
+
+module.exports = {
+  loadWebDashboardData,
+  summarizeSnapshot
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specsmd",
-  "version": "0.1.66",
+  "version": "0.1.68",
   "description": "Multi-agent orchestration system for AI-native software development. Delivers AI-DLC, Agile, and custom SDLC flows as markdown-based agent systems.",
   "main": "lib/installer.js",
   "bin": {
@@ -12,7 +12,10 @@
     "test:schema": "vitest run __tests__/unit/schema-validation/",
     "lint:md": "markdownlint 'flows/**/*.md' --config ../.markdownlint.yaml",
     "lint:md:fix": "markdownlint 'flows/**/*.md' --config ../.markdownlint.yaml --fix",
-    "validate:all": "npm run test && npm run lint:md"
+    "sync:webview-bundle": "node scripts/sync-webview-bundle.cjs",
+    "check:webview-bundle": "node scripts/check-webview-bundle-sync.cjs",
+    "prepack": "npm run check:webview-bundle",
+    "validate:all": "npm run test && npm run lint:md && npm run check:webview-bundle"
   },
   "keywords": [
     "ai-dlc",