@webpieces/ai-hook-rules 0.4.711 → 0.4.713

package/src/bin/l0-ignored-tools.d.ts

@@ -0,0 +1,38 @@
+/**
+ * THE CODEX TOOLS L0 HAS NOTHING TO SAY ABOUT — its own module because BOTH halves of L0 read it and
+ * neither may reach the other: `l0-allowlist.ts` splices the sh alternation into the rendered shim, and
+ * `l0-decide.ts` asks the JS predicate. A set that lived in either one would make the other import it
+ * for a reason unrelated to that file's job.
+ *
+ * Dependency-free on purpose, like every other L0 module: it has to load on a tree too broken to build a
+ * DI container.
+ */
+/**
+ * TOOLS WITH NOTHING TO JUDGE — the Codex tools that are neither a shell command nor a file edit.
+ *
+ * MEASURED in a live codex-cli 0.151.0 session: `webrun`, `collaborationspawn_agent`,
+ * `collaborationwait_agent`, `view_image`, `update_plan`. The CodexAdapter already maps them to the
+ * `Ignored` routing kind on a HEALTHY tree; this is the same answer one layer out, for the fail-CLOSED
+ * path, where the guard bin never runs and the shim decides alone.
+ *
+ * Without it, an L0 fault (D/X/U/K/S) turns every one of these into a DENY: `update_plan` is how a Codex
+ * agent records what it intends to do next, so the agent would be blocked from RECORDING the cure while
+ * being told to run it. That is the deadlock shape the whole allowlist exists to remove, and it is why
+ * this is a set and not a comment.
+ *
+ * AN EXPLICIT LIST, NOT "anything unrecognised" — and that asymmetry with CodexAdapter.kindOf() is
+ * deliberate. The adapter's default is safe because a healthy tree still has every guard behind it; L0's
+ * default must be DENY, or a future write-capable Codex tool would be waved straight past a fault the
+ * day it ships. So `apply_patch` is deliberately ABSENT: it is Codex's only WRITE, it is not a cure, and
+ * under a fault it must fail closed exactly as `Write`/`Edit` do.
+ *
+ * Keep in sync with L0_IGNORED_TOOLS_SH below (locked by the twin unit test).
+ */
+export declare const L0_IGNORED_TOOLS: ReadonlySet<string>;
+/**
+ * sh twin of L0_IGNORED_TOOLS — the alternation the rendered shim splices into a `case` pattern.
+ *
+ * BUILT from the set rather than retyped, for the reason every other twin in this file is: two hand-kept
+ * lists is two answers to one question, and the one that drifts is always the one nobody is reading.
+ */
+export declare const L0_IGNORED_TOOLS_SH: string;

package/src/bin/l0-ignored-tools.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.L0_IGNORED_TOOLS_SH = exports.L0_IGNORED_TOOLS = void 0;
+/**
+ * THE CODEX TOOLS L0 HAS NOTHING TO SAY ABOUT — its own module because BOTH halves of L0 read it and
+ * neither may reach the other: `l0-allowlist.ts` splices the sh alternation into the rendered shim, and
+ * `l0-decide.ts` asks the JS predicate. A set that lived in either one would make the other import it
+ * for a reason unrelated to that file's job.
+ *
+ * Dependency-free on purpose, like every other L0 module: it has to load on a tree too broken to build a
+ * DI container.
+ */
+/**
+ * TOOLS WITH NOTHING TO JUDGE — the Codex tools that are neither a shell command nor a file edit.
+ *
+ * MEASURED in a live codex-cli 0.151.0 session: `webrun`, `collaborationspawn_agent`,
+ * `collaborationwait_agent`, `view_image`, `update_plan`. The CodexAdapter already maps them to the
+ * `Ignored` routing kind on a HEALTHY tree; this is the same answer one layer out, for the fail-CLOSED
+ * path, where the guard bin never runs and the shim decides alone.
+ *
+ * Without it, an L0 fault (D/X/U/K/S) turns every one of these into a DENY: `update_plan` is how a Codex
+ * agent records what it intends to do next, so the agent would be blocked from RECORDING the cure while
+ * being told to run it. That is the deadlock shape the whole allowlist exists to remove, and it is why
+ * this is a set and not a comment.
+ *
+ * AN EXPLICIT LIST, NOT "anything unrecognised" — and that asymmetry with CodexAdapter.kindOf() is
+ * deliberate. The adapter's default is safe because a healthy tree still has every guard behind it; L0's
+ * default must be DENY, or a future write-capable Codex tool would be waved straight past a fault the
+ * day it ships. So `apply_patch` is deliberately ABSENT: it is Codex's only WRITE, it is not a cure, and
+ * under a fault it must fail closed exactly as `Write`/`Edit` do.
+ *
+ * Keep in sync with L0_IGNORED_TOOLS_SH below (locked by the twin unit test).
+ */
+exports.L0_IGNORED_TOOLS = new Set([
+    'webrun', 'collaborationspawn_agent', 'collaborationwait_agent', 'view_image', 'update_plan',
+]);
+/**
+ * sh twin of L0_IGNORED_TOOLS — the alternation the rendered shim splices into a `case` pattern.
+ *
+ * BUILT from the set rather than retyped, for the reason every other twin in this file is: two hand-kept
+ * lists is two answers to one question, and the one that drifts is always the one nobody is reading.
+ */
+exports.L0_IGNORED_TOOLS_SH = [...exports.L0_IGNORED_TOOLS].join('|');
+//# sourceMappingURL=l0-ignored-tools.js.map

