clckernel 1.2.19 → 2.0.1

package/src/gitignore.js

@@ -4,9 +4,42 @@
  * are safely ignored in consumer repositories to preserve AGENTS.md as the SSOT.
  */
 
-const fs = require('fs');
 const path = require('path');
+const { spawnSync } = require('child_process');
+const { currentIO } = require('./io');
 
+// Repository-locating variables a hook may export; they would point git at
+// another repository than the target's.
+const GIT_LOCAL_ENV = ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_PREFIX', 'GIT_COMMON_DIR'];
+
+/**
+ * Entries whose path (or, for a directory entry, anything under it) is
+ * tracked by git in targetDir (sdds/update-no-additions, decision 3). Only
+ * literal paths are checked: negations and glob patterns are kept as they
+ * are. Outside a git repository nothing is tracked. One `git ls-files` call.
+ * @param {string} targetDir - Project root
+ * @param {string[]} entries - Candidate .gitignore entries
+ * @returns {Set<string>}
+ */
+function trackedEntries(targetDir, entries) {
+  const literal = entries.filter((e) => !e.startsWith('!') && !/[*?[\\]/.test(e));
+  if (literal.length === 0) return new Set();
+  const env = { ...process.env };
+  for (const key of GIT_LOCAL_ENV) delete env[key];
+  const bare = (e) => e.replace(/\/+$/, '');
+  const res = spawnSync('git', ['ls-files', '-z', '--', ...literal.map((e) => `:(literal)${bare(e)}`)], {
+    cwd: targetDir, env, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  if (res.error || res.status !== 0) return new Set();
+  const files = res.stdout.split('\0').filter(Boolean);
+  return new Set(literal.filter((e) => files.some((f) => f === bare(e) || f.startsWith(`${bare(e)}/`))));
+}
+
+/**
+ * Managed entries per section. An `{ entry, ifExists: true }` item names an
+ * artifact of an older release (sdds/onboarding): it is added only when that
+ * path exists in the project, so a fresh install names no retired artifact.
+ */
 const MANAGED_GITIGNORE_SECTIONS = [
   {
     header: '# CLC Kernel: Local AI IDE Mirror Symlinks (SSOT: AGENTS.md)',
@@ -24,7 +57,7 @@ const MANAGED_GITIGNORE_SECTIONS = [
     header: '# CLC Kernel: CLI Agent Skills & Playbooks',
     entries: [
       '.agents/skills/clckernel_cli/',
-      '.agents/skills/clc_forge_cli/',
+      { entry: '.agents/skills/clc_forge_cli/', ifExists: true },
     ],
   },
   {
@@ -34,10 +67,11 @@ const MANAGED_GITIGNORE_SECTIONS = [
       '!sdds/.gitkeep',
       'openspec/*',
       '!openspec/.gitkeep',
-      '.clckernel.resolved.json',
-      '.clc-forge.resolved.json',
+      { entry: '.clckernel.resolved.json', ifExists: true },
+      { entry: '.clc-forge.resolved.json', ifExists: true },
       '.husky/_/',
       '.ruff_cache/',
+      '*.clckernel-new',
     ],
   },
 ];
@@ -45,19 +79,18 @@ const MANAGED_GITIGNORE_SECTIONS = [
 /**
  * Idempotently appends missing CLC Kernel entries to target project's .gitignore.
  *
+ * Writes through the active io session (sdds/safe-update), so a dry run
+ * only records the entries it would add. An entry whose path git tracks is
+ * not added (sdds/update-no-additions, decision 3).
+ *
  * @param {string} targetDir - Target project root
  * @returns {boolean} True if .gitignore was created or modified, false if already complete.
  */
 function ensureGitignoreEntries(targetDir) {
+  const io = currentIO(targetDir);
   const gitignorePath = path.join(targetDir, '.gitignore');
-  let currentContent = '';
-  if (fs.existsSync(gitignorePath)) {
-    try {
-      currentContent = fs.readFileSync(gitignorePath, 'utf-8');
-    } catch (e) {
-      currentContent = '';
-    }
-  }
+  const existing = io.read(gitignorePath);
+  const currentContent = existing ? existing.toString('utf-8') : '';
 
   const existingLines = new Set(
     currentContent
@@ -67,11 +100,24 @@ function ensureGitignoreEntries(targetDir) {
   );
 
   const sectionsToAppend = [];
+  const added = [];
+
+  const entriesOf = (section) => section.entries
+    .filter(item => typeof item === 'string' || io.exists(path.join(targetDir, item.entry)))
+    .map(item => (typeof item === 'string' ? item : item.entry));
+
+  // A path the project tracks is never ignored behind its back: the entry is
+  // left out and reported instead.
+  const candidates = MANAGED_GITIGNORE_SECTIONS.flatMap(entriesOf)
+    .filter(entry => !existingLines.has(entry.trim()));
+  const tracked = trackedEntries(targetDir, candidates);
+  for (const entry of tracked) io.noteTrackedNotIgnored(entry);
 
   for (const section of MANAGED_GITIGNORE_SECTIONS) {
-    const missingEntries = section.entries.filter(entry => !existingLines.has(entry.trim()));
+    const missingEntries = entriesOf(section).filter(entry => !existingLines.has(entry.trim()) && !tracked.has(entry));
     if (missingEntries.length > 0) {
       sectionsToAppend.push(`${section.header}\n${missingEntries.join('\n')}`);
+      added.push(...missingEntries);
     }
   }
 
@@ -88,7 +134,7 @@ function ensureGitignoreEntries(targetDir) {
   }
   newContent += sectionsToAppend.join('\n\n') + '\n';
 
-  fs.writeFileSync(gitignorePath, newContent, 'utf-8');
+  io.appendGitignore(gitignorePath, newContent, added);
   return true;
 }
 

package/src/index.js

@@ -3,9 +3,11 @@
  * Coordinates auto-discovery, UI rendering, generator engine, and doctor checks.
  */
 
+const fs = require('fs');
 const path = require('path');
+const { spawnSync } = require('child_process');
 const { autoDetectStack } = require('./detector');
-const { printBanner, printBox, promptOptions, printSuccess, colors } = require('./ui');
+const { printBanner, printBox, promptOptions, printSuccess, partLines, colors } = require('./ui');
 const { generateHarness } = require('./generator');
 const { runDoctor } = require('./doctor');
 
@@ -18,28 +20,102 @@ const READ_ONLY_COMMANDS = new Set(['help', '--help', '-h', 'version', '--versio
  */
 const INSTALL_FLAGS = new Set(['--yes', '-y']);
 
+/** Prints the plan instead of writing (sdds/safe-update, decision 5). Not an opt-in by itself. */
+const DRY_RUN_FLAG = '--dry-run';
+
+/** Opts guards the project does not have into an update (sdds/update-no-additions). */
+const ADD_GUARDS_FLAG = '--add-guards';
+
+/**
+ * Parses the arguments after `update`: at most one target dir, --dry-run,
+ * and `--add-guards <a,b|all>` (or `--add-guards=<...>`). The names are
+ * checked against the stack's manifest by the updater, before any write.
+ * @param {string[]} rest - Arguments without the `update` word
+ * @returns {{ positionals: string[], dryRun: boolean, addGuards?: string[]|'all' }|null}
+ *   null when the input is not understood
+ */
+function parseUpdateArgs(rest) {
+  const positionals = [];
+  let dryRun = false;
+  let addGuards;
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    let value = null;
+    if (arg === DRY_RUN_FLAG) {
+      dryRun = true;
+      continue;
+    } else if (arg === ADD_GUARDS_FLAG) {
+      value = rest[i + 1];
+      if (value === undefined || value.startsWith('-')) return null;
+      i++;
+    } else if (arg.startsWith(`${ADD_GUARDS_FLAG}=`)) {
+      value = arg.slice(ADD_GUARDS_FLAG.length + 1);
+    } else if (arg.startsWith('-')) {
+      return null;
+    } else {
+      positionals.push(arg);
+      continue;
+    }
+    if (addGuards !== undefined) return null;
+    const names = value.split(',').map((n) => n.trim()).filter(Boolean);
+    if (names.length === 0) return null;
+    addGuards = names.includes('all') ? 'all' : names;
+  }
+  if (positionals.length > 1) return null;
+  return { positionals, dryRun, addGuards };
+}
+
+/**
+ * Words AGENTS.md documents as agent commands (`clckernel test`, ...). They are
+ * executed by the AI agent, not by this CLI; without this list they would be
+ * taken as an install target directory.
+ */
+const AGENT_COMMANDS = new Set(['test', 'start', 'feature', 'fix', 'commit', 'guard']);
+
 const HELP_TEXT = `
 ${'clckernel'} — CLC Kernel: The AI Agent Governance Engine
 
 USAGE
   clckernel <command> [targetDir]
 
-READ-ONLY COMMANDS (never modify your project)
+READ-ONLY COMMANDS (do not modify your project's code or config)
   help, --help, -h        Show this help
   version, --version, -v  Print the installed version
   doctor [targetDir]      Run diagnostics on a project
-  update [targetDir]      Refresh tools, playbooks and IDE symlinks
+  audit [targetDir] [--change <name>]
+                          Run the installed audit orchestrators (tools/audit.js
+                          and/or tools/audit.py) and print the summary. Writes
+                          nothing, unless --change <name>: then the report and
+                          receipt go to sdds/<name>/ (only there)
+                          Checks staged changes, or the last commit if none
 
-INSTALLATION (writes to the target project)
+WRITES TO THE TARGET PROJECT
+  update [targetDir]            Refresh tools, hooks, playbooks, IDE symlinks,
+                                .gitignore and AGENTS.md. A kernel file you
+                                edited is kept; the new version is written
+                                next to it as <file>.clckernel-new. Only the
+                                guards and mirrors you have are refreshed;
+                                none are added
+  --add-guards <a,b|all>        With update: also install these guards
   clckernel [targetDir] --yes   Provision the governance harness
+  --dry-run                     With update or --yes: print the plan, write nothing
+
+  Installation requires an explicit opt-in and an existing target directory.
+  Bare \`clckernel\` runs the interactive confirmation flow; with no TTY it
+  refuses to install.
 
-  Requires an explicit opt-in. Bare \`clckernel\` runs the interactive
-  confirmation flow; with no TTY it refuses to install.
+AGENT COMMANDS
+  test, start, feature, fix, commit, guard are defined in AGENTS.md and are
+  run by your AI agent, not by this CLI.
 
 EXAMPLES
   clckernel --help
   clckernel doctor .
+  clckernel audit .
+  clckernel audit . --change my-feature
   clckernel update .
+  clckernel update . --dry-run
+  clckernel update . --add-guards check_skills
   clckernel . --yes
 `;
 
@@ -59,6 +135,109 @@ function rejectUnknownInput(args) {
   return 1;
 }
 
+/**
+ * Explains that an AGENTS.md agent command is not a CLI command.
+ * @param {string} word - The reserved word the user typed
+ * @returns {number} Process exit code
+ */
+function rejectAgentCommand(word) {
+  process.stderr.write(
+    `\n❌ \`${word}\` is an agent command defined in AGENTS.md, not a CLI command.\n` +
+      '   Ask your AI agent to run it, or run `clckernel --help` to see CLI commands.\n\n'
+  );
+  return 1;
+}
+
+/**
+ * Resolves a user-supplied directory and checks it exists and is a directory.
+ * Prints the error itself so callers only decide the exit code.
+ * @param {string|undefined} input - Raw path argument (cwd when absent)
+ * @returns {string|null} Absolute path, or null when unusable
+ */
+function resolveExistingDir(input) {
+  const dir = input ? path.resolve(input) : process.cwd();
+  let stat;
+  try {
+    stat = fs.statSync(dir);
+  } catch (e) {
+    process.stderr.write(`\n❌ Target directory does not exist: ${dir}\n   Nothing was written.\n\n`);
+    return null;
+  }
+  if (!stat.isDirectory()) {
+    process.stderr.write(`\n❌ Target is not a directory: ${dir}\n   Nothing was written.\n\n`);
+    return null;
+  }
+  return dir;
+}
+
+/**
+ * `clckernel audit [dir] [--change <name>]`: runs every orchestrator installed
+ * in dir/tools (audit.js, then audit.py) with cwd = dir. A mixed stack has
+ * both, and each only discovers guards of its own language, so all of them
+ * must run. --change is passed through (the orchestrators validate the name).
+ * @param {string|undefined} input - Target directory argument
+ * @param {string|null} [change] - SDD change name for the report, or null
+ * @returns {number} Exit code: the first non-zero orchestrator status, else 0
+ */
+function runAudit(input, change = null) {
+  const dir = resolveExistingDir(input);
+  if (!dir) return 1;
+
+  const candidates = [
+    { file: 'audit.js', cmd: process.execPath },
+    { file: 'audit.py', cmd: 'python3' },
+  ];
+  const orchestrators = candidates.filter((c) => fs.existsSync(path.join(dir, 'tools', c.file)));
+  if (orchestrators.length === 0) {
+    process.stderr.write(
+      `\n❌ No audit orchestrator found in ${path.join(dir, 'tools')} (audit.js or audit.py).\n` +
+        `   Install the harness first: clckernel ${input || '.'} --yes\n\n`
+    );
+    return 1;
+  }
+
+  let exitCode = 0;
+  for (const orchestrator of orchestrators) {
+    const orchestratorArgs = [path.join('tools', orchestrator.file), ...(change ? ['--change', change] : [])];
+    const res = spawnSync(orchestrator.cmd, orchestratorArgs, {
+      cwd: dir,
+      stdio: 'inherit',
+    });
+    let status;
+    if (res.error) {
+      process.stderr.write(`\n❌ Could not run tools/${orchestrator.file}: ${res.error.message}\n\n`);
+      status = 1;
+    } else {
+      status = res.status === null ? 1 : res.status;
+    }
+    if (status !== 0 && exitCode === 0) exitCode = status;
+  }
+  return exitCode;
+}
+
+/**
+ * `audit` arguments: at most one target dir and one `--change <name>`.
+ * @param {string[]} rest - Arguments after `audit`
+ * @returns {{ targetDir?: string, change: string|null } | null} null on unknown input
+ */
+function parseAuditArgs(rest) {
+  const out = { targetDir: undefined, change: null };
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (arg === '--change') {
+      const name = rest[i + 1];
+      if (out.change !== null || name === undefined || name.startsWith('-')) return null;
+      out.change = name;
+      i += 1;
+    } else if (arg.startsWith('-') || out.targetDir !== undefined) {
+      return null;
+    } else {
+      out.targetDir = arg;
+    }
+  }
+  return out;
+}
+
 async function runCli() {
   const args = process.argv.slice(2);
   const command = args[0];
@@ -78,16 +257,39 @@ async function runCli() {
     return;
   }
 
+  if (AGENT_COMMANDS.has(command)) {
+    process.exitCode = rejectAgentCommand(command);
+    return;
+  }
+
+  if (command === 'audit') {
+    const parsed = parseAuditArgs(args.slice(1));
+    if (!parsed) {
+      process.exitCode = rejectUnknownInput(args);
+      return;
+    }
+    process.exitCode = runAudit(parsed.targetDir, parsed.change);
+    return;
+  }
+
   if (command === 'doctor' || args.includes('--doctor')) {
     const target = args[1] && args[1] !== '--doctor' ? args[1] : (args[0] === 'doctor' ? null : args[0]);
-    runDoctor(target ? path.resolve(target) : process.cwd());
+    const failures = runDoctor(target ? path.resolve(target) : process.cwd());
+    if (failures > 0) process.exitCode = 1;
     return;
   }
 
   if (command === 'update' || args.includes('--update')) {
-    const target = args[1] && args[1] !== '--update' ? args[1] : (args[0] === 'update' ? null : args[0]);
+    const rest = [...args];
+    rest.splice(rest.indexOf(command === 'update' ? 'update' : '--update'), 1);
+    const parsed = parseUpdateArgs(rest);
+    if (!parsed) {
+      process.exitCode = rejectUnknownInput(args);
+      return;
+    }
     const { runUpdate } = require('./updater');
-    await runUpdate(target ? path.resolve(target) : process.cwd());
+    const target = parsed.positionals[0];
+    await runUpdate(target ? path.resolve(target) : process.cwd(), { dryRun: parsed.dryRun, addGuards: parsed.addGuards });
     return;
   }
 
@@ -95,15 +297,26 @@ async function runCli() {
   // or an explicit install flag.
   const flags = args.filter((a) => a.startsWith('-'));
   const positionals = args.filter((a) => !a.startsWith('-'));
-  const unknownFlags = flags.filter((f) => !INSTALL_FLAGS.has(f));
+  const unknownFlags = flags.filter((f) => !INSTALL_FLAGS.has(f) && f !== DRY_RUN_FLAG);
+  const dryRun = flags.includes(DRY_RUN_FLAG);
 
   if (unknownFlags.length > 0 || positionals.length > 1) {
     process.exitCode = rejectUnknownInput(args);
     return;
   }
 
-  const targetDir = positionals.length === 1 ? path.resolve(positionals[0]) : process.cwd();
-  const explicitInstall = INSTALL_FLAGS.has(command) || flags.length > 0;
+  if (positionals.length === 1 && AGENT_COMMANDS.has(positionals[0])) {
+    process.exitCode = rejectAgentCommand(positionals[0]);
+    return;
+  }
+
+  // A mistyped path must never become a freshly created directory.
+  const targetDir = resolveExistingDir(positionals[0]);
+  if (!targetDir) {
+    process.exitCode = 1;
+    return;
+  }
+  const explicitInstall = flags.some((f) => INSTALL_FLAGS.has(f));
   const isInteractive = Boolean(process.stdin.isTTY) && !process.env.CI;
 
   if (!explicitInstall && !isInteractive) {
@@ -116,6 +329,20 @@ async function runCli() {
     return;
   }
 
+  // The project config is read before the prompt and before any write: an
+  // invalid one stops the install here (sdds/config-foundation).
+  const { readProjectConfig } = require('./config');
+  let projectConfig;
+  try {
+    projectConfig = readProjectConfig(targetDir);
+  } catch (err) {
+    if (err.name !== 'ConfigError') throw err;
+    process.stderr.write(`\n❌ ${err.message}\n   Nothing was written.\n\n`);
+    process.exitCode = 1;
+    return;
+  }
+  for (const warning of projectConfig.warnings) process.stderr.write(`⚠ ${warning}\n`);
+
   // 1. Print Pro ASCII Banner
   printBanner();
 
@@ -124,15 +351,18 @@ async function runCli() {
 
   // 3. Render Formatted Configuration Box
   printBox('🔍 CONFIGURACIÓN DETECTADA AUTOMÁTICAMENTE', [
+    { label: '📁 Target', value: targetDir, badgeColor: colors.cyan },
     { label: '📦 Tipo de Proyecto', value: detected.projectType.toUpperCase(), badgeColor: colors.amber },
     { label: '🚀 Framework', value: detected.framework, badgeColor: colors.emerald },
     { label: '🎨 Estilos & UI', value: `${detected.styling} (${detected.uiLibrary})`, badgeColor: colors.violet },
     { label: '🧪 Test Runner', value: detected.testRunner, badgeColor: colors.cyan },
-    { label: '🔒 Git Hooks', value: detected.gitHooks, badgeColor: colors.blue }
+    { label: '🔒 Git Hooks', value: detected.gitHooks, badgeColor: colors.blue },
+    // Multi-part repos (sdds/fullstack-monorepo): one row per part.
+    ...partLines(detected).map((line) => ({ label: '🧩 Parte', value: line, badgeColor: colors.emerald }))
   ]);
 
   // 4. Prompt User for Confirmation or Override
-  const finalConfig = await promptOptions(detected);
+  const finalConfig = await promptOptions(detected, { targetDir });
 
   // 5. Generate Harness & Safeguards
   let s;
@@ -142,14 +372,23 @@ async function runCli() {
     s.start('Configurando salvaguardas y motor de gobernanza...');
   }
 
-  generateHarness(targetDir, finalConfig);
+  const { installedGuards, hook, plan } = generateHarness(targetDir, finalConfig, { dryRun, projectConfig }) || {};
 
   if (s) {
-    s.stop('Salvaguardas y motor de gobernanza configurados.');
+    s.stop(dryRun ? 'Plan listo (dry run).' : 'Salvaguardas y motor de gobernanza configurados.');
   }
 
-  // 6. Render Pro Success Card
-  printSuccess(targetDir, finalConfig.projectType === 'frontend', finalConfig);
+  // 6. Render Pro Success Card (or, for a dry run, only the plan)
+  const { printPlan } = require('./ui');
+  if (dryRun) {
+    if (plan) printPlan(plan, { dryRun: true });
+    return;
+  }
+  printSuccess(targetDir, hook, finalConfig, installedGuards);
+  if (plan) printPlan(plan);
+  // sdds/onboarding: what to do next, true to this install.
+  const { nextStepsLines } = require('./ui');
+  console.log(`\n${nextStepsLines(hook, plan, finalConfig).join('\n')}\n`);
 }
 
 module.exports = { runCli };