chati-dev 4.3.0 → 4.4.0

package/src/preview/launcher.js

@@ -1,235 +0,0 @@
-/**
- * @fileoverview Preview server lifecycle management.
- * Spawns dev servers, finds available ports, health-checks, and opens browsers.
- * NEVER kills existing processes — only manages servers it spawns.
- */
-
-import net from 'net';
-import http from 'http';
-import { spawn } from 'child_process';
-import { platform } from 'os';
-import { LogBuffer } from './log-buffer.js';
-
-/**
- * Test if a port is available (not in use by another process).
- * Uses net.createServer to probe — never kills existing services.
- *
- * @param {number} port
- * @returns {Promise<boolean>}
- */
-function isPortAvailable(port) {
-  return new Promise((resolve) => {
-    const server = net.createServer();
-    server.once('error', () => resolve(false));
-    server.once('listening', () => {
-      server.close(() => resolve(true));
-    });
-    server.listen(port);
-  });
-}
-
-/**
- * Find an available port starting from a given number.
- * Scans sequentially — NEVER kills existing processes on occupied ports.
- *
- * @param {number} [startPort=3000] - Port to start scanning from
- * @param {number} [maxAttempts=20] - Maximum ports to try
- * @returns {Promise<number>} Available port number
- * @throws {Error} If no port is available within range
- */
-export async function findAvailablePort(startPort = 3000, maxAttempts = 20) {
-  for (let attempt = 0; attempt < maxAttempts; attempt++) {
-    const port = startPort + attempt;
-    const available = await isPortAvailable(port);
-    if (available) return port;
-  }
-
-  throw new Error(
-    `No available port found in range ${startPort}-${startPort + maxAttempts - 1}`,
-  );
-}
-
-/**
- * Wait for an HTTP server to respond on the given URL.
- * Polls with exponential backoff until the server is ready.
- *
- * @param {string} url - URL to check (e.g., "http://localhost:3000")
- * @param {number} [timeout=30000] - Max wait time in ms
- * @returns {Promise<void>}
- * @throws {Error} If server doesn't respond within timeout
- */
-export function waitForServer(url, timeout = 30000) {
-  const startTime = Date.now();
-  let delay = 500;
-
-  return new Promise((resolve, reject) => {
-    function attempt() {
-      if (Date.now() - startTime > timeout) {
-        reject(new Error(`Server at ${url} did not respond within ${timeout}ms`));
-        return;
-      }
-
-      const req = http.get(url, (res) => {
-        // Any response (even 404) means server is up
-        res.resume();
-        resolve();
-      });
-
-      req.on('error', () => {
-        // Server not ready yet — retry with backoff
-        delay = Math.min(delay * 1.5, 3000);
-        setTimeout(attempt, delay);
-      });
-
-      req.setTimeout(2000, () => {
-        req.destroy();
-        setTimeout(attempt, delay);
-      });
-    }
-
-    attempt();
-  });
-}
-
-/**
- * Open a URL in the system's default browser.
- *
- * @param {string} url - URL to open
- * @returns {void}
- */
-export function openBrowser(url) {
-  const os = platform();
-  let command;
-  let args;
-
-  if (os === 'darwin') {
-    command = 'open';
-    args = [url];
-  } else if (os === 'win32') {
-    command = 'cmd';
-    args = ['/c', 'start', url];
-  } else {
-    command = 'xdg-open';
-    args = [url];
-  }
-
-  const proc = spawn(command, args, { stdio: 'ignore', detached: true });
-  proc.unref();
-}
-
-/**
- * Gracefully kill a child process.
- * Sends SIGTERM, waits 3s, then SIGKILL if still alive.
- *
- * @param {import('child_process').ChildProcess} proc
- * @returns {Promise<void>}
- */
-function killProcess(proc) {
-  return new Promise((resolve) => {
-    if (!proc || proc.killed || proc.exitCode !== null) {
-      resolve();
-      return;
-    }
-
-    const forceKillTimer = setTimeout(() => {
-      try {
-        proc.kill('SIGKILL');
-      } catch { /* expected: process may already be dead */
-        // Already dead
-      }
-      resolve();
-    }, 3000);
-
-    proc.once('exit', () => {
-      clearTimeout(forceKillTimer);
-      resolve();
-    });
-
-    try {
-      proc.kill('SIGTERM');
-    } catch { /* expected: process may already be dead */
-      clearTimeout(forceKillTimer);
-      resolve();
-    }
-  });
-}
-
-/**
- * Launch a preview server for the project.
- *
- * @param {string} projectDir - Absolute path to project root
- * @param {object} options
- * @param {string} options.command - Command to run (e.g., "npm")
- * @param {string[]} options.args - Command arguments (e.g., ["run", "dev"])
- * @param {number} options.port - Port to use
- * @param {string} [options.framework='unknown'] - Detected framework name
- * @param {boolean} [options.openBrowser=true] - Open browser after server is ready
- * @param {number} [options.timeout=30000] - Health check timeout in ms
- * @returns {Promise<{ url: string, port: number, pid: number, framework: string, logs: LogBuffer, kill: () => Promise<void> }>}
- */
-export async function launchPreview(projectDir, options) {
-  const {
-    command,
-    args,
-    port,
-    framework = 'unknown',
-    openBrowser: shouldOpenBrowser = true,
-    timeout = 30000,
-  } = options;
-
-  const logs = new LogBuffer();
-  const url = `http://localhost:${port}`;
-
-  // Spawn the dev server
-  const proc = spawn(command, args, {
-    cwd: projectDir,
-    env: { ...process.env, PORT: String(port) },
-    stdio: ['ignore', 'pipe', 'pipe'],
-  });
-
-  // Capture stdout
-  if (proc.stdout) {
-    proc.stdout.on('data', (data) => {
-      for (const line of data.toString().split('\n')) {
-        if (line.trim()) logs.append(line, 'stdout');
-      }
-    });
-  }
-
-  // Capture stderr
-  if (proc.stderr) {
-    proc.stderr.on('data', (data) => {
-      for (const line of data.toString().split('\n')) {
-        if (line.trim()) logs.append(line, 'stderr');
-      }
-    });
-  }
-
-  // Handle spawn errors
-  const spawnError = await new Promise((resolve) => {
-    proc.once('error', (err) => resolve(err));
-    // Give it a moment to fail or succeed
-    setTimeout(() => resolve(null), 500);
-  });
-
-  if (spawnError) {
-    throw new Error(`Failed to start dev server: ${spawnError.message}`);
-  }
-
-  // Wait for the server to be ready
-  await waitForServer(url, timeout);
-
-  // Open browser
-  if (shouldOpenBrowser) {
-    openBrowser(url);
-  }
-
-  return {
-    url,
-    port,
-    pid: proc.pid,
-    framework,
-    logs,
-    kill: () => killProcess(proc),
-  };
-}