package/src/bin/l0-ignored-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"l0-ignored-tools.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/bin/l0-ignored-tools.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;GAQG;AACH;;;;;;;;;;;;;;;;;;;;GAoBG;AACU,QAAA,gBAAgB,GAAwB,IAAI,GAAG,CAAC;IACzD,QAAQ,EAAE,0BAA0B,EAAE,yBAAyB,EAAE,YAAY,EAAE,aAAa;CAC/F,CAAC,CAAC;AAEH;;;;;GAKG;AACU,QAAA,mBAAmB,GAAG,CAAC,GAAG,wBAAgB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC","sourcesContent":["/**\n * THE CODEX TOOLS L0 HAS NOTHING TO SAY ABOUT — its own module because BOTH halves of L0 read it and\n * neither may reach the other: `l0-allowlist.ts` splices the sh alternation into the rendered shim, and\n * `l0-decide.ts` asks the JS predicate. A set that lived in either one would make the other import it\n * for a reason unrelated to that file's job.\n *\n * Dependency-free on purpose, like every other L0 module: it has to load on a tree too broken to build a\n * DI container.\n */\n/**\n * TOOLS WITH NOTHING TO JUDGE — the Codex tools that are neither a shell command nor a file edit.\n *\n * MEASURED in a live codex-cli 0.151.0 session: `webrun`, `collaborationspawn_agent`,\n * `collaborationwait_agent`, `view_image`, `update_plan`. The CodexAdapter already maps them to the\n * `Ignored` routing kind on a HEALTHY tree; this is the same answer one layer out, for the fail-CLOSED\n * path, where the guard bin never runs and the shim decides alone.\n *\n * Without it, an L0 fault (D/X/U/K/S) turns every one of these into a DENY: `update_plan` is how a Codex\n * agent records what it intends to do next, so the agent would be blocked from RECORDING the cure while\n * being told to run it. That is the deadlock shape the whole allowlist exists to remove, and it is why\n * this is a set and not a comment.\n *\n * AN EXPLICIT LIST, NOT \"anything unrecognised\" — and that asymmetry with CodexAdapter.kindOf() is\n * deliberate. The adapter's default is safe because a healthy tree still has every guard behind it; L0's\n * default must be DENY, or a future write-capable Codex tool would be waved straight past a fault the\n * day it ships. So `apply_patch` is deliberately ABSENT: it is Codex's only WRITE, it is not a cure, and\n * under a fault it must fail closed exactly as `Write`/`Edit` do.\n *\n * Keep in sync with L0_IGNORED_TOOLS_SH below (locked by the twin unit test).\n */\nexport const L0_IGNORED_TOOLS: ReadonlySet<string> = new Set([\n    'webrun', 'collaborationspawn_agent', 'collaborationwait_agent', 'view_image', 'update_plan',\n]);\n\n/**\n * sh twin of L0_IGNORED_TOOLS — the alternation the rendered shim splices into a `case` pattern.\n *\n * BUILT from the set rather than retyped, for the reason every other twin in this file is: two hand-kept\n * lists is two answers to one question, and the one that drifts is always the one nobody is reading.\n */\nexport const L0_IGNORED_TOOLS_SH = [...L0_IGNORED_TOOLS].join('|');\n"]}

package/src/bin/setup-config.d.ts

@@ -0,0 +1,19 @@
+type Json = Record<string, unknown>;
+type RuleEntry = Json;
+type Section = Record<string, RuleEntry>;
+interface ConfigFile {
+    extends?: string;
+    rules: Section;
+    hookGuards: Section;
+    commands: Json;
+    excludePaths: string[];
+    'match-rules': Json[];
+    rulesDir: string[];
+}
+interface MigrateResult {
+    config: ConfigFile;
+    changes: string[];
+}
+export declare function migrate(existing: Json): MigrateResult;
+export declare function seedOrSyncConfig(projectRoot: string): void;
+export {};

package/src/bin/setup-config.js

