@hublo/sentinel 1.5.0 → 1.5.1-alpha.1

package/README.md

@@ -55,9 +55,13 @@ sentinel --init --preset <react|nest|node|svelte>   # every role sentinel ships
 pnpm install   # fetch what --init declared, then commit
 ```
 
-With no target named, `--init` adopts every role, in the order that makes the result correct:
-the linter's autofix runs, then the formatter runs **last** and formats everything every role
-wrote. Naming one target (`--init --lint`) adopts just that role and leaves the rest alone.
+With no target named, `--init` on a module that has adopted nothing adopts every role, in the
+order that makes the result correct: the linter's autofix runs, then the formatter runs **last**
+and formats everything every role wrote. On a module that has already adopted a role, the same
+bare `--init` re-inits only the roles it has, read the way `--inspect` reports them, and says
+which. Naming a target (`--init --build`) adopts just that role and leaves the rest alone, with
+one pairing: lint and format are always adopted together, so `--init --lint` adopts oxfmt too.
+`--init --all` adopts every role on any module.
 
 `--init` writes the config stubs, the `typecheck`/`lint`/... scripts, and pins the `@hublo/sentinel` devDependency into the module (no manual `pnpm add`); it scaffolds a `package.json` for a `project.json`-only module. It also applies, once, the workspace prep that module needs at the root, only when the root's own config shows it is needed (e.g. an i18next singleton override when the repo runs a second TypeScript, a release-age allow-list when the repo uses that pnpm gate). See the [adoption cheat sheet](docs/typescript-adoption.md) for the full list.
 
@@ -127,7 +131,7 @@ And the app's `package.json` scripts route every check through the one CLI (run
 **Step 3 — evolve the toolchain, in one central place:**
 
 - a **rule change** → bump the `@hublo/sentinel` version; the stubs already point at it, so there is **nothing to regenerate**;
-- a **structural change** (new tool, new preset, runner swap) → run `sentinel --init` once to refresh the stubs (sentinel tells you when this is needed).
+- a **structural change** (new tool, new preset, runner swap) → run `sentinel --init` once to refresh the stubs (sentinel tells you when this is needed). On an adopted module it re-inits the roles the module has, and no others.
 
 **Step 4 — stay converged:** a drift guard in CI flags any module whose config quietly diverged from the shared source.
 
@@ -412,6 +416,7 @@ OPTIONS    --module <name>    from the root: scope to one module
            --ci               from the root: affected only; non-zero exit on failure
            --fix              auto-fix where applicable
            --dry-run          preview a --init without writing
+           --rehearse         with --dry-run: run the autofixes in a copy, name the source they rewrite
            --json             machine-readable output (report / inspect / status / --dry-run)
            -- <tool options>  --run only: pass the rest to the tool itself (one type)
 

package/dist/bin/sentinel.js

@@ -8,19 +8,20 @@ import {
   describeFramework,
   dispatch,
   palette,
+  presetNotInstalledYet,
   registerAdapters,
   resolve
-} from "../chunk-MOELAQPC.js";
+} from "../chunk-64H5HBPH.js";
 import {
   resolveContext
-} from "../chunk-43HQ6BVJ.js";
+} from "../chunk-J2USE3KV.js";
 import {
   ensureWorkspacePrep,
   findWorkspaceRoot,
   inspectWorkspacePrep,
   readOwnVersion,
   readProjectPackageJson
-} from "../chunk-IL5PPLXE.js";
+} from "../chunk-JRZI5IIN.js";
 import {
   LONG_RUNNING_TARGETS,
   OUTPUT_SHAPES,
@@ -35,157 +36,6 @@ import "../chunk-QXFCZON7.js";
 // bin/sentinel.ts
 import { program } from "commander";
 
-// src/roles/build/declined.ts
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-var DEPRECATED_NX_BUILDER = "@nx/webpack:webpack";
-function buildsWithDeprecatedExecutor(cwd2) {
-  const projectJson = join(cwd2, "project.json");
-  if (!existsSync(projectJson)) return false;
-  try {
-    const project = JSON.parse(readFileSync(projectJson, "utf8"));
-    return project.targets?.build?.executor === DEPRECATED_NX_BUILDER;
-  } catch {
-    return false;
-  }
-}
-function explainDecline(cwd2) {
-  if (buildConfigFile(cwd2) !== void 0) {
-    return ` This module HAS a Vite config, so detection is the likely problem: the build toolchain is declared at the workspace root, which makes a front app detect as "node". Pass --preset to say what it is.`;
-  }
-  if (buildsWithDeprecatedExecutor(cwd2)) {
-    return ` This module still builds through ${DEPRECATED_NX_BUILDER}, which Nx v24 removes. It has no Vite config yet, so there is nothing for --build to adopt: add one that imports @hublo/sentinel/build/nest, then run this again. See docs/build-adoption.md.`;
-  }
-  return ` This module has neither a Vite config nor an Nx build target, so it builds nothing and --build is out of scope for it. Nothing was written, and nothing is wrong.`;
-}
-
-// src/cli/run-init.ts
-function asMessage(error) {
-  return error instanceof Error ? error.message : String(error);
-}
-async function runInit(ctx) {
-  const { modules, scope } = resolveContext(ctx.cwd, { module: ctx.module, ci: false });
-  const [module] = modules;
-  if (scope === "all" || scope === "affected" || !module) {
-    ctx.fail(
-      "--init writes files: target one module (run from its directory, or pass --module). Adopting every module at once is intentionally not allowed \u2014 adopt gradually."
-    );
-  }
-  const available = availableTargets();
-  if (ctx.targetsExplicit) {
-    const unwired = ctx.targets.filter((type) => !available.includes(type));
-    if (unwired.length > 0) {
-      ctx.fail(
-        `target(s) not available yet: ${unwired.map((t) => `--${t}`).join(", ")}. Available now: ${available.map((t) => `--${t}`).join(", ") || "(none yet)"}.`
-      );
-    }
-  }
-  const toRun = ctx.targets.filter((type) => available.includes(type)).sort((a, b) => Number(a === "format") - Number(b === "format"));
-  const outcomes = [];
-  const record = (outcome) => {
-    outcomes.push(outcome);
-  };
-  let worst = 0;
-  for (const type of toRun) {
-    try {
-      const code = await dispatch({
-        verb: ctx.verb,
-        target: type,
-        runner: ctx.runner,
-        cwd: module.root,
-        preset: ctx.preset,
-        dryRun: ctx.dryRun,
-        json: ctx.json,
-        record
-      });
-      worst = Math.max(worst, code);
-    } catch (error) {
-      if (error instanceof PresetUnsupportedError) {
-        if (ctx.targetsExplicit) {
-          const hint = type === "build" ? explainDecline(module.root) : ` Pass --preset if it was detected wrongly (hoisted dependencies make detection fall back to "node").`;
-          process.stderr.write(
-            `
-sentinel (${type}): this module's preset is "${error.preset}", and --${type} has no adapter for it.${hint}
-`
-          );
-          worst = Math.max(worst, 1);
-        }
-        record({
-          role: type,
-          status: "unsupported",
-          reason: `this module's preset is "${error.preset}", and --${type} has no adapter for it.`
-        });
-        continue;
-      }
-      process.stderr.write(`
-sentinel (${type}): ${asMessage(error)}
-`);
-      record({ role: type, status: "failed", reason: asMessage(error) });
-      worst = Math.max(worst, 1);
-    }
-  }
-  let workspace = [];
-  if (worst === 0) {
-    const root = findWorkspaceRoot(module.root);
-    if (root) {
-      const changes = ensureWorkspacePrep({
-        root,
-        dryRun: ctx.dryRun,
-        // Only when the FORMAT role actually adopted: a module still formatted by the root
-        // must not be excluded from it.
-        formattedModule: toRun.includes("format") ? module.root : void 0,
-        // Same rule for the report directory: only when the STATIC ANALYSIS role adopted.
-        analysedModule: toRun.includes("static-analysis")
-      });
-      workspace = changes;
-      const prefix = ctx.dryRun ? "  dry run: " : "  ";
-      for (const change of changes) process.stderr.write(`${prefix}${change}
-`);
-      if (changes.length > 0 && !ctx.dryRun) {
-        process.stderr.write(
-          palette(process.stderr).dim("  run `pnpm install` to apply the workspace changes\n")
-        );
-      }
-    }
-  }
-  if (ctx.json) {
-    process.stdout.write(
-      JSON.stringify(
-        { dryRun: ctx.dryRun, module: module.name, roles: outcomes, workspace },
-        null,
-        2
-      ) + "\n"
-    );
-  }
-  return worst;
-}
-
-// src/cli/run-validate.ts
-async function runValidate(ctx) {
-  const { modules } = resolveContext(ctx.cwd, { module: ctx.module, ci: ctx.ci });
-  const unsupported = ctx.targets.filter((target) => target !== "test");
-  if (unsupported.length > 0) {
-    const named = unsupported.map((target) => `--${target}`).join(", ");
-    process.stdout.write(
-      `  \xB7 ${named}: not available yet. \`--validate\` answers \`--test\` today, by recording a suite before a migration and comparing it after. Nothing was checked for ${named}.
-`
-    );
-  }
-  if (!ctx.targets.includes("test")) return 1;
-  const { validateModuleTests } = await import("../validate-FRMENKHM.js");
-  const outcomes = modules.flatMap(
-    (module) => validateModuleTests(module.name, module.root)
-  );
-  for (const outcome of outcomes) {
-    const suite = outcome.suite === "main" ? "" : ` [${outcome.suite}]`;
-    process.stdout.write(
-      `  ${outcome.ok ? "\u2713" : "\u2717"} ${outcome.module}${suite} \u2014 ${outcome.message}
-`
-    );
-  }
-  return outcomes.every((outcome) => outcome.ok) ? 0 : 1;
-}
-
 // src/core/orchestrate.ts
 async function analyse(params) {
   const results = [];
@@ -341,6 +191,355 @@ function generateSummaries(results, requestedTargets) {
     results: results.map(generateSummary)
   };
 }
