chati-dev 1.3.3 → 2.0.1

package/src/gates/g5-deploy-ready.js

@@ -0,0 +1,180 @@
+/**
+ * @fileoverview G5 — Deploy Ready Gate
+ *
+ * Pre-Deploy gate that validates everything is ready for deployment.
+ * Checks that QA-Implementation passed, documentation is updated,
+ * release notes exist, all tasks are complete, and no blockers remain.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { GateBase } from './gate-base.js';
+import { loadSession } from '../orchestrator/session-manager.js';
+import { loadHandoff } from '../tasks/handoff.js';
+
+export class DeployReadyGate extends GateBase {
+  constructor() {
+    super({
+      id: 'g5-deploy-ready',
+      name: 'Deploy Ready',
+      pipelinePoint: 'pre-deploy',
+      agent: 'devops',
+    });
+  }
+
+  /**
+   * Collect evidence about deployment readiness.
+   *
+   * @param {string} projectDir
+   * @returns {object} Evidence about QA status, docs, release notes, blockers
+   */
+  _collectEvidence(projectDir) {
+    const evidence = {
+      qaImplPassed: false,
+      readmeUpdated: false,
+      changelogUpdated: false,
+      releaseNotesPrepared: false,
+      allTasksCompleted: false,
+      noOpenBlockers: true,
+      sessionState: null,
+    };
+
+    // Check QA-Implementation status
+    const qaHandoff = loadHandoff(projectDir, 'qa-implementation');
+    if (qaHandoff.loaded && qaHandoff.handoff) {
+      evidence.qaImplPassed = qaHandoff.handoff.score >= 90 &&
+        qaHandoff.handoff.status === 'complete';
+    }
+
+    // Check README exists
+    const readmePaths = [
+      join(projectDir, 'README.md'),
+      join(projectDir, 'readme.md'),
+    ];
+    for (const readmePath of readmePaths) {
+      if (existsSync(readmePath)) {
+        evidence.readmeUpdated = true;
+        break;
+      }
+    }
+
+    // Check CHANGELOG exists
+    const changelogPaths = [
+      join(projectDir, 'CHANGELOG.md'),
+      join(projectDir, 'docs', 'CHANGELOG.md'),
+      join(projectDir, 'changelog.md'),
+      join(projectDir, 'CHANGES.md'),
+    ];
+    for (const clPath of changelogPaths) {
+      if (existsSync(clPath)) {
+        evidence.changelogUpdated = true;
+        break;
+      }
+    }
+
+    // Check release notes
+    const releaseNotePaths = [
+      join(projectDir, 'RELEASE.md'),
+      join(projectDir, 'chati.dev', 'artifacts', 'release-notes.md'),
+    ];
+    for (const rnPath of releaseNotePaths) {
+      if (existsSync(rnPath)) {
+        evidence.releaseNotesPrepared = true;
+        break;
+      }
+    }
+
+    // Load session state
+    const sessionResult = loadSession(projectDir);
+    if (sessionResult.loaded && sessionResult.session) {
+      const agents = sessionResult.session.agents || {};
+      const completedAgents = sessionResult.session.completed_agents || [];
+
+      // Check all required agents are completed
+      const requiredAgents = Object.keys(agents).filter(
+        a => agents[a].status !== 'skipped'
+      );
+      const allComplete = requiredAgents.every(
+        a => completedAgents.includes(a) || agents[a].status === 'completed'
+      );
+
+      evidence.allTasksCompleted = allComplete;
+
+      // Check for open blockers in any handoff
+      for (const agentName of completedAgents) {
+        const agentHandoff = loadHandoff(projectDir, agentName);
+        if (agentHandoff.loaded && agentHandoff.handoff) {
+          const blockers = agentHandoff.handoff.blockers || [];
+          if (blockers.length > 0) {
+            evidence.noOpenBlockers = false;
+            break;
+          }
+        }
+      }
+
+      evidence.sessionState = {
+        mode: sessionResult.session.mode,
+        completedCount: completedAgents.length,
+        totalAgents: Object.keys(agents).length,
+      };
+    }
+
+    return evidence;
+  }
+
+  /**
+   * Validate deployment readiness evidence.
+   *
+   * @param {object} evidence
+   * @returns {{ score: number, criteriaResults: string[], allCriteria: string[], warnings: string[] }}
+   */
+  _validateEvidence(evidence) {
+    const allCriteria = [
+      'QA-Implementation passed',
+      'README updated',
+      'CHANGELOG updated',
+      'Release notes prepared',
+      'All tasks completed',
+      'No open blockers',
+    ];
+
+    const criteriaResults = [];
+    const warnings = [];
+
+    if (evidence.qaImplPassed) {
+      criteriaResults.push('QA-Implementation passed');
+    } else {
+      warnings.push('QA-Implementation has not passed');
+    }
+
+    if (evidence.readmeUpdated) {
+      criteriaResults.push('README updated');
+    }
+
+    if (evidence.changelogUpdated) {
+      criteriaResults.push('CHANGELOG updated');
+    }
+
+    if (evidence.releaseNotesPrepared) {
+      criteriaResults.push('Release notes prepared');
+    }
+
+    if (evidence.allTasksCompleted) {
+      criteriaResults.push('All tasks completed');
+    } else {
+      warnings.push('Not all tasks are completed');
+    }
+
+    if (evidence.noOpenBlockers) {
+      criteriaResults.push('No open blockers');
+    } else {
+      warnings.push('Open blockers remain from agent handoffs');
+    }
+
+    const score = allCriteria.length > 0
+      ? Math.round((criteriaResults.length / allCriteria.length) * 100)
+      : 0;
+
+    return { score, criteriaResults, allCriteria, warnings };
+  }
+}

