contextos-agents 2.0.0 → 2.1.1

package/bin/index.js

@@ -32,6 +32,15 @@ const flags = {
     const i = args.indexOf('--add-skill');
     return i !== -1 ? args[i + 1] : null;
   })(),
+  project:     (() => {
+    const i = args.indexOf('--project');
+    return i !== -1 && args[i + 1] && !args[i + 1].startsWith('-') ? path.resolve(args[i + 1]) : process.cwd();
+  })(),
+  target:      (() => {
+    const i = args.indexOf('--target');
+    return i !== -1 && args[i + 1] && !args[i + 1].startsWith('-') ? args[i + 1] : null;
+  })(),
+  githubAnnotations: args.includes('--github-annotations'),
 };
 
 // ── Help / Version ────────────────────────────────────────────────────────────
@@ -64,12 +73,16 @@ Options:
   --minimal           Install only 7 core skills (lightweight footprint)
   --profile <name>    Install a specific profile (mvp, startup, enterprise, frontend, backend)
   --auto              Auto-detect tech stack and apply recommended profile
+  --project <path>    Specify target project root directory (default: current directory)
+  --target <adapters> Target adapter(s) to verify or export (default: all)
+  --github-annotations Emit GitHub Actions workflow commands and step summary
   --with-mcp, --mcp   [DEPRECATED] Use the separate @contextos/mcp package instead
   --skip-compile      Skip running ctx.js export after installation
   --add-skill <ref>   Install a community plugin skill after setup
 
 Commands:
   init                Install and configure .agents/ in target project
+  gate                Run deterministic quality gate against adapter drift
   status              Display project configuration, active profile, and lockfile status
   update              Safely update skills without overwriting custom changes
   uninstall           Safely uninstall ContextOS files (preserves user custom skills)
@@ -84,6 +97,10 @@ Commands:
   watch               Start continuous file watcher and auto-sync daemon
   detect              Analyze project and display detected tech stack & IDE
   install-skill       Interactive skill installer (or pass <ref> / --from-repo)
+  scan                Scan Git staged changes for secrets, placeholders, and scope
+  hook <cmd>          Manage isolated pre-commit Git governance hooks (install, uninstall)
+  recover             List or recover from interrupted filesystem transactions
+  explain [rule]      Inspect rule catalog, enforcement levels, and checkers
   setup-mcp           [DEPRECATED] Add MCP execution server to an existing .agents/ project
 
 Profiles:
@@ -250,20 +267,141 @@ if (mainCommand === 'recover') {
   process.exit(0);
 }
 
