@nforma.ai/nforma 0.2.1

package/bin/observe-handler-internal.cjs

@@ -0,0 +1,301 @@
+/**
+ * Internal work detection handler for /qgsd:observe
+ * Scans local project state for:
+ * 1. Unfinished quick tasks (PLAN.md without SUMMARY.md)
+ * 2. Stale debug sessions (quorum-debug-latest.md)
+ * 3. TODO/FIXME/HACK/XXX comments in codebase (tracked as debt)
+ * 4. Active milestone phases without VERIFICATION.md
+ *
+ * Returns standard observe schema: { source_label, source_type, status, issues[] }
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+/**
+ * Format age from mtime (Date) to human-readable string
+ * Named distinctly from observe-handlers.cjs formatAge(isoString) to avoid confusion.
+ * @param {Date} mtime - File modification time
+ * @returns {string} Human-readable age like "5m", "2h", "3d"
+ */
+function formatAgeFromMtime(mtime) {
+  if (!mtime || !(mtime instanceof Date)) return 'unknown';
+  const diffMs = Date.now() - mtime.getTime();
+  if (diffMs < 0) return 'future';
+  const minutes = Math.floor(diffMs / 60000);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h`;
+  const days = Math.floor(hours / 24);
+  return `${days}d`;
+}
+
+/**
+ * Internal work detection handler
+ * Scans four categories: unfinished quick tasks, stale debug sessions, TODO comments, active unverified phases
+ *
+ * @param {object} sourceConfig - { label?, ...other config }
+ * @param {object} options - { projectRoot?, limitOverride? }
+ * @returns {object} Standard observe schema result
+ */
+function handleInternal(sourceConfig, options) {
+  const label = sourceConfig.label || 'Internal Work';
+  const projectRoot = options.projectRoot || process.cwd();
+  const issues = [];
+
+  try {
+    // Category 1: Unfinished quick tasks
+    try {
+      const quickDir = path.resolve(projectRoot, '.planning/quick');
+      if (fs.existsSync(quickDir)) {
+        const entries = fs.readdirSync(quickDir, { withFileTypes: true });
+        for (const entry of entries) {
+          if (!entry.isDirectory()) continue;
+
+          // Extract task number from directory name: e.g., "168-add-internal-work-detection"
+          const dirName = entry.name;
+          const match = dirName.match(/^(\d+)-/);
+          if (!match) continue;
+
+          const taskNum = match[1];
+          const slug = dirName.slice(match[0].length);
+
+          const planPath = path.join(quickDir, dirName, `${taskNum}-PLAN.md`);
+          const summaryPath = path.join(quickDir, dirName, `${taskNum}-SUMMARY.md`);
+
+          // Check: PLAN exists but SUMMARY does not
+          if (fs.existsSync(planPath) && !fs.existsSync(summaryPath)) {
+            const planStat = fs.statSync(planPath);
+            issues.push({
+              id: `internal-quick-${taskNum}`,
+              title: `Unfinished quick task #${taskNum}: ${slug}`,
+              severity: 'warning',
+              url: '',
+              age: formatAgeFromMtime(planStat.mtime),
+              created_at: planStat.mtime.toISOString(),
+              meta: 'PLAN exists, no SUMMARY',
+              source_type: 'internal',
+              issue_type: 'issue',
+              _route: `/qgsd:quick "${slug}"`
+            });
+          }
+        }
+      }
+    } catch (err) {
+      // Log warning but continue with other scans (fail-open)
+      console.warn(`[observe-internal] Warning scanning quick tasks: ${err.message}`);
+    }
+
+    // Category 2: Stale debug sessions
+    try {
+      const debugPath = path.resolve(projectRoot, '.planning/quick/quorum-debug-latest.md');
+      if (fs.existsSync(debugPath)) {
+        const stat = fs.statSync(debugPath);
+
+        // Check if less than 7 days old
+        const diffMs = Date.now() - stat.mtime.getTime();
+        const sevenDaysMs = 7 * 24 * 60 * 60 * 1000;
+
+        if (diffMs < sevenDaysMs) {
+          // Read file content to check for "unresolved" or "status: open"
+          const content = fs.readFileSync(debugPath, 'utf8');
+          const isUnresolved = /unresolved|status:\s*open/i.test(content);
+
+          if (isUnresolved) {
+            issues.push({
+              id: 'internal-debug-latest',
+              title: 'Unresolved debug session: quorum-debug-latest.md',
+              severity: 'info',
+              url: '',
+              age: formatAgeFromMtime(stat.mtime),
+              created_at: stat.mtime.toISOString(),
+              meta: 'Debug session may need resolution',
+              source_type: 'internal',
+              issue_type: 'issue',
+              _route: '/qgsd:debug --resume'
+            });
+          }
+        }
+      }
+    } catch (err) {
+      // Log warning but continue with other scans (fail-open)
+      console.warn(`[observe-internal] Warning scanning debug sessions: ${err.message}`);
+    }
+
+    // Category 3: TODO/FIXME/HACK/XXX comments in codebase
+    try {
+      // Fix 5: Validate projectRoot exists before running grep
+      if (!fs.existsSync(projectRoot)) {
+        console.warn(`[observe-internal] projectRoot does not exist: ${projectRoot}, skipping TODO scan`);
+      } else {
+        const todoPatterns = [
+          { tag: 'FIXME', severity: 'warning' },
+          { tag: 'HACK', severity: 'warning' },
+          { tag: 'XXX', severity: 'warning' },
+          { tag: 'TODO', severity: 'info' }
+        ];
+
+        // Fix 2: Exclude .planning/ at grep level (not post-filter) to ensure
+        // limit cap applies to real results, not .planning/ noise
+        const excludeDirs = [
+          'node_modules', '.git', '.planning',
+          'vendor', 'dist', '.next', 'coverage'
+        ];
+        const excludeGlobs = excludeDirs.map(d => `--exclude-dir=${d}`);
+
+        // File extensions to scan
+        const includeExts = ['--include=*.js', '--include=*.cjs', '--include=*.mjs',
+          '--include=*.ts', '--include=*.tsx', '--include=*.jsx',
+          '--include=*.md', '--include=*.json', '--include=*.py',
+          '--include=*.sh', '--include=*.css', '--include=*.html'];
+
+        // Single grep call for all patterns: TODO|FIXME|HACK|XXX
+        // Fix 1: Use -Z (--null) for NUL-separated file:line:content to handle colons in paths
+        const pattern = '\\b(TODO|FIXME|HACK|XXX)\\b';
+        const grepArgs = ['-rnZ', '-E', pattern, ...includeExts, ...excludeGlobs, projectRoot];
+
+        let grepOutput = '';
+        try {
+          grepOutput = execFileSync('grep', grepArgs, {
+            encoding: 'utf8',
+            maxBuffer: 5 * 1024 * 1024, // 5MB cap
+            timeout: 15000 // 15s timeout
+          });
+        } catch (grepErr) {
+          // grep exits 1 when no matches found — that's fine
+          if (grepErr.status !== 1) {
+            console.warn(`[observe-internal] grep failed: ${grepErr.message}`);
+          }
+        }
+
+        if (grepOutput) {
+          const lines = grepOutput.split('\n').filter(l => l.trim());
+          const limit = options.limitOverride || 50; // Cap to avoid noise
+          const todoSeverityMap = Object.fromEntries(todoPatterns.map(p => [p.tag, p.severity]));
+
+          let count = 0;
+          for (const line of lines) {
+            if (count >= limit) break;
+
+            // Fix 1: With -Z flag, grep outputs: filePath\0lineNum:content
+            // Split on first NUL byte to get filePath, then split remainder on first colon for lineNum:content
+            const nulIdx = line.indexOf('\0');
+            if (nulIdx < 0) {
+              // Fallback for grep implementations that don't support -Z:
+              // use legacy colon-split parsing
+              const colonIdx = line.indexOf(':');
+              if (colonIdx < 0) continue;
+              const afterFile = line.indexOf(':', colonIdx + 1);
+              if (afterFile < 0) continue;
+              var filePath = line.slice(0, colonIdx);
+              var lineNum = line.slice(colonIdx + 1, afterFile);
+              var content = line.slice(afterFile + 1).trim();
+            } else {
+              var filePath = line.slice(0, nulIdx);
+              const remainder = line.slice(nulIdx + 1);
+              const colonIdx = remainder.indexOf(':');
+              if (colonIdx < 0) continue;
+              var lineNum = remainder.slice(0, colonIdx);
+              var content = remainder.slice(colonIdx + 1).trim();
+            }
+
+            // Determine which tag matched
+            const tagMatch = content.match(/\b(TODO|FIXME|HACK|XXX)\b/);
+            const tag = tagMatch ? tagMatch[1] : 'TODO';
+            const severity = todoSeverityMap[tag] || 'info';
+
+            // Make path relative to project root for readability
+            const relPath = path.relative(projectRoot, filePath);
+
+            // Fix 3: Enrich TODO issues with fingerprint fields for debt writer
+            // fingerprintIssue expects: { exception_type, function_name, message }
+            issues.push({
+              id: `internal-todo-${relPath}:${lineNum}`,
+              title: `${tag} in ${relPath}:${lineNum}`,
+              severity,
+              url: '',
+              age: '',
+              created_at: new Date().toISOString(),
+              meta: content.slice(0, 120),
+              source_type: 'internal',
+              issue_type: 'issue',
+              exception_type: tag,
+              function_name: relPath,
+              _route: `/qgsd:quick "Resolve ${tag} at ${relPath}:${lineNum}"`
+            });
+            count++;
+          }
+        }
+      }
+    } catch (err) {
+      console.warn(`[observe-internal] Warning scanning TODOs: ${err.message}`);
+    }
+
+    // Category 4: Active milestone phases without VERIFICATION.md
+    try {
+      const stateFilePath = path.resolve(projectRoot, '.planning/STATE.md');
+      if (fs.existsSync(stateFilePath)) {
+        const stateContent = fs.readFileSync(stateFilePath, 'utf8');
+
+        // Extract Phase: value from STATE.md
+        const phaseMatch = stateContent.match(/^Phase:\s+(.+?)$/m);
+        if (phaseMatch) {
+          let phase = phaseMatch[1].trim();
+
+          // Skip if phase is empty or placeholder
+          if (phase && phase !== '-' && phase !== '---') {
+            // Sanitize phase string to prevent path traversal
+            phase = phase.replace(/[^a-z0-9-]/g, '');
+
+            if (phase) {
+              const phaseDir = path.join(projectRoot, '.planning/phases', phase);
+
+              // Check if phase directory exists
+              if (fs.existsSync(phaseDir) && fs.statSync(phaseDir).isDirectory()) {
+                // Check if any VERIFICATION.md file exists
+                const entries = fs.readdirSync(phaseDir);
+                const hasVerification = entries.some(f => f.endsWith('-VERIFICATION.md'));
+
+                if (!hasVerification) {
+                  issues.push({
+                    id: `internal-milestone-${phase}`,
+                    title: `Active phase ${phase} has no verification`,
+                    severity: 'warning',
+                    url: '',
+                    age: '',
+                    created_at: new Date().toISOString(),
+                    meta: 'Phase active in STATE.md but no VERIFICATION.md found',
+                    source_type: 'internal',
+                    issue_type: 'issue',
+                    _route: '/qgsd:solve'
+                  });
+                }
+              }
+            }
+          }
+        }
+      }
+    } catch (err) {
+      // Log warning but continue with other scans (fail-open)
+      console.warn(`[observe-internal] Warning scanning milestone phases: ${err.message}`);
+    }
+
+    return {
+      source_label: label,
+      source_type: 'internal',
+      status: 'ok',
+      issues
+    };
+  } catch (err) {
+    return {
+      source_label: label,
+      source_type: 'internal',
+      status: 'error',
+      error: `Internal work detection failed: ${err.message}`,
+      issues: []
+    };
+  }
+}
+
+module.exports = { handleInternal, formatAgeFromMtime };

