contextos-agents 2.1.0 → 2.2.0

package/.agents/adapters/aider/export.js

@@ -90,8 +90,8 @@ function render(context) {
       }
 
       aiderConfContent = yamlProv + '\n' + YAML.stringify(parsed);
-    } catch {
-      aiderConfContent = yamlProv + '\nread:\n  - CONVENTIONS.md\n';
+    } catch (err) {
+      throw new Error(`Failed to parse existing .aider.conf.yml: ${err.message}. Aborting to protect existing configuration from data loss.`);
     }
   } else {
     aiderConfContent = [

package/.agents/adapters/claude/export.js

@@ -9,13 +9,15 @@ const { collectSkillDirectories, readMeaningfulMarkdown } = require('../shared.j
 const { registerAdapter, applyArtifacts } = require('../pure-compiler.js');
 
 const GENERATOR_ID = 'claude@2';
+const CLAUDE_START_MARKER = '<!-- CONTEXTOS:START -->';
+const CLAUDE_END_MARKER = '<!-- CONTEXTOS:END -->';
 
 function describe() {
   return {
     name: 'claude',
     version: '2.0.0',
-    description: 'Compiles clean markdown skills for Claude Code CLI',
-    targetPattern: '.agents/generated/claude/skills/**/SKILL.md',
+    description: 'Compiles clean markdown skills for Claude Code CLI and manages CLAUDE.md entrypoint',
+    targetPattern: '{CLAUDE.md,.agents/generated/claude/skills/**/SKILL.md}',
   };
 }
 
@@ -53,6 +55,50 @@ function renderClaudeSkill(skillDir, context) {
   };
 }
 
+function renderClaudeRootIndex(skills, context) {
+  const projectRoot = context?.projectRoot || '.';
+  const claudePath = path.join(projectRoot, 'CLAUDE.md');
+  let existingContent = '';
+  if (fs.existsSync(claudePath)) {
+    try {
+      existingContent = fs.readFileSync(claudePath, 'utf8');
+    } catch {}
+  }
+
+  const skillEntries = skills.map(skillDir => {
+    const name = path.basename(skillDir);
+    return `- [${name}](.agents/generated/claude/skills/${name}/SKILL.md)`;
+  }).join('\n');
+
+  const managedBlock = `${CLAUDE_START_MARKER}
+<!-- Do not edit this section directly. Synchronized by ContextOS. -->
+# ContextOS Agent Governance
+
+The following skills are managed by ContextOS:
+${skillEntries}
+${CLAUDE_END_MARKER}`;
+
+  let finalContent;
+  if (existingContent.includes(CLAUDE_START_MARKER)) {
+    const regex = new RegExp(`${CLAUDE_START_MARKER}[\\s\\S]*?${CLAUDE_END_MARKER}`);
+    finalContent = existingContent.replace(regex, managedBlock);
+  } else if (existingContent.trim()) {
+    finalContent = `${existingContent.trimEnd()}\n\n${managedBlock}\n`;
+  } else {
+    finalContent = `${managedBlock}\n`;
+  }
+
+  return {
+    path: 'CLAUDE.md',
+    content: finalContent.replace(/\r\n/g, '\n'),
+    mediaType: 'text/markdown',
+    kind: 'generated-adapter',
+    generator: GENERATOR_ID,
+    sourceSkillIds: skills.map(s => path.basename(s)),
+    inputsHash: context?.sourceGraphHash || 'none',
+  };
+}
+
 function render(context) {
   const skills = collectSkillDirectories(context?.profile, context?.projectRoot);
   const artifacts = [];
@@ -62,6 +108,11 @@ function render(context) {
     if (art) artifacts.push(art);
   }
 
+  if (skills.length > 0) {
+    const rootIndex = renderClaudeRootIndex(skills, context);
+    if (rootIndex) artifacts.push(rootIndex);
+  }
+
   return artifacts;
 }
 

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

@@ -170,10 +170,13 @@ function detectDrift(projectRoot, adapters = 'all', options = {}) {
     } else {
       const diskContent = fs.readFileSync(fullPath, 'utf8');
       const diskSemanticHash = computeSemanticHash(diskContent);
+      const lockRecord = lockfile?.managedFiles?.[art.path];
 
-      // Check if disk matches projected render
-      if (diskSemanticHash !== projectedSemanticHash) {
-        const lockRecord = lockfile?.managedFiles?.[art.path];
+      // Check if disk matches projected render and recorded lockfile
+      const matchesProjection = diskSemanticHash === projectedSemanticHash;
+      const matchesLock = lockRecord ? diskSemanticHash === lockRecord.semanticTextSha256 : matchesProjection;
+
+      if (!matchesProjection || !matchesLock) {
         if (lockRecord && lockRecord.semanticTextSha256 !== diskSemanticHash) {
           findings[DRIFT_STATES.MODIFIED_MANAGED_OUTPUT].push({
             path: art.path,

package/.agents/adapters/pure-compiler.js

@@ -86,11 +86,22 @@ function loadCompilerContext(projectRoot, options = {}) {
 
   // 2. Profile v2
   let profile = null;
-  try {
-    const profiles = require('../profiles.js');
-    profile = options.profile ? profiles.getProfile(options.profile, absRoot) : profiles.getActiveProfile(absRoot);
-  } catch {
-    profile = null;
+  const profiles = require('../profiles.js');
+  if (options.profile) {
+    try {
+      profile = profiles.getProfile(options.profile, absRoot);
+    } catch (err) {
+      throw new Error(`Failed to load profile '${options.profile}': ${err.message}`);
+    }
+    if (!profile) {
+      throw new Error(`Profile '${options.profile}' was specified but does not exist.`);
+    }
+  } else {
+    try {
+      profile = profiles.getActiveProfile(absRoot);
+    } catch {
+      profile = null;
+    }
   }
 
   // 3. Workspace Graph
@@ -172,9 +183,10 @@ function listAdapters() {
  */
 function renderAdapters(projectRoot, adapterNames = 'all', options = {}) {
   const context = loadCompilerContext(projectRoot, options);
-  const targets = adapterNames === 'all'
+  const rawTargets = adapterNames === 'all'
     ? listAdapters()
     : (Array.isArray(adapterNames) ? adapterNames : [adapterNames]);
+  const targets = rawTargets.flatMap(a => (typeof a === 'string' && a.includes(',') ? a.split(',').map(s => s.trim()).filter(Boolean) : a));
 
   const allArtifacts = [];
   const pathToArtifact = new Map();

package/.agents/ctx.js

@@ -55,10 +55,13 @@ function printHelp() {
   console.log('  watch                           Start continuous file watcher and auto-sync daemon');
   console.log('  init                            Show initialization guide');
   console.log('  install-skill <ref>             Alias for skill add (install a plugin)');
-  console.log('  skill add   <ref>               Install a plugin skill (GitHub or npm)');
+  console.log('  skill add   <ref|--all>         Install a plugin skill or all catalog skills (--all)');
   console.log('  skill remove <name>             Uninstall a plugin skill');
-  console.log('  skill list                      List installed skills (builtin + plugins)');
+  console.log('  skill list [--available]        List installed skills (and available catalog skills)');
   console.log('  skill search [query]            Search the community skill registry');
+  console.log('  skill override <name>           Create editable project copy of an upstream skill');
+  console.log('  skill diff <name>               Show differences between local override and upstream');
+  console.log('  skill eject <name>              Eject upstream skill to standalone project skill');
   console.log('');
   console.log('Plugin ref formats:');
   console.log('  username/repo                    GitHub repo root SKILL.md');
@@ -253,8 +256,8 @@ if (command === 'export') {
     : (args.find(a => a.startsWith('--scope=')) || '').split('=')[1] || null;
 
   if (subcommand === 'list') {
-    const list = profiles.listProfiles();
-    const active = profiles.getActiveProfile();
+    const list = profiles.listProfiles(process.cwd());
+    const active = profiles.getActiveProfile(process.cwd());
     if (asJson) {
       console.log(JSON.stringify({ active, profiles: list }, null, 2));
     } else {
@@ -285,7 +288,7 @@ if (command === 'export') {
       console.error('[ERROR] Usage: node ctx.js profile show <name> [--json]');
       process.exit(1);
     }
-    const profile = profiles.getProfile(name);
+    const profile = profiles.getProfile(name, process.cwd());
     if (!profile) {
       console.error(`[ERROR] Profile '${name}' not found.`);
       process.exit(1);
@@ -306,7 +309,7 @@ if (command === 'export') {
       process.exit(1);
     }
     try {
-      const explanation = profiles.explainProfile(name);
+      const explanation = profiles.explainProfile(name, process.cwd());
       if (asJson) {
         console.log(JSON.stringify(explanation, null, 2));
       } else {
@@ -634,15 +637,17 @@ if (command === 'export') {
   }
 
   if (subcommand === 'add') {
+    const isAll = args.includes('--all') || ref === '--all' || ref === 'all';
     const forceUnsafe = args.includes('--force-unsafe-prompts') || args.includes('--force-unsafe');
-    plugins.add(ref, { dryRun, checksum, forceUnsafe }).catch(err => {
+    plugins.add(isAll ? '--all' : ref, { dryRun, checksum, forceUnsafe, all: isAll }).catch(err => {
       console.error(`[ERROR] ${err.message}`);
       process.exit(1);
     });
   } else if (subcommand === 'remove') {
     plugins.remove(ref);
   } else if (subcommand === 'list') {
-    plugins.list();
+    const available = args.includes('--available') || args.includes('-a') || args.includes('--all');
+    plugins.list({ available });
   } else if (subcommand === 'search') {
     const query = args.slice(2).join(' ');
     plugins.search(query).catch(err => {