contextos-agents 2.0.0 → 2.1.1

package/bin/lib/scan.js

@@ -0,0 +1,461 @@
+/**
+ * bin/lib/scan.js
+ * ContextOS Staged Index Scanner & Code Governance Engine
+ *
+ * Inspects Git staged changes for:
+ * 1. Hardcoded secrets, API tokens, private keys, and blocked files
+ * 2. Unfinished lazy placeholder stubs in newly added code
+ * 3. Scope containment violations against declared task scopes
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  findGitRoot,
+  getStagedFiles,
+  getStagedBlob,
+  getStagedAddedLines,
+} = require('./git-snapshot.js');
+
+// ── Blocked File Names and Extensions ───────────────────────────────────────
+
+const BLOCKED_EXACT_NAMES = new Set([
+  '.env',
+  '.env.local',
+  '.env.production',
+  '.env.development',
+  '.env.staging',
+  '.env.test',
+  '.netrc',
+  '.git-credentials',
+  '.npmrc',
+  'credentials.json',
+  'service-account.json',
+  'serviceaccountkey.json',
+  'id_rsa',
+  'id_ed25519',
+  'mcp_config.json',
+]);
+
+const BLOCKED_EXTENSIONS = new Set([
+  '.key',
+  '.pem',
+  '.pfx',
+  '.p12',
+  '.pkcs12',
+]);
+
+// ── Secret Content Patterns ──────────────────────────────────────────────────
+
+const SECRET_PATTERNS = [
+  {
+    ruleId: 'SEC-001',
+    name: 'Private Key Header',
+    pattern: /-----BEGIN\s+(?:RSA|OPENSSH|EC|DSA|PGP)?\s*PRIVATE\s+KEY-----/,
+  },
+  {
+    ruleId: 'SEC-002',
+    name: 'Hardcoded User Home Path Leak',
+    pattern: /(?:[a-zA-Z]:[/\\]Users[/\\]|\/(?:home|Users)\/)[a-zA-Z0-9_-]+[/\\](?:Desktop|Documents|Downloads|code|projects|repos)\b/i,
+  },
+  {
+    ruleId: 'SEC-003',
+    name: 'GitHub Personal Access Token',
+    pattern: /\b(?:ghp|gho)_[A-Za-z0-9]{36}\b/,
+  },
+  {
+    ruleId: 'SEC-004',
+    name: 'GitHub Fine-Grained PAT',
+    pattern: /\bgithub_pat_[A-Za-z0-9_]{82}\b/,
+  },
+  {
+    ruleId: 'SEC-005',
+    name: 'Google API Key',
+    pattern: /\bAIza[A-Za-z0-9_-]{35}\b/,
+  },
+  {
+    ruleId: 'SEC-006',
+    name: 'OpenAI API Key',
+    pattern: /\bsk-[A-Za-z0-9]{32,}\b/,
+  },
+  {
+    ruleId: 'SEC-007',
+    name: 'Anthropic API Key',
+    pattern: /\bsk-ant-[A-Za-z0-9-]{90,}\b/,
+  },
+  {
+    ruleId: 'SEC-008',
+    name: 'OpenRouter API Key',
+    pattern: /\bsk-or-v1-[a-f0-9]{64}\b/,
+  },
+  {
+    ruleId: 'SEC-009',
+    name: 'Slack Token',
+    pattern: /\bxox[baprs]-[A-Za-z0-9_-]{10,48}\b/,
+  },
+  {
+    ruleId: 'SEC-010',
+    name: 'npm Access Token',
+    pattern: /\bnpm_[A-Za-z0-9]{32,36}\b/,
+  },
+  {
+    ruleId: 'SEC-011',
+    name: 'AWS Access Key ID',
+    pattern: /\bAKIA[0-9A-Z]{16}\b/,
+  },
+];
+
+// ── Lazy Placeholder Patterns ───────────────────────────────────────────────
+
+const PLACEHOLDER_PATTERNS = [
+  {
+    ruleId: 'CODE-001',
+    name: 'Lazy Stub Comment',
+    pattern: /(?:\/\/|\/\*|#)\s*(?:TODO:\s*implement later|\.\.\.\s*rest of code stays here\s*\.\.\.|TODO:\s*implement\b)/i,
+  },
+  {
+    ruleId: 'CODE-002',
+    name: 'NotImplementedError Stub',
+    pattern: /raise\s+NotImplementedError\s*\(\s*["'].*TODO.*["']\s*\)/i,
+  },
+  {
+    ruleId: 'CODE-003',
+    name: 'Python Pass Stub',
+    pattern: /^\s*pass\s*#\s*TODO\b/i,
+  },
+];
+
+// Exempt path segments and exact files (e.g. test fixtures, test files)
+const EXEMPT_SEGMENTS = new Set([
+  'tests',
+  '.git',
+  'node_modules',
+]);
+
+const EXEMPT_EXACT_PATHS = new Set([
+  'scripts/check-secrets.js',
+  'bin/lib/scan.js',
+]);
+
+function isExempt(filePath) {
+  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) {
+  if (str.length <= 8) return '***';
+  return str.slice(0, 4) + '...' + str.slice(-4);
+}
+
+/**
+ * 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();
+  const normPattern = pattern.replace(/\\/g, '/').toLowerCase();
+
+  if (normPattern.endsWith('/**')) {
+    const prefix = normPattern.slice(0, -3);
+    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 !rest.includes('/');
+  }
+  if (normPattern.includes('*')) {
+    const reg = new RegExp('^' + normPattern.replace(/\./g, '\\.').replace(/\*/g, '[^/]*') + '$');
+    return reg.test(normFile);
+  }
+  return normFile === normPattern || normFile.startsWith(normPattern + '/');
+}
+
+/**
+ * Runs the staged scanner on the given repository root.
+ *
+ * @param {Object} options - Scan configuration options
+ * @returns {Object} Structured scan results with findings and status code
+ */
+function runScan(options = {}) {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const gitRoot = findGitRoot(cwd);
+
+  if (!gitRoot) {
+    return {
+      ok: false,
+      code: 2,
+      error: 'Not a Git repository. ContextOS scanner requires Git.',
+      findings: [],
+      stats: { filesScanned: 0, violations: 0 },
+    };
+  }
+
+  const checkSecrets = options.secrets !== false;
+  const checkPlaceholders = Boolean(options.placeholders);
+  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 (targetScopeFile) {
+    const resolvedScopePath = path.resolve(gitRoot, targetScopeFile);
+    if (!fs.existsSync(resolvedScopePath)) {
+      return {
+        ok: false,
+        code: 2,
+        error: `Scope file not found: ${targetScopeFile}`,
+        findings: [],
+        stats: { filesScanned: 0, violations: 0 },
+      };
+    }
+    try {
+      const scopeData = JSON.parse(fs.readFileSync(resolvedScopePath, 'utf8'));
+      const list = Array.isArray(scopeData) ? scopeData : scopeData.allowedPaths || scopeData.files;
+      if (!Array.isArray(list)) {
+        throw new Error('Scope declaration must be an array of paths or have an allowedPaths array');
+      }
+      for (const p of list) {
+        if (path.isAbsolute(p) || p.includes('..')) {
+          throw new Error(`Scope entry "${p}" is invalid (must be relative and cannot traverse outside repo)`);
+        }
+      }
+      allowedScopePatterns = list;
+      scopeStatus = `active (${targetScopeFile})`;
+    } catch (err) {
+      return {
+        ok: false,
+        code: 2,
+        error: `Invalid task scope file: ${err.message}`,
+        findings: [],
+        stats: { filesScanned: 0, violations: 0 },
+      };
+    }
+  }
+
+  let stagedEntries = [];
+  try {
+    stagedEntries = getStagedFiles(gitRoot);
+  } catch (err) {
+    return {
+      ok: false,
+      code: 2,
+      error: `Failed to inspect Git index: ${err.message}`,
+      findings: [],
+      stats: { filesScanned: 0, violations: 0 },
+    };
+  }
+
+  const findings = [];
+  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) {
+    const relPath = entry.path;
+    const baseName = path.basename(relPath).toLowerCase();
+    const extName = path.extname(relPath).toLowerCase();
+
+    // 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) {
+        findings.push({
+          ruleId: 'SCOPE-001',
+          file: relPath,
+          type: 'Scope Violation',
+          severity: 'error',
+          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({
+        ruleId: 'SEC-000',
+        file: relPath,
+        type: 'Blocked Filename',
+        severity: 'error',
+        details: `Filename "${baseName}" is forbidden from being committed into Git.`,
+      });
+      continue;
+    }
+
+    // 3. Blocked Extensions Check
+    if (checkSecrets && BLOCKED_EXTENSIONS.has(extName)) {
+      findings.push({
+        ruleId: 'SEC-000',
+        file: relPath,
+        type: 'Blocked Extension',
+        severity: 'error',
+        details: `Extension "${extName}" indicates private cryptographic keys or certificates.`,
+      });
+      continue;
+    }
+
+    // Skip content scan for exempt paths
+    if (isExempt(relPath)) 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 },
+      };
+    }
+
+    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/);
+
+    // 4. Staged Content Secrets Check
+    if (checkSecrets) {
+      for (let lineNum = 1; lineNum <= lines.length; lineNum++) {
+        const line = lines[lineNum - 1];
+        for (const { ruleId, name, pattern } of SECRET_PATTERNS) {
+          const match = line.match(pattern);
+          if (match) {
+            findings.push({
+              ruleId,
+              file: relPath,
+              line: lineNum,
+              type: name,
+              severity: 'error',
+              details: `Detected pattern "${name}": ${redact(match[0])}`,
+            });
+          }
+        }
+      }
+    }
+
+    // 5. Newly Added Code Placeholders Check
+    if (checkPlaceholders && addedLinesMap.has(relPath)) {
+      const addedLines = addedLinesMap.get(relPath);
+      // Skip markdown and doc files for placeholder checks
+      if (extName !== '.md' && extName !== '.txt') {
+        for (const { line, content: addedLine } of addedLines) {
+          if (addedLine.includes('contextos:allow-placeholder')) continue;
+
+          for (const { ruleId, name, pattern } of PLACEHOLDER_PATTERNS) {
+            const match = addedLine.match(pattern);
+            if (match) {
+              findings.push({
+                ruleId,
+                file: relPath,
+                line,
+                type: name,
+                severity: 'warning',
+                details: `Detected un-implemented placeholder stub: "${match[0].trim()}"`,
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+
+  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,
+      violationsCount: findings.length,
+      errorsCount: findings.filter(f => f.severity === 'error').length,
+      warningsCount: findings.filter(f => f.severity === 'warning').length,
+    },
+  };
+}
+
+module.exports = {
+  runScan,
+  BLOCKED_EXACT_NAMES,
+  BLOCKED_EXTENSIONS,
+  SECRET_PATTERNS,
+  PLACEHOLDER_PATTERNS,
+  matchesScope,
+  redact,
+};

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;
+}
+```