+async function adoptedTargets(params) {
+  const { results } = await analyse({
+    verb: "status",
+    targets: params.targets,
+    modules: [params.module],
+    preset: params.preset,
+    runner: params.runner,
+    targetsExplicit: false,
+    ci: false,
+    fix: false
+  });
+  return results.filter((row) => row.data?.adopted === true).map((row) => row.target);
+}
+
+// src/core/rehearse.ts
+import { createHash } from "node:crypto";
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, relative, sep } from "node:path";
+var NOT_COPIED = /* @__PURE__ */ new Set(["node_modules", ".git"]);
+function contents(root) {
+  const found = /* @__PURE__ */ new Map();
+  const queue = [root];
+  while (queue.length > 0) {
+    const dir = queue.pop();
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!NOT_COPIED.has(entry.name)) queue.push(path);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      found.set(relative(root, path), createHash("sha1").update(readFileSync(path)).digest("hex"));
+    }
+  }
+  return found;
+}
+function stage(moduleDir, scratch) {
+  const root = findWorkspaceRoot(moduleDir);
+  const segments = root === void 0 ? [basename(moduleDir)] : relative(root, moduleDir).split(sep).filter((segment) => segment !== "");
+  let real = root ?? dirname(moduleDir);
+  let shadow = scratch;
+  for (const segment of segments) {
+    for (const entry of root === void 0 ? [] : readdirSync(real)) {
+      if (entry === segment || entry === ".git") continue;
+      symlinkSync(join(real, entry), join(shadow, entry));
+    }
+    real = join(real, segment);
+    shadow = join(shadow, segment);
+    mkdirSync(shadow);
+  }
+  rmSync(shadow, { recursive: true, force: true });
+  cpSync(moduleDir, shadow, {
+    recursive: true,
+    filter: (source) => source === moduleDir || !NOT_COPIED.has(basename(source)) && !lstatSync(source).isSymbolicLink()
+  });
+  if (existsSync(join(moduleDir, "node_modules"))) {
+    symlinkSync(join(moduleDir, "node_modules"), join(shadow, "node_modules"), "dir");
+  }
+  return shadow;
+}
+async function rehearseAfterInit(moduleDir, roles) {
+  const rehearsing = roles.filter((role) => role.adapter.rehearseAfterInit !== void 0);
+  if (rehearsing.length === 0) return [];
+  const scratch = realpathSync(mkdtempSync(join(tmpdir(), "sentinel-rehearsal-")));
+  try {
+    let copy;
+    try {
+      copy = stage(moduleDir, scratch);
+    } catch (error) {
+      const failure = error instanceof Error ? error.message : String(error);
+      return rehearsing.map((role) => ({ target: role.target, rewrites: [], failure }));
+    }
+    const planned = /* @__PURE__ */ new Set();
+    for (const role of roles) {
+      for (const file of role.files) {
+        planned.add(file.path);
+        const target = join(copy, file.path);
+        if (file.deleted) {
+          rmSync(target, { force: true });
+          continue;
+        }
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, file.after);
+      }
+    }
+    const results = [];
+    for (const role of rehearsing) {
+      const before = contents(copy);
+      const failure = await role.adapter.rehearseAfterInit?.(
+        {
+          module: basename(moduleDir),
+          cwd: copy,
+          preset: role.preset,
+          ci: false,
+          fix: true,
+          written: role.files.filter((file) => !file.deleted).map((file) => file.path)
+        },
+        moduleDir
+      );
+      const after = contents(copy);
+      const rewrites = [...after].filter(([path, hash]) => before.get(path) !== hash && !planned.has(path)).map(([path]) => path).sort();
+      results.push({
+        target: role.target,
+        rewrites,
+        // The tool names files by the path it read them from, which is the copy. Said as the
+        // module's own paths: the copy is gone by the time anyone reads this.
+        ...failure === void 0 ? {} : { failure: failure.replaceAll(`${copy}/`, "").replaceAll(copy, ".") }
+      });
+    }
+    return results;
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+// src/roles/build/declined.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
+import { join as join2 } from "node:path";
+var DEPRECATED_NX_BUILDER = "@nx/webpack:webpack";
+function buildsWithDeprecatedExecutor(cwd2) {
+  const projectJson = join2(cwd2, "project.json");
+  if (!existsSync2(projectJson)) return false;
+  try {
+    const project = JSON.parse(readFileSync2(projectJson, "utf8"));
+    return project.targets?.build?.executor === DEPRECATED_NX_BUILDER;
+  } catch {
+    return false;
+  }
+}
+function explainDecline(cwd2) {
+  if (buildConfigFile(cwd2) !== void 0) {
+    return ` This module HAS a Vite config, so detection is the likely problem: the build toolchain is declared at the workspace root, which makes a front app detect as "node". Pass --preset to say what it is.`;
+  }
+  if (buildsWithDeprecatedExecutor(cwd2)) {
+    return ` This module still builds through ${DEPRECATED_NX_BUILDER}, which Nx v24 removes. It has no Vite config yet, so there is nothing for --build to adopt: add one that imports @hublo/sentinel/build/nest, then run this again. See docs/build-adoption.md.`;
+  }
+  return ` This module has neither a Vite config nor an Nx build target, so it builds nothing and --build is out of scope for it. Nothing was written, and nothing is wrong.`;
+}
+
+// src/cli/run-init.ts
+function asMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+var ADOPTED_TOGETHER = ["lint", "format"];
+function pairedTargets(named, available) {
+  if (!named.some((type) => ADOPTED_TOGETHER.includes(type))) return [];
+  return ADOPTED_TOGETHER.filter((type) => available.includes(type) && !named.includes(type));
+}
+var NAMED_REWRITES = 10;
+var AUTOFIX_TOOL = { lint: "linter", format: "formatter" };
+function describeUnrehearsed(target) {
+  return `the ${target} autofix runs on adoption and can rewrite source, as moving to another ${AUTOFIX_TOOL[target] ?? "tool"} does; add --rehearse to name the files (it runs the pass in a throwaway copy, as long as the real one)`;
+}
+function describeRehearsal(target, rewrites, failure) {
+  const pass = `the ${target} autofix`;
+  const said = failure === void 0 ? "" : ` (it also reported: ${failure})`;
+  if (rewrites.length === 0) {
+    if (failure === void 0) return `${pass} would rewrite nothing beyond the files above`;
+    if (presetNotInstalledYet(failure)) {
+      return `${pass} cannot be rehearsed yet: its preset is not installed in this module, which is expected before the first \`pnpm install\`. After it, this dry-run names what it rewrites`;
+    }
+    return `could not rehearse ${pass}, so what it rewrites is not known: ${failure}`;
+  }
+  const named = rewrites.slice(0, NAMED_REWRITES).join(", ");
+  const rest = rewrites.length - NAMED_REWRITES;
+  return `${pass} would rewrite ${rewrites.length} file${rewrites.length === 1 ? "" : "s"} beyond the ones above: ${rest > 0 ? `${named} and ${rest} more` : named}${said}`;
+}
+async function rolesToInit(ctx, module, available) {
+  const requested = ctx.targets.filter((type) => available.includes(type));
+  if (ctx.targetsExplicit || ctx.allTargets) return requested;
+  const adopted = await adoptedTargets({
+    module,
+    targets: requested,
+    preset: ctx.preset,
+    runner: ctx.runner
+  });
+  if (adopted.length === 0) return requested;
+  process.stderr.write(
+    palette(process.stderr).dim(
+      `  re-initializing the roles this module has adopted (${adopted.map((t) => `--${t}`).join(", ")}); to adopt another, name it (sentinel --init --<role>), or pass --all for every role
+`
+    )
+  );
+  return adopted;
+}
+async function runInit(ctx) {
+  const { modules, scope } = resolveContext(ctx.cwd, { module: ctx.module, ci: false });
+  const [module] = modules;
+  if (scope === "all" || scope === "affected" || !module) {
+    ctx.fail(
+      "--init writes files: target one module (run from its directory, or pass --module). Adopting every module at once is intentionally not allowed \u2014 adopt gradually."
+    );
+  }
+  const available = availableTargets();
+  if (ctx.targetsExplicit) {
+    const unwired = ctx.targets.filter((type) => !available.includes(type));
+    if (unwired.length > 0) {
+      ctx.fail(
+        `target(s) not available yet: ${unwired.map((t) => `--${t}`).join(", ")}. Available now: ${available.map((t) => `--${t}`).join(", ") || "(none yet)"}.`
+      );
+    }
+  }
+  const named = await rolesToInit(ctx, module, available);
+  const paired = pairedTargets(named, available);
+  const toRun = [...named, ...paired].sort(
+    (a, b) => Number(a === "format") - Number(b === "format")
+  );
+  for (const type of paired) {
+    process.stderr.write(
+      palette(process.stderr).dim(
+        `  adopting --${type} too: lint and format are adopted together, see the lint adoption guide
+`
+      )
+    );
+  }
+  const outcomes = [];
+  const record = (outcome) => {
+    outcomes.push(outcome);
+  };
+  const planned = [];
+  let worst = 0;
+  for (const type of toRun) {
+    try {
+      const code = await dispatch({
+        verb: ctx.verb,
+        target: type,
+        runner: ctx.runner,
+        cwd: module.root,
+        preset: ctx.preset,
+        dryRun: ctx.dryRun,
+        json: ctx.json,
+        record,
+        planned: (role) => planned.push(role)
+      });
+      worst = Math.max(worst, code);
+    } catch (error) {
+      if (error instanceof PresetUnsupportedError) {
+        if (ctx.targetsExplicit && !paired.includes(type)) {
+          const hint = type === "build" ? explainDecline(module.root) : ` Pass --preset if it was detected wrongly (hoisted dependencies make detection fall back to "node").`;
+          process.stderr.write(
+            `
+sentinel (${type}): this module's preset is "${error.preset}", and --${type} has no adapter for it.${hint}
+`
+          );
+          worst = Math.max(worst, 1);
+        }
+        record({
+          role: type,
+          status: "unsupported",
+          reason: `this module's preset is "${error.preset}", and --${type} has no adapter for it.`
+        });
+        continue;
+      }
+      process.stderr.write(`
+sentinel (${type}): ${asMessage(error)}
+`);
+      record({ role: type, status: "failed", reason: asMessage(error) });
+      worst = Math.max(worst, 1);
+    }
+  }
+  if (ctx.dryRun && worst === 0 && !ctx.rehearse && !ctx.json) {
+    for (const { target } of planned.filter((role) => role.adapter.rehearseAfterInit)) {
+      process.stderr.write(`  dry run: ${describeUnrehearsed(target)}
+`);
+    }
+  }
+  if (ctx.dryRun && worst === 0 && ctx.rehearse) {
+    for (const { target, rewrites, failure } of await rehearseAfterInit(module.root, planned)) {
+      const outcome = outcomes.find((entry) => entry.role === target);
+      if (outcome !== void 0) outcome.rewrites = rewrites;
+      if (ctx.json) continue;
+      process.stderr.write(`  dry run: ${describeRehearsal(target, rewrites, failure)}
+`);
+    }
+  }
+  let workspace = [];
+  if (worst === 0) {
+    const root = findWorkspaceRoot(module.root);
+    if (root) {
+      const changes = ensureWorkspacePrep({
+        root,
+        dryRun: ctx.dryRun,
+        // Only when the FORMAT role actually adopted: a module still formatted by the root
+        // must not be excluded from it.
+        formattedModule: toRun.includes("format") ? module.root : void 0,
+        // Same rule for the report directory: only when the STATIC ANALYSIS role adopted.
+        analysedModule: toRun.includes("static-analysis")
+      });
+      workspace = changes;
+      const prefix = ctx.dryRun ? "  dry run: " : "  ";
+      for (const change of changes) process.stderr.write(`${prefix}${change}
+`);
+      if (changes.length > 0 && !ctx.dryRun) {
+        process.stderr.write(
+          palette(process.stderr).dim("  run `pnpm install` to apply the workspace changes\n")
+        );
+      }
+    }
+  }
+  if (ctx.json) {
+    process.stdout.write(
+      JSON.stringify(
+        { dryRun: ctx.dryRun, module: module.name, roles: outcomes, workspace },
+        null,
+        2
+      ) + "\n"
+    );
+  }
+  return worst;
+}
+
+// src/cli/run-validate.ts
+async function runValidate(ctx) {
+  const { modules } = resolveContext(ctx.cwd, { module: ctx.module, ci: ctx.ci });
+  const unsupported = ctx.targets.filter((target) => target !== "test");
+  if (unsupported.length > 0) {
+    const named = unsupported.map((target) => `--${target}`).join(", ");
+    process.stdout.write(
+      `  \xB7 ${named}: not available yet. \`--validate\` answers \`--test\` today, by recording a suite before a migration and comparing it after. Nothing was checked for ${named}.
+`
+    );
+  }
+  if (!ctx.targets.includes("test")) return 1;
+  const { validateModuleTests } = await import("../validate-TIPIECG6.js");
+  const outcomes = modules.flatMap(
+    (module) => validateModuleTests(module.name, module.root)
+  );
+  for (const outcome of outcomes) {
+    const suite = outcome.suite === "main" ? "" : ` [${outcome.suite}]`;
+    process.stdout.write(
+      `  ${outcome.ok ? "\u2713" : "\u2717"} ${outcome.module}${suite} \u2014 ${outcome.message}
+`
+    );
+  }
+  return outcomes.every((outcome) => outcome.ok) ? 0 : 1;
+}
 
 // src/core/render.ts
 var HEAD_KEYS = /* @__PURE__ */ new Set([
@@ -627,7 +826,10 @@ program.name("sentinel").description("One CLI that guards code health: presets,
 ).option("--report", "deprecated: use --run --json").option("--status", "deprecated: use --inspect").option(
   "--module <name>",
   "from the workspace root: scope to one module (omit = all; inside a module dir, drop this)"
-).option("--preset <name>", `the stack preset to apply (${PRESET_NAMES.join(", ")})`).option("--flavour <name>", "deprecated: use --preset").option("--runner <tool>", "override the default runner (e.g. eslint, biome)").option("--ci", "CI mode: from the root, only the affected modules; non-zero exit on failure").option("--fix", "auto-fix where applicable").option("--dry-run", "preview the changes without writing (--init)").option("--json", "machine-readable output, for every verb").option(
+).option("--preset <name>", `the stack preset to apply (${PRESET_NAMES.join(", ")})`).option("--flavour <name>", "deprecated: use --preset").option("--runner <tool>", "override the default runner (e.g. eslint, biome)").option("--ci", "CI mode: from the root, only the affected modules; non-zero exit on failure").option("--fix", "auto-fix where applicable").option("--dry-run", "preview the changes without writing (--init)").option(
+  "--rehearse",
+  "with --init --dry-run: run the lint and format autofixes in a throwaway copy and name the source they rewrite (as slow as the real pass)"
+).option("--json", "machine-readable output, for every verb").option(
   "--output <shape>",
   "output shape for a role that writes reports (console, json, html, markdown); console by default"
 ).option(
@@ -650,7 +852,8 @@ program.name("sentinel").description("One CLI that guards code health: presets,
     // Deliberately not enumerated here. A hand-written list drifts, and this one did: it
     // still said "lint, format, typescript" after the build role shipped, so the help told
     // adopters the build was not covered when it was. "Available now", below, is derived.
-    "  sentinel --init --preset react                     # adopt every available role (see below)",
+    "  sentinel --init --preset react                     # a new module: adopt every available role",
+    "  sentinel --init                                    # an adopted module: re-init the roles it has",
     "  sentinel --init --typescript --preset react       # set up the current module + workspace",
     "  sentinel --run --typescript -- --noImplicitAny     # ask the tool a question of your own"
   ].join("\n")
@@ -742,6 +945,11 @@ if (!Number.isInteger(maxDiagnostics) || maxDiagnostics < 0) {
 if (opts.dryRun && verb !== "init") {
   program.error("--dry-run only applies to --init (the read verbs never write).");
 }
+if (opts.rehearse && !opts.dryRun) {
+  program.error(
+    "--rehearse only applies to --init --dry-run: the real --init runs the autofix passes themselves."
+  );
+}
 if (toolArgs.length > 0) {
   if (verb !== "run") {
     program.error(
@@ -769,6 +977,7 @@ async function main() {
     cwd,
     targets,
     targetsExplicit,
+    allTargets: Boolean(opts.all),
     preset,
     toolArgs,
     maxDiagnostics,
@@ -781,6 +990,7 @@ async function main() {
     // a role that writes reports: two ways to ask for the same thing would be a trap.
     output: parseOutput(opts.output, Boolean(opts.json)) ?? (opts.json ? "json" : void 0),
     dryRun: Boolean(opts.dryRun),
+    rehearse: Boolean(opts.rehearse),
     fail: (message) => program.error(message)
   };
   const exitCode = verb === "init" ? await runInit(context) : verb === "validate" ? await runValidate(context) : await runVerb(context);