package/src/gates/gate-base.js

@@ -0,0 +1,144 @@
+/**
+ * @fileoverview GateBase — Template Method pattern base class for quality gates.
+ *
+ * Provides the abstract skeleton for all pipeline quality gates.
+ * Subclasses implement _collectEvidence() and _validateEvidence()
+ * while this base class handles evaluation orchestration.
+ */
+
+import { evaluateGate, getGateThreshold, resolveGateAction } from '../autonomy/autonomous-gate.js';
+
+/**
+ * Abstract base class for quality gates.
+ *
+ * Uses the Template Method pattern: evaluate() is the template that
+ * calls _collectEvidence() and _validateEvidence() which subclasses implement.
+ */
+export class GateBase {
+  /**
+   * @param {object} config
+   * @param {string} config.id - Unique gate identifier (e.g. 'g1-planning-complete')
+   * @param {string} config.name - Human-readable gate name
+   * @param {string} config.pipelinePoint - Pipeline point this gate guards
+   * @param {string} config.agent - Agent whose output this gate evaluates
+   */
+  constructor(config) {
+    if (new.target === GateBase) {
+      throw new Error('GateBase is abstract and cannot be instantiated directly.');
+    }
+
+    const { id, name, pipelinePoint, agent } = config;
+
+    if (!id || !name || !pipelinePoint || !agent) {
+      throw new Error('GateBase requires id, name, pipelinePoint, and agent in config.');
+    }
+
+    this.id = id;
+    this.name = name;
+    this.pipelinePoint = pipelinePoint;
+    this.agent = agent;
+  }
+
+  /**
+   * Evaluate the quality gate.
+   *
+   * Template Method: collects evidence, validates it, then either runs
+   * autonomous evaluation or returns recommendation for human review.
+   *
+   * @param {string} projectDir - Project root directory
+   * @param {string} [mode='autonomous'] - 'autonomous' or 'human-in-the-loop'
+   * @returns {object} GateResult: { result, score, evidence, recommendation, canProceed }
+   */
+  evaluate(projectDir, mode = 'autonomous') {
+    // Step 1: Collect evidence (subclass implements)
+    const evidence = this._collectEvidence(projectDir);
+
+    // Step 2: Validate evidence (subclass implements)
+    const validation = this._validateEvidence(evidence);
+
+    const { score, criteriaResults, allCriteria, warnings = [] } = validation;
+
+    if (mode === 'autonomous') {
+      // Step 3a: Autonomous evaluation via autonomous-gate module
+      const gateResult = evaluateGate({
+        agent: this.agent,
+        score,
+        criteriaResults,
+        allCriteria,
+        warnings,
+      });
+
+      const action = resolveGateAction(gateResult.result, mode);
+
+      return {
+        gateId: this.id,
+        gateName: this.name,
+        result: gateResult.result,
+        score: gateResult.score,
+        evidence,
+        recommendation: action.action,
+        canProceed: gateResult.canProceed,
+        details: gateResult.details,
+        warnings,
+      };
+    }
+
+    // Step 3b: Human-in-the-loop — return evidence + recommendation
+    const threshold = getGateThreshold(this.agent);
+    const recommendation = score >= threshold
+      ? 'Recommend approval — criteria met.'
+      : `Recommend review — score ${score} below threshold ${threshold}.`;
+
+    return {
+      gateId: this.id,
+      gateName: this.name,
+      result: 'review',
+      score,
+      evidence,
+      recommendation,
+      canProceed: false, // Human must explicitly approve
+      details: {
+        criteriaResults,
+        allCriteria,
+        threshold,
+      },
+      warnings,
+    };
+  }
+
+  /**
+   * Collect evidence from the project filesystem.
+   * ABSTRACT — subclass MUST implement.
+   *
+   * @param {string} _projectDir
+   * @returns {object} Evidence data
+   */
+  _collectEvidence(_projectDir) {
+    throw new Error(`${this.constructor.name} must implement _collectEvidence()`);
+  }
+
+  /**
+   * Validate collected evidence and produce a score.
+   * ABSTRACT — subclass MUST implement.
+   *
+   * @param {object} _evidence
+   * @returns {{ score: number, criteriaResults: string[], allCriteria: string[], warnings: string[] }}
+   */
+  _validateEvidence(_evidence) {
+    throw new Error(`${this.constructor.name} must implement _validateEvidence()`);
+  }
+
+  /**
+   * Get gate metadata.
+   *
+   * @returns {{ id: string, name: string, pipelinePoint: string, threshold: number }}
+   */
+  getInfo() {
+    return {
+      id: this.id,
+      name: this.name,
+      pipelinePoint: this.pipelinePoint,
+      threshold: getGateThreshold(this.agent),
+    };
+  }
+}