package/src/preview/log-buffer.js

@@ -1,103 +0,0 @@
-/**
- * @fileoverview Circular log buffer for capturing server output.
- * Used by the preview launcher to collect stdout/stderr from dev servers.
- * Provides filtered views (errors, recent) for Dev agent context.
- */
-
-/**
- * Circular buffer that captures server logs with metadata.
- * Automatically evicts oldest entries when capacity is reached.
- */
-export class LogBuffer {
-  #lines = [];
-  #maxLines;
-
-  /**
-   * @param {number} [maxLines=200] - Maximum lines to retain
-   */
-  constructor(maxLines = 200) {
-    this.#maxLines = maxLines;
-  }
-
-  /**
-   * Append a log line.
-   * @param {string} line - Raw output line
-   * @param {'stdout'|'stderr'} [stream='stdout'] - Source stream
-   */
-  append(line, stream = 'stdout') {
-    if (typeof line !== 'string') return;
-
-    this.#lines.push({
-      line: line.trim(),
-      stream,
-      timestamp: Date.now(),
-    });
-
-    // Evict oldest when over capacity
-    if (this.#lines.length > this.#maxLines) {
-      this.#lines.shift();
-    }
-  }
-
-  /**
-   * Get all buffered lines.
-   * @returns {Array<{ line: string, stream: string, timestamp: number }>}
-   */
-  getAll() {
-    return [...this.#lines];
-  }
-
-  /**
-   * Get lines that look like errors or warnings.
-   * Includes all stderr lines + stdout lines matching error patterns.
-   * @returns {Array<{ line: string, stream: string, timestamp: number }>}
-   */
-  getErrors() {
-    return this.#lines.filter(
-      (l) =>
-        l.stream === 'stderr' ||
-        /(error|warn(ing)?|exception|failed|fatal|panic|unhandled)/i.test(l.line),
-    );
-  }
-
-  /**
-   * Get the N most recent lines.
-   * @param {number} [n=50] - Number of lines
-   * @returns {Array<{ line: string, stream: string, timestamp: number }>}
-   */
-  getRecent(n = 50) {
-    return this.#lines.slice(-n);
-  }
-
-  /**
-   * Get total number of buffered lines.
-   * @returns {number}
-   */
-  get size() {
-    return this.#lines.length;
-  }
-
-  /**
-   * Clear all buffered lines.
-   */
-  clear() {
-    this.#lines = [];
-  }
-
-  /**
-   * Format logs as structured context for the Dev agent.
-   * Includes error summary + recent output for debugging.
-   * @returns {{ totalLines: number, errorCount: number, errors: string[], recentOutput: string[] }}
-   */
-  toContext() {
-    const errors = this.getErrors();
-    const recent = this.getRecent(50);
-
-    return {
-      totalLines: this.#lines.length,
-      errorCount: errors.length,
-      errors: errors.map((e) => e.line),
-      recentOutput: recent.map((l) => `[${l.stream}] ${l.line}`),
-    };
-  }
-}

