contextos-agents 1.6.1 → 1.7.0

package/bin/lib/lockfile.js

@@ -0,0 +1,251 @@
+/**
+ * bin/lib/lockfile.js
+ * ContextOS Lockfile Engine & Provenance Tracking (schemaVersion: 1)
+ *
+ * Tracks files managed by ContextOS installations to ensure:
+ * - Zero data loss during updates (never overwrite user-modified files)
+ * - Safe uninstallation (never delete user-created files or modified managed files)
+ * - Transparent provenance for adapters and generated files
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const LOCKFILE_REL_PATH = '.agents/contextos.lock.json';
+
+/**
+ * Normalize a relative path to standard POSIX-style relative path without leading ./
+ * e.g. ".agents\\core\\skills" -> ".agents/core/skills"
+ */
+function normalizePath(relPath) {
+  if (!relPath) return '';
+  return relPath
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '')
+    .replace(/^\//, '');
+}
+
+/**
+ * Compute SHA-256 hash of a string or buffer.
+ * Automatically normalizes CRLF line endings to LF to ensure cross-platform reproducibility.
+ */
+function computeHash(content) {
+  if (content === null || content === undefined) return '';
+  const normalized = typeof content === 'string'
+    ? content.replace(/\r\n/g, '\n')
+    : content;
+  return crypto.createHash('sha256').update(normalized).digest('hex');
+}
+
+/**
+ * Read a file and compute its SHA-256 hash (with CRLF normalization).
+ * Returns null if file does not exist or cannot be read.
+ */
+function computeFileHash(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    const content = fs.readFileSync(filePath, 'utf8');
+    return computeHash(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Create a fresh lockfile data structure.
+ */
+function createLockfileData(options = {}) {
+  return {
+    schemaVersion: 1,
+    installedPackage: options.installedPackage || 'contextos-agents',
+    version: options.version || '1.7.0',
+    selectedProfile: options.selectedProfile || 'default',
+    installedAt: options.installedAt || new Date().toISOString(),
+    managedFiles: options.managedFiles ? { ...options.managedFiles } : {},
+  };
+}
+
+/**
+ * Record a managed file entry in the lockfile data.
+ */
+function recordManagedFile(lockData, relPath, contentOrHash) {
+  if (!lockData || !relPath) return;
+  const norm = normalizePath(relPath);
+  const hash = typeof contentOrHash === 'string' && contentOrHash.length === 64 && /^[0-9a-f]{64}$/i.test(contentOrHash)
+    ? contentOrHash.toLowerCase()
+    : computeHash(contentOrHash);
+
+  lockData.managedFiles[norm] = {
+    sha256: hash,
+    managed: true,
+  };
+}
+
+/**
+ * Load and parse the lockfile from target project directory.
+ * Returns null if lockfile does not exist or is invalid.
+ */
+function loadLockfile(projectDir) {
+  try {
+    const lockfilePath = path.join(projectDir, LOCKFILE_REL_PATH);
+    if (!fs.existsSync(lockfilePath)) return null;
+
+    const raw = fs.readFileSync(lockfilePath, 'utf8');
+    const parsed = JSON.parse(raw);
+
+    if (parsed && parsed.schemaVersion === 1 && typeof parsed.managedFiles === 'object') {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save lockfile data to target project directory atomically.
+ */
+function saveLockfile(projectDir, lockData) {
+  const lockfilePath = path.join(projectDir, LOCKFILE_REL_PATH);
+  const lockfileDir = path.dirname(lockfilePath);
+
+  if (!fs.existsSync(lockfileDir)) {
+    fs.mkdirSync(lockfileDir, { recursive: true });
+  }
+
+  const tmpPath = `${lockfilePath}.tmp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const content = JSON.stringify(lockData, null, 2) + '\n';
+
+  try {
+    fs.writeFileSync(tmpPath, content, 'utf8');
+    fs.renameSync(tmpPath, lockfilePath);
+  } catch (err) {
+    try {
+      if (fs.existsSync(tmpPath)) fs.unlinkSync(tmpPath);
+    } catch {}
+    // Fallback direct write
+    fs.writeFileSync(lockfilePath, content, 'utf8');
+  }
+}
+
+/**
+ * Check if a given relative path is tracked as a managed file in the lockfile.
+ */
+function isManagedFile(lockData, relPath) {
+  if (!lockData || !lockData.managedFiles) return false;
+  const norm = normalizePath(relPath);
+  return Boolean(lockData.managedFiles[norm]?.managed);
+}
+
+/**
+ * Check if a managed file has been modified by the user compared to its recorded installation hash.
+ * Returns false if file is unmanaged or does not exist on disk.
+ */
+function isFileModified(projectDir, relPath, lockData) {
+  if (!lockData || !lockData.managedFiles) return false;
+  const norm = normalizePath(relPath);
+  const entry = lockData.managedFiles[norm];
+
+  if (!entry || !entry.managed) return false;
+
+  const fullPath = path.join(projectDir, norm);
+  if (!fs.existsSync(fullPath)) return false;
+
+  const diskHash = computeFileHash(fullPath);
+  if (!diskHash) return false;
+
+  return diskHash !== entry.sha256;
+}
+
+/**
+ * Classify a file into an explicit lifecycle state:
+ * - 'UNMANAGED': File not present in lockfile (e.g. user-created skill or config)
+ * - 'MANAGED_CLEAN': File present in lockfile and content matches installation hash
+ * - 'MANAGED_MODIFIED': File present in lockfile but modified on disk by user
+ * - 'MISSING': File present in lockfile but not found on disk
+ */
+function classifyFile(projectDir, relPath, lockData) {
+  const norm = normalizePath(relPath);
+  const fullPath = path.join(projectDir, norm);
+  const exists = fs.existsSync(fullPath);
+  const managed = isManagedFile(lockData, norm);
+
+  if (!managed) return 'UNMANAGED';
+  if (!exists) return 'MISSING';
+
+  return isFileModified(projectDir, norm, lockData) ? 'MANAGED_MODIFIED' : 'MANAGED_CLEAN';
+}
+
+/**
+ * Safe migration helper for existing installations that lack a lockfile.
+ * Recursively scans target project's .agents directory, compares each file
+ * against the distribution sourceDir.
+ *
+ * ONLY files whose content hash exactly matches the distribution source are
+ * claimed as managed. User custom skills or edited files are left unmanaged.
+ */
+function migrateExistingInstallation(projectDir, sourceAgentsDir, options = {}) {
+  const targetAgentsDir = path.join(projectDir, '.agents');
+  const lockData = createLockfileData(options);
+
+  if (!fs.existsSync(targetAgentsDir)) {
+    if (!options.inMemory && !options.dryRun) {
+      saveLockfile(projectDir, lockData);
+    }
+    return lockData;
+  }
+
+  function walk(currentDir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        walk(fullPath);
+      } else if (entry.isFile()) {
+        // Skip lockfile itself
+        if (entry.name === 'contextos.lock.json') continue;
+
+        const relToAgents = path.relative(targetAgentsDir, fullPath).replace(/\\/g, '/');
+        const relToProject = `.agents/${relToAgents}`;
+
+        const sourceFile = path.join(sourceAgentsDir, relToAgents);
+        if (fs.existsSync(sourceFile) && fs.statSync(sourceFile).isFile()) {
+          const targetHash = computeFileHash(fullPath);
+          const sourceHash = computeFileHash(sourceFile);
+
+          if (targetHash && sourceHash && targetHash === sourceHash) {
+            recordManagedFile(lockData, relToProject, targetHash);
+          }
+        }
+      }
+    }
+  }
+
+  walk(targetAgentsDir);
+  if (!options.inMemory && !options.dryRun) {
+    saveLockfile(projectDir, lockData);
+  }
+  return lockData;
+}
+
+module.exports = {
+  LOCKFILE_REL_PATH,
+  normalizePath,
+  computeHash,
+  computeFileHash,
+  createLockfileData,
+  recordManagedFile,
+  loadLockfile,
+  saveLockfile,
+  isManagedFile,
+  isFileModified,
+  classifyFile,
+  migrateExistingInstallation,
+};

package/bin/lib/safe-writer.js

@@ -0,0 +1,259 @@
+/**
+ * bin/lib/safe-writer.js
+ * Safe Atomic File Writer & Conflict Management for ContextOS
+ *
+ * Implements non-destructive file writes and uninstalls:
+ * - Classified actions: CREATE, UPDATE, CONFLICT, SKIP, DELETE
+ * - Unmanaged user-created files are NEVER touched or deleted
+ * - User-modified managed files trigger sidecar (.contextos.new) without overwriting user work
+ * - Atomic write via temporary file + rename with rollback on failure
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  normalizePath,
+  computeHash,
+  computeFileHash,
+  classifyFile,
+  recordManagedFile,
+  isManagedFile,
+} = require('./lockfile.js');
+
+/**
+ * Atomically write content to a file with directory creation and rollback.
+ */
+function atomicWriteFile(targetPath, content) {
+  const dir = path.dirname(targetPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const tmpPath = `${targetPath}.tmp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  try {
+    fs.writeFileSync(tmpPath, content, 'utf8');
+    fs.renameSync(tmpPath, targetPath);
+  } catch (err) {
+    try {
+      if (fs.existsSync(tmpPath)) fs.unlinkSync(tmpPath);
+    } catch {}
+    // Direct write fallback
+    fs.writeFileSync(targetPath, content, 'utf8');
+  }
+}
+
+/**
+ * Clean up empty parent directories up to the .agents boundary.
+ */
+function cleanEmptyParentDirectories(filePath) {
+  let currentDir = path.dirname(filePath);
+  while (
+    currentDir &&
+    currentDir.includes('.agents') &&
+    !currentDir.endsWith('.agents') &&
+    !currentDir.endsWith('.agents/') &&
+    !currentDir.endsWith('.agents\\')
+  ) {
+    try {
+      const entries = fs.readdirSync(currentDir);
+      if (entries.length === 0) {
+        fs.rmdirSync(currentDir);
+        currentDir = path.dirname(currentDir);
+      } else {
+        break;
+      }
+    } catch {
+      break;
+    }
+  }
+}
+
+/**
+ * Plan a file write operation against the current filesystem and lockfile state.
+ *
+ * Returns an ActionPlan:
+ * - 'CREATE': File does not exist on disk yet
+ * - 'SKIP': File exists and is either already identical ('UP_TO_DATE') or user-created ('UNMANAGED_USER_FILE')
+ * - 'UPDATE': Clean managed file with updated content
+ * - 'CONFLICT': Managed file that the user has customized; writes to .contextos.new
+ */
+function planFileWrite({ projectDir, relPath, content, lockData, options = {} }) {
+  const normRel = normalizePath(relPath);
+  const fullPath = path.join(projectDir, normRel);
+  const newHash = computeHash(content);
+
+  if (!fs.existsSync(fullPath)) {
+    return {
+      action: 'CREATE',
+      relPath: normRel,
+      targetPath: fullPath,
+      newContent: content,
+      newHash,
+      reason: 'NEW_FILE',
+    };
+  }
+
+  const classification = classifyFile(projectDir, normRel, lockData);
+
+  if (classification === 'UNMANAGED') {
+    return {
+      action: 'SKIP',
+      relPath: normRel,
+      targetPath: fullPath,
+      reason: 'UNMANAGED_USER_FILE',
+    };
+  }
+
+  if (classification === 'MANAGED_MODIFIED') {
+    const conflictFullPath = `${fullPath}.contextos.new`;
+    const conflictRelPath = `${normRel}.contextos.new`;
+    return {
+      action: 'CONFLICT',
+      relPath: normRel,
+      targetPath: fullPath,
+      conflictFullPath,
+      conflictPath: conflictRelPath,
+      newContent: content,
+      newHash,
+      reason: 'USER_MODIFIED',
+    };
+  }
+
+  // MANAGED_CLEAN: check if content changed
+  const diskHash = computeFileHash(fullPath);
+  if (diskHash === newHash) {
+    return {
+      action: 'SKIP',
+      relPath: normRel,
+      targetPath: fullPath,
+      reason: 'UP_TO_DATE',
+    };
+  }
+
+  return {
+    action: 'UPDATE',
+    relPath: normRel,
+    targetPath: fullPath,
+    newContent: content,
+    oldHash: diskHash,
+    newHash,
+    reason: 'CONTENT_UPDATED',
+  };
+}
+
+/**
+ * Execute a planned file write operation.
+ */
+function executeFileWrite(planItem, lockData, { dryRun = false } = {}) {
+  if (dryRun) {
+    return { ...planItem, executed: false, dryRun: true };
+  }
+
+  if (planItem.action === 'SKIP') {
+    return { ...planItem, executed: false };
+  }
+
+  if (planItem.action === 'CREATE' || planItem.action === 'UPDATE') {
+    atomicWriteFile(planItem.targetPath, planItem.newContent);
+    if (lockData) {
+      recordManagedFile(lockData, planItem.relPath, planItem.newHash || planItem.newContent);
+    }
+    return { ...planItem, executed: true };
+  }
+
+  if (planItem.action === 'CONFLICT') {
+    const conflictTarget = planItem.conflictFullPath || `${planItem.targetPath}.contextos.new`;
+    atomicWriteFile(conflictTarget, planItem.newContent);
+    return {
+      ...planItem,
+      executed: true,
+      conflictPath: planItem.conflictPath || `${planItem.relPath}.contextos.new`,
+    };
+  }
+
+  return { ...planItem, executed: false };
+}
+
+/**
+ * Plan a file deletion operation during uninstall or cleanup.
+ *
+ * Returns ActionPlan:
+ * - 'DELETE': Managed file whose disk content matches installation hash (clean)
+ * - 'SKIP': File is unmanaged ('UNMANAGED_USER_FILE'), modified by user ('USER_MODIFIED_PRESERVED'),
+ *           or already gone ('ALREADY_MISSING').
+ */
+function planFileDelete({ projectDir, relPath, lockData, options = {} }) {
+  const normRel = normalizePath(relPath);
+  const fullPath = path.join(projectDir, normRel);
+  const classification = classifyFile(projectDir, normRel, lockData);
+
+  if (classification === 'UNMANAGED') {
+    return {
+      action: 'SKIP',
+      relPath: normRel,
+      targetPath: fullPath,
+      reason: 'UNMANAGED_USER_FILE',
+    };
+  }
+
+  if (classification === 'MANAGED_MODIFIED') {
+    return {
+      action: 'SKIP',
+      relPath: normRel,
+      targetPath: fullPath,
+      reason: 'USER_MODIFIED_PRESERVED',
+    };
+  }
+
+  if (classification === 'MISSING') {
+    return {
+      action: 'SKIP',
+      relPath: normRel,
+      targetPath: fullPath,
+      reason: 'ALREADY_MISSING',
+    };
+  }
+
+  return {
+    action: 'DELETE',
+    relPath: normRel,
+    targetPath: fullPath,
+    reason: 'MANAGED_CLEAN',
+  };
+}
+
+/**
+ * Execute a planned file deletion operation.
+ */
+function executeFileDelete(planItem, lockData, { dryRun = false } = {}) {
+  if (dryRun) {
+    return { ...planItem, executed: false, dryRun: true };
+  }
+
+  if (planItem.action === 'DELETE') {
+    if (fs.existsSync(planItem.targetPath)) {
+      try {
+        fs.unlinkSync(planItem.targetPath);
+      } catch (err) {
+        return { ...planItem, executed: false, error: err.message };
+      }
+    }
+
+    if (lockData && lockData.managedFiles) {
+      delete lockData.managedFiles[planItem.relPath];
+    }
+
+    cleanEmptyParentDirectories(planItem.targetPath);
+    return { ...planItem, executed: true };
+  }
+
+  return { ...planItem, executed: false };
+}
+
+module.exports = {
+  atomicWriteFile,
+  planFileWrite,
+  executeFileWrite,
+  planFileDelete,
+  executeFileDelete,
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "contextos-agents",
-  "version": "1.6.1",
-  "description": "Install a .agents folder into your project to teach AI assistants best practices: UI/UX, architecture, security, and engineering workflow skills.",
+  "version": "1.7.0",
+  "description": "ContextOS — Deterministic context compiler, MCP runtime, and high-precision agent skills for pair-programming.",
   "bin": {
     "contextos": "./bin/index.js",
     "contextos-agents": "./bin/index.js",
@@ -25,8 +25,7 @@
     ".agents/adapters",
     ".agents/core",
     ".agents/generated",
-    ".agents/mcp",
-    "benchmarks/gemini-issues.js"
+    ".agents/plugins/contextos"
   ],
   "scripts": {
     "build": "node .agents/ctx.js export all",
@@ -39,8 +38,8 @@
     "check:secrets": "node scripts/check-secrets.js --all",
     "setup:hooks": "node scripts/install-hooks.js",
     "watch": "node .agents/watch.js",
-    "test": "node --test --test-concurrency=1 tests/install.test.js tests/export.test.js tests/skills.test.js tests/validate.test.js tests/plugins.test.js tests/benchmark.test.js tests/profile.test.js tests/resolver.test.js",
-    "prepublishOnly": "npm run validate && cd contextos-mcp && npm install && npm run build:bundle && cd .. && npm run build"
+    "test": "node --test --test-concurrency=1 tests/install.test.js tests/lockfile.test.js tests/safe-writer.test.js tests/adapter-safety.test.js tests/update.test.js tests/uninstall.test.js tests/plugin-security.test.js tests/export.test.js tests/skills.test.js tests/validate.test.js tests/plugins.test.js tests/benchmark.test.js tests/profile.test.js tests/resolver.test.js tests/cli-registry.test.js tests/profile-enforcement.test.js tests/doctor-hardening.test.js",
+    "prepublishOnly": "cd contextos-mcp && npm install && npm run build && npm run build:root-sync && cd .. && npm run validate && npm run build"
   },
   "keywords": [
     "ai",

package/registry.json

@@ -12,7 +12,9 @@
       "npm": null,
       "github": "kok-o/contextos-agents",
       "path": ".agents/core/skills/ponytail-mindset",
-      "builtin": true
+      "builtin": true,
+      "type": "instruction-only",
+      "resources": ["EXAMPLES.md", "SKILL.md", "TROUBLESHOOTING.md", "VALIDATION.json"]
     },
     {
       "id": "koko-o/gstack-roles",
@@ -23,7 +25,9 @@
       "npm": null,
       "github": "kok-o/contextos-agents",
       "path": ".agents/core/skills/gstack-roles",
-      "builtin": true
+      "builtin": true,
+      "type": "instruction-only",
+      "resources": ["EXAMPLES.md", "SKILL.md", "TROUBLESHOOTING.md", "VALIDATION.json"]
     },
     {
       "id": "koko-o/impeccable-design",
@@ -34,18 +38,22 @@
       "npm": null,
       "github": "kok-o/contextos-agents",
       "path": ".agents/core/skills/impeccable-design",
-      "builtin": true
+      "builtin": true,
+      "type": "instruction-only",
+      "resources": ["EXAMPLES.md", "SKILL.md", "TROUBLESHOOTING.md", "VALIDATION.json"]
     },
     {
       "id": "koko-o/graphify",
       "name": "graphify",
-      "description": "Codebase knowledge graph generator via Tree-sitter AST parsing and semantic indexing.",
+      "description": "Codebase knowledge graph generator and architecture mapping guide. Instructs agents on AST dependency extraction and blast radius analysis.",
       "author": "koko-o",
       "tags": ["knowledge-graph", "ast", "tree-sitter", "dependencies", "architecture"],
       "npm": null,
       "github": "kok-o/contextos-agents",
       "path": ".agents/core/skills/graphify",
-      "builtin": true
+      "builtin": true,
+      "type": "instruction-only",
+      "resources": ["EXAMPLES.md", "SKILL.md", "VALIDATION.json"]
     }
   ],
   "contributing": "https://github.com/kok-o/contextos-agents/blob/main/CONTRIBUTING.md#publishing-a-skill-as-a-plugin",

package/registry.schema.json

@@ -25,7 +25,9 @@
         "npm":         { "type": ["string", "null"], "description": "npm package name if published" },
         "github":      { "type": ["string", "null"], "description": "GitHub repo in owner/repo format" },
         "path":        { "type": ["string", "null"], "description": "Path within the GitHub repo to the skill directory" },
-        "builtin":     { "type": "boolean", "description": "true = ships with contextos-agents core" }
+        "builtin":     { "type": "boolean", "description": "true = ships with contextos-agents core" },
+        "type":        { "type": "string", "enum": ["instruction-only", "compiler", "runtime", "experimental"], "description": "Skill capability model" },
+        "resources":   { "type": "array", "items": { "type": "string" }, "description": "Explicit manifest of files bundled with this skill" }
       }
     }
   }