@@ -0,0 +1,370 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.migrate = migrate;
+exports.seedOrSyncConfig = seedOrSyncConfig;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const rules_config_1 = require("@webpieces/rules-config");
+const to_error_1 = require("../core/to-error");
+/**
+ * SEEDING AND MIGRATING `webpieces.config.json` — the installer's OTHER job.
+ *
+ * Split out of ./setup.ts purely for size, and along the seam that was already there: setup.ts is now
+ * hook WIRING (which settings file gets which matcher and which shim command) and this module is CONFIG
+ * SHAPE (which rules exist, where a retired key moves to). They share only `main()`, which calls this
+ * once and then wires the hooks.
+ *
+ * Like setup.ts it is deliberately DI-FREE: `wp-install-ai-hooks` has to run on a half-written
+ * node_modules (see install-entry.ts), so every function here is module-scope and imports nothing that
+ * needs a container.
+ */
+const CONFIG_FILENAME = 'webpieces.config.json';
+// The seeded buildCommand comes from @webpieces/rules-config, NOT from a copy here. This file used to
+// hold its own — with `--base=origin/main`, a DIFFERENT base from the one the gate documents — so a
+// freshly set-up repo was seeded with a command that rebuilds projects touched by other people's
+// merged PRs, and whole-repo-build-guard then quoted that command back in its refusals.
+const DEFAULT_UPSERT_PR = 'pnpm wp-start-upsert-pr';
+const DEFAULT_MERGE_COMPLETE = 'pnpm wp-finish-upsert-pr';
+// webpieces-disable no-function-outside-class -- sibling of the other seed* helpers; this module is config-shape builders by design
+function seedRule(ruleName) {
+    // Both escape hatches are seeded (and REQUIRED) so every rule block shows them: 0 = active,
+    // null = no branch scoping. A human/AI edits these to time-box or branch-scope a rule off.
+    //
+    // The ENTIRE entry comes from rules-config's seedEntryForRule() — the same module that owns the
+    // schema the loader validates against, so the installer can never emit an entry the loader
+    // rejects. It supplies: the recommended mode (the SAME recommendation the validator prints in its
+    // copy-paste snippet, so seed and advice cannot disagree), both hatches, and a default for every
+    // other schema-REQUIRED field. Seeding used to be a flat 'OFF' plus the two hatches, which was
+    // wrong twice over: adopters got nothing enforced, AND the entry was missing required fields
+    // (e.g. branch-creation-guard.autoReapMergedBranches), so the config failed to load on first run.
+    return (0, rules_config_1.seedEntryForRule)(ruleName);
+}
+// The guard-hint command strings live under `guardHints`. The flat `upsertPr`/`mergeComplete` keys this
+// used to seed are RETIRED and now fail validation — seeding them meant every freshly installed repo was
+// born on a shape the validator rejects.
+// webpieces-disable no-function-outside-class -- this module is deliberately DI-FREE: `wp-install-ai-hooks` must run on a half-written node_modules (see install-entry.ts), so it cannot build a container to hold a method
+function seedCommands() {
+    return {
+        'pr-gate': { mode: 'OFF', buildCommand: rules_config_1.DEFAULT_BUILD_COMMAND, gates: [] },
+        guardHints: { prCreationOrPush: DEFAULT_UPSERT_PR, mergeInProgress: DEFAULT_MERGE_COMPLETE },
+    };
+}
+// Required excludePaths block: ONE glob list suppressing hook enforcement per file path. Seeded empty
+// (enforce everywhere) — a client adds paths (e.g. "repositories/**") to exempt vendored trees.
+//
+// Deliberately NOT seeded with webpieces' own `.webpieces/` state dir. That exemption lives in CODE
+// (`isWebpiecesStateDir`, consulted by `filterByExcludedPaths` ahead of this list and regardless of it),
+// and a glob here would be a second, weaker spelling of it — weaker because `.webpieces/**` compiles to
+// an anchored regex that misses the bare directory the predicate matches, and because a config entry
+// invites a consumer to delete it and believe the exemption went with it.
+// webpieces-disable no-function-outside-class -- sibling of the other seed* helpers; this module is config-shape builders by design
+function seedExcludePaths() {
+    return [];
+}
+// Bring an existing `excludePaths` forward to the single-list shape. Already a list → untouched.
+// Legacy `{ rules, guards }` → unioned (order preserved, duplicates dropped) and recorded as a change
+// so `wp-install-ai-hooks` is the migration path rather than a hand-edit. Anything else → seeded [].
+// webpieces-disable no-any-unknown -- `raw` is opaque consumer JSON until narrowed here
+// webpieces-disable no-function-outside-class -- sibling of the other seed*/migrate* helpers; this module is config-shape builders by design
+function migrateExcludePaths(raw, changes) {
+    if (Array.isArray(raw))
+        return raw.filter(p => typeof p === 'string');
+    if (typeof raw === 'object' && raw !== null) {
+        // webpieces-disable no-any-unknown -- narrowing the opaque legacy block from consumer JSON
+        const legacy = raw;
+        const rules = Array.isArray(legacy['rules']) ? legacy['rules'] : [];
+        const guards = Array.isArray(legacy['guards']) ? legacy['guards'] : [];
+        const merged = [...new Set([...rules, ...guards].filter(p => typeof p === 'string'))];
+        changes.push(`migrated excludePaths {rules,guards} -> one list (${merged.length} path(s))`);
+        return merged;
+    }
+    changes.push('added excludePaths ([])');
+    return seedExcludePaths();
+}
+/** One retired flat command string and the guardHints field it becomes. Data-only (per CLAUDE.md). */
+class GuardHintMove {
+    retiredKey;
+    hintKey;
+    fallback;
+    constructor(retiredKey, hintKey, fallback) {
+        this.retiredKey = retiredKey;
+        this.hintKey = hintKey;
+        this.fallback = fallback;
+    }
+}
+/**
+ * Bring `commands` forward to the `guardHints` shape, moving the RETIRED flat `upsertPr`/`mergeComplete`
+ * strings and DELETING them. Deleting is the point: the validator now rejects them, so leaving them behind
+ * would keep the config failing after a "successful" sync.
+ *
+ * The consumer's own value wins over the default — a repo that renamed its gated command keeps that name.
+ */
+// webpieces-disable no-function-outside-class -- sibling of the other seed*/migrate* helpers; this module is config-shape builders by design
+function migrateGuardHints(commands, changes) {
+    const hints = (typeof commands['guardHints'] === 'object' && commands['guardHints'] !== null)
+        ? commands['guardHints'] : {};
+    const moves = [
+        new GuardHintMove('upsertPr', 'prCreationOrPush', DEFAULT_UPSERT_PR),
+        new GuardHintMove('mergeComplete', 'mergeInProgress', DEFAULT_MERGE_COMPLETE),
+    ];
+    for (const move of moves) {
+        const retiredKey = move.retiredKey;
+        const hintKey = move.hintKey;
+        const fallback = move.fallback;
+        const carried = commands[retiredKey];
+        if (carried !== undefined) {
+            delete commands[retiredKey];
+            if (hints[hintKey] === undefined)
+                hints[hintKey] = carried;
+            changes.push(`moved retired commands.${retiredKey} -> commands.guardHints.${hintKey}`);
+        }
+        if (hints[hintKey] === undefined) {
+            hints[hintKey] = fallback;
+            changes.push(`added commands.guardHints.${hintKey}`);
+        }
+    }
+    commands['guardHints'] = hints;
+}
+/**
+ * Apply the RETIRED rule/guard retirements in place. These used to be rewritten silently at load time, so
+ * a consumer's file kept the dead name forever; the loader now rejects it, which makes this the one
+ * command that can fix the file. Skips a rename when the new name is already configured, so an explicit
+ * entry is never clobbered by a stale one.
+ *
+ * NOT EVERY RETIREMENT IS A RENAME, and treating them all as one produced garbage. `whole-repo-build-guard`
+ * moved OUT of webpieces.config.json entirely — its `movedTo` is the PROSE destination
+ * `~/.webpieces/config.json → experimental.whole-repo-build-guard`, not a sibling key — so the rename
+ * branch below would have created a hookGuards entry literally named that whole sentence, which no
+ * validator knows and which the next run reports as another unknown rule. `prunable` is the discriminator:
+ * when the entry says deleting is the whole fix, DELETE it, exactly as `ConfigPruner` does.
+ */
+// webpieces-disable no-function-outside-class -- sibling of the other seed*/migrate* helpers; this module is config-shape builders by design
+function migrateRetiredRuleNames(section, changes) {
+    for (const entry of rules_config_1.RETIRED_CONFIG_KEYS) {
+        if (entry.scope !== rules_config_1.RETIRED_SCOPE_RULE)
+            continue;
+        if (!(entry.key in section))
+            continue;
+        if (entry.prunable) {
+            delete section[entry.key];
+            changes.push(`deleted retired "${entry.key}" (it moved to ${entry.movedTo})`);
+            continue;
+        }
+        mergeIntoDestination(section, entry.key, entry.movedTo, changes);
+    }
+    fillRequiredFields(section, changes);
+}
+/**
+ * Fold one retired key's entry into its destination, whether the destination exists yet or not.
+ *
+ * THIS IS N→1, NOT 1:1, and the difference is the whole reason this helper exists. Four retired keys
+ * now point at ONE destination (`branch-state-guard`, `pr-lifecycle-guard`). The previous code renamed
+ * the first key it met and then, finding the destination already present, DELETED each of the other
+ * three outright — so which guard's settings survived depended on RETIRED_CONFIG_KEYS declaration
+ * order rather than on the consumer's file, and the survivor carried only that one guard's fields, so
+ * it was missing required fields of the merged schema. `wp-install-ai-hooks` is the command advertised
+ * as the migration path; half-migrating every consumer into an invalid config is not an option.
+ *
+ * UNION, first writer wins per field. Earlier-declared keys are the more specific ones (only
+ * feature-branch-guard carries `branchNamingConvention`), and a field already present on the
+ * destination — because the consumer wrote it, or an earlier key contributed it — is never overwritten.
+ * Fields the merged schema does not know are dropped by the same pass, since carrying a deleted field
+ * across (`upsertPrCommand`) would produce a config the validator immediately rejects.
+ */
+// webpieces-disable no-function-outside-class -- sibling of the other seed*/migrate* helpers; this module is config-shape builders by design
+function mergeIntoDestination(section, key, destination, changes) {
+    const source = asSection(section[key]);
+    delete section[key];
+    const fields = (0, rules_config_1.schemaFieldNames)(destination);
+    const target = asSection(section[destination]);
+    const existed = destination in section;
+    const carried = [];
+    const dropped = [];
+    for (const field of Object.keys(source)) {
+        if (fields !== null && !fields.includes(field)) {
+            dropped.push(field);
+            continue;
+        }
+        if (field in target)
+            continue;
+        target[field] = source[field];
+        carried.push(field);
+    }
+    section[destination] = target;
+    const verb = existed ? 'merged' : 'renamed';
+    const droppedNote = dropped.length > 0 ? `; dropped deleted field(s) ${dropped.join(', ')}` : '';
+    changes.push(`${verb} retired "${key}" -> "${destination}" (carried ${carried.join(', ') || 'nothing new'}${droppedNote})`);
+}
+/**
+ * Fill any schema-REQUIRED field a migrated entry ended up without.
+ *
+ * A union of four partial entries is not guaranteed to satisfy the destination's schema — the merged
+ * `branch-state-guard` needs `mode` and both escape hatches, and a consumer whose four old entries
+ * predate one of them would land short. Seeding the gap from the SAME source the installer and the
+ * validator use (seedEntryForRule) is what makes the install command a complete instruction
+ * rather than a first step. Only ever ADDS; a value the consumer stated is never touched.
+ */
+// webpieces-disable no-function-outside-class -- sibling of the other seed*/migrate* helpers; this module is config-shape builders by design
+function fillRequiredFields(section, changes) {
+    for (const name of Object.keys(section)) {
+        if ((0, rules_config_1.schemaFieldNames)(name) === null)
+            continue;
+        // A rule ENTRY is a flat bag of scalars, so it is read as Json here rather than through
+        // asSection (whose values are whole entries). Same object either way; only the view differs.
+        const entry = asSection(section[name]);
+        const seed = (0, rules_config_1.seedEntryForRule)(name);
+        const added = [];
+        for (const field of Object.keys(seed)) {
+            if (field in entry)
+                continue;
+            entry[field] = seed[field];
+            added.push(field);
+        }
+        if (added.length === 0)
+            continue;
+        section[name] = entry;
+        changes.push(`filled required field(s) on "${name}": ${added.join(', ')}`);
+    }
+}
+// Deep-copy the framework's default match-rules (the no-fetch guard) into plain JSON for the config
+// file. Round-tripping through JSON turns the MatchRuleConfig instances into plain objects.
+// webpieces-disable no-function-outside-class -- this module is deliberately DI-FREE: `wp-install-ai-hooks` must run on a half-written node_modules (see install-entry.ts), so it cannot build a container to hold a method
+function seedMatchRules() {
+    return JSON.parse(JSON.stringify(rules_config_1.DEFAULT_MATCH_RULES));
+}
+// webpieces-disable no-function-outside-class -- this module is deliberately DI-FREE: `wp-install-ai-hooks` must run on a half-written node_modules (see install-entry.ts), so it cannot build a container to hold a method
+function buildSeedConfig() {
+    const rules = {};
+    const hookGuards = {};
+    for (const name of (0, rules_config_1.allRuleNames)()) {
+        if ((0, rules_config_1.sectionForRule)(name) === 'hookGuards')
+            hookGuards[name] = seedRule(name);
+        else
+            rules[name] = seedRule(name);
+    }
+    return {
+        rules, hookGuards, commands: seedCommands(), excludePaths: seedExcludePaths(),
+        // Seed the required match-rules array with the framework's default no-fetch guard. A fresh
+        // project gets contract-first enforcement out of the box; clients edit it and add more entries.
+        'match-rules': seedMatchRules(),
+        rulesDir: [],
+    };
+}
+// webpieces-disable no-function-outside-class -- this module is deliberately DI-FREE: `wp-install-ai-hooks` must run on a half-written node_modules (see install-entry.ts), so it cannot build a container to hold a method
+function writeConfig(configPath, config) {
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 4) + '\n');
+}
+// webpieces-disable no-function-outside-class -- this module is deliberately DI-FREE: `wp-install-ai-hooks` must run on a half-written node_modules (see install-entry.ts), so it cannot build a container to hold a method
+function readConfig(configPath) {
+    const raw = fs.readFileSync(configPath, 'utf8');
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        const error = (0, to_error_1.toError)(err);
+        throw new Error(`${CONFIG_FILENAME} has invalid JSON — fix it, then retry: ${error.message}`, { cause: error });
+    }
+}
+// webpieces-disable no-function-outside-class -- this module is deliberately DI-FREE: `wp-install-ai-hooks` must run on a half-written node_modules (see install-entry.ts), so it cannot build a container to hold a method
+function asSection(value) {
+    return (typeof value === 'object' && value !== null && !Array.isArray(value)) ? value : {};
+}
+// Migrate an existing config to the rules / hookGuards / commands layout and add any missing rules.
+// Returns a human-readable list of what changed (empty = already up to date).
+// webpieces-disable no-function-outside-class -- this module is deliberately DI-FREE: `wp-install-ai-hooks` must run on a half-written node_modules (see install-entry.ts), so it cannot build a container to hold a method
+function migrate(existing) {
+    const changes = [];
+    const rules = asSection(existing['rules']);
+    const hookGuards = asSection(existing['hookGuards']);
+    const commands = (typeof existing['commands'] === 'object' && existing['commands'] !== null)
+        ? existing['commands'] : {};
+    // Move a deprecated top-level pr-gate block under commands.
+    if (existing['pr-gate'] !== undefined && commands['pr-gate'] === undefined) {
+        commands['pr-gate'] = existing['pr-gate'];
+        changes.push('moved top-level "pr-gate" → commands["pr-gate"]');
+    }
+    // Apply retired RENAMES first, so a renamed guard is placed and presence-checked under its new name
+    // rather than being treated as unknown and re-added alongside its own stale entry.
+    migrateRetiredRuleNames(rules, changes);
+    migrateRetiredRuleNames(hookGuards, changes);
+    // Move guards mistakenly left in rules into hookGuards.
+    for (const name of Object.keys(rules)) {
+        if ((0, rules_config_1.isHookGuard)(name)) {
+            hookGuards[name] = rules[name];
+            delete rules[name];
+            changes.push(`moved "${name}" from rules → hookGuards`);
+        }
+    }
+    // Move code rules mistakenly placed in hookGuards back into rules.
+    for (const name of Object.keys(hookGuards)) {
+        if (!(0, rules_config_1.isHookGuard)(name) && (0, rules_config_1.allRuleNames)().includes(name)) {
+            rules[name] = hookGuards[name];
+            delete hookGuards[name];
+            changes.push(`moved "${name}" from hookGuards → rules`);
+        }
+    }
+    // Add any missing built-in into its correct section, ENFORCING at its recommended mode (not OFF).
+    for (const name of (0, rules_config_1.allRuleNames)()) {
+        const target = (0, rules_config_1.sectionForRule)(name) === 'hookGuards' ? hookGuards : rules;
+        if (!(name in target)) {
+            const entry = seedRule(name);
+            target[name] = entry;
+            changes.push(`added "${name}" (${String(entry['mode'])}) to ${(0, rules_config_1.sectionForRule)(name)}`);
+        }
+    }
+    // Fill command defaults.
+    if (commands['pr-gate'] === undefined) {
+        commands['pr-gate'] = { mode: 'OFF', buildCommand: rules_config_1.DEFAULT_BUILD_COMMAND, gates: [] };
+        changes.push('added commands["pr-gate"] (OFF)');
+    }
+    migrateGuardHints(commands, changes);
+    // Seed the now-required excludePaths list (empty = enforce everywhere) if the config predates it,
+    // and MIGRATE the legacy `{ rules: [], guards: [] }` object to the single list by unioning them.
+    // The union is behaviour-preserving for every config we have seen (both lists set identically), and
+    // widening is the safe direction anyway: a path either side excluded stays excluded.
+    const excludePaths = migrateExcludePaths(existing['excludePaths'], changes);
+    // Seed the now-required match-rules array (with the default no-fetch guard) if the config predates
+    // it. A client that has already customized it keeps their array untouched.
+    let matchRules;
+    if (Array.isArray(existing['match-rules'])) {
+        matchRules = existing['match-rules'];
+    }
+    else {
+        matchRules = seedMatchRules();
+        changes.push('added "match-rules" (seeded with the no-fetch guard)');
+    }
+    const rulesDir = Array.isArray(existing['rulesDir']) ? existing['rulesDir'] : [];
+    const config = { rules, hookGuards, commands, excludePaths, 'match-rules': matchRules, rulesDir };
+    if (typeof existing['extends'] === 'string')
+        config.extends = existing['extends'];
+    return { config, changes };
+}
+// Seed the config when it is missing, migrate it when it is not. ONE behaviour, always — there is no
+// "migrate but stop here" mode any more. The flag that used to select it was never NECESSARY (the validator prints
+// the exact edit for every error at once, and editing webpieces.config.json is always allowed through the
+// guard — the documented primary cure), it REFUSED to act when the config was missing (useless in the one
+// case automation would have helped), and it gave deny messages a second competing path when they are
+// supposed to end in exactly one action. Readers also mistook it for the shim-repair command, which it
+// never was — `wp-upgrade-shim` is that.
+// webpieces-disable no-function-outside-class -- setup.ts is deliberately DI-free (it must run on a half-written node_modules; see install-entry.ts), so every function here is module-scope
+function seedOrSyncConfig(projectRoot) {
+    const configPath = path.join(projectRoot, CONFIG_FILENAME);
+    if (!fs.existsSync(configPath)) {
+        writeConfig(configPath, buildSeedConfig());
+        console.log(`  [ai-hooks] Created ${CONFIG_FILENAME} (rules / hookGuards / commands); each rule seeded at its recommended mode — gradual where supported, so only code you change is enforced.`);
+        console.log('  Enable the ones you want by changing "mode".');
+        return;
+    }
+    const result = migrate(readConfig(configPath));
+    if (result.changes.length === 0) {
+        console.log(`  [ai-hooks] ${CONFIG_FILENAME} already uses the rules / hookGuards / commands layout — no changes.`);
+        return;
+    }
+    writeConfig(configPath, result.config);
+    console.log(`  [ai-hooks] Migrated ${CONFIG_FILENAME}:`);
+    for (const change of result.changes)
+        console.log(`    - ${change}`);
+}
+//# sourceMappingURL=setup-config.js.map

