@eltonssouza/development-utility-kit 1.0.0

package/dashboard/server-app.js

@@ -0,0 +1,403 @@
+'use strict';
+
+/**
+ * server-app.js — Express application factory (no listen call).
+ * Extracted from server.js so tests can require the app without starting a real server.
+ * server.js requires this module and calls app.listen().
+ */
+
+const path = require('path');
+const fs = require('fs');
+const express = require('express');
+const { openDb, initSchema, queryProjects, queryModels } = require('./db');
+const { getRtkStats, getRtkDaily } = require('./rtk');
+
+// ── Repo root (BR-002): always relative to this file's __dirname ──────────────
+// dashboard/server-app.js -> __dirname = dashboard/ -> .. = repo root
+const REPO_ROOT = path.resolve(__dirname, '..');
+
+// ── Whitelist prefixes for /api/docs/file (BR-001) ────────────────────────────
+// All paths must use forward slashes after normalize.
+const WHITELIST_PREFIXES = [
+  '.claude/',
+  'docs/brain/',
+  'docs/discovery/',
+  'docs/plans/',
+  'docs/prd/',
+  'docs/issues/',
+  'dashboard/public/content/',
+];
+
+/**
+ * Validate a client-supplied relative path against the whitelist.
+ * Returns the resolved absolute path on success, or null if rejected.
+ *
+ * Rejection criteria (BR-001):
+ *   - contains ".." segment
+ *   - starts with "/" (absolute Unix)
+ *   - contains ":\\" or ":/" (Windows drive letter)
+ *   - normalized path does not start with one of the WHITELIST_PREFIXES
+ *   - resolved file is a symlink
+ *
+ * @param {string} rawPath  — value from query string
+ * @returns {string|null}   — absolute path or null
+ */
+function validateDocPath(rawPath) {
+  if (!rawPath || typeof rawPath !== 'string') return null;
+
+  // Reject obvious traversal / absolute / drive-letter patterns
+  if (rawPath.includes('..')) return null;
+  if (rawPath.startsWith('/')) return null;
+  if (/[a-zA-Z]:[/\\]/.test(rawPath)) return null;
+
+  // Normalize using posix separators (forward slash) for consistent prefix check
+  const normalised = path.normalize(rawPath).replace(/\\/g, '/');
+
+  // Reject if normalised form still contains ".."
+  if (normalised.includes('..')) return null;
+
+  // Check whitelist
+  const allowed = WHITELIST_PREFIXES.some((prefix) => normalised.startsWith(prefix));
+  if (!allowed) return null;
+
+  // Resolve to absolute path
+  const abs = path.resolve(REPO_ROOT, normalised);
+
+  // Symlink check
+  try {
+    const lstat = fs.lstatSync(abs);
+    if (lstat.isSymbolicLink()) return null;
+  } catch {
+    // File does not exist — let the read fail naturally (404 is fine; 403 only for policy)
+  }
+
+  return abs;
+}
+
+// ── Markdown parsers for SKILL.md / agent .md / ADR .md ──────────────────────
+
+/**
+ * Attempt to extract frontmatter key from a YAML block (--- ... ---).
+ * Falls back to null if not found.
+ * @param {string} content
+ * @param {string} key
+ * @returns {string|null}
+ */
+function extractFrontmatter(content, key) {
+  const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!fmMatch) return null;
+  const fm = fmMatch[1];
+  const lineMatch = fm.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'));
+  return lineMatch ? lineMatch[1].trim().replace(/^['"]|['"]$/g, '') : null;
+}
+
+/**
+ * Extract h1 heading from markdown content.
+ * @param {string} content
+ * @returns {string|null}
+ */
+function extractH1(content) {
+  const m = content.match(/^#\s+(.+)$/m);
+  return m ? m[1].trim() : null;
+}
+
+/**
+ * Extract first non-empty paragraph (skipping frontmatter and headings).
+ * @param {string} content
+ * @returns {string}
+ */
+function extractFirstParagraph(content) {
+  // Remove frontmatter
+  const withoutFm = content.replace(/^---\s*\n[\s\S]*?\n---\s*\n?/, '');
+  // Find first non-empty, non-heading line
+  for (const line of withoutFm.split('\n')) {
+    const t = line.trim();
+    if (t && !t.startsWith('#') && !t.startsWith('```')) {
+      return t.substring(0, 200);
+    }
+  }
+  return '';
+}
+
+/**
+ * Parse a SKILL.md file into a SkillEntry.
+ * D-003: tolerant parser — tries frontmatter first, then markdown headings/paragraphs.
+ *
+ * @param {string} content   — raw file contents
+ * @param {string} filePath  — absolute path
+ * @param {string} relPath   — repo-relative path (forward slashes)
+ * @returns {{name: string, description: string, triggers: string[], path: string}}
+ */
+function parseSkillMd(content, filePath, relPath) {
+  // Name: frontmatter "name:" > directory name (parent folder of SKILL.md)
+  const name =
+    extractFrontmatter(content, 'name') ||
+    extractH1(content) ||
+    path.basename(path.dirname(filePath));
+
+  // Description: frontmatter "description:" > first paragraph
+  const description =
+    extractFrontmatter(content, 'description') || extractFirstParagraph(content);
+
+  // Triggers: look for "## When it triggers" section or "triggers:" frontmatter
+  let triggers = [];
+  const triggersSection = content.match(/##\s+When it triggers\s*\n([\s\S]*?)(?=\n##|\n---|$)/i);
+  if (triggersSection) {
+    triggers = triggersSection[1]
+      .split('\n')
+      .map((l) => l.replace(/^[-*]\s*/, '').trim())
+      .filter(Boolean)
+      .slice(0, 5);
+  } else {
+    const fmTriggers = extractFrontmatter(content, 'triggers');
+    if (fmTriggers) triggers = [fmTriggers];
+  }
+
+  return { name, description, triggers, path: relPath };
+}
+
+/**
+ * Parse an agent .md file into an AgentEntry.
+ * @param {string} content
+ * @param {string} filePath
+ * @param {string} relPath
+ * @returns {{name: string, description: string, model: string, path: string}}
+ */
+function parseAgentMd(content, filePath, relPath) {
+  const name =
+    extractFrontmatter(content, 'name') ||
+    extractH1(content) ||
+    path.basename(filePath, '.md');
+
+  const description =
+    extractFrontmatter(content, 'description') || extractFirstParagraph(content);
+
+  // Default model per CLAUDE.md table (D-003)
+  const model = extractFrontmatter(content, 'model') || 'sonnet';
+
+  return { name, description, model, path: relPath };
+}
+
+/**
+ * Parse an ADR .md file into an AdrEntry.
+ * @param {string} content
+ * @param {string} filePath   — absolute
+ * @param {string} relPath    — repo-relative
+ * @returns {{number: number, slug: string, title: string, status: string, path: string}}
+ */
+function parseAdrMd(content, filePath, relPath) {
+  const filename = path.basename(filePath, '.md');
+  const numMatch = filename.match(/ADR-(\d+)/i);
+  const number = numMatch ? parseInt(numMatch[1], 10) : 0;
+
+  const slug = filename;
+  const title =
+    extractFrontmatter(content, 'title') ||
+    extractH1(content) ||
+    filename;
+
+  const status = extractFrontmatter(content, 'status') || 'Unknown';
+
+  return { number, slug, title, status, path: relPath };
+}
+
+// ── Database setup ────────────────────────────────────────────────────────────
+
+let db;
+try {
+  db = openDb();
+  initSchema(db);
+} catch (err) {
+  process.stderr.write('Warning: could not open telemetry DB: ' + err.message + '\n');
+  db = null;
+}
+
+// ── Express app ───────────────────────────────────────────────────────────────
+
+const app = express();
+
+// CORS permissive for local dashboard
+app.use((req, res, next) => {
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+  next();
+});
+
+// Static frontend
+app.use(express.static(path.join(__dirname, 'public')));
+
+// ── Telemetry endpoints ───────────────────────────────────────────────────────
+
+const THIRTY_DAYS_S = 30 * 24 * 60 * 60;
+
+app.get('/api/projects', (req, res) => {
+  const sinceTs = Math.floor(Date.now() / 1000) - THIRTY_DAYS_S;
+  const projects = db ? queryProjects(db, sinceTs) : [];
+  res.json(projects);
+});
+
+app.get('/api/rtk', async (req, res) => {
+  try {
+    const [stats, daily] = await Promise.all([getRtkStats(), getRtkDaily()]);
+    if (!stats && !daily) {
+      res.json(null);
+      return;
+    }
+    res.json({
+      tokens_saved: stats ? stats.tokens_saved : 0,
+      savings_pct: stats ? stats.savings_pct : 0,
+      daily: daily || [],
+    });
+  } catch {
+    res.json(null);
+  }
+});
+
+app.get('/api/stats', async (req, res) => {
+  try {
+    const sinceTs = Math.floor(Date.now() / 1000) - THIRTY_DAYS_S;
+
+    const projectRows = db ? queryProjects(db, sinceTs) : [];
+    const modelRows = db ? queryModels(db) : [];
+
+    const [rtkStats, rtkDaily] = await Promise.all([getRtkStats(), getRtkDaily()]);
+
+    const rtk =
+      rtkStats || rtkDaily
+        ? {
+            tokens_saved: rtkStats ? rtkStats.tokens_saved : 0,
+            savings_pct: rtkStats ? rtkStats.savings_pct : 0,
+            daily: rtkDaily || [],
+          }
+        : null;
+
+    function buildModels(rows) {
+      const total = rows.reduce((s, r) => s + Number(r.count), 0);
+      const out = { opus: { count: 0, pct: 0 }, sonnet: { count: 0, pct: 0 }, haiku: { count: 0, pct: 0 } };
+      for (const row of rows) {
+        const key = ['opus', 'sonnet', 'haiku'].includes(row.model) ? row.model : null;
+        if (key) {
+          out[key].count = Number(row.count);
+          out[key].pct = total > 0 ? Math.round((Number(row.count) / total) * 1000) / 10 : 0;
+        }
+      }
+      return out;
+    }
+
+    res.json({
+      projects: projectRows,
+      models: buildModels(modelRows),
+      rtk,
+    });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// ── Docs endpoints (/api/docs/*) ──────────────────────────────────────────────
+
+/**
+ * GET /api/docs/skills
+ * Reads .claude/skills/{name}/SKILL.md files from repo root.
+ * Returns [{name, description, triggers, path}]
+ */
+app.get('/api/docs/skills', (req, res) => {
+  const skillsDir = path.join(REPO_ROOT, '.claude', 'skills');
+  const results = [];
+
+  try {
+    const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const skillFile = path.join(skillsDir, entry.name, 'SKILL.md');
+      if (!fs.existsSync(skillFile)) continue;
+      const content = fs.readFileSync(skillFile, 'utf8');
+      const relPath = `.claude/skills/${entry.name}/SKILL.md`;
+      results.push(parseSkillMd(content, skillFile, relPath));
+    }
+    res.json(results);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * GET /api/docs/agents
+ * Reads .claude/agents/*.md files from repo root.
+ * Returns [{name, description, model, path}]
+ */
+app.get('/api/docs/agents', (req, res) => {
+  const agentsDir = path.join(REPO_ROOT, '.claude', 'agents');
+  const results = [];
+
+  try {
+    const files = fs.readdirSync(agentsDir).filter((f) => f.endsWith('.md'));
+    for (const file of files) {
+      const abs = path.join(agentsDir, file);
+      const lstat = fs.lstatSync(abs);
+      if (lstat.isSymbolicLink()) continue; // skip symlinks
+      const content = fs.readFileSync(abs, 'utf8');
+      const relPath = `.claude/agents/${file}`;
+      results.push(parseAgentMd(content, abs, relPath));
+    }
+    res.json(results);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * GET /api/docs/adrs
+ * Reads docs/brain/decisions/ADR-*.md, sorted by ADR number ascending.
+ * Returns [{number, slug, title, status, path}]
+ */
+app.get('/api/docs/adrs', (req, res) => {
+  const decisionsDir = path.join(REPO_ROOT, 'docs', 'brain', 'decisions');
+  const results = [];
+
+  try {
+    const files = fs.readdirSync(decisionsDir).filter((f) => /^ADR-\d+/i.test(f) && f.endsWith('.md'));
+    for (const file of files) {
+      const abs = path.join(decisionsDir, file);
+      const lstat = fs.lstatSync(abs);
+      if (lstat.isSymbolicLink()) continue;
+      const content = fs.readFileSync(abs, 'utf8');
+      const relPath = `docs/brain/decisions/${file}`;
+      results.push(parseAdrMd(content, abs, relPath));
+    }
+    results.sort((a, b) => a.number - b.number);
+    res.json(results);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * GET /api/docs/file?path=<relative-path>
+ * Returns raw markdown content of a whitelisted file.
+ * Returns 403 for any path outside whitelist, containing "..", absolute, drive letters, or symlinks.
+ */
+app.get('/api/docs/file', (req, res) => {
+  const rawPath = req.query.path;
+  const absPath = validateDocPath(rawPath);
+
+  if (!absPath) {
+    return res.status(403).json({ error: 'Forbidden' });
+  }
+
+  try {
+    const content = fs.readFileSync(absPath, 'utf8');
+    res.type('text/plain').send(content);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      res.status(404).json({ error: 'Not found' });
+    } else {
+      res.status(500).json({ error: err.message });
+    }
+  }
+});
+
+// ── Export for testing ────────────────────────────────────────────────────────
+
+module.exports = { app };

package/dashboard/server.js

@@ -0,0 +1,104 @@
+'use strict';
+
+const path = require('path');
+const net = require('net');
+const { spawn } = require('child_process');
+const os = require('os');
+const { app } = require('./server-app');
+
+// ── CLI args ──────────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+let startPort = 4242;
+let openBrowser = true;
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--port' && i + 1 < args.length) {
+    const n = parseInt(args[++i], 10);
+    if (!isNaN(n)) startPort = n;
+  } else if (args[i] === '--no-open') {
+    openBrowser = false;
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/**
+ * Find a free TCP port starting from `start`.
+ * Tries up to 20 ports before giving up.
+ * @param {number} start
+ * @returns {Promise<number>}
+ */
+function findFreePort(start) {
+  return new Promise((resolve, reject) => {
+    let port = start;
+    const tryPort = () => {
+      const server = net.createServer();
+      server.once('error', (err) => {
+        if (err.code === 'EADDRINUSE') {
+          port += 1;
+          if (port > start + 20) {
+            reject(new Error('Could not find a free port in range ' + start + '–' + (start + 20)));
+          } else {
+            tryPort();
+          }
+        } else {
+          reject(err);
+        }
+      });
+      server.once('listening', () => {
+        server.close(() => resolve(port));
+      });
+      server.listen(port, '127.0.0.1');
+    };
+    tryPort();
+  });
+}
+
+/**
+ * Open the default browser to the given URL.
+ */
+function openUrl(url) {
+  const platform = os.platform();
+  let cmd, cmdArgs;
+  if (platform === 'win32') {
+    cmd = 'cmd';
+    cmdArgs = ['/c', 'start', '', url];
+  } else if (platform === 'darwin') {
+    cmd = 'open';
+    cmdArgs = [url];
+  } else {
+    cmd = 'xdg-open';
+    cmdArgs = [url];
+  }
+  spawn(cmd, cmdArgs, { detached: true, stdio: 'ignore' }).unref();
+}
+
+// ── Start ─────────────────────────────────────────────────────────────────────
+
+(async () => {
+  let port;
+  try {
+    port = await findFreePort(startPort);
+  } catch (err) {
+    process.stderr.write('Error: ' + err.message + '\n');
+    process.exit(1);
+  }
+
+  const server = app.listen(port, '127.0.0.1', () => {
+    const url = 'http://localhost:' + port;
+    process.stdout.write('Dashboard running at ' + url + '\n');
+    if (openBrowser) {
+      openUrl(url);
+    }
+  });
+
+  server.on('error', (err) => {
+    process.stderr.write('Server error: ' + err.message + '\n');
+    process.exit(1);
+  });
+
+  // Graceful shutdown
+  process.on('SIGTERM', () => server.close(() => process.exit(0)));
+  process.on('SIGINT', () => server.close(() => process.exit(0)));
+})();