-// Proxy commands to .agents/ctx.js when executed in a ContextOS project
+// Gate command (deterministic quality gate verification)
+if (mainCommand === 'gate') {
+  const { runGate, emitGitHubAnnotations, writeGitHubSummary } = require('./lib/gate.js');
+  let target = flags.target || (args[1] && !args[1].startsWith('-') ? args[1] : 'all');
+  if (typeof target === 'string' && target.includes(',')) {
+    target = target.split(',').map(s => s.trim()).filter(Boolean);
+  }
+  const result = runGate(flags.project, {
+    target,
+    profile: flags.profile,
+    json: flags.json,
+  });
+
+  if (process.env.GITHUB_ACTIONS === 'true' || flags.githubAnnotations) {
+    emitGitHubAnnotations(result);
+    writeGitHubSummary(result);
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`\nContextOS Quality Gate (${result.schemaVersion})\n`);
+    console.log(`  Project: ${result.projectRoot}`);
+    console.log(`  Status : ${result.status.toUpperCase()} (code ${result.code})`);
+    console.log(`  Message: ${result.message}\n`);
+    if (result.drift && result.drift.hasDrift) {
+      console.log(`! Drift detected (${result.drift.totalFindings} findings):`);
+      for (const [state, items] of Object.entries(result.drift.findings)) {
+        if (items.length > 0) {
+          console.log(`  [${state}] (${items.length}):`);
+          for (const item of items) {
+            console.log(`    • ${item.path || item.reason || JSON.stringify(item)}`);
+          }
+        }
+      }
+      if (result.drift.collisions && result.drift.collisions.length > 0) {
+        console.log(`\n  [PATH_COLLISIONS] (${result.drift.collisions.length}):`);
+        for (const c of result.drift.collisions) {
+          console.log(`    • ${c.path} (between ${c.firstAdapter} and ${c.secondAdapter})`);
+        }
+      }
+    }
+  }
+  process.exit(result.code);
+}
+
+// Export check mode (in-process verification without spawning untrusted project scripts)
+if (mainCommand === 'export' && args.includes('--check')) {
+  const { detectDrift } = require('../.agents/adapters/drift-detector.js');
+  const rawTarget = flags.target || (args[1] && !args[1].startsWith('-') ? args[1] : 'all');
+  const drift = detectDrift(flags.project, rawTarget, { profile: flags.profile });
+
+  if (process.env.GITHUB_ACTIONS === 'true' || flags.githubAnnotations) {
+    const { emitGitHubAnnotations, writeGitHubSummary } = require('./lib/gate.js');
+    const gateFormat = {
+      ok: !drift.hasDrift && !drift.hasError,
+      code: drift.code !== undefined ? drift.code : (drift.hasDrift ? 1 : 0),
+      status: drift.status || (drift.hasError ? 'error' : (drift.hasDrift ? 'drift' : 'pass')),
+      projectRoot: flags.project,
+      target: rawTarget,
+      profile: flags.profile || 'default',
+      drift,
+      message: drift.hasDrift ? 'Adapter drift detected' : 'Artifacts synchronized',
+    };
+    emitGitHubAnnotations(gateFormat);
+    writeGitHubSummary(gateFormat);
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify(drift, null, 2));
+  } else {
+    console.log('\nContextOS - Adapter Output Drift Check\n');
+    console.log(`  Project: ${flags.project}`);
+    if (!drift.hasDrift && !drift.hasError) {
+      console.log(`✓ No adapter drift detected. All ${drift.projectedCount} output artifacts are synchronized.`);
+    } else {
+      console.log(`! Drift detected (${drift.totalFindings} finding(s)):\n`);
+      for (const [state, items] of Object.entries(drift.findings)) {
+        if (items.length > 0) {
+          console.log(`  [${state}] (${items.length}):`);
+          for (const item of items) {
+            console.log(`    • ${item.path || item.reason || JSON.stringify(item)}`);
+          }
+        }
+      }
+      if (drift.collisions && drift.collisions.length > 0) {
+        console.log(`\n  [PATH_COLLISIONS] (${drift.collisions.length}):`);
+        for (const c of drift.collisions) {
+          console.log(`    • ${c.path} (between ${c.firstAdapter} and ${c.secondAdapter})`);
+        }
+      }
+      console.log('\nRun: contextos export all    to synchronize outputs with source skills.\n');
+    }
+  }
+  process.exit(drift.code !== undefined ? drift.code : (drift.hasDrift ? 1 : 0));
+}
+
+// Scan command (Git staged index security and placeholder scanner)
+if (mainCommand === 'scan') {
+  const scanModule = require('./commands/scan.js');
+  scanModule(args, flags);
+  process.exit(0);
+}
+
+// Hook command (safe Git hook lifecycle management)
+if (mainCommand === 'hook') {
+  const { hookCommand } = require('./commands/hook.js');
+  hookCommand(args, flags);
+  process.exit(0);
+}
+
+// Proxy commands to trusted package .agents/ctx.js targeting flags.project
 const PROXY_COMMANDS = [
-  'profile', 'export', 'validate', 'resolve', 'skill', 'index',
+  'profile', 'export', 'validate', 'audit', 'resolve', 'skill', 'index',
   'clean-worktrees', 'stats', 'watch', 'compile', 'explain',
   'thread'
 ];
 
-const ctxPath = path.join(process.cwd(), '.agents', 'ctx.js');
-const hasLocalCtx = fs.existsSync(ctxPath);
+const packageCtxPath = path.join(__dirname, '..', '.agents', 'ctx.js');
 
-if (mainCommand && PROXY_COMMANDS.includes(mainCommand) && hasLocalCtx) {
+if (mainCommand && PROXY_COMMANDS.includes(mainCommand)) {
   const { execFileSync } = require('child_process');
+  const filteredArgs = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--project') {
+      i++; // skip project path
+      continue;
+    }
+    filteredArgs.push(args[i]);
+  }
   try {
-    execFileSync(process.execPath, [ctxPath, ...args], { stdio: 'inherit' });
+    execFileSync(process.execPath, [packageCtxPath, ...filteredArgs], {
+      cwd: flags.project,
+      stdio: 'inherit',
+    });
   } catch (e) {
     process.exit(e.status || 1);
   }
@@ -300,34 +438,7 @@ if (mainCommand === 'watch') {
   watchModule.runWatch(process.cwd());
 }
 
