contextos-agents 1.6.1 → 2.0.0-beta.2

package/bin/lib/detector.js

@@ -0,0 +1,106 @@
+/**
+ * bin/lib/detector.js
+ * ContextOS — Full Stack & IDE Environment Detector
+ *
+ * Inspects the target repository to detect:
+ *   1. Project tech stack (Next.js, React, NestJS, FastAPI, etc.)
+ *   2. Active developer IDE / agent tools (Cursor, Claude, Zed, VSCode Copilot, Gemini)
+ *   3. Recommended profile and auto-export adapter targets
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const profiles = require('../../.agents/profiles.js');
+
+/**
+ * Detects active IDEs and AI assistant configs in the project.
+ *
+ * @param {string} [projectDir=process.cwd()] - Project directory
+ * @returns {{ detected: string[], recommendedAgents: string[] }}
+ */
+function detectIdeEnvironment(projectDir = process.cwd()) {
+  const detected = [];
+  const recommendedAgents = new Set();
+
+  // 1. Cursor
+  if (fs.existsSync(path.join(projectDir, '.cursor')) || 
+      fs.existsSync(path.join(projectDir, '.cursorrules')) ||
+      fs.existsSync(path.join(projectDir, '.cursor', 'rules'))) {
+    detected.push('Cursor');
+    recommendedAgents.add('cursor');
+  }
+
+  // 2. Claude Code
+  if (fs.existsSync(path.join(projectDir, 'CLAUDE.md')) ||
+      fs.existsSync(path.join(projectDir, '.claude'))) {
+    detected.push('Claude Code');
+    recommendedAgents.add('claude');
+  }
+
+  // 3. Zed
+  if (fs.existsSync(path.join(projectDir, '.zed'))) {
+    detected.push('Zed');
+    recommendedAgents.add('zed');
+  }
+
+  // 4. GitHub Copilot / VSCode
+  if (fs.existsSync(path.join(projectDir, '.github', 'copilot-instructions.md')) ||
+      fs.existsSync(path.join(projectDir, '.vscode'))) {
+    detected.push('GitHub Copilot');
+    recommendedAgents.add('copilot');
+  }
+
+  // 5. Aider
+  if (fs.existsSync(path.join(projectDir, '.aider.conf.yml')) ||
+      fs.existsSync(path.join(projectDir, 'CONVENTIONS.md'))) {
+    detected.push('Aider');
+    recommendedAgents.add('aider');
+  }
+
+  // 6. Gemini / Antigravity
+  if (fs.existsSync(path.join(projectDir, '.gemini')) ||
+      fs.existsSync(path.join(projectDir, 'GEMINI.md'))) {
+    detected.push('Google Gemini / Antigravity');
+    recommendedAgents.add('gemini');
+  }
+
+  // Default agent is gemini if none detected
+  if (recommendedAgents.size === 0) {
+    recommendedAgents.add('gemini');
+  }
+
+  return {
+    detected,
+    recommendedAgents: Array.from(recommendedAgents),
+  };
+}
+
+/**
+ * Performs unified tech stack and IDE environment detection.
+ *
+ * @param {string} [projectDir=process.cwd()] - Project directory
+ * @returns {Object} Full detection report
+ */
+function detectProjectAttributes(projectDir = process.cwd()) {
+  const stack = profiles.detectStack(projectDir);
+  const ide = detectIdeEnvironment(projectDir);
+
+  return {
+    stack,
+    ide,
+    summary: {
+      technologies: stack.detected.length ? stack.detected : ['Generic JavaScript'],
+      ides: ide.detected.length ? ide.detected : ['Standard IDE'],
+      recommendedProfile: stack.recommendedProfile,
+      recommendedAgents: ide.recommendedAgents,
+      recommendedSkills: stack.recommendedSkills,
+    },
+  };
+}
+
+module.exports = {
+  detectIdeEnvironment,
+  detectProjectAttributes,
+};

package/bin/lib/lockfile.js

@@ -0,0 +1,253 @@
+/**
+ * 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.1',
+    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 {}
+    const atomicError = new Error(`Atomic lockfile update failed; original lockfile was preserved: ${err.message}`);
+    atomicError.code = 'CTX_LOCKFILE_ATOMIC_WRITE_FAILED';
+    atomicError.cause = err;
+    throw atomicError;
+  }
+}
+
+/**
+ * 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,290 @@
+/**
+ * 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');
+
+    let renamed = false;
+    let lastError = null;
+    const maxRetries = 3;
+    const delays = [10, 50, 100];
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        fs.renameSync(tmpPath, targetPath);
+        renamed = true;
+        break;
+      } catch (renameErr) {
+        lastError = renameErr;
+        // Check for transient locking errors common on Windows (EPERM, EBUSY, EACCES)
+        const isTransient = renameErr.code === 'EPERM' || renameErr.code === 'EBUSY' || renameErr.code === 'EACCES';
+        if (isTransient && attempt < maxRetries) {
+          const waitMs = delays[attempt];
+          try {
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, waitMs);
+          } catch {
+            const start = Date.now();
+            while (Date.now() - start < waitMs) {}
+          }
+        } else {
+          break;
+        }
+      }
+    }
+
+    if (!renamed) {
+      throw lastError || new Error(`Failed to atomically rename ${tmpPath} to ${targetPath}`);
+    }
+  } catch (err) {
+    try {
+      if (fs.existsSync(tmpPath)) fs.unlinkSync(tmpPath);
+    } catch {}
+    throw err;
+  }
+}
+
+/**
+ * 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,
+  cleanEmptyParentDirectories,
+};