contextos-agents 1.6.1 → 2.0.0-beta.2

package/.agents/adapters/cursor/export.js

@@ -1,20 +1,23 @@
+/**
+ * .agents/adapters/cursor/export.js
+ * ContextOS Cursor Pure Adapter (.cursorrules and .cursor/rules/*.mdc)
+ */
+
 const fs = require('fs');
 const path = require('path');
 const { AGENTS_MD_PATH, collectSkillDirectories, extractYamlField, stripFrontmatter, readMeaningfulMarkdown } = require('../shared.js');
+const { registerAdapter, applyArtifacts, createProvenanceHeader } = require('../pure-compiler.js');
 
-// Output paths
-const OUTPUT_FILE = path.join(process.cwd(), '.cursorrules');
-const CURSOR_RULES_DIR = path.join(process.cwd(), '.cursor', 'rules');
+const GENERATOR_ID = 'cursor@2';
 
-/**
- * Cursor adapter — export.js
- *
- * Generates:
- *   1. Modern modular Cursor rules in `.cursor/rules/<skill>.mdc` with glob filters
- *   2. Flat `.cursorrules` at project root for backwards compatibility
- *
- * Format spec: https://docs.cursor.com/context/rules-for-ai
- */
+function describe() {
+  return {
+    name: 'cursor',
+    version: '2.0.0',
+    description: 'Compiles modular rules for Cursor (.cursor/rules/*.mdc and legacy .cursorrules)',
+    targetPattern: '.cursor/rules/*.mdc',
+  };
+}
 
 function getSkillGlobsAndFlags(skillName) {
   const ALWAYS_APPLY_SKILLS = ['engineering-workflow', 'gstack-roles', 'ponytail-mindset'];
@@ -22,7 +25,6 @@ function getSkillGlobsAndFlags(skillName) {
     return { globs: '', alwaysApply: true };
   }
 
-  // Precise surgical globs mapping to prevent context flooding
   const GLOB_MAP = {
     'react': '**/*.{tsx,jsx}',
     'react-best-practices': '**/*.{tsx,jsx}',
@@ -58,9 +60,9 @@ function getSkillGlobsAndFlags(skillName) {
 }
 
 function buildSkillSection(skillDir) {
-  const skillName  = path.basename(skillDir);
-  const skillMdPath  = path.join(skillDir, 'SKILL.md');
-  const yamlPath   = path.join(skillDir, 'skill.yaml');
+  const skillName = path.basename(skillDir);
+  const skillMdPath = path.join(skillDir, 'SKILL.md');
+  const yamlPath = path.join(skillDir, 'skill.yaml');
 
   let title = skillName;
   let description = '';
@@ -70,9 +72,7 @@ function buildSkillSection(skillDir) {
     description = extractYamlField(yaml, 'description') || '';
   }
 
-  if (!fs.existsSync(skillMdPath)) {
-    return null;
-  }
+  if (!fs.existsSync(skillMdPath)) return null;
 
   const raw = fs.readFileSync(skillMdPath, 'utf8');
   const body = stripFrontmatter(raw);
@@ -130,78 +130,93 @@ ${body}
   return { skillName, mdcContent };
 }
 
-function run() {
-  console.log('Starting Cursor adapter export...');
-
-  const sections = [];
-
-  // ── Header ──────────────────────────────────────────────────────────────────
-  sections.push(
-    `# ContextOS — AI Rules for Cursor\n` +
-    `# Auto-generated by: node .agents/ctx.js export cursor\n` +
-    `# Source: .agents/core/skills/  ·  Do not edit manually.\n\n` +
-    `> **Core law: Do not read everything. Read only what the current task requires.**\n\n` +
-    `Detailed rules are modularized in \`.cursor/rules/*.mdc\` with file-glob activation.\n` +
-    `Core orchestration is handled by \`.cursor/rules/00-project-rules.mdc\`.\n`
-  );
+function render(context) {
+  const projectRoot = context?.projectRoot || '.';
+  const agentsMdPath = fs.existsSync(path.join(projectRoot, '.agents', 'AGENTS.md'))
+    ? path.join(projectRoot, '.agents', 'AGENTS.md')
+    : AGENTS_MD_PATH;
 
-  // Prepare .cursor/rules directory
-  fs.mkdirSync(CURSOR_RULES_DIR, { recursive: true });
+  const artifacts = [];
 
-  let count = 0;
-  let mdcCount = 0;
+  const prov = createProvenanceHeader({
+    generator: GENERATOR_ID,
+    sourceGraphHash: context?.sourceGraphHash,
+    profileId: context?.profileId,
+    profileHash: context?.profileHash,
+  });
 
-  // Write 00-project-rules.mdc
-  if (fs.existsSync(AGENTS_MD_PATH)) {
-    const agentsMd = fs.readFileSync(AGENTS_MD_PATH, 'utf8');
+  // 1. 00-project-rules.mdc
+  if (fs.existsSync(agentsMdPath)) {
+    const agentsMd = fs.readFileSync(agentsMdPath, 'utf8');
     const projectMdc = `---
 description: "ContextOS core project rules and role orchestration"
 globs: ""
 alwaysApply: true
 ---
 
+${prov}
 # ContextOS — Project Operating System Rules
 
 ${agentsMd}
 `;
-    fs.writeFileSync(path.join(CURSOR_RULES_DIR, '00-project-rules.mdc'), projectMdc);
-    mdcCount++;
+    artifacts.push({
+      path: '.cursor/rules/00-project-rules.mdc',
+      content: projectMdc.replace(/\r\n/g, '\n'),
+      mediaType: 'text/markdown',
+      kind: 'generated-adapter',
+      generator: GENERATOR_ID,
+      sourceSkillIds: ['project-rules'],
+      inputsHash: context?.sourceGraphHash || 'none',
+    });
   }
 
-  // ── Skills Index ─────────────────────────────────────────────────────────────
-  sections.push('\n---\n\n# Skills Index (Loaded On-Demand)\n\n' +
-    'The following specialist skills are configured as `.cursor/rules/<skill>.mdc`:\n');
-  const skills = collectSkillDirectories();
-  const activeMdcFiles = new Set(['00-project-rules.mdc']);
-
+  const skills = collectSkillDirectories(context?.profile);
   for (const skill of skills) {
-    const section = buildSkillSection(skill);
-    if (section) {
-      sections.push(section);
-      count++;
-    }
-
     const mdc = generateCursorMdc(skill);
     if (mdc) {
-      const mdcFileName = `${mdc.skillName}.mdc`;
-      activeMdcFiles.add(mdcFileName);
-      fs.writeFileSync(path.join(CURSOR_RULES_DIR, mdcFileName), mdc.mdcContent);
-      mdcCount++;
+      const fullMdc = mdc.mdcContent.replace(/\r\n/g, '\n');
+      artifacts.push({
+        path: `.cursor/rules/${mdc.skillName}.mdc`,
+        content: fullMdc,
+        mediaType: 'text/markdown',
+        kind: 'generated-adapter',
+        generator: GENERATOR_ID,
+        sourceSkillIds: [mdc.skillName],
+        inputsHash: context?.sourceGraphHash || 'none',
+      });
     }
   }
 
-  // Clean up stale .mdc rules from uninstalled skills/plugins
-  if (fs.existsSync(CURSOR_RULES_DIR)) {
-    for (const file of fs.readdirSync(CURSOR_RULES_DIR)) {
-      if (file.endsWith('.mdc') && !activeMdcFiles.has(file)) {
-        fs.unlinkSync(path.join(CURSOR_RULES_DIR, file));
-      }
+  return artifacts;
+}
+
+function validate(artifacts) {
+  const diagnostics = [];
+  for (const art of artifacts) {
+    if (!art.content || art.content.length === 0) {
+      diagnostics.push({ path: art.path, message: 'Empty artifact content' });
     }
   }
+  return diagnostics;
+}
 
-  fs.writeFileSync(OUTPUT_FILE, sections.join('\n'));
-  console.log(`Generated .cursorrules (${count} skills) → ${OUTPUT_FILE}`);
-  console.log(`Generated .cursor/rules/*.mdc (${mdcCount} rules) → ${CURSOR_RULES_DIR}`);
+function run(options = {}) {
+  const { loadCompilerContext } = require('../pure-compiler.js');
+  const projectRoot = options.projectRoot || '.';
+  const context = loadCompilerContext(projectRoot, options);
+  const artifacts = render(context);
+  const result = applyArtifacts(projectRoot, artifacts, { command: 'export cursor', context });
+  console.log(`✓ Cursor export complete: ${result.appliedCount} files applied (tx: ${result.txId})`);
+  return result;
 }
 
-module.exports = { run };
+const adapter = {
+  describe,
+  render,
+  validate,
+  run,
+};
+
+registerAdapter('cursor', adapter);
+
+module.exports = adapter;

package/.agents/adapters/drift-detector.js

@@ -0,0 +1,196 @@
+/**
+ * .agents/adapters/drift-detector.js
+ * ContextOS Adapter Output Drift & Out-of-Sync Detector
+ *
+ * Implements Section 12.4 drift states:
+ * - STALE_INPUT: Source graph or profile modified since last compile
+ * - MISSING_OUTPUT: Planned or recorded file absent from disk
+ * - MODIFIED_MANAGED_OUTPUT: Disk content differs from lockfile (user edits)
+ * - ORPHAN_MANAGED_OUTPUT: Lockfile records file no longer rendered
+ * - ADAPTER_VERSION_MISMATCH: Generator version differs
+ * - PROFILE_MISMATCH: Active profile differs from lockfile profile
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { LockfileV2Manager, computeExactHash, computeSemanticHash } = require('../filesystem/index.js');
+const { renderAdapters } = require('./pure-compiler.js');
+
+const DRIFT_STATES = {
+  STALE_INPUT: 'STALE_INPUT',
+  MISSING_OUTPUT: 'MISSING_OUTPUT',
+  MODIFIED_MANAGED_OUTPUT: 'MODIFIED_MANAGED_OUTPUT',
+  ORPHAN_MANAGED_OUTPUT: 'ORPHAN_MANAGED_OUTPUT',
+  ADAPTER_VERSION_MISMATCH: 'ADAPTER_VERSION_MISMATCH',
+  PROFILE_MISMATCH: 'PROFILE_MISMATCH',
+};
+
+/**
+ * Computes a unified textual diff snippet between before and after strings.
+ */
+function computeDiffSnippet(beforeStr, afterStr, maxLines = 15) {
+  const beforeLines = beforeStr.split(/\r?\n/);
+  const afterLines = afterStr.split(/\r?\n/);
+  const diffLines = [];
+
+  let lineCount = 0;
+  for (let i = 0; i < Math.max(beforeLines.length, afterLines.length); i++) {
+    const b = beforeLines[i];
+    const a = afterLines[i];
+    if (b !== a) {
+      if (b !== undefined) {
+        diffLines.push(`- ${b}`);
+        lineCount++;
+      }
+      if (a !== undefined) {
+        diffLines.push(`+ ${a}`);
+        lineCount++;
+      }
+    }
+    if (lineCount >= maxLines) {
+      diffLines.push('... (diff truncated)');
+      break;
+    }
+  }
+
+  return diffLines.join('\n');
+}
+
+/**
+ * Analyzes drift between current project state, Lockfile v2, and projected adapter render.
+ *
+ * @param {string} projectRoot
+ * @param {string[]|string} [adapters='all']
+ * @param {object} [options]
+ * @returns {object} Structured drift report
+ */
+function detectDrift(projectRoot, adapters = 'all', options = {}) {
+  const absRoot = path.resolve(projectRoot);
+  const lockManager = new LockfileV2Manager(absRoot);
+  const lockfile = lockManager.read();
+
+  const { artifacts, collisions, context } = renderAdapters(absRoot, adapters, options);
+
+  const findings = {
+    [DRIFT_STATES.STALE_INPUT]: [],
+    [DRIFT_STATES.MISSING_OUTPUT]: [],
+    [DRIFT_STATES.MODIFIED_MANAGED_OUTPUT]: [],
+    [DRIFT_STATES.ORPHAN_MANAGED_OUTPUT]: [],
+    [DRIFT_STATES.ADAPTER_VERSION_MISMATCH]: [],
+    [DRIFT_STATES.PROFILE_MISMATCH]: [],
+  };
+
+  const diffs = [];
+
+  // 1. Check Profile Mismatch
+  if (lockfile && lockfile.profile) {
+    if (context.profileId && lockfile.profile.id !== context.profileId) {
+      findings[DRIFT_STATES.PROFILE_MISMATCH].push({
+        expected: context.profileId,
+        actual: lockfile.profile.id,
+      });
+    }
+  }
+
+  // 2. Check Stale Input (Source Graph Hash)
+  if (lockfile && lockfile.sourceGraphHash) {
+    if (context.sourceGraphHash && lockfile.sourceGraphHash !== context.sourceGraphHash) {
+      findings[DRIFT_STATES.STALE_INPUT].push({
+        expected: context.sourceGraphHash,
+        actual: lockfile.sourceGraphHash,
+      });
+    }
+  }
+
+  const projectedPaths = new Set(artifacts.map(a => a.path));
+
+  // 3. Inspect each projected artifact against disk and lockfile
+  for (const art of artifacts) {
+    const fullPath = path.resolve(absRoot, art.path);
+    const projectedContent = art.content.toString('utf8');
+    const projectedExactHash = computeExactHash(art.content);
+    const projectedSemanticHash = computeSemanticHash(art.content);
+
+    if (!fs.existsSync(fullPath)) {
+      findings[DRIFT_STATES.MISSING_OUTPUT].push({
+        path: art.path,
+        reason: 'Projected artifact does not exist on disk',
+      });
+      diffs.push({
+        path: art.path,
+        type: 'missing',
+        diff: `+ (new file, ${projectedContent.length} bytes)`,
+      });
+    } else {
+      const diskContent = fs.readFileSync(fullPath, 'utf8');
+      const diskSemanticHash = computeSemanticHash(diskContent);
+
+      // Check if disk matches projected render
+      if (diskSemanticHash !== projectedSemanticHash) {
+        const lockRecord = lockfile?.managedFiles?.[art.path];
+        if (lockRecord && lockRecord.semanticTextSha256 !== diskSemanticHash) {
+          findings[DRIFT_STATES.MODIFIED_MANAGED_OUTPUT].push({
+            path: art.path,
+            reason: 'Managed file was modified by user on disk',
+            diskHash: diskSemanticHash,
+            lockHash: lockRecord.semanticTextSha256,
+          });
+        } else {
+          findings[DRIFT_STATES.STALE_INPUT].push({
+            path: art.path,
+            reason: 'Generated artifact differs from source skills projection',
+          });
+        }
+
+        diffs.push({
+          path: art.path,
+          type: 'modified',
+          diff: computeDiffSnippet(diskContent, projectedContent),
+        });
+      }
+    }
+  }
+
+  // 4. Check for orphan files recorded in lockfile but no longer projected
+  if (lockfile && lockfile.managedFiles) {
+    for (const [recordedPath, meta] of Object.entries(lockfile.managedFiles)) {
+      if (!projectedPaths.has(recordedPath)) {
+        const fullRecorded = path.resolve(absRoot, recordedPath);
+        if (fs.existsSync(fullRecorded)) {
+          findings[DRIFT_STATES.ORPHAN_MANAGED_OUTPUT].push({
+            path: recordedPath,
+            reason: 'File recorded in lockfile is no longer generated by active skills/profile',
+          });
+          diffs.push({
+            path: recordedPath,
+            type: 'orphan',
+            diff: `- (orphan file on disk, ${meta.kind})`,
+          });
+        }
+      }
+    }
+  }
+
+  if (diffs.length === 0 && findings[DRIFT_STATES.ORPHAN_MANAGED_OUTPUT].length === 0) {
+    findings[DRIFT_STATES.STALE_INPUT] = [];
+    findings[DRIFT_STATES.PROFILE_MISMATCH] = [];
+  }
+
+  const totalFindings = Object.values(findings).reduce((acc, list) => acc + list.length, 0);
+  const hasDrift = totalFindings > 0 || collisions.length > 0;
+
+  return {
+    hasDrift,
+    totalFindings,
+    findings,
+    collisions,
+    diffs,
+    projectedCount: artifacts.length,
+  };
+}
+
+module.exports = {
+  detectDrift,
+  computeDiffSnippet,
+  DRIFT_STATES,
+};

package/.agents/adapters/gemini/export.js

@@ -1,18 +1,31 @@
+/**
+ * .agents/adapters/gemini/export.js
+ * ContextOS Gemini & Antigravity IDE Pure Adapter
+ */
+
 const fs = require('fs');
 const path = require('path');
-const { collectSkillDirectories, resetDirectory, readMeaningfulMarkdown, extractYamlField } = require('../shared.js');
-
-const GENERATED_SKILLS_PATH = path.join(__dirname, '..', '..', 'generated', 'gemini', 'skills');
+const { collectSkillDirectories, readMeaningfulMarkdown, extractYamlField } = require('../shared.js');
+const { registerAdapter, applyArtifacts } = require('../pure-compiler.js');
+
+const GENERATOR_ID = 'gemini@2';
+
+function describe() {
+  return {
+    name: 'gemini',
+    version: '2.0.0',
+    description: 'Compiles modular skills for Gemini 3.8 and Google Antigravity IDE',
+    targetPattern: '.agents/generated/gemini/skills/**/SKILL.md',
+  };
+}
 
-function generateGeminiSkill(skillDir) {
+function renderGeminiSkill(skillDir, context) {
   const skillName = path.basename(skillDir);
   const yamlPath = path.join(skillDir, 'skill.yaml');
   const existingSkillMdPath = path.join(skillDir, 'SKILL.md');
-  const outputDir = path.join(GENERATED_SKILLS_PATH, skillName);
 
   if (!fs.existsSync(existingSkillMdPath) && !fs.existsSync(yamlPath)) {
-    console.log(`Skipping ${skillName} (no skill.yaml or SKILL.md)`);
-    return;
+    return [];
   }
 
   let name = skillName;
@@ -30,11 +43,9 @@ function generateGeminiSkill(skillDir) {
   }
   description = description || `ContextOS skill for ${name}`;
 
-  // Find all .md files in the skill directory deterministically
   const files = fs.readdirSync(skillDir).sort((a, b) => a.localeCompare(b, 'en', { sensitivity: 'base' }));
   const mdFiles = files.filter(f => f.endsWith('.md'));
 
-  // Primary skill content first: SKILL.md is canonical; fallback to <skillName>.md
   const primaryMd = mdFiles.includes('SKILL.md')
     ? 'SKILL.md'
     : (mdFiles.find(f => f === `${skillName}.md`) || mdFiles[0]);
@@ -42,22 +53,16 @@ function generateGeminiSkill(skillDir) {
   let mergedContent = '';
   if (primaryMd) {
     let primaryText = fs.readFileSync(path.join(skillDir, primaryMd), 'utf8');
-    // Strip existing frontmatter from source so we don't double-nest
     primaryText = primaryText.replace(/^---[\s\S]*?---\r?\n/, '');
     mergedContent += primaryText;
   }
 
-  // Partition supplemental markdown files for deterministic, logical ordering:
-  // 1. Specific topic / reference docs (e.g. accessibility.md), sorted alphabetically
-  // 2. EXAMPLES.md
-  // 3. TROUBLESHOOTING.md
   const otherTopicFiles = mdFiles.filter(f => f !== primaryMd && f !== 'EXAMPLES.md' && f !== 'TROUBLESHOOTING.md');
   const orderedExtras = [...otherTopicFiles];
   if (mdFiles.includes('EXAMPLES.md') && primaryMd !== 'EXAMPLES.md') orderedExtras.push('EXAMPLES.md');
   if (mdFiles.includes('TROUBLESHOOTING.md') && primaryMd !== 'TROUBLESHOOTING.md') orderedExtras.push('TROUBLESHOOTING.md');
 
   for (const mdFile of orderedExtras) {
-    // Avoid re-appending content that was already inlined via Source comments in SKILL.md
     if (mergedContent.includes(`<!-- Source: ${mdFile} -->`)) continue;
     const extraContent = readMeaningfulMarkdown(path.join(skillDir, mdFile));
     if (extraContent) {
@@ -65,7 +70,6 @@ function generateGeminiSkill(skillDir) {
     }
   }
 
-  // Construct Gemini SKILL.md format (normalizing line endings to \n)
   const outputContent = `---
 name: ${name}
 description: >
@@ -74,42 +78,69 @@ description: >
 ${mergedContent.trimStart()}
 `.replace(/\r\n/g, '\n');
 
-  fs.mkdirSync(outputDir, { recursive: true });
-  fs.writeFileSync(path.join(outputDir, 'SKILL.md'), outputContent);
+  const artifacts = [
+    {
+      path: `.agents/generated/gemini/skills/${skillName}/SKILL.md`,
+      content: outputContent,
+      mediaType: 'text/markdown',
+      kind: 'generated-adapter',
+      generator: GENERATOR_ID,
+      sourceSkillIds: [skillName],
+      inputsHash: context?.sourceGraphHash || 'none',
+    },
+    {
+      path: `.agents/skills/${skillName}/SKILL.md`,
+      content: outputContent,
+      mediaType: 'text/markdown',
+      kind: 'generated-adapter',
+      generator: GENERATOR_ID,
+      sourceSkillIds: [skillName],
+      inputsHash: context?.sourceGraphHash || 'none',
+    },
+  ];
+
+  return artifacts;
+}
+
+function render(context) {
+  const skills = collectSkillDirectories(context?.profile);
+  const artifacts = [];
+
+  for (const skill of skills) {
+    const rendered = renderGeminiSkill(skill, context);
+    artifacts.push(...rendered);
+  }
 
-  console.log(`Generated SKILL.md for ${skillName}`);
+  return artifacts;
 }
 
-const ANTIGRAVITY_SKILLS_PATH = path.join(__dirname, '..', '..', 'skills');
-
-function copyFolderRecursiveSync(source, target) {
-  if (!fs.existsSync(target)) fs.mkdirSync(target, { recursive: true });
-  const files = fs.readdirSync(source).sort((a, b) => a.localeCompare(b, 'en', { sensitivity: 'base' }));
-  for (const file of files) {
-    const curSource = path.join(source, file);
-    const curTarget = path.join(target, file);
-    if (fs.statSync(curSource).isDirectory()) {
-      copyFolderRecursiveSync(curSource, curTarget);
-    } else {
-      fs.copyFileSync(curSource, curTarget);
+function validate(artifacts) {
+  const diagnostics = [];
+  for (const art of artifacts) {
+    if (!art.content || art.content.length === 0) {
+      diagnostics.push({ path: art.path, message: 'Empty artifact content' });
     }
   }
+  return diagnostics;
 }
 
-function run() {
-  console.log('Starting Gemini adapter export...');
-  resetDirectory(GENERATED_SKILLS_PATH);
-  
-  const skills = collectSkillDirectories();
-  for (const skill of skills) {
-    generateGeminiSkill(skill);
-  }
+function run(options = {}) {
+  const { loadCompilerContext } = require('../pure-compiler.js');
+  const projectRoot = options.projectRoot || '.';
+  const context = loadCompilerContext(projectRoot, options);
+  const artifacts = render(context);
+  const result = applyArtifacts(projectRoot, artifacts, { command: 'export gemini', context });
+  console.log(`✓ Gemini export complete: ${result.appliedCount} files applied (tx: ${result.txId})`);
+  return result;
+}
 
-  // Also sync to .agents/skills for Antigravity IDE native discovery
-  resetDirectory(ANTIGRAVITY_SKILLS_PATH);
-  copyFolderRecursiveSync(GENERATED_SKILLS_PATH, ANTIGRAVITY_SKILLS_PATH);
+const adapter = {
+  describe,
+  render,
+  validate,
+  run,
+};
 
-  console.log('Export complete. Skills are in generated/gemini/skills and .agents/skills');
-}
+registerAdapter('gemini', adapter);
 
-module.exports = { run };
+module.exports = adapter;