iikit-dashboard 1.6.0 → 1.7.0

package/bin/iikit-dashboard.js

@@ -2,69 +2,29 @@
 'use strict';
 
 const path = require('path');
-const { createServer, removePidfile } = require('../src/server');
+const { execFileSync } = require('child_process');
 
-// Parse arguments
 const args = process.argv.slice(2);
-let projectPath = path.resolve(process.cwd());
-let port = 3000;
+let projectPath = '.';
+let watch = false;
 
 for (let i = 0; i < args.length; i++) {
-  if (args[i] === '--path' && args[i + 1]) {
-    projectPath = path.resolve(args[i + 1]);
-    i++;
-  } else if (args[i] === '--port' && args[i + 1]) {
-    port = parseInt(args[i + 1], 10);
+  if (args[i] === '--watch' || args[i] === '-w') {
+    watch = true;
+  } else if (args[i] === '--path' && args[i + 1]) {
+    projectPath = args[i + 1];
     i++;
   } else if (!args[i].startsWith('--')) {
-    // Positional argument = project path
-    projectPath = path.resolve(args[i]);
+    projectPath = args[i];
   }
 }
 
-async function main() {
-  console.log(`\n  IIKit Dashboard`);
-  console.log(`  ===============\n`);
-  console.log(`  Project: ${projectPath}`);
-
-  try {
-    const result = await createServer({ projectPath, port });
-    const url = `http://localhost:${result.port}`;
-    console.log(`  Server:  ${url}`);
-    console.log(`\n  Open your browser to view the dashboard.\n`);
-
-    // Try to open browser (best effort, don't fail if it doesn't work)
-    try {
-      const { exec } = require('child_process');
-      const cmd = process.platform === 'darwin' ? 'open' :
-                  process.platform === 'win32' ? 'start' : 'xdg-open';
-      exec(`${cmd} ${url}`);
-    } catch {
-      // Ignore browser open errors
-    }
-
-    // Handle graceful shutdown
-    process.on('SIGINT', () => {
-      console.log('\n  Shutting down...');
-      removePidfile(projectPath);
-      result.server.close(() => {
-        if (result.watcher) result.watcher.close();
-        process.exit(0);
-      });
-    });
+const generatorPath = path.join(__dirname, '..', 'src', 'generate-dashboard.js');
+const generatorArgs = [generatorPath, projectPath];
+if (watch) generatorArgs.push('--watch');
 
-    process.on('SIGTERM', () => {
-      removePidfile(projectPath);
-      result.server.close(() => {
-        if (result.watcher) result.watcher.close();
-        process.exit(0);
-      });
-    });
-
-  } catch (err) {
-    console.error(`  Error: ${err.message}`);
-    process.exit(1);
-  }
+try {
+  execFileSync(process.execPath, generatorArgs, { stdio: 'inherit' });
+} catch (err) {
+  process.exit(err.status || 1);
 }
-
-main();

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "iikit-dashboard",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Real-time dashboard for Intent Integrity Kit (IIKit) — visualizes every phase of specification-driven AI development",
-  "main": "src/server.js",
+  "main": "src/generate-dashboard.js",
   "bin": {
     "iikit-dashboard": "bin/iikit-dashboard.js"
   },
@@ -11,10 +11,11 @@
     "src/"
   ],
   "scripts": {
-    "start": "node bin/iikit-dashboard.js",
-    "test": "jest --forceExit --testPathIgnorePatterns=test/visual",
+    "start": "node src/generate-dashboard.js . --watch",
+    "test": "jest --testPathIgnorePatterns=test/visual",
     "test:visual": "npx playwright test",
-    "test:visual:update": "npx playwright test --update-snapshots"
+    "test:visual:update": "npx playwright test --update-snapshots",
+    "build:generator": "node build/bundle-generator.js"
   },
   "keywords": [
     "iikit",
@@ -36,13 +37,11 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.74.0",
-    "chokidar": "^3.6.0",
-    "express": "^5.2.1",
-    "ws": "^8.19.0"
+    "chokidar": "^3.6.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.58.2",
+    "esbuild": "^0.27.3",
     "jest": "^30.2.0"
   }
 }