package/bin/observe-handler-logstash.cjs

@@ -0,0 +1,153 @@
+/**
+ * Logstash/Elasticsearch source handler for /qgsd:observe
+ * Queries Elasticsearch indices for log entries matching severity filters
+ * Returns standard issue schema for the observe registry
+ */
+
+/**
+ * Format age from ISO date to human-readable string
+ * @param {string} isoDate - ISO8601 date string
+ * @returns {string} Human-readable age
+ */
+function formatAge(isoDate) {
+  if (!isoDate) return 'unknown';
+  const diffMs = Date.now() - new Date(isoDate).getTime();
+  if (diffMs < 0) return 'future';
+  const minutes = Math.floor(diffMs / 60000);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h`;
+  const days = Math.floor(hours / 24);
+  return `${days}d`;
+}
+
+/**
+ * Normalize log level to standard severity
+ * @param {string} level - Log level from Elasticsearch hit
+ * @returns {string} Normalized severity
+ */
+function normalizeSeverity(level) {
+  if (!level) return 'info';
+  const lower = String(level).toLowerCase();
+  const mapping = {
+    error: 'error',
+    fatal: 'error',
+    critical: 'error',
+    warn: 'warning',
+    warning: 'warning',
+    info: 'info',
+    debug: 'info',
+    trace: 'info'
+  };
+  return mapping[lower] || 'info';
+}
+
+/**
+ * Logstash/Elasticsearch source handler
+ * Queries Elasticsearch indices for log entries and maps hits to standard schema
+ *
+ * @param {object} sourceConfig - { type, label, endpoint, index?, auth_env?, auth_type?, filter?, issue_type? }
+ * @param {object} options - { fetchFn? }
+ * @returns {Promise<object>} Standard schema result
+ */
+async function handleLogstash(sourceConfig, options) {
+  const label = sourceConfig.label || 'Logstash';
+  const endpoint = (sourceConfig.endpoint || '').replace(/\/$/, '');
+  const index = sourceConfig.index || 'logstash-*';
+  const fetchFn = (options && options.fetchFn) || globalThis.fetch;
+  const filter = sourceConfig.filter || {};
+
+  try {
+    // Build auth headers
+    const headers = { 'Content-Type': 'application/json' };
+    if (sourceConfig.auth_env) {
+      const token = process.env[sourceConfig.auth_env];
+      if (token) {
+        const authType = sourceConfig.auth_type || 'ApiKey';
+        headers['Authorization'] = `${authType} ${token}`;
+      }
+    }
+
+    // Build Elasticsearch DSL query
+    const since = filter.since || '1h';
+    const levels = filter.levels || ['error', 'warn'];
+    const limit = filter.limit || 50;
+
+    const queryBody = {
+      query: {
+        bool: {
+          filter: [
+            { range: { '@timestamp': { gte: `now-${since}` } } },
+            { terms: { level: levels } }
+          ]
+        }
+      },
+      size: limit,
+      sort: [{ '@timestamp': 'desc' }]
+    };
+
+    const url = `${endpoint}/${index}/_search`;
+    const response = await fetchFn(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(queryBody)
+    });
+
+    if (!response.ok) {
+      return {
+        source_label: label,
+        source_type: 'logstash',
+        status: 'error',
+        error: `HTTP ${response.status} from Elasticsearch`,
+        issues: []
+      };
+    }
+
+    const data = await response.json();
+    const hits = (data && data.hits && Array.isArray(data.hits.hits)) ? data.hits.hits : [];
+
+    const issues = hits.map((hit, idx) => {
+      const source = hit._source || {};
+      const message = source.message || 'No message';
+      const title = message.length > 120 ? message.slice(0, 120) + '...' : message;
+      const level = source.level || '';
+      const timestamp = source['@timestamp'] || new Date().toISOString();
+
+      // Build compact meta from extra fields (exclude message and @timestamp)
+      const extraFields = Object.entries(source)
+        .filter(([k]) => k !== 'message' && k !== '@timestamp' && k !== 'level')
+        .map(([k, v]) => `${k}=${v}`)
+        .join(', ');
+      const meta = extraFields.length > 200 ? extraFields.slice(0, 200) + '...' : extraFields;
+
+      return {
+        id: `es-${hit._id || idx}`,
+        title,
+        severity: normalizeSeverity(level),
+        url: '',
+        age: formatAge(timestamp),
+        created_at: timestamp,
+        meta,
+        source_type: 'logstash',
+        issue_type: sourceConfig.issue_type || 'issue'
+      };
+    });
+
+    return {
+      source_label: label,
+      source_type: 'logstash',
+      status: 'ok',
+      issues
+    };
+  } catch (err) {
+    return {
+      source_label: label,
+      source_type: 'logstash',
+      status: 'error',
+      error: `Elasticsearch fetch failed: ${err.message}`,
+      issues: []
+    };
+  }
+}
+
+module.exports = { handleLogstash };

package/bin/observe-handler-prometheus.cjs

@@ -0,0 +1,185 @@
+/**
+ * Prometheus source handler for /qgsd:observe
+ * Supports: /api/v1/alerts (active alerts) and /api/v1/query (PromQL)
+ * Returns standard issue schema for the observe registry
+ */
+
+/**
+ * Format age from ISO date to human-readable string
+ * @param {string} isoDate - ISO8601 date string
+ * @returns {string} Human-readable age
+ */
+function formatAge(isoDate) {
+  if (!isoDate) return 'unknown';
+  const diffMs = Date.now() - new Date(isoDate).getTime();
+  if (diffMs < 0) return 'future';
+  const minutes = Math.floor(diffMs / 60000);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h`;
+  const days = Math.floor(hours / 24);
+  return `${days}d`;
+}
+
+/**
+ * Prometheus source handler
+ * Fetches alerts or runs PromQL query, maps results to standard issue schema
+ *
+ * @param {object} sourceConfig - { type, label, endpoint, auth_env?, query?, threshold?, issue_type? }
+ * @param {object} options - { fetchFn? }
+ * @returns {Promise<object>} Standard schema result
+ */
+async function handlePrometheus(sourceConfig, options) {
+  const label = sourceConfig.label || 'Prometheus';
+  const endpoint = (sourceConfig.endpoint || '').replace(/\/$/, '');
+  const fetchFn = (options && options.fetchFn) || globalThis.fetch;
+
+  try {
+    // Build auth headers
+    const headers = {};
+    if (sourceConfig.auth_env) {
+      const token = process.env[sourceConfig.auth_env];
+      if (token) {
+        headers['Authorization'] = `Bearer ${token}`;
+      }
+    }
+
+    // Choose mode: query field → PromQL, else → alerts
+    const hasQuery = sourceConfig.query && sourceConfig.query.trim().length > 0;
+    const url = hasQuery
+      ? `${endpoint}/api/v1/query?query=${encodeURIComponent(sourceConfig.query)}`
+      : `${endpoint}/api/v1/alerts`;
+
+    const response = await fetchFn(url, { headers });
+
+    if (!response.ok) {
+      return {
+        source_label: label,
+        source_type: 'prometheus',
+        status: 'error',
+        error: `HTTP ${response.status} from Prometheus`,
+        issues: []
+      };
+    }
+
+    const data = await response.json();
+
+    if (hasQuery) {
+      return mapQueryResult(data, sourceConfig, label);
+    } else {
+      return mapAlertsResult(data, sourceConfig, label);
+    }
+  } catch (err) {
+    return {
+      source_label: label,
+      source_type: 'prometheus',
+      status: 'error',
+      error: `Prometheus fetch failed: ${err.message}`,
+      issues: []
+    };
+  }
+}
+
+/**
+ * Map /api/v1/alerts response to standard schema
+ */
+function mapAlertsResult(data, sourceConfig, label) {
+  const alerts = (data && data.data && Array.isArray(data.data.alerts)) ? data.data.alerts : [];
+
+  const issues = alerts.map((alert, idx) => {
+    const labels = alert.labels || {};
+    const annotations = alert.annotations || {};
+    const alertname = labels.alertname || `alert-${idx}`;
+    const severity = labels.severity || 'warning';
+    const state = alert.state || 'unknown';
+    const activeAt = alert.activeAt || new Date().toISOString();
+
+    // Build meta: state + key labels
+    const metaParts = [`state: ${state}`];
+    if (annotations.summary) metaParts.push(annotations.summary);
+    const labelKeys = Object.keys(labels).filter(k => k !== 'alertname' && k !== 'severity');
+    if (labelKeys.length > 0) {
+      metaParts.push(labelKeys.map(k => `${k}=${labels[k]}`).join(', '));
+    }
+
+    return {
+      id: `prom-alert-${idx}`,
+      title: alertname,
+      severity,
+      url: alert.generatorURL || `${sourceConfig.endpoint || ''}/alerts`,
+      age: formatAge(activeAt),
+      created_at: activeAt,
+      meta: metaParts.join(' | '),
+      source_type: 'prometheus',
+      issue_type: sourceConfig.issue_type || 'drift'
+    };
+  });
+
+  return {
+    source_label: label,
+    source_type: 'prometheus',
+    status: 'ok',
+    issues
+  };
+}
+
+/**
+ * Map /api/v1/query response to standard schema
+ */
+function mapQueryResult(data, sourceConfig, label) {
+  const resultType = (data && data.data && data.data.resultType) || 'vector';
+  const result = (data && data.data && data.data.result) || [];
+
+  let issues = [];
+
+  if (resultType === 'scalar') {
+    // Scalar: result is [timestamp, "value"]
+    const value = Array.isArray(result) ? result[1] : String(result);
+    issues = [{
+      id: 'prom-query-scalar',
+      title: `Query result: ${sourceConfig.query || 'scalar'}`,
+      severity: 'info',
+      url: sourceConfig.endpoint || '',
+      age: '',
+      created_at: new Date().toISOString(),
+      meta: `value: ${value}`,
+      source_type: 'prometheus',
+      issue_type: sourceConfig.issue_type || 'drift'
+    }];
+  } else {
+    // Vector: result is array of { metric: {...}, value: [ts, "val"] }
+    issues = (Array.isArray(result) ? result : []).map((item, idx) => {
+      const metric = item.metric || {};
+      const metricName = metric.__name__ || 'unknown_metric';
+      const value = Array.isArray(item.value) ? item.value[1] : '0';
+
+      // Build title from metric name + labels
+      const labelParts = Object.entries(metric)
+        .filter(([k]) => k !== '__name__')
+        .map(([k, v]) => `${k}="${v}"`)
+        .join(', ');
+      const title = labelParts ? `${metricName}{${labelParts}}` : metricName;
+
+      return {
+        id: `prom-query-${idx}`,
+        title,
+        severity: 'info',
+        url: sourceConfig.endpoint || '',
+        age: '',
+        created_at: new Date().toISOString(),
+        meta: `value: ${value}`,
+        source_type: 'prometheus',
+        issue_type: sourceConfig.issue_type || 'drift'
+      };
+    });
+  }
+
+  return {
+    source_label: label,
+    source_type: 'prometheus',
+    status: 'ok',
+    issues
+  };
+}
+
+module.exports = { handlePrometheus };