package/src/gates/index.js

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Quality Gates barrel exports and registry.
+ *
+ * Provides all gate classes and a registry function to look up
+ * the appropriate gate for a given pipeline point.
+ */
+
+export { GateBase } from './gate-base.js';
+export { CircuitBreaker, CIRCUIT_STATES } from './circuit-breaker.js';
+export { PlanningCompleteGate } from './g1-planning-complete.js';
+export { QAPlanningGate } from './g2-qa-planning.js';
+export { ImplementationGate } from './g3-implementation.js';
+export { QAImplementationGate, QA_IMPL_VERDICTS } from './g4-qa-implementation.js';
+export { DeployReadyGate } from './g5-deploy-ready.js';
+
+import { PlanningCompleteGate as _G1 } from './g1-planning-complete.js';
+import { QAPlanningGate as _G2 } from './g2-qa-planning.js';
+import { ImplementationGate as _G3 } from './g3-implementation.js';
+import { QAImplementationGate as _G4 } from './g4-qa-implementation.js';
+import { DeployReadyGate as _G5 } from './g5-deploy-ready.js';
+
+/**
+ * Pipeline point to gate class mapping.
+ */
+const PIPELINE_POINT_MAP = {
+  'pre-build': _G1,
+  'post-qa-planning': _G2,
+  'post-dev': _G3,
+  'post-qa-impl': _G4,
+  'pre-deploy': _G5,
+};
+
+/**
+ * Get the gate instance for a specific pipeline point.
+ *
+ * @param {string} point - Pipeline point identifier
+ * @returns {import('./gate-base.js').GateBase} Gate instance
+ * @throws {Error} If no gate is registered for the given point
+ */
+export function getGateForPipelinePoint(point) {
+  const GateClass = PIPELINE_POINT_MAP[point];
+  if (!GateClass) {
+    throw new Error(`No gate registered for pipeline point: ${point}`);
+  }
+  return new GateClass();
+}