package/src/generate-dashboard.js

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+const { parseSpecStories, parseTasks, parseConstitutionPrinciples, parsePremise } = require('./parser');
+const { computeBoardState } = require('./board');
+const { computeAssertionHash, checkIntegrity } = require('./integrity');
+const { computePipelineState } = require('./pipeline');
+const { computeStoryMapState } = require('./storymap');
+const { computePlanViewState } = require('./planview');
+const { computeChecklistViewState } = require('./checklist');
+const { computeTestifyState } = require('./testify');
+const { computeAnalyzeState } = require('./analyze');
+const { computeBugsState } = require('./bugs');
+
+/**
+ * List features from specs/ directory.
+ * A feature is a directory under specs/ that contains spec.md (FR-004).
+ */
+function listFeatures(projectPath) {
+  const specsDir = path.join(projectPath, 'specs');
+  if (!fs.existsSync(specsDir)) return [];
+
+  const entries = fs.readdirSync(specsDir, { withFileTypes: true });
+  const features = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const featureDir = path.join(specsDir, entry.name);
+    const specPath = path.join(featureDir, 'spec.md');
+    if (!fs.existsSync(specPath)) continue;
+
+    const tasksPath = path.join(featureDir, 'tasks.md');
+    const specContent = fs.readFileSync(specPath, 'utf-8');
+    const tasksContent = fs.existsSync(tasksPath) ? fs.readFileSync(tasksPath, 'utf-8') : '';
+    const stories = parseSpecStories(specContent);
+    const tasks = parseTasks(tasksContent);
+
+    const checkedCount = tasks.filter(t => t.checked).length;
+    const totalCount = tasks.length;
+
+    const namePart = entry.name.replace(/^\d+-/, '');
+    const name = namePart.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+
+    features.push({
+      id: entry.name,
+      name,
+      stories: stories.length,
+      progress: `${checkedCount}/${totalCount}`
+    });
+  }
+
+  return features.reverse();
+}
+
+/**
+ * Compute board state with integrity for a feature.
+ */
+function getBoardState(projectPath, featureId) {
+  const featureDir = path.join(projectPath, 'specs', featureId);
+  const specPath = path.join(featureDir, 'spec.md');
+  const tasksPath = path.join(featureDir, 'tasks.md');
+  const testSpecsPath = path.join(featureDir, 'tests', 'test-specs.md');
+  const contextPath = path.join(featureDir, 'context.json');
+
+  const specContent = fs.existsSync(specPath) ? fs.readFileSync(specPath, 'utf-8') : '';
+  const tasksContent = fs.existsSync(tasksPath) ? fs.readFileSync(tasksPath, 'utf-8') : '';
+
+  const stories = parseSpecStories(specContent);
+  const tasks = parseTasks(tasksContent);
+  const board = computeBoardState(stories, tasks);
+
+  let integrity = { status: 'missing', currentHash: null, storedHash: null };
+  if (fs.existsSync(testSpecsPath)) {
+    const testSpecsContent = fs.readFileSync(testSpecsPath, 'utf-8');
+    const currentHash = computeAssertionHash(testSpecsContent);
+    let storedHash = null;
+    if (fs.existsSync(contextPath)) {
+      try {
+        const context = JSON.parse(fs.readFileSync(contextPath, 'utf-8'));
+        storedHash = context?.testify?.assertion_hash || null;
+      } catch {
+        // malformed context.json
+      }
+    }
+    integrity = checkIntegrity(currentHash, storedHash);
+  }
+
+  return { ...board, integrity };
+}
+
+/**
+ * Assemble DASHBOARD_DATA for all features.
+ */
+async function assembleDashboardData(projectPath) {
+  const resolvedPath = path.resolve(projectPath);
+  const features = listFeatures(resolvedPath);
+  const constitution = parseConstitutionPrinciples(resolvedPath);
+  const premise = parsePremise(resolvedPath);
+
+  const featureData = {};
+  for (const feature of features) {
+    const fid = feature.id;
+    try {
+      featureData[fid] = {
+        board: getBoardState(resolvedPath, fid),
+        pipeline: computePipelineState(resolvedPath, fid),
+        storyMap: computeStoryMapState(resolvedPath, fid),
+        planView: await computePlanViewState(resolvedPath, fid),
+        checklist: computeChecklistViewState(resolvedPath, fid),
+        testify: computeTestifyState(resolvedPath, fid),
+        analyze: computeAnalyzeState(resolvedPath, fid),
+        bugs: computeBugsState(resolvedPath, fid)
+      };
+    } catch (err) {
+      process.stderr.write(`Error: Parser failed on specs/${fid}/spec.md: ${err.message}. Check artifact syntax.\n`);
+      process.exit(5);
+    }
+  }
+
+  return {
+    meta: {
+      projectPath: resolvedPath,
+      generatedAt: new Date().toISOString()
+    },
+    features,
+    constitution,
+    premise,
+    featureData
+  };
+}
+
+/**
+ * Inject data into HTML template and return the complete HTML string.
+ */
+function buildHtml(templateHtml, dashboardData) {
+  let html = templateHtml;
+
+  // Inject DASHBOARD_DATA and meta-refresh into <head> (FR-004, FR-005, FR-007)
+  // DASHBOARD_DATA must be in <head> so it's available before the IIFE in <body> runs
+  // Escape </script> to prevent script-tag injection from data file content (SC-008)
+  const safeJson = JSON.stringify(dashboardData).replace(/<\/script>/gi, '<\\/script>');
+  const headInject = `  <meta http-equiv="refresh" content="2">\n` +
+    `  <script>window.DASHBOARD_DATA = ${safeJson};</script>\n`;
+  html = html.replace('</head>', headInject + '</head>');
+
+  // Inject JS fallback reload before </body> (FR-007)
+  html = html.replace('</body>', `<script>setInterval(() => location.reload(), 2000);</script>\n</body>`);
+
+  return html;
+}
+
+/**
+ * Write HTML atomically: write to .tmp then rename (FR-011).
+ */
+function writeAtomic(outputPath, content) {
+  const dir = path.dirname(outputPath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const tmpPath = outputPath + '.tmp';
+  fs.writeFileSync(tmpPath, content, 'utf-8');
+  fs.renameSync(tmpPath, outputPath);
+}
+
+// Template HTML — loaded from file (modular) or inlined by esbuild (bundled)
+let _cachedTemplate = null;
+function loadTemplate() {
+  if (_cachedTemplate) return _cachedTemplate;
+  const templatePath = path.join(__dirname, 'public', 'index.html');
+  _cachedTemplate = fs.readFileSync(templatePath, 'utf-8');
+  return _cachedTemplate;
+}
+
+/**
+ * Run one generation cycle.
+ */
+async function generate(projectPath) {
+  const resolvedPath = path.resolve(projectPath);
+  const templateHtml = loadTemplate();
+
+  const dashboardData = await assembleDashboardData(resolvedPath);
+
+  // Size warning (SC-007)
+  for (const feature of dashboardData.features) {
+    const featureJson = JSON.stringify(dashboardData.featureData[feature.id] || {});
+    if (featureJson.length > 500 * 1024) {
+      const sizeMB = (featureJson.length / (1024 * 1024)).toFixed(1);
+      process.stderr.write(`Warning: Feature ${feature.id}: large artifacts detected (${sizeMB} MB). Dashboard may load slowly.\n`);
+    }
+  }
+
+  const html = buildHtml(templateHtml, dashboardData);
+  const outputPath = path.join(resolvedPath, '.specify', 'dashboard.html');
+
+  writeAtomic(outputPath, html);
+  const now = new Date().toISOString().slice(0, 19).replace('T', ' ');
+  process.stdout.write(`[${now}] Generated dashboard.html (${(html.length / 1024).toFixed(0)} KB)\n`);
+}
+
+/**
+ * Main CLI entry point.
+ */
+async function main() {
+  const args = process.argv.slice(2);
+  const watchFlag = args.includes('--watch');
+  const positionalArgs = args.filter(a => a !== '--watch');
+
+  if (positionalArgs.length === 0) {
+    process.stderr.write('Error: Project path is required. Usage: generate-dashboard.js <projectPath> [--watch]\n');
+    process.exit(1);
+  }
+
+  const projectPath = path.resolve(positionalArgs[0]);
+
+  // Validate project directory exists (exit 1)
+  if (!fs.existsSync(projectPath) || !fs.statSync(projectPath).isDirectory()) {
+    process.stderr.write(`Error: Project directory not found: ${projectPath}. Verify the path is correct.\n`);
+    process.exit(1);
+  }
+
+  // Validate CONSTITUTION.md exists (exit 3)
+  const constitutionPath = path.join(projectPath, 'CONSTITUTION.md');
+  if (!fs.existsSync(constitutionPath)) {
+    process.stderr.write('Error: CONSTITUTION.md not found in project root. Create one using /iikit-00-constitution.\n');
+    process.exit(3);
+  }
+
+  // Check write permissions (exit 4)
+  const specifyDir = path.join(projectPath, '.specify');
+  try {
+    fs.mkdirSync(specifyDir, { recursive: true });
+    // Test write by creating and removing a temp file
+    const testFile = path.join(specifyDir, '.write-test-' + process.pid);
+    fs.writeFileSync(testFile, '');
+    fs.unlinkSync(testFile);
+  } catch (err) {
+    process.stderr.write(`Error: Permission denied writing to .specify/dashboard.html. Check directory permissions.\n`);
+    process.exit(4);
+  }
+
+  // Run initial generation
+  try {
+    await generate(projectPath);
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message}\n`);
+    process.exit(5);
+  }
+
+  // Watch mode (FR-008)
+  if (watchFlag) {
+    let chokidar;
+    try {
+      chokidar = require('chokidar');
+    } catch {
+      process.stderr.write('Error: chokidar is required for --watch mode. Install it: npm install chokidar\n');
+      process.exit(1);
+    }
+
+    const watchGlobs = [
+      path.join(projectPath, 'specs', '**', '*.md'),
+      path.join(projectPath, 'CONSTITUTION.md'),
+      path.join(projectPath, 'PREMISE.md')
+    ];
+
+    const watcher = chokidar.watch(watchGlobs, {
+      ignoreInitial: true,
+      ignored: [
+        '**/node_modules/**',
+        '**/.git/**',
+        '**/dist/**',
+        path.join(projectPath, '.specify', 'dashboard.html'),
+        /.*cache.*/,
+        /.*\.tmp$/
+      ],
+      awaitWriteFinish: { stabilityThreshold: 200, pollInterval: 50 }
+    });
+
+    let debounceTimer = null;
+    watcher.on('all', () => {
+      if (debounceTimer) clearTimeout(debounceTimer);
+      debounceTimer = setTimeout(async () => {
+        try {
+          await generate(projectPath);
+        } catch (err) {
+          process.stderr.write(`Error during re-generation: ${err.message}\n`);
+        }
+      }, 300);
+    });
+
+    process.stdout.write(`Watching for changes in ${projectPath}...\n`);
+
+    process.on('SIGINT', () => {
+      watcher.close();
+      process.exit(0);
+    });
+    process.on('SIGTERM', () => {
+      watcher.close();
+      process.exit(0);
+    });
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { generate, assembleDashboardData, buildHtml, listFeatures, getBoardState };

package/src/parser.js

@@ -241,6 +241,23 @@ function hasClarifications(specContent) {
   return /^## Clarifications/m.test(specContent);
 }
 
+/**
+ * Parse PREMISE.md to return its raw markdown content.
+ *
+ * @param {string} projectPath - Path to the project root
+ * @returns {{content: string|null, exists: boolean}}
+ */
+function parsePremise(projectPath) {
+  const premisePath = path.join(projectPath, 'PREMISE.md');
+
+  if (!fs.existsSync(premisePath)) {
+    return { content: null, exists: false };
+  }
+
+  const content = fs.readFileSync(premisePath, 'utf-8');
+  return { content, exists: true };
+}
+
 /**
  * Parse CONSTITUTION.md to extract principles with full details and version metadata.
  *
@@ -1258,4 +1275,4 @@ function extractField(section, fieldName) {
   return value;
 }
 
-module.exports = { parseSpecStories, parseTasks, parseChecklists, parseChecklistsDetailed, parseConstitutionTDD, hasClarifications, parseConstitutionPrinciples, parseRequirements, parseSuccessCriteria, parseClarifications, parseStoryRequirementRefs, parseTechContext, parseFileStructure, parseAsciiDiagram, parseTesslJson, parseResearchDecisions, parseTestSpecs, parseTaskTestRefs, parseAnalysisFindings, parseAnalysisCoverage, parseAnalysisMetrics, parseConstitutionAlignment, parsePhaseSeparation, parseBugs };
+module.exports = { parseSpecStories, parseTasks, parseChecklists, parseChecklistsDetailed, parseConstitutionTDD, hasClarifications, parseConstitutionPrinciples, parsePremise, parseRequirements, parseSuccessCriteria, parseClarifications, parseStoryRequirementRefs, parseTechContext, parseFileStructure, parseAsciiDiagram, parseTesslJson, parseResearchDecisions, parseTestSpecs, parseTaskTestRefs, parseAnalysisFindings, parseAnalysisCoverage, parseAnalysisMetrics, parseConstitutionAlignment, parsePhaseSeparation, parseBugs };

package/src/pipeline.js

@@ -27,6 +27,7 @@ function computePipelineState(projectPath, featureId) {
   const tasksExists = fs.existsSync(tasksPath);
   const testSpecsExists = fs.existsSync(testSpecsPath);
   const constitutionExists = fs.existsSync(constitutionPath);
+  const premiseExists = fs.existsSync(path.join(projectPath, 'PREMISE.md'));
   const analysisExists = fs.existsSync(analysisPath);
 
   // Read spec content for clarifications check
@@ -47,7 +48,7 @@ function computePipelineState(projectPath, featureId) {
   const phases = [
     {
       id: 'constitution',
-      name: 'Constitution',
+      name: premiseExists ? 'Premise &\nConstitution' : 'Constitution',
       status: constitutionExists ? 'complete' : 'not_started',
       progress: null,
       optional: false