-const PROJECT_ONLY_COMMANDS = ['profile', 'export', 'validate', 'resolve', 'skill', 'index', 'clean-worktrees', 'compile', 'explain'];
-if (mainCommand && PROJECT_ONLY_COMMANDS.includes(mainCommand) && !hasLocalCtx) {
-  console.error('[ERROR] .agents/ctx.js not found in current directory.');
-  console.error('        Are you in a ContextOS project? Run `contextos` or `npx contextos-agents` first.');
-  process.exit(1);
-}
-
-if (mainCommand === 'audit') {
-  if (!hasLocalCtx) {
-    console.error('[ERROR] .agents/ctx.js not found. Are you in a ContextOS project?');
-    process.exit(1);
-  }
-  const { execFileSync } = require('child_process');
-  try {
-    execFileSync(process.execPath, [ctxPath, 'validate'], { stdio: 'inherit' });
-  } catch (e) {
-    process.exit(1);
-  }
-  process.exit(0);
-}
-
 if (mainCommand === 'install-skill') {
-  const ctxPath = path.join(process.cwd(), '.agents', 'ctx.js');
-  if (!fs.existsSync(ctxPath)) {
-    console.error('[ERROR] .agents/ctx.js not found. Are you in a ContextOS project?');
-    process.exit(1);
-  }
-  
   const fromRepo = (() => {
     const i = args.indexOf('--from-repo');
     return i !== -1 ? args[i + 1] : null;
@@ -338,7 +449,10 @@ if (mainCommand === 'install-skill') {
   if (ref) {
     const { execFileSync } = require('child_process');
     try {
-      execFileSync(process.execPath, [ctxPath, 'skill', 'add', ref], { stdio: 'inherit' });
+      execFileSync(process.execPath, [packageCtxPath, 'skill', 'add', ref], {
+        cwd: flags.project,
+        stdio: 'inherit',
+      });
     } catch (e) {
       process.exit(1);
     }
@@ -434,6 +548,9 @@ if (mainCommand === 'install-skill') {
   console.error('             To use the MCP Bridge or execution runtime, install @contextos/mcp:');
   console.error('             npm install @contextos/mcp --save-dev');
   process.exit(1);
+} else if (mainCommand && mainCommand !== 'init') {
+  console.error(`[ERROR] Unknown command: '${mainCommand}'. Run 'contextos --help' for available commands.`);
+  process.exit(1);
 } else {
 
 // ── Paths ─────────────────────────────────────────────────────────────────────

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,214 @@
+/**
+ * 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',
+      ['-c', 'core.quotepath=false', 'diff', '--cached', '-z', '--name-status', '--no-ext-diff'],
+      { 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.
+ * Fails closed with an error if the staged blob cannot be read.
+ *
+ * @param {string} relativePath - Path relative to repo root
+ * @param {string} [cwd=process.cwd()] - Working directory
+ * @returns {Buffer} Staged file buffer
+ */
+function getStagedBlob(relativePath, cwd = process.cwd()) {
+  const posixPath = relativePath.replace(/\\/g, '/');
+  try {
+    const buf = execFileSync(
+      'git',
+      ['--literal-pathspecs', 'show', `:${posixPath}`],
+      {
+        cwd,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        maxBuffer: 10 * 1024 * 1024,
+      }
+    );
+    return buf;
+  } catch (err) {
+    const errMsg = err.stderr ? err.stderr.toString('utf8').trim() : err.message;
+    throw new Error(`Failed to read staged blob for "${posixPath}": ${errMsg}`);
+  }
+}
+
+/**
+ * Extracts added lines from git diff --cached -U0 for each staged file.
+ * Returns only lines that were added (+), excluding diff headers and deleted lines (-).
+ * Uses --literal-pathspecs, --no-ext-diff, and --no-textconv for strict path isolation.
+ *
+ * @param {string} [cwd=process.cwd()] - Working directory
+ * @param {string[]} [files=null] - Optional list of staged file paths. If omitted, discovered via getStagedFiles.
+ * @returns {Map<string, Array<{ line: number, content: string }>>} Added lines by file
+ */
+function getStagedAddedLines(cwd = process.cwd(), files = null) {
+  const addedLinesByFile = new Map();
+
+  let targetFiles = files;
+  if (!targetFiles) {
+    const staged = getStagedFiles(cwd);
+    targetFiles = staged.filter(e => e.status !== 'D').map(e => e.path);
+  }
+
+  for (const filePath of targetFiles) {
+    try {
+      const posixPath = filePath.replace(/\\/g, '/');
+      const diffOutput = execFileSync(
+        'git',
+        [
+          '--literal-pathspecs',
+          '-c', 'core.quotepath=false',
+          'diff',
+          '--cached',
+          '-U0',
+          '--no-ext-diff',
+          '--no-textconv',
+          '--',
+          posixPath,
+        ],
+        {
+          cwd,
+          encoding: 'utf8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+          maxBuffer: 10 * 1024 * 1024,
+        }
+      );
+
+      if (!diffOutput) continue;
+
+      const lines = diffOutput.split(/\r?\n/);
+      let currentLineNum = 0;
+      const fileAddedLines = [];
+
+      for (const line of lines) {
+        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('+++')) {
+          const content = line.slice(1);
+          fileAddedLines.push({
+            line: currentLineNum,
+            content,
+          });
+          currentLineNum++;
+        }
+      }
+
+      if (fileAddedLines.length > 0) {
+        addedLinesByFile.set(filePath, fileAddedLines);
+      }
+    } catch (err) {
+      throw new Error(`Failed to extract staged diff for "${filePath}": ${err.message}`);
+    }
+  }
+
+  return addedLinesByFile;
+}
+
+module.exports = {
+  findGitRoot,
+  findHooksDir,
+  getStagedFiles,
+  getStagedBlob,
+  getStagedAddedLines,
+};