tribunal-kit 9.2.4 → 9.2.6

package/src/cli.js

@@ -0,0 +1,430 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * tribunal-kit CLI Core (TypeScript version)
+ *
+ * Commands are lazy-loaded: only the invoked command's module is require()'d.
+ * This means `tk status` loads ~4 files instead of ~17, cutting startup I/O by ~70%.
+ */
+Object.defineProperty(exports, '__esModule', { value: true });
+exports.main = main;
+const logger_1 = require('./utils/logger');
+const helpers_1 = require('./utils/helpers');
+const PKG = require('../package.json');
+const CURRENT_VERSION = PKG.version;
+// ── Arg Parser ───────────────────────────────────────────
+function parseArgs(argv) {
+  const args = { command: null, flags: {} };
+  const raw = argv.slice(2);
+  for (let i = 0; i < raw.length; i++) {
+    const arg = raw[i];
+    if (!arg.startsWith('-')) {
+      if (!args.command) {
+        args.command = arg;
+      }
+      continue;
+    }
+    if (arg === '--force') {
+      args.flags.force = true;
+    } else if (arg === '--quiet') {
+      args.flags.quiet = true;
+    } else if (arg === '--verbose') {
+      args.flags.verbose = true;
+    } else if (arg === '--dry-run') {
+      args.flags.dryRun = true;
+    } else if (arg === '--minimal') {
+      args.flags.minimal = true;
+    } else if (arg.startsWith('--profile=')) {
+      args.flags.profile = arg.split('=').slice(1).join('=');
+    } else if (arg === '--profile') {
+      const nextVal = raw[++i];
+      args.flags.profile = nextVal || 'full';
+    } else if (arg === '--skip-update-check') {
+      args.flags.skipUpdateCheck = true;
+    } else if (arg === '--write') {
+      args.flags.write = true;
+    } else if (arg === '--head') {
+      args.flags.head = true;
+    } else if (arg.startsWith('--path=')) {
+      args.flags.path = arg.split('=').slice(1).join('=');
+    } else if (arg === '--path') {
+      const nextVal = raw[++i];
+      if (!nextVal || nextVal.startsWith('--')) {
+        console.error(`  \x1b[91m✖ --path requires a directory argument\x1b[0m`);
+        process.exit(1);
+      }
+      args.flags.path = nextVal;
+    } else if (arg.startsWith('--target=')) {
+      args.flags.target = arg.split('=').slice(1).join('=');
+    } else if (arg === '--target') {
+      const nextVal = raw[++i];
+      if (!nextVal || nextVal.startsWith('--')) {
+        console.error(`  \x1b[91m✖ --target requires an argument\x1b[0m`);
+        process.exit(1);
+      }
+      args.flags.target = nextVal;
+    } else if (arg.startsWith('--branch=')) {
+      args.flags.branch = arg.split('=').slice(1).join('=');
+    } else if (arg === '--branch') {
+      args.flags.branch = raw[++i];
+    } else if (arg.startsWith('--log=')) {
+      args.flags.log = arg.split('=').slice(1).join('=');
+    } else if (arg === '--log') {
+      args.flags.log = raw[++i];
+    } else if (arg.startsWith('--strategy=')) {
+      args.flags.strategy = arg.split('=').slice(1).join('=');
+    } else if (arg === '--strategy') {
+      args.flags.strategy = raw[++i];
+    }
+  }
+  return args;
+}
+function cmdHelp(quiet = false) {
+  (0, helpers_1.banner)(quiet);
+  const cmd = (name, desc) =>
+    `  ${(0, logger_1.c)('cyan', name.padEnd(10))}  ${(0, logger_1.c)('gray', desc)}`;
+  const opt = (flag, desc) =>
+    `  ${(0, logger_1.c)('yellow', flag.padEnd(22))}  ${(0, logger_1.c)('gray', desc)}`;
+  const ex = s => `  ${(0, logger_1.c)('gray', '▸')} ${(0, logger_1.c)('white', s)}`;
+  (0, logger_1.log)((0, logger_1.bold)('  Commands'));
+  (0, logger_1.log)(`  ${(0, logger_1.c)('gray', '─'.repeat(40))}`);
+  (0, logger_1.log)(cmd('init', 'Install .agent/ into current project'));
+  (0, logger_1.log)(cmd('update', 'Re-install to get latest version'));
+  (0, logger_1.log)(cmd('status', 'Check if .agent/ is installed'));
+  (0, logger_1.log)(cmd('learn', 'Evolve project idioms based on git diffs'));
+  (0, logger_1.log)(
+    cmd('case', 'Manage Case Law precedents (add, search, list, show, stats, overrule)'),
+  );
+  (0, logger_1.log)(cmd('graph', 'Build and visualize the architecture graph'));
+  (0, logger_1.log)(
+    cmd('arch', 'Architecture Intelligence (map, verify, impact, diff, audit, project)'),
+  );
+  (0, logger_1.log)(cmd('mutate', 'Run the Mutation Engine to test test-suite reliability'));
+  (0, logger_1.log)(cmd('context', 'Retrieve a highly-optimized Context Snapshot for a file'));
+  (0, logger_1.log)(cmd('sync', 'Synchronize IDE bridge files with current rules'));
+  (0, logger_1.log)(
+    cmd('align', 'Clean AI outputs (strip slop, collapse lists, validate code traps)'),
+  );
+  (0, logger_1.log)(cmd('marathon', 'Long-running agent harness (init, status, next, mark)'));
+  (0, logger_1.log)(cmd('hook', 'Install pre-push git hook for auto-learning'));
+  (0, logger_1.log)(
+    cmd('compile', 'Compile rules into a static instruction file for terminal agents'),
+  );
+  (0, logger_1.log)(
+    cmd('memory', '4-Type Taxonomy Persistent Memory Engine (store, recall, gc, stats, export)'),
+  );
+  (0, logger_1.log)(
+    cmd('optimize-skill', 'Optimize project skills actively using SkillOpt validation gates'),
+  );
+  (0, logger_1.log)(cmd('validate', 'Validate a JSON payload against a Tribunal schema'));
+  (0, logger_1.log)(cmd('min-context', 'Remove empty lines from a context file'));
+  (0, logger_1.log)(cmd('dag-schedule', 'Compute parallel execution waves from task dependencies'));
+  (0, logger_1.log)(
+    cmd('context-compress', 'Compress a context file while retaining VERIFY comments'),
+  );
+  (0, logger_1.log)(cmd('optimize-step', 'Apply bounded SkillOpt edits from a JSON payload'));
+  (0, logger_1.log)(
+    cmd('guardrail', 'Validate .agent/ integrity (phantom refs, count mismatches, drift)'),
+  );
+  (0, logger_1.log)(
+    cmd('contract', 'AI Agent Behavioral Contract Testing (init, verify, list, trace, replay)'),
+  );
+  (0, logger_1.log)(cmd('impact-tier', 'Classify task governance impact tier (0-3)'));
+  (0, logger_1.log)(cmd('context-rank', 'Deterministic evidence-driven context ranking and token budgeting'));
+  (0, logger_1.log)(cmd('browse', 'Token-efficient page reader (pruned to <4k bytes)'));
+  (0, logger_1.log)(cmd('audit-web', 'Live browser accessibility, console & vitals auditor'));
+  (0, logger_1.log)(cmd('compare-web', 'Visual regression differ for CI & release gating'));
+  (0, logger_1.log)(
+    cmd('deconstruct', 'Reverse-engineer live web elements into React TSX + Tailwind'),
+  );
+  (0, logger_1.log)(cmd('heal', 'Runtime Sentinel error hunter & live fix verifier'));
+  (0, logger_1.log)(
+    cmd('sdd', 'Subagent-Driven Development workspace & brief slicing (workspace, brief, diff)'),
+  );
+  (0, logger_1.log)(cmd('uninstall', 'Remove .agent/ folder from project'));
+  (0, logger_1.log)(
+    cmd('system1', 'Manage Laya System-1 inference engine (enable, disable, status, clean)'),
+  );
+  console.log();
+  (0, logger_1.log)((0, logger_1.bold)('  Options'));
+  (0, logger_1.log)(`  ${(0, logger_1.c)('gray', '─'.repeat(40))}`);
+  (0, logger_1.log)(opt('--force', 'Overwrite existing .agent/ folder'));
+  (0, logger_1.log)(opt('--path <dir>', 'Install in specific directory'));
+  (0, logger_1.log)(opt('--target <name>', 'Target terminal agent for compile (e.g. aider)'));
+  (0, logger_1.log)(opt('--quiet', 'Suppress all output'));
+  (0, logger_1.log)(opt('--verbose', 'Show detailed debug logging'));
+  (0, logger_1.log)(opt('--dry-run', 'Preview actions without executing'));
+  (0, logger_1.log)(opt('--minimal', 'Install core agents/skills only (~13 agents)'));
+  (0, logger_1.log)(opt('--skip-update-check', 'Skip auto-update version check'));
+  (0, logger_1.log)(opt('--head', '(learn) Diff against last commit instead of staged'));
+  (0, logger_1.log)(opt('--write', '(align) Write aligned output in-place to the target file'));
+  (0, logger_1.log)(opt('--version, -v', 'Print installed version'));
+  console.log();
+  (0, logger_1.log)((0, logger_1.bold)('  Aliases'));
+  (0, logger_1.log)(`  ${(0, logger_1.c)('gray', '─'.repeat(40))}`);
+  (0, logger_1.log)(
+    `  ${(0, logger_1.c)('cyan', 'tk')}  ${(0, logger_1.c)('gray', 'Shorthand for tribunal-kit (e.g., tk init, tk status)')}`,
+  );
+  console.log();
+  (0, logger_1.log)((0, logger_1.bold)('  Examples'));
+  (0, logger_1.log)(`  ${(0, logger_1.c)('gray', '─'.repeat(40))}`);
+  (0, logger_1.log)(ex('npx tribunal-kit init'));
+  (0, logger_1.log)(ex('tk init --force'));
+  (0, logger_1.log)(ex('tk init --path ./my-app'));
+  (0, logger_1.log)(ex('npx tribunal-kit init --dry-run'));
+  (0, logger_1.log)(ex('tk update'));
+  (0, logger_1.log)(ex('tk status'));
+  (0, logger_1.log)(ex('tk learn'));
+  (0, logger_1.log)(ex('tk learn --dry-run'));
+  (0, logger_1.log)(ex('tk learn --head'));
+  (0, logger_1.log)(ex('tk case add'));
+  (0, logger_1.log)(ex('tk case search "useEffect"'));
+  (0, logger_1.log)(ex('tk case list'));
+  (0, logger_1.log)(ex('tk case show --id 1'));
+  (0, logger_1.log)(ex('tk case stats'));
+  (0, logger_1.log)(ex('tk case export'));
+  (0, logger_1.log)(ex('tk case overrule --id 1'));
+  (0, logger_1.log)(ex('tk graph'));
+  (0, logger_1.log)(ex('tk mutate src/utils.js "npm test"'));
+  (0, logger_1.log)(ex('tk marathon init "Build a todo app"'));
+  (0, logger_1.log)(ex('tk marathon status'));
+  (0, logger_1.log)(ex('tk marathon next'));
+  (0, logger_1.log)(ex('tk marathon mark 5 pass'));
+  (0, logger_1.log)(ex('tk hook'));
+  (0, logger_1.log)(ex('tk compile'));
+  (0, logger_1.log)(ex('echo "Certainly! Here is - item 1" | tk align'));
+  (0, logger_1.log)(ex('tk align output.md --write'));
+  (0, logger_1.log)(
+    ex('tk memory store --type semantic --content "Uses PostgreSQL" --tags db,orm'),
+  );
+  (0, logger_1.log)(ex('tk optimize-skill --target project-idioms "npm test"'));
+  (0, logger_1.log)(ex('tk memory recall --query "database" --budget 2000'));
+  (0, logger_1.log)(ex('tk memory gc'));
+  (0, logger_1.log)(ex('tk memory stats'));
+  (0, logger_1.log)(ex('tk memory export'));
+  (0, logger_1.log)(ex('tk uninstall'));
+  console.log();
+}
+// ── Lazy Loaders ─────────────────────────────────────────
+// Each command module is require()'d only when invoked.
+// Running `tk status` loads ~4 files instead of ~17.
+function loadCmd(modulePath, exportName) {
+  return require(modulePath)[exportName];
+}
+async function runWithUpdateCheck(command, flags) {
+  const shouldSkip = flags.skipUpdateCheck || process.env.TK_SKIP_UPDATE_CHECK === '1';
+  if (!shouldSkip && (command === 'init' || command === 'update')) {
+    // version.ts is only loaded for init/update — not every command
+    const { autoUpdateCheck } = require('./utils/version');
+    const originalArgs = process.argv.slice(2);
+    const didReInvoke = await autoUpdateCheck(originalArgs, CURRENT_VERSION);
+    if (didReInvoke) {
+      process.exit(0);
+    }
+  }
+  const quiet = flags.quiet || false;
+  switch (command) {
+    case 'init': {
+      const cmdInit = loadCmd('./commands/init', 'cmdInit');
+      await cmdInit(flags, quiet);
+      break;
+    }
+    case 'update': {
+      const cmdUpdate = loadCmd('./commands/update', 'cmdUpdate');
+      await cmdUpdate(flags);
+      break;
+    }
+    case 'status': {
+      const cmdStatus = loadCmd('./commands/status', 'cmdStatus');
+      cmdStatus(flags, quiet);
+      break;
+    }
+    case 'learn': {
+      const cmdLearn = loadCmd('./commands/learn', 'cmdLearn');
+      await cmdLearn(flags, quiet);
+      break;
+    }
+    case 'case': {
+      const cmdCase = loadCmd('./commands/case', 'cmdCase');
+      await cmdCase(flags, process.argv, quiet);
+      break;
+    }
+    case 'hook': {
+      const cmdHook = loadCmd('./commands/hook', 'cmdHook');
+      cmdHook(flags);
+      break;
+    }
+    case 'graph': {
+      const cmdGraph = loadCmd('./commands/graph', 'cmdGraph');
+      await cmdGraph(flags, quiet);
+      break;
+    }
+    case 'arch': {
+      const cmdArch = loadCmd('./commands/arch', 'cmdArch');
+      await cmdArch(flags, process.argv, quiet);
+      break;
+    }
+    case 'mutate': {
+      const cmdMutate = loadCmd('./commands/mutate', 'cmdMutate');
+      await cmdMutate(flags, process.argv);
+      break;
+    }
+    case 'context': {
+      const cmdContext = loadCmd('./commands/context', 'cmdContext');
+      cmdContext(flags, process.argv);
+      break;
+    }
+    case 'sync': {
+      const cmdSync = loadCmd('./commands/sync', 'cmdSync');
+      await cmdSync();
+      break;
+    }
+    case 'align': {
+      const cmdAlign = loadCmd('./commands/align', 'cmdAlign');
+      await cmdAlign(flags, process.argv, quiet);
+      break;
+    }
+    case 'marathon': {
+      const cmdMarathon = loadCmd('./commands/marathon', 'cmdMarathon');
+      await cmdMarathon(flags, process.argv, quiet);
+      break;
+    }
+    case 'minimal': {
+      const cmdMinimal = loadCmd('./commands/minimal', 'cmdMinimal');
+      cmdMinimal(flags, quiet);
+      break;
+    }
+    case 'compile': {
+      const cmdCompile = loadCmd('./commands/compile', 'cmdCompile');
+      await cmdCompile(flags, quiet);
+      break;
+    }
+    case 'uninstall': {
+      const cmdUninstall = loadCmd('./commands/uninstall', 'cmdUninstall');
+      cmdUninstall(flags, quiet);
+      break;
+    }
+    case 'memory': {
+      const cmdMemory = loadCmd('./commands/memory', 'cmdMemory');
+      await cmdMemory(flags, process.argv, quiet);
+      break;
+    }
+    case 'optimize-skill': {
+      const cmdOptimizeSkill = loadCmd('./commands/optimize', 'cmdOptimizeSkill');
+      await cmdOptimizeSkill(flags, process.argv, quiet);
+      break;
+    }
+    case 'guardrail': {
+      const cmdGuardrail = loadCmd('./commands/guardrail', 'cmdGuardrail');
+      await cmdGuardrail(flags, process.argv, quiet);
+      break;
+    }
+    case 'contract': {
+      const cmdContract = loadCmd('./commands/contract', 'cmdContract');
+      await cmdContract(flags, process.argv, quiet);
+      break;
+    }
+    case 'validate': {
+      const cmdValidate = loadCmd('./commands/validate', 'cmdValidate');
+      cmdValidate(flags, process.argv, quiet);
+      break;
+    }
+    case 'min-context': {
+      const cmdMinContext = loadCmd('./commands/native', 'cmdMinContext');
+      cmdMinContext(process.argv, quiet);
+      break;
+    }
+    case 'dag-schedule': {
+      const cmdDagSchedule = loadCmd('./commands/native', 'cmdDagSchedule');
+      cmdDagSchedule(process.argv, quiet);
+      break;
+    }
+    case 'context-compress': {
+      const cmdContextCompress = loadCmd('./commands/native', 'cmdContextCompress');
+      cmdContextCompress(process.argv, quiet);
+      break;
+    }
+    case 'optimize-step': {
+      const cmdOptimizeStep = loadCmd('./commands/native', 'cmdOptimizeStep');
+      cmdOptimizeStep(process.argv, quiet);
+      break;
+    }
+    case 'impact-tier': {
+      const cmdImpactTier = loadCmd('./commands/native', 'cmdImpactTier');
+      await cmdImpactTier(process.argv, quiet);
+      break;
+    }
+    case 'context-rank': {
+      const cmdContextRank = loadCmd('./commands/context', 'cmdContextRank');
+      cmdContextRank(flags, process.argv, quiet);
+      break;
+    }
+    case 'system1': {
+      const cmdSystem1 = loadCmd('./commands/system1', 'cmdSystem1');
+      await cmdSystem1(flags, process.argv, quiet);
+      break;
+    }
+    case 'browse': {
+      const cmdBrowse = loadCmd('./commands/browse', 'cmdBrowse');
+      await cmdBrowse(flags, process.argv, quiet);
+      break;
+    }
+    case 'audit-web': {
+      const cmdAuditWeb = loadCmd('./commands/audit-web', 'cmdAuditWeb');
+      await cmdAuditWeb(flags, process.argv, quiet);
+      break;
+    }
+    case 'compare-web': {
+      const cmdCompareWeb = loadCmd('./commands/compare-web', 'cmdCompareWeb');
+      await cmdCompareWeb(flags, process.argv, quiet);
+      break;
+    }
+    case 'deconstruct': {
+      const cmdDeconstruct = loadCmd('./commands/deconstruct', 'cmdDeconstruct');
+      await cmdDeconstruct(flags, process.argv, quiet);
+      break;
+    }
+    case 'heal': {
+      const cmdHeal = loadCmd('./commands/heal', 'cmdHeal');
+      await cmdHeal(flags, process.argv, quiet);
+      break;
+    }
+    case 'review': {
+      const cmdReview = loadCmd('./commands/review', 'cmdReview');
+      await cmdReview(flags, process.argv, quiet);
+      break;
+    }
+    case 'sdd': {
+      const cmdSdd = loadCmd('./commands/sdd', 'cmdSdd');
+      await cmdSdd(flags, process.argv, quiet);
+      break;
+    }
+    case 'help':
+    case '--help':
+    case '-h':
+    case null:
+      cmdHelp(quiet);
+      break;
+    case '--version':
+    case '-v':
+      (0, logger_1.log)(CURRENT_VERSION);
+      break;
+    default:
+      (0, logger_1.err)(`Unknown command: "${command}"`);
+      console.log();
+      (0, logger_1.dim)('Run tribunal-kit --help for usage');
+      process.exit(1);
+  }
+}
+// ── Main ──────────────────────────────────────────────────
+async function main() {
+  const { command, flags } = parseArgs(process.argv);
+  (0, logger_1.setLogLevels)(flags.quiet || false, flags.verbose || false);
+  await runWithUpdateCheck(command, flags);
+}
+if (require.main === module) {
+  main().catch(err => {
+    console.error(`\x1b[91m✖ Fatal Error:\x1b[0m ${err.message || err}`);
+    process.exit(1);
+  });
+}

