@eltonssouza/development-utility-kit 0.10.0

package/bin/cli.js

@@ -0,0 +1,848 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const { spawnSync, spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const help = require('./lib/help');
+const identity = require('./lib/identity');
+const backup = require('./lib/backup');
+const manifestLib = require('./lib/manifest');
+const localDirLib = require('./lib/local-dir');
+const doctor = require('./lib/doctor');
+const lint = require('./lib/lint');
+const adr = require('./lib/adr');
+
+// ─── parseArgs ────────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {{
+ *   command: string|null,
+ *   positional: string[],
+ *   sub: string|null,
+ *   dryRun: boolean,
+ *   help: boolean,
+ *   version: boolean,
+ *   checkOnly: boolean,
+ *   force: boolean,
+ *   apply: boolean,
+ *   filters: string[],
+ *   excludes: string[],
+ *   dashboardPort: string|null,
+ *   dashboardNoOpen: boolean,
+ *   dashboardPassthrough: string[],
+ *   json: boolean,
+ *   strict: boolean,
+ *   categories: string[],
+ * }} ParsedArgs
+ */
+
+/**
+ * Parse the argv of a duk invocation.
+ * @param {string[]} argv
+ * @returns {ParsedArgs}
+ */
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const result = {
+    command: null,
+    positional: [],
+    sub: null,
+    dryRun: false,
+    help: false,
+    version: false,
+    checkOnly: false,
+    force: false,
+    apply: false,
+    filters: [],
+    excludes: [],
+    dashboardPort: null,
+    dashboardNoOpen: false,
+    dashboardPassthrough: [],
+    json: false,
+    strict: false,
+    categories: [],
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--help' || arg === '-h') {
+      result.help = true;
+    } else if (arg === '--version' || arg === '-v') {
+      result.version = true;
+    } else if (arg === '--path') {
+      process.stderr.write(
+        'Error: --path is no longer supported. Use "duk install" from the target directory directly.\n'
+      );
+      process.exit(1);
+    } else if (arg === '--sub') {
+      if (i + 1 < args.length) {
+        result.sub = args[++i];
+      } else {
+        process.stderr.write('Error: --sub requires a directory name argument\n');
+        process.exit(1);
+      }
+    } else if (arg === '--dry-run') {
+      result.dryRun = true;
+    } else if (arg === '--check-only') {
+      result.checkOnly = true;
+    } else if (arg === '--force') {
+      result.force = true;
+    } else if (arg === '--apply') {
+      result.apply = true;
+    } else if (arg === '--filter') {
+      if (i + 1 < args.length) {
+        result.filters.push(args[++i]);
+      } else {
+        process.stderr.write('Error: --filter requires an expression argument\n');
+        process.exit(1);
+      }
+    } else if (arg === '--exclude') {
+      if (i + 1 < args.length) {
+        result.excludes.push(args[++i]);
+      } else {
+        process.stderr.write('Error: --exclude requires a name argument\n');
+        process.exit(1);
+      }
+    } else if (arg === '--port') {
+      if (i + 1 < args.length) {
+        result.dashboardPort = args[++i];
+        result.dashboardPassthrough.push('--port', result.dashboardPort);
+      } else {
+        process.stderr.write('Error: --port requires a port number\n');
+        process.exit(1);
+      }
+    } else if (arg === '--no-open') {
+      result.dashboardNoOpen = true;
+      result.dashboardPassthrough.push('--no-open');
+    } else if (arg === '--json') {
+      result.json = true;
+    } else if (arg === '--strict') {
+      result.strict = true;
+    } else if (arg === '--category') {
+      if (i + 1 < args.length) {
+        // Comma-separated values allowed
+        for (const c of args[++i].split(',')) {
+          const t = c.trim();
+          if (t) result.categories.push(t);
+        }
+      } else {
+        process.stderr.write('Error: --category requires a name argument\n');
+        process.exit(1);
+      }
+    } else if (!arg.startsWith('-')) {
+      if (result.command === null) {
+        // BR-006: normalise update → install
+        result.command = arg === 'update' ? 'install' : arg;
+      } else {
+        result.positional.push(arg);
+      }
+    } else {
+      // Unknown flag — surface usage
+      process.stderr.write(`Warning: unknown flag "${arg}" ignored.\n`);
+    }
+  }
+
+  return result;
+}
+
+// ─── detectProjectType ────────────────────────────────────────────────────────
+
+/**
+ * @typedef {{ type: string, stackHints: string[] }} DetectionResult
+ */
+
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Legacy file-based detector. Newer richer stack detection lives in
+ * `bin/lib/detect-stack.js` (Wave 5 metade B). Kept here because adopt
+ * still uses it for type + stackHints in CLAUDE.md.
+ * @param {string} dir
+ * @returns {DetectionResult}
+ */
+function detectProjectType(dir) {
+  const signals = new Set();
+
+  function scanDir(scanDir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(scanDir);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = path.join(scanDir, entry);
+      if (entry === 'pom.xml' || entry === 'build.gradle') {
+        signals.add('backend');
+        continue;
+      }
+      if (entry === 'n8n') {
+        try {
+          if (fs.statSync(full).isDirectory()) signals.add('automation/n8n');
+        } catch { /* ignore */ }
+        continue;
+      }
+      if (/^docker-compose.*\.yml$/.test(entry)) {
+        try {
+          const content = fs.readFileSync(full, 'utf8');
+          if (content.includes('n8n')) signals.add('automation/n8n');
+        } catch { /* ignore */ }
+        continue;
+      }
+      if (entry === 'package.json') {
+        const pkg = readJsonSafe(full);
+        if (pkg) {
+          const deps = Object.assign({}, pkg.dependencies || {}, pkg.devDependencies || {});
+          if ('react-native' in deps) signals.add('mobile');
+          else if ('@angular/core' in deps) signals.add('frontend-angular');
+          else if ('vite' in deps) signals.add('frontend-vite');
+        }
+      }
+    }
+  }
+
+  scanDir(dir);
+
+  let rootEntries;
+  try {
+    rootEntries = fs.readdirSync(dir);
+  } catch {
+    rootEntries = [];
+  }
+  for (const entry of rootEntries) {
+    const full = path.join(dir, entry);
+    try {
+      if (fs.statSync(full).isDirectory() && !entry.startsWith('.')) {
+        scanDir(full);
+      }
+    } catch { /* ignore */ }
+  }
+
+  const stackHints = Array.from(signals);
+  const hasBackend = signals.has('backend');
+  const hasMobile = signals.has('mobile');
+  const hasFrontend = signals.has('frontend-angular') || signals.has('frontend-vite');
+  const hasN8n = signals.has('automation/n8n');
+  const distinctDomains = [hasBackend, hasMobile, hasFrontend, hasN8n].filter(Boolean).length;
+
+  const friendlyHints = stackHints.map((s) => {
+    if (s === 'frontend-angular') return '@angular/core';
+    if (s === 'frontend-vite') return 'vite';
+    return s;
+  });
+
+  if (distinctDomains >= 3 || (hasBackend && hasMobile && hasN8n)) {
+    return { type: 'complex/multi-domain', stackHints: friendlyHints };
+  }
+  if (distinctDomains === 2) return { type: 'fullstack', stackHints: friendlyHints };
+  if (hasBackend) return { type: 'backend', stackHints: friendlyHints };
+  if (hasMobile) return { type: 'mobile', stackHints: friendlyHints };
+  if (hasFrontend) return { type: 'frontend', stackHints: friendlyHints };
+  if (hasN8n) return { type: 'automation/n8n', stackHints: friendlyHints };
+  return { type: 'fullstack', stackHints: [] };
+}
+
+// ─── package root + version ───────────────────────────────────────────────────
+
+function packageRoot() {
+  return path.resolve(__dirname, '..');
+}
+
+function harnessVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot(), 'package.json'), 'utf8'));
+    return pkg.version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+// ─── adoptProject (install / update) ──────────────────────────────────────────
+
+/**
+ * @typedef {{
+ *   cwd: string,
+ *   sub: string|null,
+ *   dryRun: boolean,
+ *   force: boolean,
+ *   initialIdentity?: string|null,
+ * }} AdoptOptions
+ */
+
+/**
+ * Orchestrate install: drift check → backup → copy → MANIFEST + HARNESS_VERSION
+ * + local/ → CLAUDE.md merge.
+ *
+ * @param {AdoptOptions} opts
+ */
+function adoptProject(opts) {
+  const { cwd, sub, dryRun, force } = opts;
+  const initialIdentity = opts.initialIdentity || null;
+
+  const subDir = sub ? path.join(cwd, sub) : cwd;
+
+  if (sub && !fs.existsSync(subDir)) {
+    process.stderr.write(`Error: subdirectory "${subDir}" does not exist.\n`);
+    process.exit(1);
+  }
+
+  const dr = detectProjectType(subDir);
+
+  const pkgRoot = packageRoot();
+  const srcClaude = path.join(pkgRoot, '.claude');
+  const srcClaudeMd = path.join(pkgRoot, 'CLAUDE.md');
+  const destClaude = path.join(subDir, '.claude');
+  const destClaudeMd = path.join(subDir, 'CLAUDE.md');
+
+  // Item 21 — self-destruction guard.
+  // If install runs inside the harness source tree, the backup step would
+  // `mv srcClaude → srcClaude.bak`, removing the very source about to be
+  // copied. Abort early with a clear message before any destructive op.
+  const pkgRootResolved = path.resolve(pkgRoot);
+  const targetResolved = path.resolve(subDir);
+  if (targetResolved === pkgRootResolved) {
+    process.stderr.write('Error: cannot install harness into its own source tree.\n');
+    process.stderr.write(`Target directory equals the harness package root:\n  ${pkgRootResolved}\n`);
+    process.stderr.write('Run "duk install" from a separate project directory.\n');
+    process.exit(1);
+  }
+  // Secondary check: target has package.json declaring the harness itself.
+  // Catches cases where the path equality misses (symlinks, normalised differently).
+  const targetPkgJsonPath = path.join(targetResolved, 'package.json');
+  if (fs.existsSync(targetPkgJsonPath)) {
+    try {
+      const targetPkg = JSON.parse(fs.readFileSync(targetPkgJsonPath, 'utf8'));
+      if (targetPkg && targetPkg.name === '@eltonssouza/development-utility-kit') {
+        process.stderr.write('Error: cannot install harness into its own source tree.\n');
+        process.stderr.write(`Target package.json declares: ${targetPkg.name}\n`);
+        process.stderr.write('Run "duk install" from a separate project directory.\n');
+        process.exit(1);
+      }
+    } catch {
+      // Ignore parse errors — only the secondary check, primary covers cwd === pkgRoot.
+    }
+  }
+
+  // Drift detection (only if .claude/ already exists and not forced)
+  if (!dryRun && fs.existsSync(destClaude) && !force) {
+    const drift = manifestLib.detectDrift(destClaude);
+    if (drift.hasManifest && (drift.drifted.length > 0 || drift.removed.length > 0)) {
+      process.stderr.write('\nLocal drift detected in .claude/:\n');
+      for (const f of drift.drifted) process.stderr.write(`   - ${f} (sha mismatch)\n`);
+      for (const f of drift.removed) process.stderr.write(`   - ${f} (removed locally)\n`);
+      process.stderr.write('\nOptions:\n');
+      process.stderr.write('  1. duk install --force          # overwrite + backup (drift preserved in .claude.bak)\n');
+      process.stderr.write('  2. Move customisations to .claude/local/  # never touched by install\n');
+      process.stderr.write('  3. Open PR on the harness repo if your change is canonical\n\n');
+      process.stderr.write('Aborted. No changes written.\n');
+      process.exit(1);
+    }
+  }
+
+  if (dryRun) {
+    process.stdout.write('[dry-run] No files will be written.\n');
+    process.stdout.write(`Detected type  : ${dr.type}\n`);
+    process.stdout.write(`Stack hints    : ${dr.stackHints.join(', ') || '(none)'}\n`);
+    process.stdout.write(`Target dir     : ${subDir}\n`);
+    process.stdout.write(`Harness version: ${harnessVersion()}\n`);
+    if (fs.existsSync(destClaude)) {
+      process.stdout.write('  [dry-run] would backup .claude/ -> .claude.bak/\n');
+    }
+    process.stdout.write('  [dry-run] would write .claude/ from package\n');
+    process.stdout.write('  [dry-run] would write .claude/HARNESS_VERSION\n');
+    process.stdout.write('  [dry-run] would write .claude/.MANIFEST (sha256 baseline)\n');
+    localDirLib.ensureLocalDir(destClaude, true);
+    process.stdout.write(`  [dry-run] would write CLAUDE.md${fs.existsSync(destClaudeMd) ? ' (preserving ## Project Identity)' : ' (fresh)'}\n`);
+    process.exit(0);
+  }
+
+  // Backup existing .claude/
+  backup.backupClaudeDir(subDir, false);
+
+  // Copy package .claude/ into target
+  if (!fs.existsSync(srcClaude)) {
+    process.stderr.write(`Error: package .claude/ directory not found at ${srcClaude}\n`);
+    process.exit(1);
+  }
+  backup.copyDir(srcClaude, destClaude);
+
+  // Provision .claude/local/
+  localDirLib.ensureLocalDir(destClaude, false);
+
+  // Write HARNESS_VERSION
+  const version = harnessVersion();
+  manifestLib.writeHarnessVersion(destClaude, version);
+
+  // Generate + write .MANIFEST AFTER everything else is in place
+  manifestLib.writeManifest(destClaude, version);
+
+  // Read template CLAUDE.md
+  let templateContent = '';
+  if (fs.existsSync(srcClaudeMd)) {
+    templateContent = fs.readFileSync(srcClaudeMd, 'utf8');
+  }
+
+  // Determine identity section
+  let identitySection;
+  if (initialIdentity) {
+    identitySection = initialIdentity;
+  } else if (fs.existsSync(destClaudeMd)) {
+    const existingContent = fs.readFileSync(destClaudeMd, 'utf8');
+    const preserved = identity.readIdentitySection(existingContent);
+    identitySection = preserved !== null ? preserved : identity.generateIdentitySection(dr);
+  } else {
+    identitySection = identity.generateIdentitySection(dr);
+  }
+
+  const merged = identity.mergeClaudeMd('', templateContent, identitySection);
+  fs.writeFileSync(destClaudeMd, merged, 'utf8');
+
+  // Confirmation output
+  process.stdout.write('\nProject injection complete.\n');
+  process.stdout.write(`Detected type  : ${dr.type}\n`);
+  process.stdout.write(`Stack hints    : ${dr.stackHints.join(', ') || '(none)'}\n`);
+  process.stdout.write(`Target dir     : ${subDir}\n`);
+  process.stdout.write(`Harness version: ${version}\n`);
+  process.stdout.write('Written        : .claude/ (+ HARNESS_VERSION, .MANIFEST, local/)\n');
+  process.stdout.write('Written        : CLAUDE.md\n');
+}
+
+// ─── newProject (duk new <name>) ──────────────────────────────────────────────
+
+/**
+ * Validate a project folder name (kebab-case-ish, no path separators).
+ * @param {string} name
+ * @returns {string|null} error message or null if valid
+ */
+function validateProjectName(name) {
+  if (!name) return 'Project name is required.';
+  if (name.length > 80) return 'Project name is too long (max 80 chars).';
+  if (/[\s/\\:*?"<>|]/.test(name)) return 'Project name contains invalid characters.';
+  if (name.startsWith('.') || name.startsWith('-')) return 'Project name must not start with "." or "-".';
+  return null;
+}
+
+/**
+ * Scaffold a new project: mkdir + git init + CLAUDE.md placeholder + install.
+ * @param {string} name
+ * @param {{ dryRun: boolean }} options
+ */
+function newProject(name, options) {
+  const err = validateProjectName(name);
+  if (err) {
+    process.stderr.write(`Error: ${err}\n`);
+    process.exit(1);
+  }
+
+  const target = path.resolve(process.cwd(), name);
+  if (fs.existsSync(target)) {
+    process.stderr.write(`Error: folder "${target}" already exists.\n`);
+    process.exit(1);
+  }
+
+  if (options.dryRun) {
+    process.stdout.write('[dry-run] No files will be written.\n');
+    process.stdout.write(`  [dry-run] would mkdir ${target}\n`);
+    process.stdout.write('  [dry-run] would run "git init"\n');
+    process.stdout.write('  [dry-run] would write CLAUDE.md with empty Project Identity\n');
+    process.stdout.write('  [dry-run] would run "duk install" inside the new folder\n');
+    process.exit(0);
+  }
+
+  // 1. mkdir
+  fs.mkdirSync(target, { recursive: true });
+
+  // 2. git init (non-fatal if git not installed; warn and continue)
+  const gitResult = spawnSync('git', ['init', '-q'], {
+    cwd: target,
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+  });
+  if (gitResult.status !== 0) {
+    process.stdout.write('Warning: "git init" failed or git is not in PATH. Continuing without git repo.\n');
+  }
+
+  // 3. Run install with initialIdentity = empty placeholder
+  const placeholderIdentity = identity.emptyIdentitySection(name);
+  adoptProject({
+    cwd: target,
+    sub: null,
+    dryRun: false,
+    force: true, // fresh folder — no drift possible
+    initialIdentity: placeholderIdentity,
+  });
+
+  // 4. Next-steps banner
+  process.stdout.write('\n');
+  process.stdout.write(`Project "${name}" created.\n\n`);
+  process.stdout.write('Next steps:\n');
+  process.stdout.write(`  1. cd ${name}\n`);
+  process.stdout.write('  2. Open Cowork or Claude Code in this folder\n');
+  process.stdout.write('  3. First message: "sabatina pra projeto novo"\n');
+  process.stdout.write('     → stack-discovery skill walks you through 8 questions\n');
+  process.stdout.write('       and fills the Project Identity block.\n');
+}
+
+// ─── checkOnly (duk install --check-only) ────────────────────────────────────
+
+/**
+ * Best-effort lazy loader for an optional sibling module. Returns null if
+ * the module is missing; logs a one-liner about it.
+ * @param {string} relPath relative to bin/lib (e.g. "./detect-stack")
+ * @returns {object|null}
+ */
+function tryRequire(relPath) {
+  try {
+    return require(relPath);
+  } catch (e) {
+    if (e && e.code === 'MODULE_NOT_FOUND' && String(e.message).includes(relPath.replace('./', ''))) {
+      return null;
+    }
+    // Some other error (syntax, runtime) — re-throw with context
+    if (e && e.code === 'MODULE_NOT_FOUND') return null;
+    throw e;
+  }
+}
+
+function checkOnly(opts) {
+  const subDir = opts.sub ? path.join(opts.cwd, opts.sub) : opts.cwd;
+  if (opts.sub && !fs.existsSync(subDir)) {
+    process.stderr.write(`Error: subdirectory "${subDir}" does not exist.\n`);
+    process.exit(1);
+  }
+
+  process.stdout.write('Detecting stack...\n');
+
+  // Prefer the richer detector (other agent — Wave 5 metade B) if present.
+  const detectStackMod = tryRequire('./lib/detect-stack');
+  const versionCheckMod = tryRequire('./lib/version-check');
+
+  let stackInfo = null;
+  if (detectStackMod && typeof detectStackMod.detectStack === 'function') {
+    try {
+      stackInfo = detectStackMod.detectStack(subDir);
+    } catch (e) {
+      process.stderr.write(`Warning: detect-stack failed: ${e.message}\n`);
+    }
+  }
+
+  if (!stackInfo) {
+    // Fallback: use legacy detector
+    const dr = detectProjectType(subDir);
+    stackInfo = {
+      type: dr.type,
+      language: null,
+      framework: null,
+      version: null,
+      detected_from: dr.stackHints,
+    };
+    process.stdout.write('  (detect-stack module not available — using legacy detector)\n');
+  }
+
+  // detect-stack uses `language`; legacy used `lang`. Either is fine.
+  const langValue = stackInfo.language || stackInfo.lang || null;
+  const frameworkValue = stackInfo.framework && stackInfo.framework !== 'unknown'
+    ? stackInfo.framework
+    : null;
+
+  process.stdout.write(`  Detected type   : ${stackInfo.type || '(unknown)'}\n`);
+  if (langValue && langValue !== 'unknown') {
+    const langVer = stackInfo.java_version || stackInfo.node_version
+      || stackInfo.python_version || stackInfo.go_version || '';
+    process.stdout.write(`  Language        : ${langValue}${langVer ? ' ' + langVer : ''}\n`);
+  }
+  if (frameworkValue) {
+    process.stdout.write(`  Framework       : ${frameworkValue}${stackInfo.version ? ' ' + stackInfo.version : ''}\n`);
+  }
+  if (stackInfo.ui_lib) {
+    process.stdout.write(`  UI library      : ${stackInfo.ui_lib}\n`);
+  }
+  if (stackInfo.database && stackInfo.database.length > 0) {
+    process.stdout.write(`  Database        : ${stackInfo.database.join(', ')}\n`);
+  }
+  if (stackInfo.detected_from && stackInfo.detected_from.length > 0) {
+    process.stdout.write(`  Detected from   : ${stackInfo.detected_from.join(', ')}\n`);
+  }
+
+  // Harness version comparison
+  const destClaude = path.join(subDir, '.claude');
+  const localVersion = manifestLib.readHarnessVersion(destClaude);
+  const currentVersion = harnessVersion();
+  process.stdout.write('\n');
+  process.stdout.write(`Local harness   : ${localVersion || '(not installed)'}\n`);
+  process.stdout.write(`Current harness : ${currentVersion}\n`);
+
+  // Latest versions (if the API module is available)
+  if (versionCheckMod && typeof versionCheckMod.getLatestVersions === 'function') {
+    try {
+      const stackKey = stackInfo.framework || stackInfo.lang || stackInfo.type;
+      const latest = versionCheckMod.getLatestVersions(stackKey);
+      if (latest && Object.keys(latest).length > 0) {
+        process.stdout.write('\nLatest stack versions (from registries / fallback JSON):\n');
+        for (const [k, v] of Object.entries(latest)) {
+          if (k.startsWith('_')) continue;
+          process.stdout.write(`  ${k.padEnd(15)} : ${v}\n`);
+        }
+      }
+    } catch (e) {
+      process.stderr.write(`Warning: getLatestVersions failed: ${e.message}\n`);
+    }
+  } else {
+    process.stdout.write('  (version-check module not available — latest versions skipped)\n');
+  }
+
+  // Drift report (no-op write)
+  if (fs.existsSync(destClaude)) {
+    const drift = manifestLib.detectDrift(destClaude);
+    if (drift.hasManifest) {
+      const total = drift.drifted.length + drift.added.length + drift.removed.length;
+      process.stdout.write(`\nDrift           : ${total === 0 ? 'clean' : `${total} file(s)`}\n`);
+      if (total > 0) {
+        for (const f of drift.drifted) process.stdout.write(`  drift          : ${f}\n`);
+        for (const f of drift.added) process.stdout.write(`  added locally  : ${f}\n`);
+        for (const f of drift.removed) process.stdout.write(`  removed locally: ${f}\n`);
+      }
+    } else {
+      process.stdout.write('\nDrift           : (no MANIFEST baseline — run install to create one)\n');
+    }
+  }
+
+  process.stdout.write('\nNothing written. Run `duk install` to apply updates.\n');
+  process.exit(0);
+}
+
+// ─── dashboard ────────────────────────────────────────────────────────────────
+
+/**
+ * Ensure dashboard dependencies are installed, then spawn the server.
+ * @param {string[]} passthroughArgs
+ */
+function dashboard(passthroughArgs) {
+  const pkgRoot = packageRoot();
+  const dashboardDir = path.join(pkgRoot, 'dashboard');
+  const nodeModulesDir = path.join(dashboardDir, 'node_modules');
+  const serverScript = path.join(dashboardDir, 'server.js');
+
+  if (!fs.existsSync(dashboardDir)) {
+    process.stderr.write('Error: dashboard/ directory not found at ' + dashboardDir + '\n');
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(nodeModulesDir)) {
+    process.stdout.write('Installing dashboard dependencies (first run)...\n');
+    const result = spawnSync('npm', ['install', '--prefix', dashboardDir], {
+      stdio: 'inherit',
+      shell: process.platform === 'win32',
+    });
+    if (result.status !== 0) {
+      process.stderr.write('Error: npm install failed for dashboard dependencies.\n');
+      process.exit(result.status !== null ? result.status : 1);
+    }
+  }
+
+  // FR-008: print rtk gain output before starting the server
+  const rtkResult = spawnSync('rtk', ['gain'], {
+    shell: process.platform === 'win32',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  if (rtkResult.status === 0 && rtkResult.stdout && rtkResult.stdout.length > 0) {
+    process.stdout.write(rtkResult.stdout);
+  } else {
+    process.stdout.write('Note: rtk not found or returned no output — skipping gain report.\n');
+  }
+
+  const child = spawn(process.execPath, [serverScript, ...passthroughArgs], {
+    stdio: 'inherit',
+    cwd: dashboardDir,
+  });
+
+  child.on('error', (err) => {
+    process.stderr.write('Error starting dashboard server: ' + err.message + '\n');
+    process.exit(1);
+  });
+
+  child.on('close', (code) => {
+    process.exit(code !== null ? code : 0);
+  });
+}
+
+// ─── sync-all dispatcher ──────────────────────────────────────────────────────
+
+/**
+ * Delegate to bin/lib/sync-all.js (created by Wave 5 metade B). Falls back
+ * to a clear error if the module is missing.
+ *
+ * @param {string} dir
+ * @param {{ filters: string[], excludes: string[], apply: boolean, dryRun: boolean }} options
+ */
+function dispatchSyncAll(dir, options) {
+  const mod = tryRequire('./lib/sync-all');
+  if (!mod || typeof mod.runSyncAll !== 'function') {
+    process.stderr.write(
+      'Error: sync-all command is unavailable.\n' +
+      '       The bin/lib/sync-all.js module was not found.\n' +
+      '       This part of the CLI is delivered by Wave 5 metade B —\n' +
+      '       re-run `npm install` or update the harness.\n'
+    );
+    process.exit(2);
+  }
+  try {
+    return mod.runSyncAll(dir, options);
+  } catch (e) {
+    process.stderr.write(`Error running sync-all: ${e.message}\n`);
+    process.exit(1);
+  }
+}
+
+// ─── main ─────────────────────────────────────────────────────────────────────
+
+function main() {
+  // Early dispatch for commands with their own flag parsers (bypass parseArgs).
+  if (process.argv[2] === 'adr') {
+    const code = adr.runAdr(process.argv.slice(3));
+    process.exit(code);
+  }
+
+  const parsed = parseArgs(process.argv);
+  const {
+    command, positional, sub, dryRun, help: helpFlag, version,
+    checkOnly: checkOnlyFlag, force, apply, filters, excludes,
+    dashboardPassthrough, json, strict, categories,
+  } = parsed;
+
+  if (version) {
+    process.stdout.write(harnessVersion() + '\n');
+    process.exit(0);
+  }
+
+  // `duk help [command]`
+  if (command === 'help') {
+    if (positional.length === 0) {
+      help.printGeneralHelp();
+    } else {
+      help.printCommandHelp(positional[0]);
+    }
+    process.exit(process.exitCode || 0);
+  }
+
+  // `duk --help` (no command) → general help
+  if (helpFlag && command === null) {
+    help.printGeneralHelp();
+    process.exit(0);
+  }
+
+  // `duk <command> --help` → command-specific
+  if (helpFlag && command !== null) {
+    // command was already normalised update→install; pass original alias too
+    help.printCommandHelp(command);
+    process.exit(process.exitCode || 0);
+  }
+
+  // No command at all → short help
+  if (command === null) {
+    help.printShortHelp();
+    process.exit(0);
+  }
+
+  // Routing
+  if (command === 'install') {
+    if (checkOnlyFlag) {
+      checkOnly({ cwd: process.cwd(), sub: sub || null });
+      return;
+    }
+    adoptProject({
+      cwd: process.cwd(),
+      sub: sub || null,
+      dryRun,
+      force,
+    });
+    return;
+  }
+
+  if (command === 'new') {
+    const name = positional[0];
+    if (!name) {
+      process.stderr.write('Error: `duk new` requires a project name. Run `duk help new`.\n');
+      process.exit(1);
+    }
+    newProject(name, { dryRun });
+    return;
+  }
+
+  if (command === 'sync-all') {
+    const dir = positional[0];
+    if (!dir) {
+      process.stderr.write('Error: `duk sync-all` requires a directory argument. Run `duk help sync-all`.\n');
+      process.exit(1);
+    }
+    dispatchSyncAll(dir, {
+      filters,
+      excludes,
+      apply,
+      dryRun: !apply,
+    });
+    return;
+  }
+
+  if (command === 'dashboard') {
+    dashboard(dashboardPassthrough);
+    return;
+  }
+
+  if (command === 'doctor') {
+    const code = doctor.runDoctor({ json, strict });
+    process.exit(code);
+  }
+
+  if (command === 'lint') {
+    const code = lint.runLint({ json, categories });
+    process.exit(code);
+  }
+
+  if (command === 'adr') {
+    // Pass raw argv (skip 'node' + 'cli.js' + 'adr') so --by flag is preserved.
+    const code = adr.runAdr(process.argv.slice(3));
+    process.exit(code);
+  }
+
+  // Unknown command — show short help
+  process.stderr.write(`Unknown command: ${command}\n\n`);
+  help.printShortHelp();
+  process.exit(1);
+}
+
+if (require.main === module) {
+  main();
+}
+
+// Export functions for testing and for other modules to consume.
+module.exports = {
+  parseArgs,
+  detectProjectType,
+  // identity helpers re-exported for back-compat with old tests
+  generateIdentitySection: identity.generateIdentitySection,
+  emptyIdentitySection: identity.emptyIdentitySection,
+  readIdentitySection: identity.readIdentitySection,
+  mergeClaudeMd: identity.mergeClaudeMd,
+  // backup helpers
+  backupClaudeDir: backup.backupClaudeDir,
+  copyDir: backup.copyDir,
+  // command entrypoints
+  adoptProject,
+  newProject,
+  checkOnly,
+  // misc
+  packageRoot,
+  harnessVersion,
+  validateProjectName,
+};