contextos-agents 2.1.0 → 2.1.1

package/bin/lib/git-snapshot.js

@@ -61,7 +61,7 @@ function getStagedFiles(cwd = process.cwd()) {
   try {
     const output = execFileSync(
       'git',
-      ['diff', '--cached', '-z', '--name-status'],
+      ['-c', 'core.quotepath=false', 'diff', '--cached', '-z', '--name-status', '--no-ext-diff'],
       { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
     );
 
@@ -104,78 +104,105 @@ function getStagedFiles(cwd = process.cwd()) {
 
 /**
  * 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|null} Staged file buffer or null if deleted/missing
+ * @returns {Buffer} Staged file buffer
  */
 function getStagedBlob(relativePath, cwd = process.cwd()) {
+  const posixPath = relativePath.replace(/\\/g, '/');
   try {
-    const posixPath = relativePath.replace(/\\/g, '/');
-    const buf = execFileSync('git', ['show', `:${posixPath}`], {
-      cwd,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      maxBuffer: 10 * 1024 * 1024,
-    });
+    const buf = execFileSync(
+      'git',
+      ['--literal-pathspecs', '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;
+    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()) {
+function getStagedAddedLines(cwd = process.cwd(), files = null) {
   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;
+  let targetFiles = files;
+  if (!targetFiles) {
+    const staged = getStagedFiles(cwd);
+    targetFiles = staged.filter(e => e.status !== 'D').map(e => e.path);
+  }
 
-    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);
+  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,
         }
-      } else if (line.startsWith('+') && !line.startsWith('+++')) {
-        if (currentFile) {
+      );
+
+      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);
-          addedLinesByFile.get(currentFile).push({
+          fileAddedLines.push({
             line: currentLineNum,
             content,
           });
+          currentLineNum++;
         }
-        currentLineNum++;
       }
-    }
 
-    return addedLinesByFile;
-  } catch {
-    return addedLinesByFile;
+      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 = {

package/bin/lib/scan.js

@@ -127,18 +127,25 @@ const PLACEHOLDER_PATTERNS = [
   },
 ];
 
-// Exempt path substrings (e.g. test fixtures, test files, lockfiles)
-const EXEMPT_PATH_SUBSTRINGS = [
-  path.join('tests', ''),
-  path.join('.git', ''),
+// Exempt path segments and exact files (e.g. test fixtures, test files)
+const EXEMPT_SEGMENTS = new Set([
+  'tests',
+  '.git',
   'node_modules',
-  'check-secrets.js',
-  'scan.js',
-];
+]);
+
+const EXEMPT_EXACT_PATHS = new Set([
+  'scripts/check-secrets.js',
+  'bin/lib/scan.js',
+]);
 
 function isExempt(filePath) {
-  const norm = path.normalize(filePath);
-  return EXEMPT_PATH_SUBSTRINGS.some(exempt => norm.includes(exempt));
+  const norm = filePath.replace(/\\/g, '/');
+  if (EXEMPT_EXACT_PATHS.has(norm)) {
+    return true;
+  }
+  const segments = norm.split('/');
+  return segments.some(seg => EXEMPT_SEGMENTS.has(seg));
 }
 
 function redact(str) {
@@ -147,7 +154,7 @@ function redact(str) {
 }
 
 /**
- * Checks if a relative path matches a glob pattern or prefix.
+ * Checks if a relative path matches a glob pattern or prefix with strict segment boundaries.
  */
 function matchesScope(filePath, pattern) {
   const normFile = filePath.replace(/\\/g, '/').toLowerCase();
@@ -155,15 +162,16 @@ function matchesScope(filePath, pattern) {
 
   if (normPattern.endsWith('/**')) {
     const prefix = normPattern.slice(0, -3);
-    return normFile.startsWith(prefix);
+    return normFile === prefix || normFile.startsWith(prefix + '/');
   }
   if (normPattern.endsWith('/*')) {
     const prefix = normPattern.slice(0, -2);
+    if (!normFile.startsWith(prefix + '/')) return false;
     const rest = normFile.slice(prefix.length + 1);
-    return normFile.startsWith(prefix) && !rest.includes('/');
+    return !rest.includes('/');
   }
   if (normPattern.includes('*')) {
-    const reg = new RegExp('^' + normPattern.replace(/\./g, '\\.').replace(/\*/g, '.*') + '$');
+    const reg = new RegExp('^' + normPattern.replace(/\./g, '\\.').replace(/\*/g, '[^/]*') + '$');
     return reg.test(normFile);
   }
   return normFile === normPattern || normFile.startsWith(normPattern + '/');
@@ -191,17 +199,26 @@ function runScan(options = {}) {
 
   const checkSecrets = options.secrets !== false;
   const checkPlaceholders = Boolean(options.placeholders);
-  const scopeFile = options.scope || null;
   const enforce = Boolean(options.enforce);
 
+  let targetScopeFile = options.scope || null;
+  let scopeStatus = 'not_configured';
+
+  if (!targetScopeFile) {
+    const defaultScope = path.join(gitRoot, '.agents', 'task-scope.json');
+    if (fs.existsSync(defaultScope)) {
+      targetScopeFile = '.agents/task-scope.json';
+    }
+  }
+
   let allowedScopePatterns = null;
-  if (scopeFile) {
-    const resolvedScopePath = path.resolve(gitRoot, scopeFile);
+  if (targetScopeFile) {
+    const resolvedScopePath = path.resolve(gitRoot, targetScopeFile);
     if (!fs.existsSync(resolvedScopePath)) {
       return {
         ok: false,
         code: 2,
-        error: `Scope file not found: ${scopeFile}`,
+        error: `Scope file not found: ${targetScopeFile}`,
         findings: [],
         stats: { filesScanned: 0, violations: 0 },
       };
@@ -218,6 +235,7 @@ function runScan(options = {}) {
         }
       }
       allowedScopePatterns = list;
+      scopeStatus = `active (${targetScopeFile})`;
     } catch (err) {
       return {
         ok: false,
@@ -243,17 +261,28 @@ function runScan(options = {}) {
   }
 
   const findings = [];
-  const addedLinesMap = checkPlaceholders ? getStagedAddedLines(gitRoot) : new Map();
+  let addedLinesMap = new Map();
+  if (checkPlaceholders) {
+    try {
+      const activePaths = stagedEntries.filter(e => e.status !== 'D').map(e => e.path);
+      addedLinesMap = getStagedAddedLines(gitRoot, activePaths);
+    } catch (err) {
+      return {
+        ok: false,
+        code: 2,
+        error: `Failed to inspect staged added lines: ${err.message}`,
+        findings: [],
+        stats: { filesScanned: stagedEntries.length, violations: 0 },
+      };
+    }
+  }
 
   for (const entry of stagedEntries) {
-    // Skip deleted files from content and blocked filename checks
-    if (entry.status === 'D') continue;
-
     const relPath = entry.path;
     const baseName = path.basename(relPath).toLowerCase();
     const extName = path.extname(relPath).toLowerCase();
 
-    // 1. Scope Containment Check
+    // 1. Scope Containment Check (checked for ALL staged actions: added, modified, deleted, renamed)
     if (allowedScopePatterns) {
       const inScope = allowedScopePatterns.some(p => matchesScope(relPath, p));
       if (!inScope) {
@@ -265,8 +294,23 @@ function runScan(options = {}) {
           details: `Staged file "${relPath}" is outside allowed task scope`,
         });
       }
+      if (entry.oldPath) {
+        const oldInScope = allowedScopePatterns.some(p => matchesScope(entry.oldPath, p));
+        if (!oldInScope) {
+          findings.push({
+            ruleId: 'SCOPE-001',
+            file: entry.oldPath,
+            type: 'Scope Violation',
+            severity: 'error',
+            details: `Source file of rename "${entry.oldPath}" is outside allowed task scope`,
+          });
+        }
+      }
     }
 
+    // Skip deleted files from content and blocked filename checks
+    if (entry.status === 'D') continue;
+
     // 2. Blocked Exact Names Check
     if (checkSecrets && BLOCKED_EXACT_NAMES.has(baseName)) {
       findings.push({
@@ -294,12 +338,43 @@ function runScan(options = {}) {
     // Skip content scan for exempt paths
     if (isExempt(relPath)) continue;
 
-    // Read blob from index
-    const blob = getStagedBlob(relPath, gitRoot);
-    if (!blob) continue;
+    // Read blob from index (fails closed with code 2 on read errors in any mode)
+    let blob;
+    try {
+      blob = getStagedBlob(relPath, gitRoot);
+    } catch (err) {
+      return {
+        ok: false,
+        code: 2,
+        error: `Failed to read staged blob for "${relPath}": ${err.message}`,
+        findings,
+        stats: { filesScanned: stagedEntries.length, violations: findings.length },
+      };
+    }
 
-    // Skip large files (> 2MB)
-    if (blob.length > 2 * 1024 * 1024) continue;
+    if (!blob) {
+      return {
+        ok: false,
+        code: 2,
+        error: `Failed to read staged blob for "${relPath}": file unreadable in git index`,
+        findings,
+        stats: { filesScanned: stagedEntries.length, violations: findings.length },
+      };
+    }
+
+    // Large files (> 2MB): fail-closed in enforce mode
+    if (blob.length > 2 * 1024 * 1024) {
+      if (enforce) {
+        findings.push({
+          ruleId: 'SCAN-SKIP-001',
+          file: relPath,
+          type: 'Skipped Large File',
+          severity: 'error',
+          details: `Staged file "${relPath}" exceeds 2MB limit (${(blob.length / (1024 * 1024)).toFixed(2)}MB) and cannot be verified for secrets in enforce mode.`,
+        });
+      }
+      continue;
+    }
 
     const content = blob.toString('utf8');
     const lines = content.split(/\r?\n/);
@@ -352,13 +427,19 @@ function runScan(options = {}) {
 
   const hasViolations = findings.length > 0;
   // If enforce is true, violations return code 1. If enforce is false, warnings return code 0.
+  // Incomplete/failed inspection returns code 2 in all modes.
   const exitCode = hasViolations && enforce ? 1 : 0;
 
   return {
     ok: exitCode === 0,
     code: exitCode,
+    message: exitCode === 0 ? 'Verification completed cleanly, no blocking violations' : 'Blocking violations detected in staged index',
     gitRoot,
     enforce,
+    scope: {
+      file: targetScopeFile,
+      status: scopeStatus,
+    },
     findings,
     stats: {
       stagedFilesCount: stagedEntries.length,

package/catalog/skills/adapters/EXAMPLES.md

@@ -0,0 +1,19 @@
+# adapters Examples - Anti-patterns vs ContextOS Standard
+
+## Example 1: Multi-Agent Configuration
+
+### Anti-pattern: Manually Syncing 6 Different Rule Files
+
+```text
+Editing .cursorrules, then forgetting to update CLAUDE.md, then editing copilot-instructions.md.
+Rules diverge across teammates using different IDEs.
+```
+
+### Best practice: ContextOS Standard (Single Source of Truth)
+
+```bash
+# Edit skills once in .agents/core/skills/
+# Compile to all agents with one command:
+node .agents/ctx.js export all
+# Automatically updates .cursorrules, CLAUDE.md, copilot-instructions.md, .aider, .zed
+```

package/catalog/skills/adapters/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: adapters
+description: >
+  Generates agent-specific configuration files from the unified ContextOS format.
+  One internal system, multiple output formats for Claude, Gemini, Copilot, 
+  Cursor, Aider, Continue, OpenHands, and others.
+---
+
+# agent-adapters
+
+## Overview
+
+Unified cross-agent configuration engine. Translates single ContextOS source rules into optimized native formats for Claude Code (CLAUDE.md), Gemini (.agents/skills), Cursor (.cursorrules, .cursor/rules/*.mdc), GitHub Copilot, Zed, Aider, and Continue.
+
+## When to Use
+
+Activate when configuring, synchronizing, or exporting agent rules and skills across multiple IDEs and AI programming assistants.
+
+## Rules & Patterns
+
+ContextOS is agent-agnostic. This skill generates the right config format for any AI agent.
+
+## Supported Agents
+
+| Agent | Config Target | Format |
+| --- | --- | --- |
+| **Gemini / Antigravity** | `.agents/generated/gemini/skills/` | Native modular skills |
+| **Claude Code** | `.agents/generated/claude/skills/` | Aggregated markdown skills |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | Single instructions file with on-demand skill references |
+| **Cursor** | `.cursor/rules/*.mdc` + `.cursorrules` | MDC modular glob rules + fallback |
+| **Aider** | `.aider.conf.yml` + `CONVENTIONS.md` | YAML config + conventions markdown |
+| **Zed IDE** | `.zed/rules.md` + `.zed/prompts/*.md` | Native rules and prompt templates |
+
+## Generation Commands
+
+- `contextos export <agent>` (or `node .agents/ctx.js export <agent>`) - Generate config for a specific agent (`gemini`, `claude`, `cursor`, `copilot`, `aider`, `zed`).
+- `contextos export all` - Generate configs for all supported agents in a single transaction.
+
+## Adapter Logic
+
+### For Claude Code (`CLAUDE.md`)
+
+Compile into a single markdown file:
+
+1. Project overview from `docs/PRD.md` (summary only)
+2. Architecture summary from `docs/ARCHITECTURE.md`
+3. Coding rules from loaded skills
+4. Active Decision Records
+5. Current tasks from `docs/TASKS.md`
+
+### For Gemini (`.agents/AGENTS.md`)
+
+Already native format. Just ensure:
+
+1. `AGENTS.md` references the skill directory
+2. Skills have proper SKILL.md with frontmatter
+3. Context Manager rules are in AGENTS.md
+
+### For Cursor (`.cursorrules`)
+
+Compile into a flat text file:
+
+1. Project context (condensed)
+2. Coding style rules
+3. Framework-specific instructions
+4. Anti-patterns to avoid
+
+### For Aider (`.aider.conf.yml`)
+
+```yaml
+read:
+  - docs/ARCHITECTURE.md
+  - docs/API.md
+  - docs/PROJECT_GRAPH.md
+conventions:
+  - {{coding rules from skills}}
+```
+
+## Sync Rules
+
+- Adapters read from the canonical ContextOS documents
+- Never edit adapter output files directly
+- Re-run `contextos export all` after any skill or rule change
+- Each adapter file includes a header: `# Generated by ContextOS - do not edit directly`
+
+
+## Code Examples
+
+See `EXAMPLES.md` for detailed code examples.
+
+## Validation Checklist
+
+What to verify during the review phase before completing the task.
+
+## Common Mistakes
+
+Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
+
+## Integration Notes
+
+How this skill interacts with other skills.

package/catalog/skills/adapters/TROUBLESHOOTING.md

@@ -0,0 +1,7 @@
+# adapters Troubleshooting & Common Mistakes
+
+## 1. Overwriting Custom Configs
+
+- **Symptom**: Custom non-ContextOS rules wiped out during export.
+- **Root Cause**: Running export with force flags over unmanaged files.
+- **Fix**: Keep custom project overrides in dedicated config files or use plugin skills.

package/catalog/skills/adapters/VALIDATION.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "rules_followed": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "rules_followed"
+  ]
+}

package/catalog/skills/adapters/skill.yaml

@@ -0,0 +1,13 @@
+schemaVersion: 2
+name: adapters
+category: engineering
+type: compiler
+description: >
+  Generates agent-specific configuration files from unified ContextOS format.
+  Produces configs for Claude, Gemini, Copilot, Cursor, Aider, Continue, and Zed.
+version: 1.0.0
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json

package/catalog/skills/api-design/EXAMPLES.md

@@ -0,0 +1,91 @@
+# API Design - Examples & Best Practices
+
+## Example 1: Contract-First Interface with Zod & TypeScript
+
+```typescript
+import { z } from 'zod';
+
+// 1. Unified Contract Definition
+export const CreateTaskSchema = z.object({
+  title: z.string().min(1, 'Title is required').max(120, 'Title exceeds max length'),
+  description: z.string().max(1000).optional(),
+  priority: z.enum(['low', 'medium', 'high']).default('medium')
+});
+
+export type CreateTaskInput = z.infer<typeof CreateTaskSchema>;
+
+export interface TaskDTO {
+  id: string;
+  title: string;
+  description: string | null;
+  priority: 'low' | 'medium' | 'high';
+  createdAt: string; // ISO 8601 string
+}
+
+export interface APIErrorResponse {
+  error: {
+    code: string;
+    message: string;
+    details?: Array<{ field: string; message: string }>;
+  };
+}
+
+// 2. Safe Edge Controller
+export async function handleCreateTask(
+  body: unknown,
+  createTaskService: (input: CreateTaskInput) => Promise<TaskDTO>
+): Promise<{ status: number; data: TaskDTO | APIErrorResponse }> {
+  const result = CreateTaskSchema.safeParse(body);
+
+  if (!result.success) {
+    return {
+      status: 422,
+      data: {
+        error: {
+          code: 'VALIDATION_FAILED',
+          message: 'Request payload failed schema validation',
+          details: result.error.errors.map(err => ({
+            field: err.path.join('.'),
+            message: err.message
+          }))
+        }
+      }
+    };
+  }
+
+  const task = await createTaskService(result.data);
+  return { status: 201, data: task };
+}
+```
+
+---
+
+## Example 2: Idempotent Mutation Handler
+
+```typescript
+import crypto from 'node:crypto';
+
+interface IdempotencyStore {
+  get(key: string): Promise<{ status: number; body: unknown } | null>;
+  set(key: string, result: { status: number; body: unknown }, ttlSeconds: number): Promise<void>;
+}
+
+export async function withIdempotency<T>(
+  key: string | undefined,
+  store: IdempotencyStore,
+  handler: () => Promise<{ status: number; body: T }>
+): Promise<{ status: number; body: T }> {
+  if (!key) {
+    return handler();
+  }
+
+  const cached = await store.get(key);
+  if (cached) {
+    return cached as { status: number; body: T };
+  }
+
+  const response = await handler();
+  await store.set(key, response, 86400); // 24-hour cache
+  return response;
+}
+```