package/src/commands/align.js

@@ -0,0 +1,208 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { _log, err, ok, c, bold, _warn } = require('../utils/logger');
+
+function alignText(text) {
+  if (!text) return '';
+
+  let cleaned = text.trim();
+  let matches = true;
+
+  // 1. Strip Conversational Introduction Slop step-by-step
+  while (matches) {
+    matches = false;
+    const prefixes = [
+      /^(?:sure|certainly|okay|absolutely|great|of course|as requested|as you asked|happy to help|here is|here's|let's|i can help)(?:[^\n]*?)(?:[.!?;:]|\n)\s*/i,
+      /^(?:I'd be happy to help with that\.|I can certainly help you with that\.|Let me help you with that\.|Here's what you requested:)\s*/i,
+      /^(?:here is the implementation|here is the code|here are the details|here is your code|here's the implementation|here's the code|here's the solution|here are the details:)(?:[^\n]*?)(?:[.!?;:]|\n)\s*/i,
+    ];
+
+    for (const regex of prefixes) {
+      const temp = cleaned.replace(regex, '');
+      if (temp !== cleaned) {
+        cleaned = temp.trim();
+        matches = true;
+        break;
+      }
+    }
+  }
+
+  // 2. Strip Conversational Conclusion Slop
+  const outroRegexes = [
+    /[\r\n\s]*(?:i hope this helps|let me know if you need|let me know if this works|please review the code|let me know if you have any questions|feel free to ask|hope that helps|happy coding)(?:.*)$/gi,
+  ];
+
+  for (const regex of outroRegexes) {
+    cleaned = cleaned.replace(regex, '');
+  }
+
+  // 3. Bullet-point collapse logic (1-2 item list -> prose)
+  const lines = cleaned.split(/\r?\n/);
+  const resultLines = [];
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i];
+    const bulletMatch = line.match(/^(\s*)([-*]|\d+\.)\s+(.*)$/);
+
+    if (bulletMatch) {
+      const listItems = [];
+      const indent = bulletMatch[1];
+      let j = i;
+
+      while (j < lines.length) {
+        const nextLine = lines[j];
+        const nextMatch = nextLine.match(/^(\s*)([-*]|\d+\.)\s+(.*)$/);
+        if (nextMatch && nextMatch[1].length === indent.length) {
+          listItems.push({ index: j, content: nextMatch[3] });
+          j++;
+        } else if (nextLine.trim() === '') {
+          if (j + 1 < lines.length) {
+            const lookahead = lines[j + 1];
+            const lookaheadMatch = lookahead.match(/^(\s*)([-*]|\d+\.)\s+(.*)$/);
+            if (lookaheadMatch && lookaheadMatch[1].length === indent.length) {
+              j++;
+              continue;
+            }
+          }
+          break;
+        } else {
+          break;
+        }
+      }
+
+      if (listItems.length > 0 && listItems.length <= 2) {
+        const collapsedProse = listItems
+          .map(item => {
+            let content = item.content.trim();
+            if (content && !/[.!?]$/.test(content)) {
+              content += '.';
+            }
+            if (content) {
+              content = content.charAt(0).toUpperCase() + content.slice(1);
+            }
+            return content;
+          })
+          .join(' ');
+        resultLines.push(indent + collapsedProse);
+        i = j;
+      } else {
+        for (let k = i; k < j; k++) {
+          resultLines.push(lines[k]);
+        }
+        i = j;
+      }
+    } else {
+      resultLines.push(line);
+      i++;
+    }
+  }
+
+  cleaned = resultLines.join('\n');
+  return cleaned.trim();
+}
+
+function validateCodeContent(text) {
+  const warnings = [];
+
+  // Next.js 15 unawaited dynamic properties check
+  const unawaitedNext15Regex =
+    /(?<!await\s+)(cookies|headers|params)\s*\(\s*\)\s*\.\s*(get|has|set|delete|toString)/g;
+  if (unawaitedNext15Regex.test(text)) {
+    warnings.push(
+      'Next.js 15: Found unawaited call to cookies(), headers(), or params(). In Next.js 15+, these are async and must be awaited.',
+    );
+  }
+
+  // React 19 useFormState check
+  if (text.includes('useFormState')) {
+    warnings.push('React 19: Found useFormState. In React 19, this is renamed to useActionState.');
+  }
+
+  // Drizzle .filter() check
+  const drizzleFilterRegex = /\.from\s*\([^)]*\)\s*\.\s*filter\s*\(/;
+  if (drizzleFilterRegex.test(text)) {
+    warnings.push(
+      'Drizzle ORM: Found .from().filter(). Drizzle does not use .filter(), use .where() instead.',
+    );
+  }
+
+  // OpenAI gpt-5 or claude-4-opus checks
+  if (text.includes('gpt-5') || text.includes('claude-4-opus')) {
+    warnings.push('LLM Models: Found references to non-existent models (gpt-5, claude-4-opus).');
+  }
+
+  return warnings;
+}
+
+async function cmdAlign(flags, argv, quiet) {
+  let inputSource = null;
+
+  // Find if a file path is specified
+  const positionalArgs = argv.slice(3).filter(arg => !arg.startsWith('--'));
+  if (positionalArgs.length > 0) {
+    inputSource = positionalArgs[0];
+  } else if (flags.path) {
+    inputSource = flags.path;
+  }
+
+  let textContent = '';
+
+  if (inputSource) {
+    // Read from file
+    const resolvedPath = path.resolve(inputSource);
+    if (!fs.existsSync(resolvedPath)) {
+      err(`File not found: ${inputSource}`);
+      process.exit(1);
+    }
+    textContent = fs.readFileSync(resolvedPath, 'utf8');
+  } else {
+    // Read from stdin
+    textContent = await new Promise(resolve => {
+      let data = '';
+      const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: false,
+      });
+      rl.on('line', line => {
+        data += line + '\n';
+      });
+      rl.on('close', () => {
+        resolve(data);
+      });
+    });
+  }
+
+  const aligned = alignText(textContent);
+  const warnings = validateCodeContent(aligned);
+
+  // Print warnings to stderr so they don't corrupt stdout piping
+  if (warnings.length > 0 && !quiet) {
+    process.stderr.write('\n' + bold(c('yellow', '⚠️  OCAE Alignment Validator Warnings:')) + '\n');
+    for (const warnMsg of warnings) {
+      process.stderr.write(`  ${c('yellow', '●')} ${warnMsg}\n`);
+    }
+    process.stderr.write('\n');
+  }
+
+  if (flags.write && inputSource) {
+    // Write in-place to the file
+    fs.writeFileSync(path.resolve(inputSource), aligned, 'utf8');
+    if (!quiet) {
+      ok(`Aligned output written in-place to: ${c('cyan', inputSource)}`);
+    }
+  } else {
+    // Print to stdout
+    process.stdout.write(aligned + '\n');
+  }
+}
+
+module.exports = {
+  cmdAlign,
+  alignText,
+  validateCodeContent,
+};