contextos-agents 1.6.1 → 1.7.0

package/bin/commands/uninstall.js

@@ -0,0 +1,207 @@
+/**
+ * bin/commands/uninstall.js
+ * ContextOS CLI — Safe Uninstall Command
+ *
+ * Removes ContextOS artifacts safely:
+ * - Only deletes clean managed files (content matches installation hash)
+ * - Never deletes user-modified managed files (USER_MODIFIED_PRESERVED)
+ * - Never deletes user-created custom skills or unmanaged files
+ * - Preserves .agents/ directory if user files remain
+ * - Removes .agents/ cleanly if no user files remain
+ * - Supports --dry-run
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  loadLockfile,
+  migrateExistingInstallation,
+} = require('../lib/lockfile.js');
+const {
+  planFileDelete,
+  executeFileDelete,
+} = require('../lib/safe-writer.js');
+
+/**
+ * Recursively count all files remaining in a directory (excluding specified skip names).
+ */
+function countFiles(dir, skipNames = new Set()) {
+  let count = 0;
+  if (!fs.existsSync(dir)) return 0;
+
+  try {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (skipNames.has(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        count += countFiles(full, skipNames);
+      } else if (entry.isFile()) {
+        count++;
+      }
+    }
+  } catch {
+    return 0;
+  }
+  return count;
+}
+
+/**
+ * Plan uninstallation for a target project.
+ */
+function planUninstall(projectDir, options = {}) {
+  const targetAgentsDir = path.join(projectDir, '.agents');
+  if (!fs.existsSync(targetAgentsDir)) {
+    return {
+      ok: false,
+      error: 'NO_AGENTS_DIR',
+      message: 'No .agents/ directory found in the target project. Nothing to uninstall.',
+      plans: [],
+      summary: { delete: 0, skipModified: 0, skipUnmanaged: 0, missing: 0 },
+    };
+  }
+
+  const sourceAgentsDir = options.sourceAgentsDir || path.join(__dirname, '..', '..', '.agents');
+
+  // Load existing lockfile or build migration plan
+  let lockData = loadLockfile(projectDir);
+  if (!lockData) {
+    lockData = migrateExistingInstallation(projectDir, sourceAgentsDir, {
+      dryRun: true,
+      inMemory: true,
+    });
+  }
+
+  const plans = [];
+  if (lockData && lockData.managedFiles) {
+    for (const relPath of Object.keys(lockData.managedFiles)) {
+      const plan = planFileDelete({
+        projectDir,
+        relPath,
+        lockData,
+      });
+      plans.push(plan);
+    }
+  }
+
+  // Count unmanaged files in .agents that are not in lockData
+  const managedSet = new Set(Object.keys(lockData?.managedFiles || {}));
+  let unmanagedFilesCount = 0;
+
+  function findUnmanaged(currentDir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const full = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        findUnmanaged(full);
+      } else if (entry.isFile()) {
+        if (entry.name === 'contextos.lock.json') continue;
+        const rel = path.relative(projectDir, full).replace(/\\/g, '/');
+        if (!managedSet.has(rel)) {
+          unmanagedFilesCount++;
+        }
+      }
+    }
+  }
+
+  findUnmanaged(targetAgentsDir);
+
+  const summary = {
+    delete: plans.filter(p => p.action === 'DELETE').length,
+    skipModified: plans.filter(p => p.action === 'SKIP' && p.reason === 'USER_MODIFIED_PRESERVED').length,
+    missing: plans.filter(p => p.action === 'SKIP' && p.reason === 'ALREADY_MISSING').length,
+    skipUnmanaged: unmanagedFilesCount,
+  };
+
+  return {
+    ok: true,
+    plans,
+    summary,
+    lockData,
+  };
+}
+
+/**
+ * Run safe uninstall against a target project.
+ */
+function runUninstall(projectDir = process.cwd(), options = {}) {
+  const dryRun = Boolean(options.dryRun);
+
+  console.log(`\nContextOS Safe Uninstall ${dryRun ? '[DRY-RUN]' : ''}`);
+  console.log(`Target: ${projectDir}`);
+
+  const planned = planUninstall(projectDir, options);
+  if (!planned.ok) {
+    console.error(`\n[ERROR] ${planned.message}`);
+    return planned;
+  }
+
+  const { lockData, plans, summary } = planned;
+
+  console.log('\nPlanned Actions:');
+  for (const item of plans) {
+    if (item.action === 'DELETE') {
+      console.log(`  - DELETE    ${item.relPath}`);
+    } else if (item.reason === 'USER_MODIFIED_PRESERVED') {
+      console.log(`  = PRESERVE  ${item.relPath} (modified by user — will NOT delete)`);
+    }
+  }
+
+  if (summary.skipUnmanaged > 0) {
+    console.log(`  = PRESERVE  ${summary.skipUnmanaged} unmanaged user file(s)/skill(s) in .agents/`);
+  }
+
+  console.log('\nSummary:');
+  console.log(`  To delete:     ${summary.delete}`);
+  console.log(`  Preserved:     ${summary.skipModified} (user-modified) + ${summary.skipUnmanaged} (user-created)`);
+
+  if (dryRun) {
+    console.log('\n[DRY-RUN] No files were deleted.');
+    return { ...planned, executed: false };
+  }
+
+  // Execute deletions
+  let deletedCount = 0;
+  for (const item of plans) {
+    if (item.action === 'DELETE') {
+      const res = executeFileDelete(item, lockData, { dryRun: false });
+      if (res.executed) deletedCount++;
+    }
+  }
+
+  const targetAgentsDir = path.join(projectDir, '.agents');
+  const lockfilePath = path.join(targetAgentsDir, 'contextos.lock.json');
+
+  // Count remaining files in .agents (excluding lockfile)
+  const remainingFiles = countFiles(targetAgentsDir, new Set(['contextos.lock.json']));
+
+  if (remainingFiles === 0) {
+    // Completely clean, remove lockfile and .agents directory
+    try {
+      if (fs.existsSync(lockfilePath)) fs.unlinkSync(lockfilePath);
+      fs.rmSync(targetAgentsDir, { recursive: true, force: true });
+      console.log('\n[OK] ContextOS completely uninstalled. .agents/ removed.');
+    } catch (err) {
+      console.warn(`[WARN] Could not remove .agents directory: ${err.message}`);
+    }
+  } else {
+    // User files or modified files remain — remove lockfile or keep remaining?
+    try {
+      if (fs.existsSync(lockfilePath)) fs.unlinkSync(lockfilePath);
+    } catch {}
+    console.log(`\n[OK] Clean ContextOS artifacts uninstalled (${deletedCount} removed).`);
+    console.log(`[INFO] .agents/ preserved because ${remainingFiles} user-modified or custom file(s) remain.`);
+  }
+
+  return { ...planned, executed: true, deletedCount, remainingFiles };
+}
+
+module.exports = {
+  planUninstall,
+  runUninstall,
+};