package/src/quality/metrics-collector.js

@@ -1,281 +0,0 @@
-/**
- * @fileoverview Quality metrics collector and trend analysis.
- *
- * Persists quality metrics over time and calculates trends
- * (improving, stable, declining) via linear regression.
- *
- * Constitution Article XIV — Framework Registry Governance.
- */
-
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
-import { join, dirname } from 'path';
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-/** Metrics storage filename. */
-const METRICS_FILE = 'quality-history.json';
-
-/** Metrics directory relative to project root. */
-const METRICS_DIR = '.chati/metrics';
-
-/** Maximum metrics entries to keep per project. */
-export const MAX_METRICS_ENTRIES = 500;
-
-/** Valid metric types. */
-export const METRIC_TYPES = {
-  QA_SCORE: 'qa_score',
-  HEALTH_SCORE: 'health_score',
-  TEST_COUNT: 'test_count',
-  COVERAGE: 'coverage',
-  LINT_ERRORS: 'lint_errors',
-  BUILD_TIME: 'build_time',
-};
-
-/** Trend direction values. */
-export const TREND_DIRECTION = {
-  IMPROVING: 'improving',
-  STABLE: 'stable',
-  DECLINING: 'declining',
-};
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Get the metrics file path for a project.
- *
- * @param {string} projectDir
- * @returns {string}
- */
-function getMetricsPath(projectDir) {
-  return join(projectDir, METRICS_DIR, METRICS_FILE);
-}
-
-/**
- * Load metrics from disk.
- *
- * @param {string} projectDir
- * @returns {{ metrics: object[] }}
- */
-function loadMetrics(projectDir) {
-  const filePath = getMetricsPath(projectDir);
-  if (!existsSync(filePath)) {
-    return { metrics: [] };
-  }
-
-  try {
-    const raw = readFileSync(filePath, 'utf-8');
-    const data = JSON.parse(raw);
-    return { metrics: Array.isArray(data.metrics) ? data.metrics : [] };
-  } catch { /* expected: file may not exist */
-    return { metrics: [] };
-  }
-}
-
-/**
- * Save metrics to disk.
- *
- * @param {string} projectDir
- * @param {{ metrics: object[] }} data
- */
-function saveMetrics(projectDir, data) {
-  const filePath = getMetricsPath(projectDir);
-  const dir = dirname(filePath);
-
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
-  }
-
-  // Trim to MAX_METRICS_ENTRIES
-  if (data.metrics.length > MAX_METRICS_ENTRIES) {
-    data.metrics = data.metrics.slice(-MAX_METRICS_ENTRIES);
-  }
-
-  writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
-}
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-/**
- * @typedef {object} MetricEntry
- * @property {string} type - Metric type (from METRIC_TYPES)
- * @property {number} value - Metric value
- * @property {string} [agent] - Agent that produced the metric
- * @property {string} [sessionId] - Session identifier
- * @property {string} timestamp - ISO timestamp
- */
-
-/**
- * Record a quality metric.
- *
- * @param {string} projectDir
- * @param {{ type: string, value: number, agent?: string, sessionId?: string }} metric
- * @returns {{ recorded: boolean, total: number }}
- */
-export function recordMetric(projectDir, metric) {
-  if (!metric || typeof metric.value !== 'number') {
-    return { recorded: false, total: 0 };
-  }
-
-  const validTypes = Object.values(METRIC_TYPES);
-  if (!validTypes.includes(metric.type)) {
-    return { recorded: false, total: 0 };
-  }
-
-  const data = loadMetrics(projectDir);
-
-  data.metrics.push({
-    type: metric.type,
-    value: metric.value,
-    agent: metric.agent || null,
-    sessionId: metric.sessionId || null,
-    timestamp: new Date().toISOString(),
-  });
-
-  saveMetrics(projectDir, data);
-
-  return { recorded: true, total: data.metrics.length };
-}
-
-/**
- * Get metrics history with optional filtering.
- *
- * @param {string} projectDir
- * @param {{ type?: string, agent?: string, limit?: number, since?: string }} [options={}]
- * @returns {{ metrics: MetricEntry[], trend: { direction: string, slope: number, confidence: number } }}
- */
-export function getMetricsHistory(projectDir, options = {}) {
-  const data = loadMetrics(projectDir);
-  let metrics = data.metrics;
-
-  // Filter by type
-  if (options.type) {
-    metrics = metrics.filter(m => m.type === options.type);
-  }
-
-  // Filter by agent
-  if (options.agent) {
-    metrics = metrics.filter(m => m.agent === options.agent);
-  }
-
-  // Filter by time
-  if (options.since) {
-    const sinceDate = new Date(options.since).getTime();
-    metrics = metrics.filter(m => new Date(m.timestamp).getTime() >= sinceDate);
-  }
-
-  // Apply limit
-  if (options.limit && options.limit > 0) {
-    metrics = metrics.slice(-options.limit);
-  }
-
-  // Calculate trend
-  const trend = calculateTrend(metrics);
-
-  return { metrics, trend };
-}
-
-/**
- * Calculate trend from a series of metrics using linear regression.
- *
- * @param {MetricEntry[]} metrics
- * @returns {{ direction: string, slope: number, confidence: number }}
- */
-export function calculateTrend(metrics) {
-  if (!metrics || metrics.length < 3) {
-    return { direction: TREND_DIRECTION.STABLE, slope: 0, confidence: 0 };
-  }
-
-  const values = metrics.map(m => m.value);
-  const n = values.length;
-
-  // Simple linear regression: y = mx + b
-  let sumX = 0;
-  let sumY = 0;
-  let sumXY = 0;
-  let sumX2 = 0;
-
-  for (let i = 0; i < n; i++) {
-    sumX += i;
-    sumY += values[i];
-    sumXY += i * values[i];
-    sumX2 += i * i;
-  }
-
-  const slope = (n * sumXY - sumX * sumY) / (n * sumX2 - sumX * sumX);
-
-  // Calculate R² (coefficient of determination)
-  const meanY = sumY / n;
-  let ssRes = 0;
-  let ssTot = 0;
-
-  for (let i = 0; i < n; i++) {
-    const predicted = meanY + slope * (i - (n - 1) / 2);
-    ssRes += (values[i] - predicted) ** 2;
-    ssTot += (values[i] - meanY) ** 2;
-  }
-
-  const r2 = ssTot > 0 ? 1 - ssRes / ssTot : 0;
-  const confidence = Math.max(0, Math.min(1, Math.abs(r2)));
-
-  // Determine direction
-  // Normalize slope by mean to get relative change
-  const normalizedSlope = meanY !== 0 ? slope / Math.abs(meanY) : slope;
-  const threshold = 0.02; // 2% change per step is significant
-
-  let direction;
-  if (normalizedSlope > threshold && confidence > 0.3) {
-    direction = TREND_DIRECTION.IMPROVING;
-  } else if (normalizedSlope < -threshold && confidence > 0.3) {
-    direction = TREND_DIRECTION.DECLINING;
-  } else {
-    direction = TREND_DIRECTION.STABLE;
-  }
-
-  return {
-    direction,
-    slope: Math.round(slope * 1000) / 1000,
-    confidence: Math.round(confidence * 100) / 100,
-  };
-}
-
-/**
- * Get a quality dashboard summary.
- *
- * @param {string} projectDir
- * @returns {{ latestScores: Record<string, number>, trends: Record<string, object>, totalMetrics: number, lastUpdated: string|null }}
- */
-export function getQualityDashboard(projectDir) {
-  const data = loadMetrics(projectDir);
-  const metrics = data.metrics;
-
-  if (metrics.length === 0) {
-    return { latestScores: {}, trends: {}, totalMetrics: 0, lastUpdated: null };
-  }
-
-  // Get latest value for each metric type
-  const latestScores = {};
-  const trends = {};
-
-  for (const type of Object.values(METRIC_TYPES)) {
-    const typeMetrics = metrics.filter(m => m.type === type);
-    if (typeMetrics.length > 0) {
-      latestScores[type] = typeMetrics[typeMetrics.length - 1].value;
-      trends[type] = calculateTrend(typeMetrics);
-    }
-  }
-
-  const lastUpdated = metrics[metrics.length - 1]?.timestamp || null;
-
-  return {
-    latestScores,
-    trends,
-    totalMetrics: metrics.length,
-    lastUpdated,
-  };
-}