contextos-agents 1.6.1 → 2.0.0-beta.2

package/bin/commands/update.js

@@ -0,0 +1,325 @@
+/**
+ * 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 {
+  LockfileV2Manager,
+  ProjectMutationLock,
+  JournaledTransaction,
+  computeExactHash,
+  computeSemanticHash,
+} = require('../../.agents/filesystem/index.js');
+const {
+  loadLockfile,
+  saveLockfile,
+  recordManagedFile,
+  migrateExistingInstallation,
+} = require('../lib/lockfile.js');
+const {
+  planFileWrite,
+  planFileDelete,
+  cleanEmptyParentDirectories,
+} = 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;
+  
+  const lock = new ProjectMutationLock(projectDir);
+  const lockToken = lock.acquire({ command: 'update' });
+
+  try {
+    const tx = new JournaledTransaction(projectDir);
+
+    for (const item of plans) {
+      if (item.action === 'CREATE' || item.action === 'UPDATE' || item.action === 'CONFLICT') {
+        const targetRel = item.action === 'CONFLICT' ? (item.conflictPath || `${item.relPath}.contextos.new`) : item.relPath;
+        tx.stageWrite(targetRel, item.newContent);
+        if (item.action !== 'SKIP') executedCount++;
+      } else if (item.action === 'DELETE') {
+        tx.stageDelete(item.relPath);
+        executedCount++;
+      }
+    }
+
+    const txResult = tx.commit();
+
+    // Clean up empty directories left behind by deletions
+    for (const item of plans) {
+      if (item.action === 'DELETE') {
+        cleanEmptyParentDirectories(path.join(projectDir, item.relPath));
+      }
+    }
+
+    // Update lockfile metadata via V2 Manager
+    const lockfileManager = new LockfileV2Manager(projectDir);
+    let lockfileData = lockfileManager.read();
+    
+    if (!lockfileData) {
+      lockfileData = lockfileManager.createEmpty({ packageVersion: options.packageVersion || pkg.version });
+    }
+
+    for (const item of plans) {
+      if (item.action === 'CREATE' || item.action === 'UPDATE') {
+        lockfileManager.recordManagedFile(lockfileData, item.relPath, {
+          exactSha256: computeExactHash(item.newContent),
+          semanticTextSha256: computeSemanticHash(item.newContent),
+          kind: 'distribution-skill',
+          generator: 'update',
+          lastTransaction: txResult.txId,
+        });
+      } else if (item.action === 'DELETE') {
+        if (lockfileData.managedFiles && lockfileData.managedFiles[item.relPath]) {
+          delete lockfileData.managedFiles[item.relPath];
+        }
+      }
+    }
+
+    lockfileData.package.version = options.packageVersion || pkg.version;
+    // We update the timestamp equivalent in v2
+    lockfileManager.write(lockfileData);
+
+    if (lockData) {
+      for (const item of plans) {
+        if (item.action === 'CREATE' || item.action === 'UPDATE') {
+          recordManagedFile(lockData, item.relPath, item.newContent);
+        } else if (item.action === 'DELETE') {
+          if (lockData.managedFiles) delete lockData.managedFiles[item.relPath];
+        }
+      }
+      lockData.version = options.packageVersion || pkg.version;
+      saveLockfile(projectDir, lockData);
+    }
+
+  } finally {
+    lock.release(lockToken);
+  }
+
+  console.log(`\n[OK] ContextOS successfully updated!`);
+  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.error(`[ERROR] Post-update compilation failed: ${err.message}`);
+        process.exit(1);
+      }
+    }
+  }
+
+  return { ...planned, executed: true, executedCount };
+}
+
+module.exports = {
+  planUpdate,
+  runUpdate,
+  collectDistributionFiles,
+};

package/bin/commands.js

@@ -0,0 +1,342 @@
+/**
+ * bin/commands.js
+ * ContextOS — Declarative CLI Command Registry & Status Engine
+ *
+ * Defines the canonical registry of CLI commands, options, and handlers.
+ * Supports structured execution and machine-readable --json output.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { version } = require('../package.json');
+const profiles = require('../.agents/profiles.js');
+const lockfileLib = require('./lib/lockfile.js');
+
+/**
+ * Collects holistic status metadata for a target project.
+ *
+ * @param {string} [projectDir=process.cwd()] - Project directory
+ * @returns {Object} Structured project status
+ */
+function getStatus(projectDir = process.cwd()) {
+  const agentsDir = path.join(projectDir, '.agents');
+  const hasAgents = fs.existsSync(agentsDir);
+  const lockData = lockfileLib.loadLockfile(projectDir);
+  const activeProfile = hasAgents ? profiles.getActiveProfile(projectDir) : null;
+  
+  let skillsCount = 0;
+  const skillsDir = path.join(agentsDir, 'core', 'skills');
+  if (fs.existsSync(skillsDir)) {
+    try {
+      skillsCount = fs.readdirSync(skillsDir, { withFileTypes: true })
+        .filter(d => d.isDirectory() && fs.existsSync(path.join(skillsDir, d.name, 'SKILL.md')))
+        .length;
+    } catch {
+      skillsCount = 0;
+    }
+  }
+
+  const mcpServerPath = path.join(agentsDir, 'mcp', 'server.mjs');
+  const mcpInstalled = fs.existsSync(mcpServerPath);
+
+  // Check compiled adapter outputs
+  const compiledAdapters = [];
+  if (fs.existsSync(path.join(agentsDir, 'generated', 'gemini', 'skills'))) compiledAdapters.push('gemini');
+  if (fs.existsSync(path.join(agentsDir, 'generated', 'claude', 'skills'))) compiledAdapters.push('claude');
+  if (fs.existsSync(path.join(projectDir, '.cursorrules')) || fs.existsSync(path.join(projectDir, '.cursor', 'rules'))) compiledAdapters.push('cursor');
+  if (fs.existsSync(path.join(projectDir, '.github', 'copilot-instructions.md'))) compiledAdapters.push('copilot');
+  if (fs.existsSync(path.join(projectDir, '.aider.conf.yml'))) compiledAdapters.push('aider');
+  if (fs.existsSync(path.join(projectDir, '.zed', 'rules.md'))) compiledAdapters.push('zed');
+
+  return {
+    package: 'contextos-agents',
+    version,
+    projectDir,
+    initialized: hasAgents,
+    activeProfile: activeProfile ? activeProfile.profile : (lockData?.selectedProfile || 'none'),
+    skillsCount,
+    mcpInstalled,
+    compiledAdapters,
+    lockfile: lockData ? {
+      schemaVersion: lockData.schemaVersion,
+      version: lockData.version,
+      managedFilesCount: Object.keys(lockData.managedFiles || {}).length,
+      selectedProfile: lockData.selectedProfile,
+      installedAt: lockData.installedAt,
+      updatedAt: lockData.updatedAt,
+    } : null,
+  };
+}
+
+/**
+ * Formats status object as human-readable text.
+ *
+ * @param {Object} status - Status object
+ * @returns {string} Formatted text
+ */
+function formatStatusText(status) {
+  const lines = [
+    `ContextOS Project Status (v${status.version})`,
+    `──────────────────────────────────────────────`,
+    `  Project Dir       : ${status.projectDir}`,
+    `  Initialized       : ${status.initialized ? 'Yes (.agents/ found)' : 'No (run: npx contextos-agents init)'}`,
+    `  Active Profile    : ${status.activeProfile}`,
+    `  Skills Installed  : ${status.skillsCount}`,
+    `  MCP Server        : ${status.mcpInstalled ? 'Installed (.agents/mcp/)' : 'Not installed'}`,
+    `  Adapters Compiled : ${status.compiledAdapters.length ? status.compiledAdapters.join(', ') : 'none'}`,
+  ];
+
+  if (status.lockfile) {
+    lines.push(`  Lockfile          : Valid (${status.lockfile.managedFilesCount} managed files, v${status.lockfile.version})`);
+  } else if (status.initialized) {
+    lines.push(`  Lockfile          : Missing (.agents/contextos.lock.json)`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Registry of canonical ContextOS CLI commands.
+ */
+const COMMAND_REGISTRY = {
+  init: {
+    name: 'init',
+    description: 'Compile and govern engineering context across AI coding agents.',
+    usage: 'npx contextos-agents init [options]',
+    requiresProject: false,
+    options: [
+      { flag: '--agent <target>', desc: 'Target agent (gemini, claude, cursor, auto)' },
+      { flag: '--profile <name>', desc: 'Apply specific profile (mvp, startup, enterprise, etc.)' },
+      { flag: '--auto', desc: 'Auto-detect tech stack and recommended profile' },
+      { flag: '--minimal', desc: 'Install the 7-skill neutral bootstrap.' },
+      { flag: '--force', desc: 'Overwrite existing installation' },
+      { flag: '--dry-run', desc: 'Preview installation actions without writing' },
+      { flag: '--skip-compile', desc: 'Skip auto-compiling skills after install' },
+    ],
+  },
+  status: {
+    name: 'status',
+    description: 'Display project configuration, active profile, and lockfile status',
+    usage: 'contextos status [--json]',
+    requiresProject: false,
+    options: [
+      { flag: '--json', desc: 'Output status in JSON format' },
+    ],
+  },
+  update: {
+    name: 'update',
+    description: 'Safely update skills without overwriting user custom changes',
+    usage: 'contextos update [--dry-run] [--profile <name>] [--json]',
+    requiresProject: true,
+    options: [
+      { flag: '--dry-run', desc: 'Preview updates without modifying disk' },
+      { flag: '--profile <name>', desc: 'Switch profile during update' },
+      { flag: '--json', desc: 'Output results in JSON format' },
+    ],
+  },
+  uninstall: {
+    name: 'uninstall',
+    description: 'Safely uninstall managed ContextOS files (preserves user custom skills)',
+    usage: 'contextos uninstall [--dry-run] [--json]',
+    requiresProject: true,
+    options: [
+      { flag: '--dry-run', desc: 'Preview deletions without modifying disk' },
+      { flag: '--json', desc: 'Output results in JSON format' },
+    ],
+  },
+  doctor: {
+    name: 'doctor',
+    description: 'Run project diagnostic health check (Doctor v2)',
+    usage: 'contextos doctor [--fix] [--strict] [--json]',
+    requiresProject: false,
+    options: [
+      { flag: '--fix', desc: 'Automatically remediate safe diagnostic issues and clean caches' },
+      { flag: '--strict', desc: 'Exit with non-zero code on any warning' },
+      { flag: '--json', desc: 'Output health report in versioned JSON format' },
+    ],
+  },
+  recover: {
+    name: 'recover',
+    description: 'List, rollback, or resume stuck filesystem transactions',
+    usage: 'contextos recover [--list] [--rollback <txId>] [--resume <txId>]',
+    requiresProject: true,
+    options: [
+      { flag: '--list', desc: 'List pending or broken transactions requiring recovery' },
+      { flag: '--rollback <txId>', desc: 'Rollback a broken transaction' },
+      { flag: '--resume <txId>', desc: 'Resume and complete a stuck transaction' },
+    ],
+  },
+  compile: {
+    name: 'compile',
+    description: 'Compile skill manifests into deterministic registry v2 (registry.v2.json)',
+    usage: 'contextos compile [--check] [--sarif] [--json]',
+    requiresProject: true,
+    options: [
+      { flag: '--check', desc: 'Validate manifests without writing to disk' },
+      { flag: '--sarif', desc: 'Output diagnostics in SARIF 2.1.0 format' },
+      { flag: '--json', desc: 'Output result in JSON format' },
+    ],
+  },
+  validate: {
+    name: 'validate',
+    description: 'Validate skill sources, frontmatter, dependency graph, and adapter sync',
+    usage: 'contextos validate',
+    requiresProject: true,
+    aliases: ['audit'],
+    options: [],
+  },
+  audit: {
+    name: 'audit',
+    target: 'validate',
+    description: 'Alias for validate (check skills and sync)',
+    usage: 'contextos audit',
+    requiresProject: true,
+    options: [],
+  },
+  export: {
+    name: 'export',
+    description: 'Compile skills for target agent (gemini, claude, cursor, copilot, aider, zed, all)',
+    usage: 'contextos export <target> [--profile <name>]',
+    requiresProject: true,
+    options: [
+      { flag: '--profile <name>', desc: 'Apply profile for this export run' },
+    ],
+  },
+  profile: {
+    name: 'profile',
+    description: 'Manage project profiles (list, show, explain, apply, remove)',
+    usage: 'contextos profile <list|show|explain|apply|remove> [name] [--scope <pkg>] [--no-export] [--json]',
+    requiresProject: true,
+    options: [
+      { flag: '--scope <path>', desc: 'Scope profile application or removal to specific package' },
+      { flag: '--no-export', desc: 'Skip re-exporting adapter skills after applying profile' },
+      { flag: '--json', desc: 'Output profile information in JSON format' },
+    ],
+  },
+  resolve: {
+    name: 'resolve',
+    description: 'Dynamically resolve minimal skills needed for a prompt or files',
+    usage: 'contextos resolve <prompt> [--files <a,b>] [--phase <p>] [--explain] [--budget <n>] [--json]',
+    requiresProject: true,
+    options: [
+      { flag: '--files <list>', desc: 'Comma-separated list of touched files' },
+      { flag: '--phase <name>', desc: 'Lifecycle phase (Define, Plan, Build, Verify, Review, Ship)' },
+      { flag: '--explain', desc: 'Display evidence scoring and decision breakdown' },
+      { flag: '--budget <tokens>', desc: 'Context token budget limit (default: 8000)' },
+      { flag: '--json', desc: 'Output resolution in JSON format' },
+    ],
+  },
+  explain: {
+    name: 'explain',
+    description: 'Inspect rule catalog, enforcement levels, and automated checkers',
+    usage: 'contextos explain [ruleId|skillId] [--rules] [--checkers] [--json]',
+    requiresProject: true,
+    options: [
+      { flag: '--rules', desc: 'Display all declared rules with enforcement levels' },
+      { flag: '--checkers', desc: 'Display all registered automated enforcement checkers' },
+      { flag: '--json', desc: 'Output rule and enforcement data in JSON format' },
+    ],
+  },
+  stats: {
+    name: 'stats',
+    description: 'Display token context savings report',
+    usage: 'contextos stats [--json]',
+    requiresProject: true,
+    options: [
+      { flag: '--json', desc: 'Output context savings in JSON format' },
+    ],
+  },
+  watch: {
+    name: 'watch',
+    description: 'Start continuous file watcher and auto-sync daemon',
+    usage: 'contextos watch',
+    requiresProject: true,
+    options: [],
+  },
+  detect: {
+    name: 'detect',
+    description: 'Auto-detect project tech stack, workspace evidence graph, and scope',
+    usage: 'contextos detect [--scope <path>] [--explain] [--json]',
+    requiresProject: false,
+    options: [
+      { flag: '--scope <path>', desc: 'Scope detection to nearest package of specific file or directory' },
+      { flag: '--explain', desc: 'Display evidence signals, internal dependencies, and stack breakdown' },
+      { flag: '--json', desc: 'Output workspace graph and detection in JSON format' },
+    ],
+  },
+  'install-skill': {
+    name: 'install-skill',
+    description: 'Interactive community skill installer or install by reference',
+    usage: 'contextos install-skill [<ref> | --from-repo <ref>]',
+    requiresProject: true,
+    options: [
+      { flag: '--from-repo <ref>', desc: 'Install directly from repository ref' },
+    ],
+  },
+  skill: {
+    name: 'skill',
+    description: 'Manage community plugin skills (add, remove, list, search)',
+    usage: 'contextos skill <add|remove|list|search> [args...]',
+    requiresProject: true,
+    options: [],
+  },
+  recover: {
+    name: 'recover',
+    description: 'Recover from interrupted or failed multi-file transactions',
+    usage: 'contextos recover [--status] [--rollback [txId]] [--continue [txId]]',
+    requiresProject: true,
+    options: [
+      { flag: '--status', desc: 'Inspect pending uncommitted transaction journals' },
+      { flag: '--rollback [txId]', desc: 'Roll back uncommitted or failed transaction' },
+      { flag: '--continue [txId]', desc: 'Attempt to resume and complete prepared transaction' },
+    ],
+  },
+};
+
+/**
+ * Resolves a command name or alias to canonical command definition.
+ *
+ * @param {string} name - Command name or alias
+ * @returns {Object|null} Command definition or null if unknown
+ */
+function getCommand(name) {
+  if (!name) return null;
+  const lower = name.toLowerCase().trim();
+  if (COMMAND_REGISTRY[lower]) {
+    const cmd = COMMAND_REGISTRY[lower];
+    if (cmd.target && COMMAND_REGISTRY[cmd.target]) {
+      return COMMAND_REGISTRY[cmd.target];
+    }
+    return cmd;
+  }
+  // Check aliases
+  for (const cmd of Object.values(COMMAND_REGISTRY)) {
+    if (cmd.aliases && cmd.aliases.includes(lower)) {
+      if (cmd.target && COMMAND_REGISTRY[cmd.target]) {
+        return COMMAND_REGISTRY[cmd.target];
+      }
+      return cmd;
+    }
+  }
+  return null;
+}
+
+/**
+ * Checks if a command name is recognized by the registry.
+ *
+ * @param {string} name - Command name to check
+ * @returns {boolean} True if known
+ */
+function isKnownCommand(name) {
+  return getCommand(name) !== null;
+}
+
+module.exports = {
+  COMMAND_REGISTRY,
+  getCommand,
+  isKnownCommand,
+  getStatus,
+  formatStatusText,
+};