package/bin/commands/update.js

@@ -0,0 +1,262 @@
+/**
+ * bin/commands/update.js
+ * ContextOS CLI — Safe Update Command
+ *
+ * Updates ContextOS installation non-destructively:
+ * - Scans distribution package against target project .agents directory
+ * - Plans all mutations: CREATE, UPDATE, CONFLICT, SKIP, DELETE
+ * - Never overwrites user-customized files (generates .contextos.new conflicts)
+ * - Never touches or deletes unmanaged user files or custom skills
+ * - Supports --dry-run to preview changes without modifying filesystem
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  loadLockfile,
+  saveLockfile,
+  migrateExistingInstallation,
+  createLockfileData,
+} = require('../lib/lockfile.js');
+const {
+  planFileWrite,
+  executeFileWrite,
+  planFileDelete,
+  executeFileDelete,
+} = require('../lib/safe-writer.js');
+
+const pkg = require('../../package.json');
+
+/**
+ * Collect all distributable files from the source .agents directory.
+ */
+function collectDistributionFiles(sourceAgentsDir, options = {}) {
+  const files = [];
+  const excludedSkills = new Set(options.excludedSkills || []);
+
+  function walk(currentDir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const full = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        // Skip .git or temp dirs if any
+        if (entry.name === '.git' || entry.name === 'node_modules') continue;
+
+        // Skip excluded skills by profile
+        const relToAgents = path.relative(sourceAgentsDir, full).replace(/\\/g, '/');
+        const coreMatch = relToAgents.match(/^core\/skills\/([^/]+)$/);
+        if (coreMatch && excludedSkills.has(coreMatch[1])) {
+          continue;
+        }
+        const genMatch = relToAgents.match(/^generated\/[^/]+\/skills\/([^/]+)$/);
+        if (genMatch && excludedSkills.has(genMatch[1])) {
+          continue;
+        }
+
+        walk(full);
+      } else if (entry.isFile()) {
+        // Do not distribute lockfile itself or backup files
+        if (entry.name === 'contextos.lock.json' || entry.name.endsWith('.bak')) continue;
+
+        const relToAgents = path.relative(sourceAgentsDir, full).replace(/\\/g, '/');
+        files.push({
+          relPath: `.agents/${relToAgents}`,
+          fullSourcePath: full,
+        });
+      }
+    }
+  }
+
+  walk(sourceAgentsDir);
+  return files;
+}
+
+/**
+ * Plan the update operations for a project.
+ */
+function planUpdate(projectDir, sourceAgentsDir, options = {}) {
+  const targetAgentsDir = path.join(projectDir, '.agents');
+  if (!fs.existsSync(targetAgentsDir)) {
+    return {
+      ok: false,
+      error: 'NO_AGENTS_DIR',
+      message: 'No .agents/ directory found in the target project. Run `contextos` to install first.',
+      plans: [],
+      summary: { create: 0, update: 0, conflict: 0, skip: 0, delete: 0 },
+    };
+  }
+
+  // Load existing lockfile or safely migrate
+  let lockData = loadLockfile(projectDir);
+  let migrated = false;
+  if (!lockData) {
+    lockData = migrateExistingInstallation(projectDir, sourceAgentsDir, {
+      dryRun: Boolean(options.dryRun),
+      version: pkg.version,
+    });
+    migrated = true;
+  }
+
+  // Determine active profile exclusions if available
+  let excludedSkills = [];
+  try {
+    const profilesPath = path.join(projectDir, '.agents', 'profiles.js');
+    if (fs.existsSync(profilesPath)) {
+      const profilesModule = require(profilesPath);
+      const active = profilesModule.getActiveProfile(projectDir);
+      if (active && Array.isArray(active.exclude_skills)) {
+        excludedSkills = active.exclude_skills;
+      }
+    }
+  } catch {}
+
+  const distFiles = collectDistributionFiles(sourceAgentsDir, { excludedSkills });
+  const distRelPaths = new Set(distFiles.map(f => f.relPath));
+
+  const plans = [];
+
+  // 1. Plan writes for distribution files
+  for (const item of distFiles) {
+    try {
+      const content = fs.readFileSync(item.fullSourcePath, 'utf8');
+      const plan = planFileWrite({
+        projectDir,
+        relPath: item.relPath,
+        content,
+        lockData,
+      });
+      plans.push(plan);
+    } catch {}
+  }
+
+  // 2. Plan deletions for stale managed files that no longer exist in distribution
+  if (lockData && lockData.managedFiles) {
+    for (const managedRel of Object.keys(lockData.managedFiles)) {
+      if (managedRel.startsWith('.agents/') && !distRelPaths.has(managedRel)) {
+        const delPlan = planFileDelete({
+          projectDir,
+          relPath: managedRel,
+          lockData,
+        });
+        plans.push(delPlan);
+      }
+    }
+  }
+
+  const summary = {
+    create: plans.filter(p => p.action === 'CREATE').length,
+    update: plans.filter(p => p.action === 'UPDATE').length,
+    conflict: plans.filter(p => p.action === 'CONFLICT').length,
+    skip: plans.filter(p => p.action === 'SKIP').length,
+    delete: plans.filter(p => p.action === 'DELETE').length,
+  };
+
+  return {
+    ok: true,
+    lockData,
+    migrated,
+    plans,
+    summary,
+  };
+}
+
+/**
+ * Run the update command against a target project.
+ */
+function runUpdate(projectDir = process.cwd(), options = {}) {
+  const sourceAgentsDir = options.sourceAgentsDir || path.join(__dirname, '..', '..', '.agents');
+  const dryRun = Boolean(options.dryRun);
+
+  console.log(`\nContextOS Safe Update ${dryRun ? '[DRY-RUN]' : ''}`);
+  console.log(`Target: ${projectDir}`);
+
+  const planned = planUpdate(projectDir, sourceAgentsDir, options);
+  if (!planned.ok) {
+    console.error(`\n[ERROR] ${planned.message}`);
+    return planned;
+  }
+
+  const { lockData, plans, summary } = planned;
+
+  // Print classified plan preview
+  console.log('\nPlanned Actions:');
+  for (const item of plans) {
+    if (item.action === 'CREATE') {
+      console.log(`  + CREATE    ${item.relPath}`);
+    } else if (item.action === 'UPDATE') {
+      console.log(`  ~ UPDATE    ${item.relPath}`);
+    } else if (item.action === 'CONFLICT') {
+      console.log(`  ! CONFLICT  ${item.relPath} → ${item.conflictPath || item.relPath + '.contextos.new'} (customized by user)`);
+    } else if (item.action === 'DELETE') {
+      console.log(`  - DELETE    ${item.relPath} (stale managed file)`);
+    } else if (item.action === 'SKIP' && item.reason === 'UNMANAGED_USER_FILE') {
+      console.log(`  = PRESERVE  ${item.relPath} (unmanaged user file)`);
+    }
+  }
+
+  console.log('\nSummary:');
+  console.log(`  Created:    ${summary.create}`);
+  console.log(`  Updated:    ${summary.update}`);
+  console.log(`  Conflicts:  ${summary.conflict} (written as .contextos.new)`);
+  console.log(`  Deleted:    ${summary.delete}`);
+  console.log(`  Skipped:    ${summary.skip}`);
+
+  if (dryRun) {
+    console.log('\n[DRY-RUN] No changes were written to disk.');
+    return { ...planned, executed: false };
+  }
+
+  // Execute plans
+  let executedCount = 0;
+  for (const item of plans) {
+    if (item.action === 'CREATE' || item.action === 'UPDATE' || item.action === 'CONFLICT') {
+      executeFileWrite(item, lockData, { dryRun: false });
+      if (item.action !== 'SKIP') executedCount++;
+    } else if (item.action === 'DELETE') {
+      executeFileDelete(item, lockData, { dryRun: false });
+      executedCount++;
+    }
+  }
+
+  // Update lockfile metadata
+  lockData.version = options.packageVersion || pkg.version;
+  lockData.updatedAt = new Date().toISOString();
+  saveLockfile(projectDir, lockData);
+
+  console.log(`\n[OK] ContextOS successfully updated to v${lockData.version}!`);
+  if (summary.conflict > 0) {
+    console.warn(`[WARN] ${summary.conflict} customized file(s) had upstream changes.`);
+    console.warn('       Inspect the .contextos.new file(s) to merge upstream updates.');
+  }
+
+  // Re-compile if ctx.js exists and not skipped
+  if (!options.skipCompile) {
+    const ctxPath = path.join(projectDir, '.agents', 'ctx.js');
+    if (fs.existsSync(ctxPath)) {
+      try {
+        const { execFileSync } = require('child_process');
+        console.log('\nRecompiling skills...');
+        execFileSync(process.execPath, [ctxPath, 'export', 'gemini'], {
+          cwd: projectDir,
+          stdio: 'inherit',
+        });
+      } catch (err) {
+        console.warn(`[WARN] Post-update compilation failed: ${err.message}`);
+      }
+    }
+  }
+
+  return { ...planned, executed: true, executedCount };
+}
+
+module.exports = {
+  planUpdate,
+  runUpdate,
+  collectDistributionFiles,
+};