contextos-agents 2.0.0 → 2.1.0

package/bin/lib/gate.js

@@ -0,0 +1,171 @@
+/**
+ * bin/lib/gate.js
+ * ContextOS - Quality Gate Verification Engine
+ *
+ * Implements deterministic verification paths without executing untrusted
+ * user project scripts. Operates in-process using trusted package modules.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { detectDrift } = require('../../.agents/adapters/drift-detector.js');
+const pureCompiler = require('../../.agents/adapters/pure-compiler.js');
+
+/**
+ * Runs the quality gate against a target project root.
+ *
+ * @param {string} [projectRoot=process.cwd()] - Target project directory
+ * @param {object} [options]
+ * @param {string|string[]} [options.target='all'] - Adapters to verify
+ * @param {string} [options.profile=null] - Profile name or override
+ * @param {boolean} [options.json=false] - Format as machine-readable JSON
+ * @returns {{ ok: boolean, code: number, status: string, drift: object, message: string }}
+ */
+function runGate(projectRoot = process.cwd(), options = {}) {
+  const absRoot = path.resolve(projectRoot);
+  const target = options.target || 'all';
+  const profile = options.profile || null;
+
+  // 1. Run Drift Detection via trusted in-package drift-detector
+  const drift = detectDrift(absRoot, target, { profile });
+
+  let status = 'pass';
+  let code = 0;
+  let message = 'All adapter outputs are synchronized with source skills.';
+
+  if (drift.hasError) {
+    status = 'error';
+    code = drift.code || 2;
+    message = drift.error || 'Configuration or execution error occurred during verification.';
+  } else if (drift.hasDrift) {
+    status = 'drift';
+    code = drift.code || 1;
+    message = `Adapter drift detected across ${drift.totalFindings} finding(s).`;
+  }
+
+  const result = {
+    schemaVersion: '2.0.0',
+    status,
+    code,
+    ok: code === 0,
+    projectRoot: absRoot,
+    target,
+    profile,
+    message,
+    drift,
+  };
+
+  return result;
+}
+
+/**
+ * Emits GitHub Actions workflow annotations for drift or errors.
+ *
+ * @param {object} result - Gate result
+ */
+function emitGitHubAnnotations(result) {
+  if (!result || !result.drift) return;
+
+  const escapeActionData = (str) =>
+    String(str)
+      .replace(/%/g, '%25')
+      .replace(/\r/g, '%0D')
+      .replace(/\n/g, '%0A');
+
+  const normalizePath = (p) => (p ? String(p).replace(/\\/g, '/') : '');
+
+  const { findings, collisions } = result.drift;
+
+  if (findings) {
+    for (const item of findings.MISSING_OUTPUT || []) {
+      console.error(`::error file=${normalizePath(item.path)}::[MISSING_OUTPUT] ${escapeActionData(item.reason || 'Missing projected output file')}`);
+    }
+    for (const item of findings.MODIFIED_MANAGED_OUTPUT || []) {
+      console.error(`::error file=${normalizePath(item.path)}::[MODIFIED_OUTPUT] ${escapeActionData(item.reason || 'Managed output modified on disk')}`);
+    }
+    for (const item of findings.ORPHAN_MANAGED_OUTPUT || []) {
+      console.error(`::warning file=${normalizePath(item.path)}::[ORPHAN_OUTPUT] ${escapeActionData(item.reason || 'Orphan file recorded in lockfile')}`);
+    }
+    for (const item of findings.CORRUPT_LOCKFILE || []) {
+      console.error(`::error::[CORRUPT_LOCKFILE] ${escapeActionData(item.reason || 'Lockfile is corrupt')}`);
+    }
+    for (const item of findings.CONFIG_ERROR || []) {
+      console.error(`::error::[CONFIG_ERROR] ${escapeActionData(item.reason || 'Configuration error')}`);
+    }
+    for (const item of findings.EMPTY_PROJECTION || []) {
+      console.error(`::error::[EMPTY_PROJECTION] ${escapeActionData(item.reason || 'Projected artifact set is empty')}`);
+    }
+  }
+
+  for (const c of collisions || []) {
+    console.error(`::error file=${normalizePath(c.path)}::[PATH_COLLISION] Collision between adapter ${c.firstAdapter} and ${c.secondAdapter}`);
+  }
+}
+
+/**
+ * Formats a markdown summary for GitHub Step Summary.
+ *
+ * @param {object} result - Gate result
+ * @returns {string} Markdown summary
+ */
+function formatGitHubSummary(result) {
+  const icon = result.ok ? '✅' : (result.status === 'drift' ? '⚠️' : '❌');
+  const lines = [
+    `# ${icon} ContextOS Quality Gate Report`,
+    '',
+    `**Status**: \`${result.status.toUpperCase()}\` (exit code: \`${result.code}\`)  `,
+    `**Project Root**: \`${result.projectRoot}\`  `,
+    `**Target Adapters**: \`${Array.isArray(result.target) ? result.target.join(', ') : result.target}\`  `,
+    `**Active Profile**: \`${result.profile || 'default'}\`  `,
+    `**Projected Artifacts**: \`${result.drift?.projectedCount || 0}\`  `,
+    '',
+    `### Overview`,
+    result.message,
+    '',
+  ];
+
+  if (result.drift && result.drift.totalFindings > 0) {
+    lines.push(`### Findings (${result.drift.totalFindings})`);
+    lines.push('| State | Path | Detail |');
+    lines.push('| --- | --- | --- |');
+
+    for (const [state, items] of Object.entries(result.drift.findings)) {
+      for (const item of items) {
+        const itemPath = item.path ? `\`${item.path}\`` : '*(project)*';
+        const detail = (item.reason || item.diff || '').replace(/\|/g, '\\|');
+        lines.push(`| **${state}** | ${itemPath} | ${detail} |`);
+      }
+    }
+    lines.push('');
+    lines.push('> **Remediation**: Run `npx contextos-agents export all` and commit synchronized adapter artifacts.');
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Writes the markdown summary to GITHUB_STEP_SUMMARY if available.
+ *
+ * @param {object} result - Gate result
+ */
+function writeGitHubSummary(result) {
+  const summaryFile = process.env.GITHUB_STEP_SUMMARY;
+  if (!summaryFile) return;
+
+  try {
+    const summaryMd = formatGitHubSummary(result);
+    fs.appendFileSync(summaryFile, summaryMd + '\n', 'utf8');
+  } catch {
+    // Best-effort write to step summary
+  }
+}
+
+module.exports = {
+  runGate,
+  emitGitHubAnnotations,
+  formatGitHubSummary,
+  writeGitHubSummary,
+};

package/bin/lib/git-snapshot.js

@@ -0,0 +1,187 @@
+/**
+ * bin/lib/git-snapshot.js
+ * ContextOS Git Index Snapshot & Staged Blob Reader
+ *
+ * Inspects staged changes directly from the Git index without modifying
+ * the working directory. Safely handles NUL-delimited filenames, Unicode,
+ * binary files, and path spaces.
+ */
+
+'use strict';
+
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+/**
+ * Finds the top-level repository root via Git.
+ *
+ * @param {string} [cwd=process.cwd()] - Working directory
+ * @returns {string|null} Absolute repository root or null if not a Git repository
+ */
+function findGitRoot(cwd = process.cwd()) {
+  try {
+    const root = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return path.resolve(root.trim());
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Discovers the git hooks directory, respecting core.hooksPath if set.
+ *
+ * @param {string} [cwd=process.cwd()] - Working directory
+ * @returns {string|null} Absolute path to hooks directory or null
+ */
+function findHooksDir(cwd = process.cwd()) {
+  try {
+    const gitDir = execFileSync('git', ['rev-parse', '--git-path', 'hooks'], {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    return path.resolve(cwd, gitDir);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Retrieves the list of staged files from the Git index.
+ * Uses NUL-delimited output (-z) to support spaces, Unicode, and escapes.
+ *
+ * @param {string} [cwd=process.cwd()] - Working directory
+ * @returns {Array<{ status: string, path: string, oldPath?: string }>} Staged entries
+ */
+function getStagedFiles(cwd = process.cwd()) {
+  try {
+    const output = execFileSync(
+      'git',
+      ['diff', '--cached', '-z', '--name-status'],
+      { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+    );
+
+    if (!output) return [];
+
+    const parts = output.split('\0');
+    const entries = [];
+
+    let i = 0;
+    while (i < parts.length) {
+      const statusRaw = parts[i];
+      if (!statusRaw) {
+        i++;
+        continue;
+      }
+
+      const status = statusRaw[0];
+      if (status === 'R' || status === 'C') {
+        // Rename or copy includes old path followed by new path
+        const oldPath = parts[i + 1];
+        const newPath = parts[i + 2];
+        if (newPath) {
+          entries.push({ status, path: newPath, oldPath });
+        }
+        i += 3;
+      } else {
+        const filePath = parts[i + 1];
+        if (filePath) {
+          entries.push({ status, path: filePath });
+        }
+        i += 2;
+      }
+    }
+
+    return entries;
+  } catch (err) {
+    throw new Error(`Failed to query staged files from Git: ${err.message}`);
+  }
+}
+
+/**
+ * Reads the content of a file directly from the Git staged index.
+ *
+ * @param {string} relativePath - Path relative to repo root
+ * @param {string} [cwd=process.cwd()] - Working directory
+ * @returns {Buffer|null} Staged file buffer or null if deleted/missing
+ */
+function getStagedBlob(relativePath, cwd = process.cwd()) {
+  try {
+    const posixPath = relativePath.replace(/\\/g, '/');
+    const buf = execFileSync('git', ['show', `:${posixPath}`], {
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      maxBuffer: 10 * 1024 * 1024,
+    });
+    return buf;
+  } catch (err) {
+    // If file was deleted or unreadable in index, return null
+    return null;
+  }
+}
+
+/**
+ * Extracts added lines from git diff --cached -U0 for each staged file.
+ * Returns only lines that were added (+), excluding diff headers and deleted lines (-).
+ *
+ * @param {string} [cwd=process.cwd()] - Working directory
+ * @returns {Map<string, Array<{ line: number, content: string }>>} Added lines by file
+ */
+function getStagedAddedLines(cwd = process.cwd()) {
+  const addedLinesByFile = new Map();
+
+  try {
+    const diffOutput = execFileSync('git', ['diff', '--cached', '-U0'], {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      maxBuffer: 10 * 1024 * 1024,
+    });
+
+    if (!diffOutput) return addedLinesByFile;
+
+    const lines = diffOutput.split(/\r?\n/);
+    let currentFile = null;
+    let currentLineNum = 0;
+
+    for (const line of lines) {
+      if (line.startsWith('+++ b/')) {
+        currentFile = line.slice(6).trim();
+        if (!addedLinesByFile.has(currentFile)) {
+          addedLinesByFile.set(currentFile, []);
+        }
+      } else if (line.startsWith('@@ ')) {
+        // Parse @@ -a,b +c,d @@ to get current target line number
+        const match = line.match(/\+([0-9]+)(?:,([0-9]+))?/);
+        if (match) {
+          currentLineNum = parseInt(match[1], 10);
+        }
+      } else if (line.startsWith('+') && !line.startsWith('+++')) {
+        if (currentFile) {
+          const content = line.slice(1);
+          addedLinesByFile.get(currentFile).push({
+            line: currentLineNum,
+            content,
+          });
+        }
+        currentLineNum++;
+      }
+    }
+
+    return addedLinesByFile;
+  } catch {
+    return addedLinesByFile;
+  }
+}
+
+module.exports = {
+  findGitRoot,
+  findHooksDir,
+  getStagedFiles,
+  getStagedBlob,
+  getStagedAddedLines,
+};