package/src/bin/setup-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-config.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/bin/setup-config.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport * as path from 'path';\n\nimport {\n    allRuleNames, seedEntryForRule, schemaFieldNames, sectionForRule, isHookGuard, DEFAULT_MATCH_RULES,\n    DEFAULT_BUILD_COMMAND, RETIRED_CONFIG_KEYS, RETIRED_SCOPE_RULE,\n} from '@webpieces/rules-config';\n\nimport { toError } from '../core/to-error';\n\n/**\n * SEEDING AND MIGRATING `webpieces.config.json` — the installer's OTHER job.\n *\n * Split out of ./setup.ts purely for size, and along the seam that was already there: setup.ts is now\n * hook WIRING (which settings file gets which matcher and which shim command) and this module is CONFIG\n * SHAPE (which rules exist, where a retired key moves to). They share only `main()`, which calls this\n * once and then wires the hooks.\n *\n * Like setup.ts it is deliberately DI-FREE: `wp-install-ai-hooks` has to run on a half-written\n * node_modules (see install-entry.ts), so every function here is module-scope and imports nothing that\n * needs a container.\n */\nconst CONFIG_FILENAME = 'webpieces.config.json';\n// The seeded buildCommand comes from @webpieces/rules-config, NOT from a copy here. This file used to\n// hold its own — with `--base=origin/main`, a DIFFERENT base from the one the gate documents — so a\n// freshly set-up repo was seeded with a command that rebuilds projects touched by other people's\n// merged PRs, and whole-repo-build-guard then quoted that command back in its refusals.\nconst DEFAULT_UPSERT_PR = 'pnpm wp-start-upsert-pr';\nconst DEFAULT_MERGE_COMPLETE = 'pnpm wp-finish-upsert-pr';\n// ---------------------------------------------------------------------------\n// webpieces.config.json seeding + migration to the rules / hookGuards / commands layout.\n// ---------------------------------------------------------------------------\n// webpieces-disable no-any-unknown -- webpieces.config.json / settings.json are opaque consumer JSON\ntype Json = Record<string, unknown>;\ntype RuleEntry = Json;\ntype Section = Record<string, RuleEntry>;\n\ninterface ConfigFile {\n    extends?: string;\n    rules: Section;\n    hookGuards: Section;\n    commands: Json;\n    excludePaths: string[];\n    'match-rules': Json[];\n    rulesDir: string[];\n}\n\ninterface MigrateResult {\n    config: ConfigFile;\n    changes: string[];\n}\n\n// webpieces-disable no-function-outside-class -- sibling of the other seed* helpers; this module is config-shape builders by design\nfunction seedRule(ruleName: string): RuleEntry {\n    // Both escape hatches are seeded (and REQUIRED) so every rule block shows them: 0 = active,\n    // null = no branch scoping. A human/AI edits these to time-box or branch-scope a rule off.\n    //\n    // The ENTIRE entry comes from rules-config's seedEntryForRule() — the same module that owns the\n    // schema the loader validates against, so the installer can never emit an entry the loader\n    // rejects. It supplies: the recommended mode (the SAME recommendation the validator prints in its\n    // copy-paste snippet, so seed and advice cannot disagree), both hatches, and a default for every\n    // other schema-REQUIRED field. Seeding used to be a flat 'OFF' plus the two hatches, which was\n    // wrong twice over: adopters got nothing enforced, AND the entry was missing required fields\n    // (e.g. branch-creation-guard.autoReapMergedBranches), so the config failed to load on first run.\n    return seedEntryForRule(ruleName);\n}\n\n// The guard-hint command strings live under `guardHints`. The flat `upsertPr`/`mergeComplete` keys this\n// used to seed are RETIRED and now fail validation — seeding them meant every freshly installed repo was\n// born on a shape the validator rejects.\n// webpieces-disable no-function-outside-class -- this module is deliberately DI-FREE: `wp-install-ai-hooks` must run on a half-written node_modules (see install-entry.ts), so it cannot build a container to hold a method\nfunction seedCommands(): Json {\n    return {\n        'pr-gate': { mode: 'OFF', buildCommand: DEFAULT_BUILD_COMMAND, gates: [] },\n        guardHints: { prCreationOrPush: DEFAULT_UPSERT_PR, mergeInProgress: DEFAULT_MERGE_COMPLETE },\n    };\n}\n\n// Required excludePaths block: ONE glob list suppressing hook enforcement per file path. Seeded empty\n// (enforce everywhere) — a client adds paths (e.g. \"repositories/**\") to exempt vendored trees.\n//\n// Deliberately NOT seeded with webpieces' own `.webpieces/` state dir. That exemption lives in CODE\n// (`isWebpiecesStateDir`, consulted by `filterByExcludedPaths` ahead of this list and regardless of it),\n// and a glob here would be a second, weaker spelling of it — weaker because `.webpieces/**` compiles to\n// an anchored regex that misses the bare directory the predicate matches, and because a config entry\n// invites a consumer to delete it and believe the exemption went with it.\n// webpieces-disable no-function-outside-class -- sibling of the other seed* helpers; this module is config-shape builders by design\nfunction seedExcludePaths(): string[] {\n    return [];\n}\n\n// Bring an existing `excludePaths` forward to the single-list shape. Already a list → untouched.\n// Legacy `{ rules, guards }` → unioned (order preserved, duplicates dropped) and recorded as a change\n// so `wp-install-ai-hooks` is the migration path rather than a hand-edit. Anything else → seeded [].\n// webpieces-disable no-any-unknown -- `raw` is opaque consumer JSON until narrowed here\n// webpieces-disable no-function-outside-class -- sibling of the other seed*/migrate* helpers; this module is config-shape builders by design\nfunction migrateExcludePaths(raw: unknown, changes: string[]): string[] {\n    if (Array.isArray(raw)) return (raw as string[]).filter(p => typeof p === 'string');\n    if (typeof raw === 'object' && raw !== null) {\n        // webpieces-disable no-any-unknown -- narrowing the opaque legacy block from consumer JSON\n        const legacy = raw as Record<string, unknown>;\n        const rules = Array.isArray(legacy['rules']) ? (legacy['rules'] as string[]) : [];\n        const guards = Array.isArray(legacy['guards']) ? (legacy['guards'] as string[]) : [];\n        const merged = [...new Set([...rules, ...guards].filter(p => typeof p === 'string'))];\n        changes.push(`migrated excludePaths {rules,guards} -> one list (${merged.length} path(s))`);\n        return merged;\n    }\n    changes.push('added excludePaths ([])');\n    return seedExcludePaths();\n}\n\n/** One retired flat command string and the guardHints field it becomes. Data-only (per CLAUDE.md). */\nclass GuardHintMove {\n    retiredKey: string;\n    hintKey: string;\n    fallback: string;\n\n    constructor(retiredKey: string, hintKey: string, fallback: string) {\n        this.retiredKey = retiredKey;\n        this.hintKey = hintKey;\n        this.fallback = fallback;\n    }\n}\n\n/**\n * Bring `commands` forward to the `guardHints` shape, moving the RETIRED flat `upsertPr`/`mergeComplete`\n * strings and DELETING them. Deleting is the point: the validator now rejects them, so leaving them behind\n * would keep the config failing after a \"successful\" sync.\n *\n * The consumer's own value wins over the default — a repo that renamed its gated command keeps that name.\n */\n// webpieces-disable no-function-outside-class -- sibling of the other seed*/migrate* helpers; this module is config-shape builders by design\nfunction migrateGuardHints(commands: Json, changes: string[]): void {\n    const hints: Json = (typeof commands['guardHints'] === 'object' && commands['guardHints'] !== null)\n        ? (commands['guardHints'] as Json) : {};\n    const moves: readonly GuardHintMove[] = [\n        new GuardHintMove('upsertPr', 'prCreationOrPush', DEFAULT_UPSERT_PR),\n        new GuardHintMove('mergeComplete', 'mergeInProgress', DEFAULT_MERGE_COMPLETE),\n    ];\n    for (const move of moves) {\n        const retiredKey = move.retiredKey;\n        const hintKey = move.hintKey;\n        const fallback = move.fallback;\n        const carried = commands[retiredKey];\n        if (carried !== undefined) {\n            delete commands[retiredKey];\n            if (hints[hintKey] === undefined) hints[hintKey] = carried;\n            changes.push(`moved retired commands.${retiredKey} -> commands.guardHints.${hintKey}`);\n        }\n        if (hints[hintKey] === undefined) {\n            hints[hintKey] = fallback;\n            changes.push(`added commands.guardHints.${hintKey}`);\n        }\n    }\n    commands['guardHints'] = hints;\n}\n\n/**\n * Apply the RETIRED rule/guard retirements in place. These used to be rewritten silently at load time, so\n * a consumer's file kept the dead name forever; the loader now rejects it, which makes this the one\n * command that can fix the file. Skips a rename when the new name is already configured, so an explicit\n * entry is never clobbered by a stale one.\n *\n * NOT EVERY RETIREMENT IS A RENAME, and treating them all as one produced garbage. `whole-repo-build-guard`\n * moved OUT of webpieces.config.json entirely — its `movedTo` is the PROSE destination\n * `~/.webpieces/config.json → experimental.whole-repo-build-guard`, not a sibling key — so the rename\n * branch below would have created a hookGuards entry literally named that whole sentence, which no\n * validator knows and which the next run reports as another unknown rule. `prunable` is the discriminator:\n * when the entry says deleting is the whole fix, DELETE it, exactly as `ConfigPruner` does.\n */\n// webpieces-disable no-function-outside-class -- sibling of the other seed*/migrate* helpers; this module is config-shape builders by design\nfunction migrateRetiredRuleNames(section: Section, changes: string[]): void {\n    for (const entry of RETIRED_CONFIG_KEYS) {\n        if (entry.scope !== RETIRED_SCOPE_RULE) continue;\n        if (!(entry.key in section)) continue;\n        if (entry.prunable) {\n            delete section[entry.key];\n            changes.push(`deleted retired \"${entry.key}\" (it moved to ${entry.movedTo})`);\n            continue;\n        }\n        mergeIntoDestination(section, entry.key, entry.movedTo, changes);\n    }\n    fillRequiredFields(section, changes);\n}\n\n/**\n * Fold one retired key's entry into its destination, whether the destination exists yet or not.\n *\n * THIS IS N→1, NOT 1:1, and the difference is the whole reason this helper exists. Four retired keys\n * now point at ONE destination (`branch-state-guard`, `pr-lifecycle-guard`). The previous code renamed\n * the first key it met and then, finding the destination already present, DELETED each of the other\n * three outright — so which guard's settings survived depended on RETIRED_CONFIG_KEYS declaration\n * order rather than on the consumer's file, and the survivor carried only that one guard's fields, so\n * it was missing required fields of the merged schema. `wp-install-ai-hooks` is the command advertised\n * as the migration path; half-migrating every consumer into an invalid config is not an option.\n *\n * UNION, first writer wins per field. Earlier-declared keys are the more specific ones (only\n * feature-branch-guard carries `branchNamingConvention`), and a field already present on the\n * destination — because the consumer wrote it, or an earlier key contributed it — is never overwritten.\n * Fields the merged schema does not know are dropped by the same pass, since carrying a deleted field\n * across (`upsertPrCommand`) would produce a config the validator immediately rejects.\n */\n// webpieces-disable no-function-outside-class -- sibling of the other seed*/migrate* helpers; this module is config-shape builders by design\nfunction mergeIntoDestination(section: Section, key: string, destination: string, changes: string[]): void {\n    const source = asSection(section[key]);\n    delete section[key];\n    const fields = schemaFieldNames(destination);\n    const target = asSection(section[destination]);\n    const existed = destination in section;\n    const carried: string[] = [];\n    const dropped: string[] = [];\n    for (const field of Object.keys(source)) {\n        if (fields !== null && !fields.includes(field)) { dropped.push(field); continue; }\n        if (field in target) continue;\n        target[field] = source[field];\n        carried.push(field);\n    }\n    section[destination] = target;\n    const verb = existed ? 'merged' : 'renamed';\n    const droppedNote = dropped.length > 0 ? `; dropped deleted field(s) ${dropped.join(', ')}` : '';\n    changes.push(`${verb} retired \"${key}\" -> \"${destination}\" (carried ${carried.join(', ') || 'nothing new'}${droppedNote})`);\n}\n\n/**\n * Fill any schema-REQUIRED field a migrated entry ended up without.\n *\n * A union of four partial entries is not guaranteed to satisfy the destination's schema — the merged\n * `branch-state-guard` needs `mode` and both escape hatches, and a consumer whose four old entries\n * predate one of them would land short. Seeding the gap from the SAME source the installer and the\n * validator use (seedEntryForRule) is what makes the install command a complete instruction\n * rather than a first step. Only ever ADDS; a value the consumer stated is never touched.\n */\n// webpieces-disable no-function-outside-class -- sibling of the other seed*/migrate* helpers; this module is config-shape builders by design\nfunction fillRequiredFields(section: Section, changes: string[]): void {\n    for (const name of Object.keys(section)) {\n        if (schemaFieldNames(name) === null) continue;\n        // A rule ENTRY is a flat bag of scalars, so it is read as Json here rather than through\n        // asSection (whose values are whole entries). Same object either way; only the view differs.\n        const entry: Json = asSection(section[name]);\n        const seed = seedEntryForRule(name);\n        const added: string[] = [];\n        for (const field of Object.keys(seed)) {\n            if (field in entry) continue;\n            entry[field] = seed[field];\n            added.push(field);\n        }\n        if (added.length === 0) continue;\n        section[name] = entry;\n        changes.push(`filled required field(s) on \"${name}\": ${added.join(', ')}`);\n    }\n}\n\n// Deep-copy the framework's default match-rules (the no-fetch guard) into plain JSON for the config\n// file. Round-tripping through JSON turns the MatchRuleConfig instances into plain objects.\n// webpieces-disable no-function-outside-class -- this module is deliberately DI-FREE: `wp-install-ai-hooks` must run on a half-written node_modules (see install-entry.ts), so it cannot build a container to hold a method\nfunction seedMatchRules(): Json[] {\n    return JSON.parse(JSON.stringify(DEFAULT_MATCH_RULES)) as Json[];\n}\n\n// webpieces-disable no-function-outside-class -- this module is deliberately DI-FREE: `wp-install-ai-hooks` must run on a half-written node_modules (see install-entry.ts), so it cannot build a container to hold a method\nfunction buildSeedConfig(): ConfigFile {\n    const rules: Section = {};\n    const hookGuards: Section = {};\n    for (const name of allRuleNames()) {\n        if (sectionForRule(name) === 'hookGuards') hookGuards[name] = seedRule(name);\n        else rules[name] = seedRule(name);\n    }\n    return {\n        rules, hookGuards, commands: seedCommands(), excludePaths: seedExcludePaths(),\n        // Seed the required match-rules array with the framework's default no-fetch guard. A fresh\n        // project gets contract-first enforcement out of the box; clients edit it and add more entries.\n        'match-rules': seedMatchRules(),\n        rulesDir: [],\n    };\n}\n\n// webpieces-disable no-function-outside-class -- this module is deliberately DI-FREE: `wp-install-ai-hooks` must run on a half-written node_modules (see install-entry.ts), so it cannot build a container to hold a method\nfunction writeConfig(configPath: string, config: ConfigFile): void {\n    fs.writeFileSync(configPath, JSON.stringify(config, null, 4) + '\\n');\n}\n\n// webpieces-disable no-function-outside-class -- this module is deliberately DI-FREE: `wp-install-ai-hooks` must run on a half-written node_modules (see install-entry.ts), so it cannot build a container to hold a method\nfunction readConfig(configPath: string): Json {\n    const raw = fs.readFileSync(configPath, 'utf8');\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        return JSON.parse(raw) as Json;\n    } catch (err: unknown) {\n        const error = toError(err);\n        throw new Error(`${CONFIG_FILENAME} has invalid JSON — fix it, then retry: ${error.message}`, { cause: error });\n    }\n}\n\n// webpieces-disable no-function-outside-class -- this module is deliberately DI-FREE: `wp-install-ai-hooks` must run on a half-written node_modules (see install-entry.ts), so it cannot build a container to hold a method\nfunction asSection(value: Json[string]): Section {\n    return (typeof value === 'object' && value !== null && !Array.isArray(value)) ? (value as Section) : {};\n}\n\n// Migrate an existing config to the rules / hookGuards / commands layout and add any missing rules.\n// Returns a human-readable list of what changed (empty = already up to date).\n// webpieces-disable no-function-outside-class -- this module is deliberately DI-FREE: `wp-install-ai-hooks` must run on a half-written node_modules (see install-entry.ts), so it cannot build a container to hold a method\nexport function migrate(existing: Json): MigrateResult {\n    const changes: string[] = [];\n    const rules: Section = asSection(existing['rules']);\n    const hookGuards: Section = asSection(existing['hookGuards']);\n    const commands: Json = (typeof existing['commands'] === 'object' && existing['commands'] !== null)\n        ? (existing['commands'] as Json) : {};\n\n    // Move a deprecated top-level pr-gate block under commands.\n    if (existing['pr-gate'] !== undefined && commands['pr-gate'] === undefined) {\n        commands['pr-gate'] = existing['pr-gate'];\n        changes.push('moved top-level \"pr-gate\" → commands[\"pr-gate\"]');\n    }\n    // Apply retired RENAMES first, so a renamed guard is placed and presence-checked under its new name\n    // rather than being treated as unknown and re-added alongside its own stale entry.\n    migrateRetiredRuleNames(rules, changes);\n    migrateRetiredRuleNames(hookGuards, changes);\n\n    // Move guards mistakenly left in rules into hookGuards.\n    for (const name of Object.keys(rules)) {\n        if (isHookGuard(name)) {\n            hookGuards[name] = rules[name];\n            delete rules[name];\n            changes.push(`moved \"${name}\" from rules → hookGuards`);\n        }\n    }\n    // Move code rules mistakenly placed in hookGuards back into rules.\n    for (const name of Object.keys(hookGuards)) {\n        if (!isHookGuard(name) && allRuleNames().includes(name)) {\n            rules[name] = hookGuards[name];\n            delete hookGuards[name];\n            changes.push(`moved \"${name}\" from hookGuards → rules`);\n        }\n    }\n    // Add any missing built-in into its correct section, ENFORCING at its recommended mode (not OFF).\n    for (const name of allRuleNames()) {\n        const target = sectionForRule(name) === 'hookGuards' ? hookGuards : rules;\n        if (!(name in target)) {\n            const entry = seedRule(name);\n            target[name] = entry;\n            changes.push(`added \"${name}\" (${String(entry['mode'])}) to ${sectionForRule(name)}`);\n        }\n    }\n    // Fill command defaults.\n    if (commands['pr-gate'] === undefined) {\n        commands['pr-gate'] = { mode: 'OFF', buildCommand: DEFAULT_BUILD_COMMAND, gates: [] };\n        changes.push('added commands[\"pr-gate\"] (OFF)');\n    }\n    migrateGuardHints(commands, changes);\n\n    // Seed the now-required excludePaths list (empty = enforce everywhere) if the config predates it,\n    // and MIGRATE the legacy `{ rules: [], guards: [] }` object to the single list by unioning them.\n    // The union is behaviour-preserving for every config we have seen (both lists set identically), and\n    // widening is the safe direction anyway: a path either side excluded stays excluded.\n    const excludePaths: string[] = migrateExcludePaths(existing['excludePaths'], changes);\n\n    // Seed the now-required match-rules array (with the default no-fetch guard) if the config predates\n    // it. A client that has already customized it keeps their array untouched.\n    let matchRules: Json[];\n    if (Array.isArray(existing['match-rules'])) {\n        matchRules = existing['match-rules'] as Json[];\n    } else {\n        matchRules = seedMatchRules();\n        changes.push('added \"match-rules\" (seeded with the no-fetch guard)');\n    }\n\n    const rulesDir: string[] = Array.isArray(existing['rulesDir']) ? (existing['rulesDir'] as string[]) : [];\n    const config: ConfigFile = { rules, hookGuards, commands, excludePaths, 'match-rules': matchRules, rulesDir };\n    if (typeof existing['extends'] === 'string') config.extends = existing['extends'];\n    return { config, changes };\n}\n\n// Seed the config when it is missing, migrate it when it is not. ONE behaviour, always — there is no\n// \"migrate but stop here\" mode any more. The flag that used to select it was never NECESSARY (the validator prints\n// the exact edit for every error at once, and editing webpieces.config.json is always allowed through the\n// guard — the documented primary cure), it REFUSED to act when the config was missing (useless in the one\n// case automation would have helped), and it gave deny messages a second competing path when they are\n// supposed to end in exactly one action. Readers also mistook it for the shim-repair command, which it\n// never was — `wp-upgrade-shim` is that.\n// webpieces-disable no-function-outside-class -- setup.ts is deliberately DI-free (it must run on a half-written node_modules; see install-entry.ts), so every function here is module-scope\nexport function seedOrSyncConfig(projectRoot: string): void {\n    const configPath = path.join(projectRoot, CONFIG_FILENAME);\n    if (!fs.existsSync(configPath)) {\n        writeConfig(configPath, buildSeedConfig());\n        console.log(`  [ai-hooks] Created ${CONFIG_FILENAME} (rules / hookGuards / commands); each rule seeded at its recommended mode — gradual where supported, so only code you change is enforced.`);\n        console.log('  Enable the ones you want by changing \"mode\".');\n        return;\n    }\n    const result = migrate(readConfig(configPath));\n    if (result.changes.length === 0) {\n        console.log(`  [ai-hooks] ${CONFIG_FILENAME} already uses the rules / hookGuards / commands layout — no changes.`);\n        return;\n    }\n    writeConfig(configPath, result.config);\n    console.log(`  [ai-hooks] Migrated ${CONFIG_FILENAME}:`);\n    for (const change of result.changes) console.log(`    - ${change}`);\n}\n"]}