package/src/installer/brownfield-upgrader.js

@@ -0,0 +1,249 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, readdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { hashFile } from './file-hasher.js';
+import { loadManifest, generateManifest, compareManifests, saveManifest } from './manifest.js';
+import { mergeFile } from '../merger/index.js';
+
+/**
+ * Categorize changes between current and new manifests.
+ *
+ * @param {object} currentManifest - The currently installed manifest
+ * @param {object} newManifest - The new framework version manifest
+ * @returns {{ added: string[], removed: string[], modified: string[], unchanged: string[] }}
+ */
+export function categorizeChanges(currentManifest, newManifest) {
+  return compareManifests(currentManifest, newManifest);
+}
+
+/**
+ * Detect files the user has modified since installation.
+ * Compares the current on-disk hash of each file against the hash
+ * recorded in the manifest at install time.
+ *
+ * @param {string} targetDir - Project root directory
+ * @param {object} manifest - The installed manifest
+ * @returns {{ path: string, recordedHash: string, currentHash: string }[]}
+ */
+export function detectUserModifications(targetDir, manifest) {
+  const modified = [];
+  const files = manifest.files || {};
+
+  for (const [relPath, entry] of Object.entries(files)) {
+    const absPath = join(targetDir, relPath);
+    if (!existsSync(absPath)) continue;
+
+    const currentHash = hashFile(absPath);
+    if (currentHash !== entry.hash) {
+      modified.push({
+        path: relPath,
+        recordedHash: entry.hash,
+        currentHash,
+      });
+    }
+  }
+
+  return modified;
+}
+
+/**
+ * Plan an upgrade without making any changes (dry run).
+ * Shows what would happen if upgradeInstallation were called.
+ *
+ * @param {string} targetDir - Project root where framework is installed
+ * @param {string} newFrameworkDir - Directory containing the new framework version
+ * @param {string} [newVersion='0.0.0'] - New version string
+ * @returns {{ upgraded: string[], skipped: string[], added: string[], removed: string[], preserved: string[], errors: Array<{ path: string, error: string }> }}
+ */
+export function planUpgrade(targetDir, newFrameworkDir, newVersion = '0.0.0') {
+  const result = {
+    upgraded: [],
+    skipped: [],
+    added: [],
+    removed: [],
+    preserved: [],
+    errors: [],
+  };
+
+  // Load current manifest
+  const currentManifest = loadManifest(targetDir);
+  if (!currentManifest) {
+    result.errors.push({
+      path: '.chati/manifest.json',
+      error: 'No existing manifest found. Cannot plan upgrade without a manifest.',
+    });
+    return result;
+  }
+
+  // Build new manifest from the new framework directory
+  const newManifest = generateManifest(
+    newFrameworkDir,
+    collectRelativePaths(newFrameworkDir),
+    newVersion
+  );
+
+  // Categorize
+  const changes = categorizeChanges(currentManifest, newManifest);
+
+  // Detect user modifications
+  const userMods = detectUserModifications(targetDir, currentManifest);
+  const userModPaths = new Set(userMods.map((m) => m.path));
+
+  // Added files => will be added
+  result.added = [...changes.added];
+
+  // Removed files => will be flagged for removal
+  result.removed = [...changes.removed];
+
+  // Modified files => check if user also modified them
+  for (const filePath of changes.modified) {
+    if (userModPaths.has(filePath)) {
+      // User modified this file => skip (preserve user changes)
+      result.preserved.push(filePath);
+      result.skipped.push(filePath);
+    } else {
+      // User did NOT modify => safe to upgrade
+      result.upgraded.push(filePath);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Execute an upgrade: update files from the new framework version
+ * while preserving user-modified files.
+ *
+ * @param {string} targetDir - Project root where framework is installed
+ * @param {string} newFrameworkDir - Directory containing the new framework version
+ * @param {string} [newVersion='0.0.0'] - New version string
+ * @returns {{ upgraded: string[], skipped: string[], added: string[], removed: string[], preserved: string[], errors: Array<{ path: string, error: string }> }}
+ */
+export function upgradeInstallation(targetDir, newFrameworkDir, newVersion = '0.0.0') {
+  const result = {
+    upgraded: [],
+    skipped: [],
+    added: [],
+    removed: [],
+    preserved: [],
+    errors: [],
+  };
+
+  // Load current manifest
+  const currentManifest = loadManifest(targetDir);
+  if (!currentManifest) {
+    result.errors.push({
+      path: '.chati/manifest.json',
+      error: 'No existing manifest found. Cannot upgrade without a manifest.',
+    });
+    return result;
+  }
+
+  // Build new manifest
+  const newManifest = generateManifest(
+    newFrameworkDir,
+    collectRelativePaths(newFrameworkDir),
+    newVersion
+  );
+
+  // Categorize
+  const changes = categorizeChanges(currentManifest, newManifest);
+
+  // Detect user modifications
+  const userMods = detectUserModifications(targetDir, currentManifest);
+  const userModPaths = new Set(userMods.map((m) => m.path));
+
+  // Process ADDED files
+  for (const filePath of changes.added) {
+    try {
+      const srcPath = join(newFrameworkDir, filePath);
+      const destPath = join(targetDir, filePath);
+      const destDir = dirname(destPath);
+
+      if (!existsSync(destDir)) {
+        mkdirSync(destDir, { recursive: true });
+      }
+      copyFileSync(srcPath, destPath);
+      result.added.push(filePath);
+    } catch (err) {
+      result.errors.push({ path: filePath, error: err.message });
+    }
+  }
+
+  // Process MODIFIED files
+  for (const filePath of changes.modified) {
+    if (userModPaths.has(filePath)) {
+      // User modified => try smart merge, otherwise preserve
+      try {
+        const existingContent = readFileSync(join(targetDir, filePath), 'utf-8');
+        const newContent = readFileSync(join(newFrameworkDir, filePath), 'utf-8');
+        const merged = mergeFile(filePath, existingContent, newContent);
+
+        // Only write if merge produced a different result from existing
+        if (merged !== existingContent) {
+          writeFileSync(join(targetDir, filePath), merged, 'utf-8');
+          result.upgraded.push(filePath);
+        } else {
+          result.preserved.push(filePath);
+          result.skipped.push(filePath);
+        }
+      } catch {
+        // Merge failed => preserve user's version
+        result.preserved.push(filePath);
+        result.skipped.push(filePath);
+      }
+    } else {
+      // User did NOT modify => safe to replace
+      try {
+        const srcPath = join(newFrameworkDir, filePath);
+        const destPath = join(targetDir, filePath);
+        copyFileSync(srcPath, destPath);
+        result.upgraded.push(filePath);
+      } catch (err) {
+        result.errors.push({ path: filePath, error: err.message });
+      }
+    }
+  }
+
+  // Process REMOVED files (mark but do not delete for safety)
+  result.removed = [...changes.removed];
+
+  // Save updated manifest
+  try {
+    saveManifest(targetDir, newManifest);
+  } catch (err) {
+    result.errors.push({ path: '.chati/manifest.json', error: err.message });
+  }
+
+  return result;
+}
+
+/**
+ * Collect all relative file paths under a directory recursively.
+ * Skips hidden directories (starting with '.').
+ *
+ * @param {string} rootDir - Directory to scan
+ * @param {string} [base=''] - Base path for recursion (internal)
+ * @returns {string[]} Array of relative file paths
+ */
+function collectRelativePaths(rootDir, base = '') {
+  const paths = [];
+
+  let entries;
+  try {
+    entries = readdirSync(join(rootDir, base), { withFileTypes: true });
+  } catch {
+    return paths;
+  }
+
+  for (const entry of entries) {
+    const relPath = base ? `${base}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      if (entry.name.startsWith('.')) continue;
+      paths.push(...collectRelativePaths(rootDir, relPath));
+    } else if (entry.isFile()) {
+      paths.push(relPath);
+    }
+  }
+
+  return paths;
+}