npm - @webpieces/rules-config - Versions diffs - 0.4.686 → 0.4.688 - Mend

@webpieces/rules-config 0.4.686 → 0.4.688

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/package.json +1 -1
package/src/builds-log.d.ts +193 -0
package/src/builds-log.js +508 -0
package/src/builds-log.js.map +1 -0
package/src/cli-args.d.ts +5 -2
package/src/cli-args.js +6 -3
package/src/cli-args.js.map +1 -1
package/src/home-config.d.ts +61 -5
package/src/home-config.js +86 -12
package/src/home-config.js.map +1 -1
package/src/index.d.ts +2 -1
package/src/index.js +26 -6
package/src/index.js.map +1 -1
package/src/run-main.js +11 -1
package/src/run-main.js.map +1 -1
package/templates/webpieces.buildlog.md +52 -0

package/src/cli-args.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"cli-args.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/cli-args.ts"],"names":[],"mappings":"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","sourcesContent":["import { injectable, bindingScopeValues } from 'inversify';\nimport { CliExitError } from './cli-exit-error';\n\n/*\n One optional `--flag` a command accepts. Data-only. The description is printed in `--help`, so it is\n * written for the reader who has to DECIDE whether to pass it, not as a restatement of the name.\n /\nexport class CliFlag {\n name: string; // including the leading dashes, e.g. '--no-optional'\n description: string;\n /\n The flag MAY carry a value: `--resolve dean/ONE-2275` or `--resolve=dean/ONE-2275`.\n \n \"May\", not \"must\". The one flag that needs this (`wp-push-dev --resolve`) is meaningful both bare\n * (queue every other copy) and with an argument (queue just that one), and a `valueRequired` variant\n * would be a second concept for a case nothing has. A following token is consumed as the value only\n * when it does not itself start with `-`, so `--resolve --force` still reads as two flags.\n /\n takesValue: boolean;\n\n constructor(name: string, description: string, takesValue = false) {\n this.name = name;\n this.description = description;\n this.takesValue = takesValue;\n }\n}\n\n/\n Usage descriptor for a `wp-` bin. Data-only (classes-over-interfaces): a command name, its one-line\n summary, and the flags it accepts. `CliArgs.classify` turns it into the `--help` / unknown-arg message.\n \n `flags` defaults to [] — the no-argument case stays a two-arg construction, which is what eight of the\n * nine `wp-` bins are. A flag a command does not DECLARE here is still rejected with exit 2: that guard is\n the reason this class exists (`wp-start-upsert-pr --help` once launched a squash-merge), and making it\n * flag-aware must not soften it.\n /\nexport class CliUsage {\n command: string;\n summary: string;\n flags: CliFlag[];\n\n constructor(command: string, summary: string, flags: CliFlag[] = []) {\n this.command = command;\n this.summary = summary;\n this.flags = flags;\n }\n}\n\n/\n Which declared flags argv actually carried. Data-only (a class, per CLAUDE.md), with a `has()` accessor\n * so every consumer asks the question the same way instead of open-coding `includes` against a raw array.\n /\nexport class CliArgSet {\n present: string[];\n // Values for the value-taking flags that carried one, keyed by flag name. A flag passed bare is in\n // `present` but absent here, which is exactly the distinction `--resolve` (bare) vs\n // `--resolve <branch>` needs.\n values: Map<string, string>;\n\n constructor(present: string[] = [], values: Map<string, string> = new Map<string, string>()) {\n this.present = present;\n this.values = values;\n }\n\n has(flag: string): boolean {\n return this.present.includes(flag);\n }\n\n /* The value passed with `flag`, or '' when the flag was absent or passed bare. /\n value(flag: string): string {\n return this.values.get(flag) ?? '';\n }\n}\n\n/\n Data-only outcome of checking argv against a no-argument command. `ok` true → run normally; else\n * `exitCode`/`message` are what the bin should exit with (help = 0, unknown arg = 2). Kept a pure\n * value so it can be asserted directly in tests without provoking a throw.\n /\nexport class CliArgsCheck {\n ok: boolean;\n exitCode: number;\n message: string;\n\n constructor(ok: boolean, exitCode: number, message: string) {\n this.ok = ok;\n this.exitCode = exitCode;\n this.message = message;\n }\n}\n\n/* One argv walk's result: which declared flags were seen, their values, and every unrecognized token. /\nclass CliScan {\n present: string[] = [];\n values: Map<string, string> = new Map<string, string>();\n unknown: string[] = [];\n}\n\n/* Argument guard for the no-argument `wp-` bins. /\n@injectable(bindingScopeValues.Singleton)\nexport class CliArgs {\n // The help/usage block shown for `--help` and appended to an unknown-arg error. A command with no\n // declared flags says so outright, because \"takes no arguments\" is the whole usage for eight of nine.\n private usageText(usage: CliUsage): string {\n const head = `${usage.command} — ${usage.summary}\\n\\n`;\n if (usage.flags.length === 0) {\n return head + `Usage: pnpm ${usage.command}\\nThis command takes no arguments.`;\n }\n const label = (f: CliFlag): string => (f.takesValue ? `${f.name} [<value>]` : f.name);\n const width = Math.max(...usage.flags.map((f: CliFlag): number => label(f).length));\n const rows = usage.flags.map((f: CliFlag): string => ` ${label(f).padEnd(width)} ${f.description}`);\n return head + `Usage: pnpm ${usage.command} [flags]\\n\\nFlags:\\n${rows.join('\\n')}`;\n }\n\n /*\n Pure argv classifier. No args → ok. `--help`/`-h` → not-ok, exit 0 with the usage block. Any token\n * the command did not DECLARE → not-ok, exit 2 naming the offending one(s). Split out from\n * `assertNoArgs`/`parse` so the decision is unit-testable without a thrown exception.\n \n An undeclared token is still fatal even for a command that accepts flags — a mistyped `--no-optionl`\n * must never be silently ignored and then run the flow WITH the reviews the caller meant to skip.\n /\n classify(args: string[], usage: CliUsage): CliArgsCheck {\n if (args.length === 0) return new CliArgsCheck(true, 0, '');\n if (args.includes('--help') \|\| args.includes('-h')) {\n return new CliArgsCheck(false, 0, this.usageText(usage));\n }\n const scan = this.scan(args, usage);\n if (scan.unknown.length > 0) {\n return new CliArgsCheck(false, 2, `❌ Unknown argument(s): ${scan.unknown.join(' ')}\\n\\n` + this.usageText(usage));\n }\n return new CliArgsCheck(true, 0, '');\n }\n\n /\n Walk argv once, classifying every token as a declared flag, a value belonging to the\n * value-taking flag before it, or unknown. ONE walk backs both `classify` and `parse` so the set of\n * tokens the guard accepts and the set `parse` reports can never diverge — an accepted-but-unreported\n * flag would silently run the flow without the behaviour the caller asked for.\n /\n private scan(args: string[], usage: CliUsage): CliScan {\n const byName = new Map<string, CliFlag>();\n for (const flag of usage.flags) byName.set(flag.name, flag);\n const scan = new CliScan();\n for (let i = 0; i < args.length; i += 1) {\n const token = args[i];\n const eq = token.indexOf('=');\n // `--flag=value` — split before lookup so the name is what gets matched, not the whole token.\n const name = eq > 0 ? token.slice(0, eq) : token;\n const flag = byName.get(name);\n if (flag === undefined) {\n scan.unknown.push(token);\n continue;\n }\n scan.present.push(name);\n if (!flag.takesValue) {\n // `--no-optional=x` is a typo, not an accepted flag: the value would be silently dropped.\n if (eq > 0) scan.unknown.push(token);\n continue;\n }\n if (eq > 0) {\n scan.values.set(name, token.slice(eq + 1));\n continue;\n }\n // OPTIONAL value: only a following token that is not itself a flag. `--resolve --force`\n // therefore reads as two flags, not as a resolve of a branch literally named `--force`.\n const next = i + 1 < args.length ? args[i + 1] : '';\n if (next !== '' && !next.startsWith('-')) {\n scan.values.set(name, next);\n i += 1;\n }\n }\n return scan;\n }\n\n /\n The flag-accepting sibling of {@link assertNoArgs}: same guard, but it RETURNS which declared flags\n * were passed. Call it in exactly the same place — first thing inside `runMain`, before the app touches\n * git.\n /\n parse(usage: CliUsage): CliArgSet {\n const args = process.argv.slice(2);\n const check = this.classify(args, usage);\n if (!check.ok) throw new CliExitError(check.exitCode, check.message);\n const scan = this.scan(args, usage);\n return new CliArgSet(scan.present, scan.values);\n }\n\n /\n Call it as the FIRST thing inside `runMain`, BEFORE the app touches git — a bogus flag must\n * never start a mutation flow (the `wp-start-upsert-pr --help` incident: an ignored flag silently\n * launched the squash-merge and stranded the checkout on a `…PreMerge<n>` branch).\n \n Throws `CliExitError` (never `process.exit`) so `runMain` stays the single sanctioned exit site\n * (`no-process-exit-outside-main`): help exits 0, an unknown arg exits 2, and in both cases the\n * flow never begins.\n */\n assertNoArgs(usage: CliUsage): void {\n const check = this.classify(process.argv.slice(2), usage);\n if (check.ok) return;\n throw new CliExitError(check.exitCode, check.message);\n }\n}\n"]}
1	+ {"version":3,"file":"cli-args.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/cli-args.ts"],"names":[],"mappings":"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","sourcesContent":["import { injectable, bindingScopeValues } from 'inversify';\nimport { CliExitError } from './cli-exit-error';\n\n/*\n One optional `--flag` a command accepts. Data-only. The description is printed in `--help`, so it is\n * written for the reader who has to DECIDE whether to pass it, not as a restatement of the name.\n /\nexport class CliFlag {\n name: string; // including the leading dashes, e.g. '--no-optional'\n description: string;\n /\n The flag MAY carry a value: `--resolve dean/ONE-2275` or `--resolve=dean/ONE-2275`.\n \n \"May\", not \"must\". The one flag that needs this (`wp-push-dev --resolve`) is meaningful both bare\n * (queue every other copy) and with an argument (queue just that one), and a `valueRequired` variant\n * would be a second concept for a case nothing has. A following token is consumed as the value only\n * when it does not itself start with `-`, so `--resolve --force` still reads as two flags.\n /\n takesValue: boolean;\n\n constructor(name: string, description: string, takesValue = false) {\n this.name = name;\n this.description = description;\n this.takesValue = takesValue;\n }\n}\n\n/\n Usage descriptor for a `wp-` bin. Data-only (classes-over-interfaces): a command name, its one-line\n summary, and the flags it accepts. `CliArgs.classify` turns it into the `--help` / unknown-arg message.\n \n `flags` defaults to [] — the no-argument case stays a two-arg construction, which is what MOST `wp-`\n bins are. (Deliberately not a count: the last one written down went stale the next time a bin grew a\n * flag, which is exactly the drift the corollary in CLAUDE.md is about.)\n \n A flag a command does not DECLARE here is still rejected with exit 2: that guard is\n * the reason this class exists (`wp-start-upsert-pr --help` once launched a squash-merge), and making it\n * flag-aware must not soften it.\n /\nexport class CliUsage {\n command: string;\n summary: string;\n flags: CliFlag[];\n\n constructor(command: string, summary: string, flags: CliFlag[] = []) {\n this.command = command;\n this.summary = summary;\n this.flags = flags;\n }\n}\n\n/\n Which declared flags argv actually carried. Data-only (a class, per CLAUDE.md), with a `has()` accessor\n * so every consumer asks the question the same way instead of open-coding `includes` against a raw array.\n /\nexport class CliArgSet {\n present: string[];\n // Values for the value-taking flags that carried one, keyed by flag name. A flag passed bare is in\n // `present` but absent here, which is exactly the distinction `--resolve` (bare) vs\n // `--resolve <branch>` needs.\n values: Map<string, string>;\n\n constructor(present: string[] = [], values: Map<string, string> = new Map<string, string>()) {\n this.present = present;\n this.values = values;\n }\n\n has(flag: string): boolean {\n return this.present.includes(flag);\n }\n\n /* The value passed with `flag`, or '' when the flag was absent or passed bare. /\n value(flag: string): string {\n return this.values.get(flag) ?? '';\n }\n}\n\n/\n Data-only outcome of checking argv against a no-argument command. `ok` true → run normally; else\n * `exitCode`/`message` are what the bin should exit with (help = 0, unknown arg = 2). Kept a pure\n * value so it can be asserted directly in tests without provoking a throw.\n /\nexport class CliArgsCheck {\n ok: boolean;\n exitCode: number;\n message: string;\n\n constructor(ok: boolean, exitCode: number, message: string) {\n this.ok = ok;\n this.exitCode = exitCode;\n this.message = message;\n }\n}\n\n/* One argv walk's result: which declared flags were seen, their values, and every unrecognized token. /\nclass CliScan {\n present: string[] = [];\n values: Map<string, string> = new Map<string, string>();\n unknown: string[] = [];\n}\n\n/* Argument guard for the no-argument `wp-` bins. /\n@injectable(bindingScopeValues.Singleton)\nexport class CliArgs {\n // The help/usage block shown for `--help` and appended to an unknown-arg error. A command with no\n // declared flags says so outright, because \"takes no arguments\" is the whole usage for most of them.\n private usageText(usage: CliUsage): string {\n const head = `${usage.command} — ${usage.summary}\\n\\n`;\n if (usage.flags.length === 0) {\n return head + `Usage: pnpm ${usage.command}\\nThis command takes no arguments.`;\n }\n const label = (f: CliFlag): string => (f.takesValue ? `${f.name} [<value>]` : f.name);\n const width = Math.max(...usage.flags.map((f: CliFlag): number => label(f).length));\n const rows = usage.flags.map((f: CliFlag): string => ` ${label(f).padEnd(width)} ${f.description}`);\n return head + `Usage: pnpm ${usage.command} [flags]\\n\\nFlags:\\n${rows.join('\\n')}`;\n }\n\n /*\n Pure argv classifier. No args → ok. `--help`/`-h` → not-ok, exit 0 with the usage block. Any token\n * the command did not DECLARE → not-ok, exit 2 naming the offending one(s). Split out from\n * `assertNoArgs`/`parse` so the decision is unit-testable without a thrown exception.\n \n An undeclared token is still fatal even for a command that accepts flags — a mistyped `--no-optionl`\n * must never be silently ignored and then run the flow WITH the reviews the caller meant to skip.\n /\n classify(args: string[], usage: CliUsage): CliArgsCheck {\n if (args.length === 0) return new CliArgsCheck(true, 0, '');\n if (args.includes('--help') \|\| args.includes('-h')) {\n return new CliArgsCheck(false, 0, this.usageText(usage));\n }\n const scan = this.scan(args, usage);\n if (scan.unknown.length > 0) {\n return new CliArgsCheck(false, 2, `❌ Unknown argument(s): ${scan.unknown.join(' ')}\\n\\n` + this.usageText(usage));\n }\n return new CliArgsCheck(true, 0, '');\n }\n\n /\n Walk argv once, classifying every token as a declared flag, a value belonging to the\n * value-taking flag before it, or unknown. ONE walk backs both `classify` and `parse` so the set of\n * tokens the guard accepts and the set `parse` reports can never diverge — an accepted-but-unreported\n * flag would silently run the flow without the behaviour the caller asked for.\n /\n private scan(args: string[], usage: CliUsage): CliScan {\n const byName = new Map<string, CliFlag>();\n for (const flag of usage.flags) byName.set(flag.name, flag);\n const scan = new CliScan();\n for (let i = 0; i < args.length; i += 1) {\n const token = args[i];\n const eq = token.indexOf('=');\n // `--flag=value` — split before lookup so the name is what gets matched, not the whole token.\n const name = eq > 0 ? token.slice(0, eq) : token;\n const flag = byName.get(name);\n if (flag === undefined) {\n scan.unknown.push(token);\n continue;\n }\n scan.present.push(name);\n if (!flag.takesValue) {\n // `--no-optional=x` is a typo, not an accepted flag: the value would be silently dropped.\n if (eq > 0) scan.unknown.push(token);\n continue;\n }\n if (eq > 0) {\n scan.values.set(name, token.slice(eq + 1));\n continue;\n }\n // OPTIONAL value: only a following token that is not itself a flag. `--resolve --force`\n // therefore reads as two flags, not as a resolve of a branch literally named `--force`.\n const next = i + 1 < args.length ? args[i + 1] : '';\n if (next !== '' && !next.startsWith('-')) {\n scan.values.set(name, next);\n i += 1;\n }\n }\n return scan;\n }\n\n /\n The flag-accepting sibling of {@link assertNoArgs}: same guard, but it RETURNS which declared flags\n * were passed. Call it in exactly the same place — first thing inside `runMain`, before the app touches\n * git.\n /\n parse(usage: CliUsage): CliArgSet {\n const args = process.argv.slice(2);\n const check = this.classify(args, usage);\n if (!check.ok) throw new CliExitError(check.exitCode, check.message);\n const scan = this.scan(args, usage);\n return new CliArgSet(scan.present, scan.values);\n }\n\n /\n Call it as the FIRST thing inside `runMain`, BEFORE the app touches git — a bogus flag must\n * never start a mutation flow (the `wp-start-upsert-pr --help` incident: an ignored flag silently\n * launched the squash-merge and stranded the checkout on a `…PreMerge<n>` branch).\n \n Throws `CliExitError` (never `process.exit`) so `runMain` stays the single sanctioned exit site\n * (`no-process-exit-outside-main`): help exits 0, an unknown arg exits 2, and in both cases the\n * flow never begins.\n */\n assertNoArgs(usage: CliUsage): void {\n const check = this.classify(process.argv.slice(2), usage);\n if (check.ok) return;\n throw new CliExitError(check.exitCode, check.message);\n }\n}\n"]}

package/src/home-config.d.ts CHANGED Viewed

@@ -14,9 +14,10 @@
  * This file is MACHINE-GLOBAL: ONE document on the disk, read by EVERY repo on the machine, and those
  * repos are pinned to DIFFERENT webpieces releases. Two rules follow, and they are not negotiable:
  *
- *   (a) NO KEY MAY EVER BE REQUIRED.  `readOptionalBoolean` is the ONLY reader. There is no
- *       `readRequiredBoolean`, no `RequiredHomeFlag`, no `REQUIRED_HOME_FLAGS` — those existed once and
- *       were deleted; do not reintroduce them under any name.
+ *   (a) NO KEY MAY EVER BE REQUIRED.  `readOptionalBoolean` and `readOptionalPositiveInteger` are the
+ *       ONLY readers, and BOTH are optional-by-construction. There is no `readRequiredBoolean`, no
+ *       `RequiredHomeFlag`, no `REQUIRED_HOME_FLAGS` — those existed once and were deleted; do not
+ *       reintroduce them under any name, in any type.
  *   (b) AN UNKNOWN KEY IS IGNORED, never rejected.  `warnUnknownKeys` warns; nothing throws.
  *
  * Both halves are needed, and either one alone still leaves a file that some installed release rejects:
@@ -40,7 +41,9 @@
  *
  *   UNPARSEABLE   not JSON, or not a single JSON object          → REJECT
  *   RETIRED KEY   listed in RETIRED_HOME_CONFIG_KEYS             → REJECT, carrying the migration
- *   WRONG TYPE    a KNOWN key holding a non-boolean              → REJECT
+ *   WRONG TYPE    a KNOWN key holding a value of the wrong type  → REJECT
+ *                 (a non-boolean for a boolean key; anything but a positive whole number for a
+ *                  numeric one — see `readOptionalPositiveInteger`)
  *   UNKNOWN KEY   a key no version of this validator has heard of → IGNORED, with a warning
  *
  * ─── WHY THE LAST ROW DIFFERS FROM webpieces.config.json, WHICH STAYS STRICT ──────────────────────────
@@ -123,6 +126,22 @@ export declare const HOME_EXPERIMENTAL_SECTION = "experimental";
 export declare const HOME_KEY_BUILD_GATE_LOG_CAPTURE = "buildGateLogCapture";
 export declare const HOME_KEY_WHOLE_REPO_BUILD_GUARD = "whole-repo-build-guard";
 export declare const HOME_KEY_ORPHAN_DIR_SWEEP = "orphan-dir-sweep";
+/**
+ * How many builds may be live on this machine before `pnpm wp-build` refuses to start another. The FIRST
+ * NUMERIC key in this file — see `readOptionalPositiveInteger` for why "known key, wrong type → REJECT"
+ * applies to it exactly as it applies to the booleans.
+ */
+export declare const HOME_KEY_MAX_CONCURRENT_BUILDS = "maxConcurrentBuilds";
+/**
+ * The one NON-boolean default, and the one key whose absent value is not `GUARD_OFF_WHEN_ABSENT`.
+ *
+ * Three, because contention between agents running full sweeps at once was measured at ~3.2x total test
+ * time (CLAUDE.md § "What actually makes builds slow"), and a fourth simultaneous build is well past the
+ * point where anybody gains anything. It is a NUMBER rather than an on/off flag because the useful
+ * machine-to-machine difference here is core count, not opinion — which is also why it is the one key in
+ * this file with a non-false default: "0 builds allowed" would be a machine that cannot build at all.
+ */
+export declare const DEFAULT_MAX_CONCURRENT_BUILDS = 3;
 /**
  * The complete UNDERSTOOD shape. A key not on these lists is ignored with a warning rather than
  * rejected (see the class docblock: this document is machine-global and older releases must survive
@@ -136,6 +155,17 @@ export declare const HOME_KEY_ORPHAN_DIR_SWEEP = "orphan-dir-sweep";
  * Walking the real constant makes the test cover a new key the moment it appears here.
  */
 export declare const ALLOWED_TOP_LEVEL: readonly string[];
+/**
+ * The understood `experimental.*` keys, SPLIT BY VALUE TYPE — because the spec walks these lists to build
+ * a sample document, and a sample that wrote `false` into a numeric key would be rejected by the very
+ * loader it is testing. Splitting them means a key added to either list is covered by the cross-version
+ * invariants automatically, with the right sample value, which is the whole reason the lists are exported.
+ *
+ * `ALLOWED_EXPERIMENTAL` stays the ONE list the validator warns against — derived from the two, never
+ * hand-maintained beside them, so it cannot fall out of step.
+ */
+export declare const ALLOWED_EXPERIMENTAL_BOOLEANS: readonly string[];
+export declare const ALLOWED_EXPERIMENTAL_NUMBERS: readonly string[];
 export declare const ALLOWED_EXPERIMENTAL: readonly string[];
 /** The parsed `~/.webpieces/config.json`. Data-only (per CLAUDE.md — classes, not interfaces, for data). */
 export declare class HomeConfig {
@@ -173,7 +203,17 @@ export declare class HomeConfig {
      * enough that anything still wanted has been noticed.
      */
     orphanDirSweep: boolean;
-    constructor(buildGateLogCapture: boolean, wholeRepoBuildGuard: boolean, orphanDirSweep: boolean);
+    /**
+     * How many builds may be live on this MACHINE before `pnpm wp-build` refuses to start another. Live
+     * is counted from `~/.webpieces/builds.log` — see `builds-log.ts`, and
+     * `decisions/0006-the-build-ledger-is-machine-global.md` for why that file lives outside any repo.
+     *
+     * `DEFAULT_MAX_CONCURRENT_BUILDS` when absent. The gate stages (`wp-review-upsert-pr`,
+     * `wp-finish-upsert-pr`) are NEVER refused whatever this says — blocking the sanctioned path is how
+     * you wedge a PR — though their builds do count toward what refuses an ad-hoc `wp-build`.
+     */
+    maxConcurrentBuilds: number;
+    constructor(buildGateLogCapture: boolean, wholeRepoBuildGuard: boolean, orphanDirSweep: boolean, maxConcurrentBuilds: number);
 }
 /**
  * One retired `~/.webpieces/config.json` key and the mechanical edit that replaces it. Data-only.
@@ -238,6 +278,22 @@ export declare class HomeConfigService {
     private isAbsent;
     private parse;
     private validate;
+    /**
+     * The NUMERIC sibling of {@link readOptionalBoolean}, and the same three rules apply unchanged: the
+     * key is OPTIONAL (absent → `whenAbsent`, stated out loud by the caller), a PRESENT value of the
+     * wrong type is an ERROR, and nothing here ever guesses.
+     *
+     * "Wrong type" is stricter than `typeof value === 'number'`, because for this key the wrong NUMBERS
+     * are as meaningless as the wrong types: `0` is a machine that may never build, `-1` and `2.5` are
+     * not counts of anything, and `NaN` compares false against every threshold and would silently
+     * disable the check. A positive integer is the only value that means something, so it is the only
+     * value accepted — and the rejection names the offending value, exactly as the boolean one does.
+     *
+     * This does NOT soften the machine-global forward-compatibility rule: an UNKNOWN key is still
+     * ignored with a warning. Only a key THIS release understands is type-checked, and no release of
+     * webpieces has ever given `maxConcurrentBuilds` a non-numeric meaning.
+     */
+    private readOptionalPositiveInteger;
     /**
      * An absent key falls back to `whenAbsent`, which every caller states OUT LOUD by passing
      * `GUARD_OFF_WHEN_ABSENT` — an implicit "absent means false" buried in this method would put the

package/src/home-config.js CHANGED Viewed

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HomeConfigService = exports.RETIRED_HOME_CONFIG_KEYS = exports.RetiredHomeConfigKey = exports.HomeConfig = exports.ALLOWED_EXPERIMENTAL = exports.ALLOWED_TOP_LEVEL = exports.HOME_KEY_ORPHAN_DIR_SWEEP = exports.HOME_KEY_WHOLE_REPO_BUILD_GUARD = exports.HOME_KEY_BUILD_GATE_LOG_CAPTURE = exports.HOME_EXPERIMENTAL_SECTION = exports.HOME_CONFIG_FILE = exports.HOME_CONFIG_DIR = void 0;
+exports.HomeConfigService = exports.RETIRED_HOME_CONFIG_KEYS = exports.RetiredHomeConfigKey = exports.HomeConfig = exports.ALLOWED_EXPERIMENTAL = exports.ALLOWED_EXPERIMENTAL_NUMBERS = exports.ALLOWED_EXPERIMENTAL_BOOLEANS = exports.ALLOWED_TOP_LEVEL = exports.DEFAULT_MAX_CONCURRENT_BUILDS = exports.HOME_KEY_MAX_CONCURRENT_BUILDS = exports.HOME_KEY_ORPHAN_DIR_SWEEP = exports.HOME_KEY_WHOLE_REPO_BUILD_GUARD = exports.HOME_KEY_BUILD_GATE_LOG_CAPTURE = exports.HOME_EXPERIMENTAL_SECTION = exports.HOME_CONFIG_FILE = exports.HOME_CONFIG_DIR = void 0;
 const tslib_1 = require("tslib");
 const fs = tslib_1.__importStar(require("fs"));
 const os = tslib_1.__importStar(require("os"));
@@ -24,9 +24,10 @@ const to_error_1 = require("./to-error");
  * This file is MACHINE-GLOBAL: ONE document on the disk, read by EVERY repo on the machine, and those
  * repos are pinned to DIFFERENT webpieces releases. Two rules follow, and they are not negotiable:
  *
- *   (a) NO KEY MAY EVER BE REQUIRED.  `readOptionalBoolean` is the ONLY reader. There is no
- *       `readRequiredBoolean`, no `RequiredHomeFlag`, no `REQUIRED_HOME_FLAGS` — those existed once and
- *       were deleted; do not reintroduce them under any name.
+ *   (a) NO KEY MAY EVER BE REQUIRED.  `readOptionalBoolean` and `readOptionalPositiveInteger` are the
+ *       ONLY readers, and BOTH are optional-by-construction. There is no `readRequiredBoolean`, no
+ *       `RequiredHomeFlag`, no `REQUIRED_HOME_FLAGS` — those existed once and were deleted; do not
+ *       reintroduce them under any name, in any type.
  *   (b) AN UNKNOWN KEY IS IGNORED, never rejected.  `warnUnknownKeys` warns; nothing throws.
  *
  * Both halves are needed, and either one alone still leaves a file that some installed release rejects:
@@ -50,7 +51,9 @@ const to_error_1 = require("./to-error");
  *
  *   UNPARSEABLE   not JSON, or not a single JSON object          → REJECT
  *   RETIRED KEY   listed in RETIRED_HOME_CONFIG_KEYS             → REJECT, carrying the migration
- *   WRONG TYPE    a KNOWN key holding a non-boolean              → REJECT
+ *   WRONG TYPE    a KNOWN key holding a value of the wrong type  → REJECT
+ *                 (a non-boolean for a boolean key; anything but a positive whole number for a
+ *                  numeric one — see `readOptionalPositiveInteger`)
  *   UNKNOWN KEY   a key no version of this validator has heard of → IGNORED, with a warning
  *
  * ─── WHY THE LAST ROW DIFFERS FROM webpieces.config.json, WHICH STAYS STRICT ──────────────────────────
@@ -142,6 +145,12 @@ exports.HOME_KEY_WHOLE_REPO_BUILD_GUARD = 'whole-repo-build-guard';
 // The on/off switch for the orphan-directory sweep `wp-checkout-clean-main` runs. Named for the thing
 // it switches, exactly as the guard key above is — one name, greppable from either end.
 exports.HOME_KEY_ORPHAN_DIR_SWEEP = 'orphan-dir-sweep';
+/**
+ * How many builds may be live on this machine before `pnpm wp-build` refuses to start another. The FIRST
+ * NUMERIC key in this file — see `readOptionalPositiveInteger` for why "known key, wrong type → REJECT"
+ * applies to it exactly as it applies to the booleans.
+ */
+exports.HOME_KEY_MAX_CONCURRENT_BUILDS = 'maxConcurrentBuilds';
 /**
  * EVERY key's value when it is not named — including on the machine with no such file at all, which is
  * essentially every machine. False, for all of them, with no exceptions and no per-key table.
@@ -155,6 +164,16 @@ exports.HOME_KEY_ORPHAN_DIR_SWEEP = 'orphan-dir-sweep';
  * default is stated, free to disagree with this one.
  */
 const GUARD_OFF_WHEN_ABSENT = false;
+/**
+ * The one NON-boolean default, and the one key whose absent value is not `GUARD_OFF_WHEN_ABSENT`.
+ *
+ * Three, because contention between agents running full sweeps at once was measured at ~3.2x total test
+ * time (CLAUDE.md § "What actually makes builds slow"), and a fourth simultaneous build is well past the
+ * point where anybody gains anything. It is a NUMBER rather than an on/off flag because the useful
+ * machine-to-machine difference here is core count, not opinion — which is also why it is the one key in
+ * this file with a non-false default: "0 builds allowed" would be a machine that cannot build at all.
+ */
+exports.DEFAULT_MAX_CONCURRENT_BUILDS = 3;
 /**
  * The complete UNDERSTOOD shape. A key not on these lists is ignored with a warning rather than
  * rejected (see the class docblock: this document is machine-global and older releases must survive
@@ -168,9 +187,22 @@ const GUARD_OFF_WHEN_ABSENT = false;
  * Walking the real constant makes the test cover a new key the moment it appears here.
  */
 exports.ALLOWED_TOP_LEVEL = [exports.HOME_EXPERIMENTAL_SECTION];
-exports.ALLOWED_EXPERIMENTAL = [
+/**
+ * The understood `experimental.*` keys, SPLIT BY VALUE TYPE — because the spec walks these lists to build
+ * a sample document, and a sample that wrote `false` into a numeric key would be rejected by the very
+ * loader it is testing. Splitting them means a key added to either list is covered by the cross-version
+ * invariants automatically, with the right sample value, which is the whole reason the lists are exported.
+ *
+ * `ALLOWED_EXPERIMENTAL` stays the ONE list the validator warns against — derived from the two, never
+ * hand-maintained beside them, so it cannot fall out of step.
+ */
+exports.ALLOWED_EXPERIMENTAL_BOOLEANS = [
     exports.HOME_KEY_WHOLE_REPO_BUILD_GUARD, exports.HOME_KEY_BUILD_GATE_LOG_CAPTURE, exports.HOME_KEY_ORPHAN_DIR_SWEEP,
 ];
+exports.ALLOWED_EXPERIMENTAL_NUMBERS = [exports.HOME_KEY_MAX_CONCURRENT_BUILDS];
+exports.ALLOWED_EXPERIMENTAL = [
+    ...exports.ALLOWED_EXPERIMENTAL_BOOLEANS, ...exports.ALLOWED_EXPERIMENTAL_NUMBERS,
+];
 /**
  * ─── EVERY KEY IS OPTIONAL, AND THAT IS A HARD REQUIREMENT OF WHERE THIS FILE LIVES ───────────────────
  * This file is MACHINE-GLOBAL: one document, read by every repo on the machine, and those repos pin
@@ -234,14 +266,27 @@ class HomeConfig {
      * enough that anything still wanted has been noticed.
      */
     orphanDirSweep;
-    // ALL THREE required, no defaults. A defaulted parameter would leave `new HomeConfig(true)` compiling
+    /**
+     * How many builds may be live on this MACHINE before `pnpm wp-build` refuses to start another. Live
+     * is counted from `~/.webpieces/builds.log` — see `builds-log.ts`, and
+     * `decisions/0006-the-build-ledger-is-machine-global.md` for why that file lives outside any repo.
+     *
+     * `DEFAULT_MAX_CONCURRENT_BUILDS` when absent. The gate stages (`wp-review-upsert-pr`,
+     * `wp-finish-upsert-pr`) are NEVER refused whatever this says — blocking the sanctioned path is how
+     * you wedge a PR — though their builds do count toward what refuses an ad-hoc `wp-build`.
+     */
+    maxConcurrentBuilds;
+    // ALL FOUR required, no defaults. A defaulted parameter would leave `new HomeConfig(true)` compiling
     // after this class grew a second flag, silently meaning "guard off" — an old spelling that still
-    // typechecks with a changed meaning is exactly the shim this repo does not ship. The absent-file
-    // state is constructed in exactly one place — load()'s absent-file branch.
-    constructor(buildGateLogCapture, wholeRepoBuildGuard, orphanDirSweep) {
+    // typechecks with a changed meaning is exactly the shim this repo does not ship. The 3-arg arity this
+    // class had before `maxConcurrentBuilds` is DELETED rather than overloaded, per CLAUDE.md § "NO
+    // webpieces surface is released backwards-compatible": the compile errors ARE the migration. The
+    // absent-file state is constructed in exactly one place — load()'s absent-file branch.
+    constructor(buildGateLogCapture, wholeRepoBuildGuard, orphanDirSweep, maxConcurrentBuilds) {
         this.buildGateLogCapture = buildGateLogCapture;
         this.wholeRepoBuildGuard = wholeRepoBuildGuard;
         this.orphanDirSweep = orphanDirSweep;
+        this.maxConcurrentBuilds = maxConcurrentBuilds;
     }
 }
 exports.HomeConfig = HomeConfig;
@@ -309,7 +354,7 @@ let HomeConfigService = class HomeConfigService {
         // can never disagree. Spelled out rather than defaulted in the constructor — see the note there
         // on why a defaulted parameter is a shim.
         if (raw === null) {
-            return new HomeConfig(GUARD_OFF_WHEN_ABSENT, GUARD_OFF_WHEN_ABSENT, GUARD_OFF_WHEN_ABSENT);
+            return new HomeConfig(GUARD_OFF_WHEN_ABSENT, GUARD_OFF_WHEN_ABSENT, GUARD_OFF_WHEN_ABSENT, exports.DEFAULT_MAX_CONCURRENT_BUILDS);
         }
         return this.validate(this.parse(raw, this.configPath(homeDir)), this.configPath(homeDir));
     }
@@ -396,7 +441,36 @@ let HomeConfigService = class HomeConfigService {
         // webpieces-disable no-any-unknown -- narrowed to a non-null, non-array object one line above
         const experimental = (section ?? {});
         this.warnUnknownKeys(Object.keys(experimental), exports.ALLOWED_EXPERIMENTAL, `${exports.HOME_EXPERIMENTAL_SECTION}.`);
-        return new HomeConfig(this.readOptionalBoolean(experimental, exports.HOME_KEY_BUILD_GATE_LOG_CAPTURE, file, GUARD_OFF_WHEN_ABSENT), this.readOptionalBoolean(experimental, exports.HOME_KEY_WHOLE_REPO_BUILD_GUARD, file, GUARD_OFF_WHEN_ABSENT), this.readOptionalBoolean(experimental, exports.HOME_KEY_ORPHAN_DIR_SWEEP, file, GUARD_OFF_WHEN_ABSENT));
+        return new HomeConfig(this.readOptionalBoolean(experimental, exports.HOME_KEY_BUILD_GATE_LOG_CAPTURE, file, GUARD_OFF_WHEN_ABSENT), this.readOptionalBoolean(experimental, exports.HOME_KEY_WHOLE_REPO_BUILD_GUARD, file, GUARD_OFF_WHEN_ABSENT), this.readOptionalBoolean(experimental, exports.HOME_KEY_ORPHAN_DIR_SWEEP, file, GUARD_OFF_WHEN_ABSENT), this.readOptionalPositiveInteger(experimental, exports.HOME_KEY_MAX_CONCURRENT_BUILDS, file, exports.DEFAULT_MAX_CONCURRENT_BUILDS));
+    }
+    /**
+     * The NUMERIC sibling of {@link readOptionalBoolean}, and the same three rules apply unchanged: the
+     * key is OPTIONAL (absent → `whenAbsent`, stated out loud by the caller), a PRESENT value of the
+     * wrong type is an ERROR, and nothing here ever guesses.
+     *
+     * "Wrong type" is stricter than `typeof value === 'number'`, because for this key the wrong NUMBERS
+     * are as meaningless as the wrong types: `0` is a machine that may never build, `-1` and `2.5` are
+     * not counts of anything, and `NaN` compares false against every threshold and would silently
+     * disable the check. A positive integer is the only value that means something, so it is the only
+     * value accepted — and the rejection names the offending value, exactly as the boolean one does.
+     *
+     * This does NOT soften the machine-global forward-compatibility rule: an UNKNOWN key is still
+     * ignored with a warning. Only a key THIS release understands is type-checked, and no release of
+     * webpieces has ever given `maxConcurrentBuilds` a non-numeric meaning.
+     */
+    // webpieces-disable no-any-unknown -- see parse()
+    // eslint-disable-next-line @typescript-eslint/max-params
+    readOptionalPositiveInteger(experimental, key, file, whenAbsent) {
+        const value = experimental[key];
+        if (value === undefined)
+            return whenAbsent;
+        if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {
+            throw new inform_ai_error_1.InformAiError(this.error(file, `"${exports.HOME_EXPERIMENTAL_SECTION}.${key}" must be a POSITIVE WHOLE NUMBER (1 or more), not ` +
+                `${JSON.stringify(value)}. Write it as a bare JSON number, e.g. ` +
+                `"${key}": ${String(whenAbsent)} — or delete the key to use the default of ` +
+                `${String(whenAbsent)}.`));
+        }
+        return value;
     }
     /**
      * An absent key falls back to `whenAbsent`, which every caller states OUT LOUD by passing

package/src/home-config.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"home-config.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/home-config.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport * as os from 'os';\nimport * as path from 'path';\nimport { injectable, bindingScopeValues } from 'inversify';\n\nimport { InformAiError } from './inform-ai-error';\nimport { toError } from './to-error';\n\n/*\n `~/.webpieces/config.json` — the MACHINE-GLOBAL preference file, and a different thing from the repo's\n * tracked `webpieces.config.json`. It is EXPERIMENTAL and entirely OPTIONAL.\n \n ─── ABSENT IS THE NORMAL STATE, AND IT IS NEVER AN ERROR ─────────────────────────────────────────────\n * Essentially every consumer of these packages has no such file, and for them every `wp-` command must\n behave byte-for-byte as it did before this file was ever read: no error, no warning, no log line, no\n * extra file, nothing. `load()` therefore treats EVERY failure to READ the bytes — the file missing, the\n * `~/.webpieces` directory missing, a permission error, a path component that is not a directory — as\n * \"not opted in\", and returns all-defaults silently. That is not a fallback for a wrong shape; it is the\n * definition of \"the user did not create this file\".\n \n ─── THE STANDING RULE, FOR WHOEVER EDITS THIS FILE NEXT ──────────────────────────────────────────────\n * This file is MACHINE-GLOBAL: ONE document on the disk, read by EVERY repo on the machine, and those\n * repos are pinned to DIFFERENT webpieces releases. Two rules follow, and they are not negotiable:\n \n (a) NO KEY MAY EVER BE REQUIRED. `readOptionalBoolean` is the ONLY reader. There is no\n * `readRequiredBoolean`, no `RequiredHomeFlag`, no `REQUIRED_HOME_FLAGS` — those existed once and\n * were deleted; do not reintroduce them under any name.\n * (b) AN UNKNOWN KEY IS IGNORED, never rejected. `warnUnknownKeys` warns; nothing throws.\n \n Both halves are needed, and either one alone still leaves a file that some installed release rejects:\n \n (a) covers the OLD FILE on a NEW release — a document written before a key existed, missing it.\n * (b) covers the NEW FILE on an OLD release — a document carrying a key that release never heard of.\n \n Break either one and every repo on the machine that is not on the newest release hard-blocks: a\n * rejection here fails config load, and that denies every tool call in that repo until somebody upgrades\n * all of them in lockstep. That is the outage this design exists to make impossible, and it is not\n * hypothetical — it is the shape of the incident recorded at the bottom of this docblock.\n \n `home-config.spec.ts` pins both halves, and pins them by ENUMERATING `ALLOWED_EXPERIMENTAL` rather\n * than by a hand-written list, so a key added later is covered by the invariant automatically instead of\n * silently escaping it.\n \n ─── PRESENT IS STRICT ABOUT WHAT IT UNDERSTANDS, AND FORWARD-COMPATIBLE ABOUT WHAT IT DOES NOT ───────\n * Once the bytes are readable, someone DELIBERATELY created this file, and three of the four failure\n * modes are REJECTED exactly as webpieces.config.json rejects them (see `retired-config-keys.ts`), with\n * an error naming the exact fix and no `??` fallback anywhere:\n \n UNPARSEABLE not JSON, or not a single JSON object → REJECT\n * RETIRED KEY listed in RETIRED_HOME_CONFIG_KEYS → REJECT, carrying the migration\n * WRONG TYPE a KNOWN key holding a non-boolean → REJECT\n * UNKNOWN KEY a key no version of this validator has heard of → IGNORED, with a warning\n \n ─── WHY THE LAST ROW DIFFERS FROM webpieces.config.json, WHICH STAYS STRICT ──────────────────────────\n * The difference is not a softening of policy; it is that the two files have different CARDINALITY.\n \n webpieces.config.json is REPO-TRACKED. One repo, one file, one pinned @webpieces release, and the\n * file moves through git in lockstep with the code that reads it. \"One version reads this document\" is\n * true by construction, so an unknown key there can only be a typo or a dead key — and rejecting it is\n * right, because it is the delivery mechanism for the migration.\n \n THIS file is MACHINE-GLOBAL. ONE document, read by EVERY repo on the machine, and those repos pin\n * DIFFERENT releases — deliberately, since a repo's pin is tracked and moves when its own PR lands.\n * So \"an unknown key\" here has a second, entirely legitimate cause that cannot occur in the repo file:\n * a key a NEWER release added, being read by an OLDER one. Rejecting it means adding any key to this\n * file hard-blocks every repo on the machine that has not yet been upgraded — an outage produced by\n * opting IN to an experimental flag, which is the same shape of failure that moved these flags out of\n * webpieces.config.json in the first place (see the section below).\n \n This is the exact mirror of the already-settled rule that no key here may be REQUIRED. Both halves fall\n * out of one fact: the set of valid documents must be non-empty for EVERY release on the machine at once.\n * • omit a new key → an old release must not demand it (already true: every key is optional)\n * • add a new key → an old release must not reject it (this change)\n * With only the first half, the set of valid files was still empty the moment a key was added.\n \n ─── WHAT THAT COSTS, AND WHAT PAYS FOR IT ────────────────────────────────────────────────────────────\n * The cost is real and worth stating plainly: a TYPO now silently does nothing. `\"whole-repo-build-gaurd\"`\n * used to be a loud rejection; it is now a key nothing reads, so the flag keeps its default and nothing\n * about the machine's behaviour reveals the mistake.\n \n Every key here is an OPT-IN that defaults OFF, so a typo costs the author the feature they meant to\n * switch on: misspell `whole-repo-build-guard` and the guard stays inert while they believe they armed\n * it. That is the milder of the two failures — nothing they were doing stops working — but it is still\n * invisible without a signal, which is why the warning below is not optional decoration, and why\n * `nearestKnownKey` had to get fuzzier than the case-insensitive match it replaced: `gaurd` is a\n * transposition, exactly the class of typo an equality test cannot see.\n \n That is mitigated, not eliminated, by making the ignore VISIBLE: every unknown key is printed once per\n * load as a `[webpieces]` warning on stderr, and `nearestKnownKey` upgrades that line with a \"did you\n * mean\" whenever the key is within a two-character edit of a known one — which is what a typo is, and\n * what a key from a newer release is not. A warning naming a close match is the strongest signal\n * available that does not also block a colleague on an older pin.\n \n The trade was taken this way round because the two mistakes are not symmetric. A typo costs its author\n * one flag that did not turn on, discoverable the moment they check whether the feature is doing\n * anything, on their own machine. A rejection costs every repo on the machine every tool call, and the\n * person it blocks is usually not the person who edited the file.\n \n An unknown TOP-LEVEL key is ignored on the identical argument, and it is the more important half: a\n * future release adding a second section (`preferences`, say) beside `experimental` would otherwise be\n * unreadable by every older release on the machine, which is precisely the sequencing being deleted here.\n \n ─── REJECTING IS STILL SELF-RECOVERABLE, FOR THE THREE ROWS THAT STILL REJECT ────────────────────────\n * A Write/Edit targeting THIS path is an unconditional PASS in the hook guards (see `isHomeConfigPath`,\n * wired into ai-hook-rules' runner beside the webpieces.config.json pass), so an agent can always repair\n * the file the loader just rejected.\n \n ─── WHY A MACHINE-LOCAL SWITCH LIVES HERE AND NOT IN webpieces.config.json ───────────────────────────\n * `whole-repo-build-guard` first shipped as an ordinary validated guard: `mode: 'ON'` by default AND an\n * entry required under `hookGuards`. The consequence on upgrade was an outage — a consumer repo that had\n * not yet added the entry hit fault Y, which blocks EVERY Bash call, for a feature nobody had opted into.\n \n The rule that buys back: a switch that lives HERE needs no file, no key and no edit to be in its\n * default state. A repo-tracked config key cannot express that — an entry there is something every\n * consumer must add, on a schedule set by whoever bumps the release.\n \n Note which half of that was the outage. It was the REQUIRED KEY: the failure was at config LOAD,\n * before any command was judged. That is why every key here stays OPTIONAL and why an absent file\n * returns all-defaults silently.\n \n The DEFAULT is settled separately, by a standing policy this file does not get to re-litigate: EVERY\n * `experimental.` flag ships OFF and stays OFF for two years. `whole-repo-build-guard` is one of them,\n so it is OFF unless a machine writes `{\"experimental\": {\"whole-repo-build-guard\": true}}`. A flag that\n * defaults ON is not an experiment — it is a shipped behaviour that skipped its soak period, and it\n * changes what every agent on every machine can do the moment they upgrade. Low uptake of an opt-in\n * experiment is information ABOUT the experiment; it is not a licence to force it on everybody.\n /\nexport const HOME_CONFIG_DIR = '.webpieces';\nexport const HOME_CONFIG_FILE = 'config.json';\n\n// The `experimental` section and its keys. Named as constants because both the validator and its error\n// text must spell them identically — a validator whose message names a different key than the one it\n// checks is worse than no message.\nexport const HOME_EXPERIMENTAL_SECTION = 'experimental';\nexport const HOME_KEY_BUILD_GATE_LOG_CAPTURE = 'buildGateLogCapture';\n// The on/off switch for `whole-repo-build-guard`. Spelled with the GUARD's own name, hyphens and all,\n// so `grep -rn whole-repo-build-guard` finds the switch beside the guard — and so nobody has to learn a\n// second name for one thing. It is a DIFFERENT key from buildGateLogCapture, which is #620's build-log\n// feature and merely selects WHICH refusal this guard prints.\nexport const HOME_KEY_WHOLE_REPO_BUILD_GUARD = 'whole-repo-build-guard';\n// The on/off switch for the orphan-directory sweep `wp-checkout-clean-main` runs. Named for the thing\n// it switches, exactly as the guard key above is — one name, greppable from either end.\nexport const HOME_KEY_ORPHAN_DIR_SWEEP = 'orphan-dir-sweep';\n\n/\n EVERY key's value when it is not named — including on the machine with no such file at all, which is\n * essentially every machine. False, for all of them, with no exceptions and no per-key table.\n \n That uniformity is the policy, not a coincidence: every `experimental.` flag ships OFF and stays OFF\n for two years, so \"this machine never opted in\" is byte-for-byte the behaviour of having no file. ON\n * requires an explicit `true`; absent, and an explicit `false`, are the same state.\n \n Named rather than written as a bare `false` at each call site so the reason travels with the value —\n * and there is deliberately exactly ONE such constant, because a second one would be a second place a\n * default is stated, free to disagree with this one.\n /\nconst GUARD_OFF_WHEN_ABSENT = false;\n\n/\n The complete UNDERSTOOD shape. A key not on these lists is ignored with a warning rather than\n * rejected (see the class docblock: this document is machine-global and older releases must survive\n * meeting a newer release's key), so adding a key still means adding it here — a key absent from these\n * lists is never read at all, and the flag it was meant to set keeps the default above.\n \n EXPORTED so `home-config.spec.ts` can ENUMERATE them rather than restate them. The cross-version\n * invariant (\"every key is independently omittable\") is only as good as the list the test walks, and a\n * hand-written copy of that list means a NEW key silently escapes the invariant on the day it is added —\n * which is the one failure mode nobody would notice until an older release started rejecting files.\n * Walking the real constant makes the test cover a new key the moment it appears here.\n /\nexport const ALLOWED_TOP_LEVEL: readonly string[] = [HOME_EXPERIMENTAL_SECTION];\nexport const ALLOWED_EXPERIMENTAL: readonly string[] = [\n HOME_KEY_WHOLE_REPO_BUILD_GUARD, HOME_KEY_BUILD_GATE_LOG_CAPTURE, HOME_KEY_ORPHAN_DIR_SWEEP,\n];\n\n/\n ─── EVERY KEY IS OPTIONAL, AND THAT IS A HARD REQUIREMENT OF WHERE THIS FILE LIVES ───────────────────\n * This file is MACHINE-GLOBAL: one document, read by every repo on the machine, and those repos pin\n * DIFFERENT webpieces releases. A REQUIRED key cannot survive that, because it makes the set of valid\n * files EMPTY:\n \n • omit the new key → the NEW release rejects the file (\"REQUIRED and not set\")\n * • add the new key → every OLDER release rejects the file (\"not a known key\")\n \n There is no third option, and both rejections block. `whole-repo-build-guard` was required for the\n * reason recorded in #627 — a flag that decides whether a command RUNS should not be inferred — and that\n * reasoning was sound for a single version and wrong for a shared file. It is optional now, along with\n * every other key.\n \n Absent then reads as the ONE declared default, `GUARD_OFF_WHEN_ABSENT`: false, for every key without\n * exception, which is byte-for-byte the behaviour of having no file at all.\n \n The other half of cross-version safety — an OLD release IGNORING a key a NEW one added, rather than\n * rejecting it — is solved by `warnUnknownKeys` below. The two halves are one invariant: for the set of\n * valid documents to be non-empty across every release installed on the machine, neither omitting a key\n * nor adding one may be an error.\n /\n\n// Read errors that mean \"the file is not there / not reachable\" rather than \"the file is wrong\". Every\n// one of these resolves to the all-defaults config, silently. Widened deliberately past ENOENT: the\n// parent `~/.webpieces` may not exist (ENOENT), may be a file (ENOTDIR), may be unreadable (EACCES /\n// EPERM), and the path itself may be a directory (EISDIR). None of those is a user who opted in.\nconst ABSENT_ERROR_CODES: readonly string[] = ['ENOENT', 'ENOTDIR', 'EACCES', 'EPERM', 'EISDIR', 'ELOOP', 'ENAMETOOLONG'];\n\n/* The parsed `~/.webpieces/config.json`. Data-only (per CLAUDE.md — classes, not interfaces, for data). /\nexport class HomeConfig {\n /\n EXPERIMENTAL, under test, not a supported knob. When true, the pr-gate build gate captures its full\n * output to `.webpieces/logs/` and hands a failing build's pointer to that file to the AI instead of\n * an instruction to rebuild. Default false — i.e. the behaviour every consumer has today.\n /\n buildGateLogCapture: boolean;\n\n /\n EXPERIMENTAL, and OFF unless this machine opts IN with an explicit `true`. When true,\n * `whole-repo-build-guard` BLOCKS a Bash command that would build the WHOLE monorepo and hands back\n * the repo's own scoped build command (`pnpm wp-build`). False — and absent, and no file at all —\n * makes the guard completely inert: no block, no log, no message.\n \n This is the guard's ONLY switch, and it is an OPT-IN. There is deliberately no\n * webpieces.config.json entry for it (see RETIRED_CONFIG_KEYS): a guard that every consumer must\n * ADD A KEY to avoid being blocked by is a guard that ships an outage on upgrade, which is exactly\n * what happened once. Living here means the default state needs no file, no key and no edit.\n /\n wholeRepoBuildGuard: boolean;\n\n /\n EXPERIMENTAL. When true, `wp-checkout-clean-main` ARCHIVES the orphan directories it finds — the\n * package directories left behind on every clone by an `nx g move`, which git cannot remove because\n * an ignored `dist/` or `node_modules/` survives the deletion of every tracked file under them.\n \n False — and the all-defaults value for a machine with no such file — means the sweep only REPORTS\n * what it found and moves nothing. That asymmetry is the point of shipping this behind the home\n * config at all: the author can run it live across their own clones for a release while every\n * colleague's repo is untouched, and neither state depends on a tracked key anybody must add.\n \n The sweep itself never deletes (see OrphanDirArchiver): directories move under `.webpieces/trash/`\n * with a printed `recover=`, so the worst case for a false positive is a `mv` somebody undoes. The\n * ARCHIVE is reaped after 30 days, which is a real deletion — of the second copy, on a timer long\n * enough that anything still wanted has been noticed.\n /\n orphanDirSweep: boolean;\n\n // ALL THREE required, no defaults. A defaulted parameter would leave `new HomeConfig(true)` compiling\n // after this class grew a second flag, silently meaning \"guard off\" — an old spelling that still\n // typechecks with a changed meaning is exactly the shim this repo does not ship. The absent-file\n // state is constructed in exactly one place — load()'s absent-file branch.\n constructor(buildGateLogCapture: boolean, wholeRepoBuildGuard: boolean, orphanDirSweep: boolean) {\n this.buildGateLogCapture = buildGateLogCapture;\n this.wholeRepoBuildGuard = wholeRepoBuildGuard;\n this.orphanDirSweep = orphanDirSweep;\n }\n}\n\n/\n One retired `~/.webpieces/config.json` key and the mechanical edit that replaces it. Data-only.\n \n This mirrors `RetiredConfigKey` rather than reusing it: that table's entries carry a `scope`\n * (rule-name vs key-in-section) that describes webpieces.config.json's two-level layout and means\n * nothing here, and its `label` convention names that file's sections. One shared class covering both\n * would be a type with fields that are dead for half its instances.\n /\nexport class RetiredHomeConfigKey {\n // Dotted path exactly as it appears in the file, e.g. `experimental.captureBuildGateLog`.\n key: string;\n // Where the value goes now. Empty when the key is deleted outright.\n movedTo: string;\n // The imperative fix, written for the agent that will apply it verbatim.\n instruction: string;\n\n constructor(key: string, movedTo: string, instruction: string) {\n this.key = key;\n this.movedTo = movedTo;\n this.instruction = instruction;\n }\n}\n\n/\n Every retired home-config key — the ONE place in the codebase where a dead home-config key may be\n * named, exactly as `RETIRED_CONFIG_KEYS` is for webpieces.config.json. Newest at the bottom.\n \n When you retire a key here, DELETE its read path in the same change. `home-config.spec.ts` asserts\n * every entry below actually FAILS the load, so a fallback that quietly accepts one turns it red.\n /\nexport const RETIRED_HOME_CONFIG_KEYS: readonly RetiredHomeConfigKey[] = [\n // `captureBuildGateLog` was the working name while this feature was being built, and it appears in\n // the branch history and in in-flight drafts, so it is exactly the spelling an agent reconstructing\n // the file from memory will type. It never shipped in a release; it is listed so that typing it\n // produces the rename instruction rather than a bare \"unknown key\".\n new RetiredHomeConfigKey(\n 'experimental.captureBuildGateLog', 'experimental.buildGateLogCapture',\n 'Rename the key to \"buildGateLogCapture\" inside the same \"experimental\" object. Its boolean value ' +\n 'carries over unchanged.',\n ),\n];\n\n/\n Loads and validates `~/.webpieces/config.json`, and resolves whether a path IS that file (for the\n * guard carve-out that keeps a rejection repairable).\n \n Strict about everything it UNDERSTANDS (a retired key, a known key of the wrong type, and a document\n * that is not JSON all throw); forward-compatible about everything it does not (an unknown key is\n * ignored with a warning). The class docblock at the top of this file has the reasoning.\n /\n@injectable(bindingScopeValues.Singleton)\nexport class HomeConfigService {\n /* Absolute path to the preference file. `homeDir` is a parameter so specs never touch a real HOME. /\n configPath(homeDir: string = os.homedir()): string {\n return path.join(homeDir, HOME_CONFIG_DIR, HOME_CONFIG_FILE);\n }\n\n /\n The preferences. Returns all-defaults, silently and without touching anything, when the file is not\n * there. THROWS InformAiError, naming the fix, when a file that IS there is wrong in a way this\n * release can be sure about — unparseable, a RETIRED key, or a KNOWN key of the wrong type. A key it\n * simply does not recognise is ignored with a warning, because it may be a newer release's key and\n * this file is shared by every repo on the machine.\n /\n load(homeDir: string = os.homedir()): HomeConfig {\n const raw = this.readIfPresent(this.configPath(homeDir));\n // THE ABSENT-FILE STATE, and the ONE place it is constructed. Every flag is off — the same value\n // a present file that does not name the key gets, so \"no file\" and \"file that ignores this key\"\n // can never disagree. Spelled out rather than defaulted in the constructor — see the note there\n // on why a defaulted parameter is a shim.\n if (raw === null) {\n return new HomeConfig(\n GUARD_OFF_WHEN_ABSENT, GUARD_OFF_WHEN_ABSENT, GUARD_OFF_WHEN_ABSENT);\n }\n return this.validate(this.parse(raw, this.configPath(homeDir)), this.configPath(homeDir));\n }\n\n /\n True when `candidate` names `~/.webpieces/config.json`, in any of the forms an agent writes it:\n * an absolute path, a `~/`-prefixed path, or one still spelled `$HOME/…` / `${HOME}/…`.\n \n This is what the hook guards call to grant the file an unconditional Write/Edit PASS. Without it a\n * strict loader could reject the file while the guards blocked the edit that would fix it — the one\n * wedge webpieces.config.json is already immune to, and the reason its own carve-out exists.\n /\n isHomeConfigPath(candidate: string, homeDir: string = os.homedir()): boolean {\n if (candidate.trim() === '') return false;\n return path.resolve(this.expandHome(candidate.trim(), homeDir)) === path.resolve(this.configPath(homeDir));\n }\n\n // `~`, `$HOME` and `${HOME}` at the FRONT only — a home reference anywhere else is not a home path.\n private expandHome(candidate: string, homeDir: string): string {\n if (candidate === '~') return homeDir;\n for (const prefix of ['~/', '$HOME/', '${HOME}/']) {\n if (candidate.startsWith(prefix)) return path.join(homeDir, candidate.slice(prefix.length));\n }\n return candidate;\n }\n\n /\n The file's bytes, or null meaning \"no such file — the user did not opt in\".\n \n EVERY read failure is null. This is the single most important behaviour in the file: the absent\n * path is the path every consumer of these packages is on, and it may never reach an error branch.\n * An error code outside ABSENT_ERROR_CODES is genuinely exceptional (EIO, EBUSY) and is rethrown,\n * because silently disabling on a failing disk would be its own kind of lie.\n /\n private readIfPresent(file: string): string \| null {\n // webpieces-disable no-unmanaged-exceptions -- chokepoint: this catch IS the \"you have no such file\"\n // decision, and that decision may never surface as a failure to a user who never created the file\n // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n try {\n return fs.readFileSync(file, 'utf8');\n } catch (err: unknown) {\n const error = toError(err);\n if (this.isAbsent(error)) return null;\n throw error;\n }\n }\n\n private isAbsent(error: Error): boolean {\n // webpieces-disable no-any-unknown -- node attaches `code` to fs errors without typing it on Error\n const code = (error as unknown as Record<string, unknown>)['code'];\n return typeof code === 'string' && ABSENT_ERROR_CODES.includes(code);\n }\n\n // A readable file that is not a JSON object is a WRONG file, not an absent one — hence the throw.\n // webpieces-disable no-any-unknown -- an unvalidated user-authored document; every field is narrowed below\n private parse(raw: string, file: string): Record<string, unknown> {\n // webpieces-disable no-unmanaged-exceptions -- chokepoint: JSON.parse's own message is useless to an\n // agent on its own, so it is re-thrown as the InformAiError that names the file and the fix\n // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n try {\n // webpieces-disable no-any-unknown -- opaque parsed JSON, narrowed immediately below\n const parsed: unknown = JSON.parse(raw);\n if (typeof parsed !== 'object' \|\| parsed === null \|\| Array.isArray(parsed)) {\n throw new InformAiError(this.error(file, 'the file must contain a single JSON OBJECT, e.g. {}.'));\n }\n // webpieces-disable no-any-unknown -- narrowed to a non-null, non-array object one line above\n return parsed as Record<string, unknown>;\n } catch (err: unknown) {\n const error = toError(err);\n if (error instanceof InformAiError) throw error;\n throw new InformAiError(this.error(file, `the file is not valid JSON (${error.message}).`), { cause: error });\n }\n }\n\n // webpieces-disable no-any-unknown -- see parse(); the document is user-authored and unvalidated\n private validate(raw: Record<string, unknown>, file: string): HomeConfig {\n this.assertNotRetired(raw, file);\n this.warnUnknownKeys(Object.keys(raw), ALLOWED_TOP_LEVEL, '');\n const section = raw[HOME_EXPERIMENTAL_SECTION];\n if (section !== undefined && (typeof section !== 'object' \|\| section === null \|\| Array.isArray(section))) {\n throw new InformAiError(this.error(file, `\"${HOME_EXPERIMENTAL_SECTION}\" must be a JSON object.`));\n }\n // webpieces-disable no-any-unknown -- narrowed to a non-null, non-array object one line above\n const experimental = (section ?? {}) as Record<string, unknown>;\n this.warnUnknownKeys(Object.keys(experimental), ALLOWED_EXPERIMENTAL, `${HOME_EXPERIMENTAL_SECTION}.`);\n return new HomeConfig(\n this.readOptionalBoolean(experimental, HOME_KEY_BUILD_GATE_LOG_CAPTURE, file, GUARD_OFF_WHEN_ABSENT),\n this.readOptionalBoolean(experimental, HOME_KEY_WHOLE_REPO_BUILD_GUARD, file, GUARD_OFF_WHEN_ABSENT),\n this.readOptionalBoolean(experimental, HOME_KEY_ORPHAN_DIR_SWEEP, file, GUARD_OFF_WHEN_ABSENT),\n );\n }\n\n /\n An absent key falls back to `whenAbsent`, which every caller states OUT LOUD by passing\n * `GUARD_OFF_WHEN_ABSENT` — an implicit \"absent means false\" buried in this method would put the\n * default and the key that carries it in different places, free to drift apart.\n \n A PRESENT key of the wrong type is still an ERROR, and that is the line neither the unknown-key change\n * nor this one moved: `\"whole-repo-build-guard\": \"yes\"` is a file somebody wrote wrongly, not\n * a file written for a different release. No release of webpieces has ever given this key a string\n * meaning, so there is no forward-compatibility story to protect and nothing is gained by guessing —\n * whereas guessing would turn a typed value into a silent fallback to the default, which is the very\n * cost the unknown-key warning exists to bound.\n \n This is the ONLY reader; see the every-key-is-optional note above for why there is no required\n * variant.\n /\n // webpieces-disable no-any-unknown -- see parse()\n // eslint-disable-next-line @typescript-eslint/max-params\n private readOptionalBoolean(\n experimental: Record<string, unknown>, key: string, file: string, whenAbsent: boolean,\n ): boolean {\n const value = experimental[key];\n if (value === undefined) return whenAbsent;\n return this.asBoolean(value, key, file, ' Remove the quotes, or delete the key.');\n }\n\n // webpieces-disable no-any-unknown -- see parse()\n // eslint-disable-next-line @typescript-eslint/max-params\n private asBoolean(value: unknown, key: string, file: string, fix: string): boolean {\n if (typeof value !== 'boolean') {\n throw new InformAiError(this.error(file,\n `\"${HOME_EXPERIMENTAL_SECTION}.${key}\" must be the boolean ` +\n `true or false, not ${JSON.stringify(value)}.${fix}`));\n }\n return value;\n }\n\n // Retired keys are checked BEFORE unknown-key reporting: \"unknown key\" would send an agent deleting a\n // key whose value it should be MOVING, which is the whole reason the retirement table exists.\n // webpieces-disable no-any-unknown -- see parse()\n private assertNotRetired(raw: Record<string, unknown>, file: string): void {\n for (const entry of RETIRED_HOME_CONFIG_KEYS) {\n if (!this.isPresentAt(raw, entry.key)) continue;\n const destination = entry.movedTo === ''\n ? 'It was removed with no replacement.'\n : `It moved to \"${entry.movedTo}\".`;\n throw new InformAiError(this.error(file,\n `\"${entry.key}\" is RETIRED. ${destination} ${entry.instruction}`));\n }\n }\n\n // Is `dotted` (one or two segments — the file is two levels deep by construction) actually present?\n // webpieces-disable no-any-unknown -- see parse()\n private isPresentAt(raw: Record<string, unknown>, dotted: string): boolean {\n const parts = dotted.split('.');\n if (parts.length === 1) return raw[parts[0]] !== undefined;\n const section = raw[parts[0]];\n if (typeof section !== 'object' \|\| section === null \|\| Array.isArray(section)) return false;\n // webpieces-disable no-any-unknown -- narrowed to a non-null, non-array object one line above\n return (section as Record<string, unknown>)[parts[1]] !== undefined;\n }\n\n /\n The understood keys AT ONE LEVEL, rendered from the allow-list rather than hand-listed — and\n * rendered at the level the reader's key was actually found, so a mistyped SECTION is answered with\n * the sections and a mistyped FLAG with the flags. The hand-listed version named two keys and went\n * stale the moment a third arrived, telling an agent its brand-new key was not accepted while the\n * validator right above accepted it.\n /\n private quotedKeys(allowed: readonly string[], prefix: string): string {\n return allowed.map((key: string): string => `\"${prefix}${key}\"`).join(', ');\n }\n\n /\n An unknown key is IGNORED — see the class docblock for why this one file cannot reject it — but it\n * is never SILENT. The warning is the entire mitigation for the cost of ignoring, so it says both\n * things a reader needs: that the key did nothing, and what the understood keys are.\n \n ─── WHY THIS IS NOT THE \"console side channel\" SHAPE ────────────────────────────────────────────\n * That shape is a rule or a library reporting a FAILURE — or a cure for one — by printing it instead\n * of throwing a structured value to the one top-level handler. This is the opposite case, and the\n * distinction is the entire subject of this change: an unknown key here is NOT a failure. The load\n * SUCCEEDS, a valid HomeConfig is returned, every caller proceeds normally, and there is no cure the\n * reader is obliged to apply — a key from a newer release is a CORRECT file being read by an older\n * validator. There is no throw this could be, because throwing is precisely the behaviour being\n * deleted here; and returning it would mean inventing a warnings channel through `load()` that no\n * caller has any reason to render.\n \n stderr, not stdout, for the usual reason: this runs inside hooks whose stdout is a JSON decision\n * and inside `wp-` commands whose stdout is their real output, and neither may be polluted. It is\n the same channel, with the same `[webpieces]` prefix, that `state-dir-migration.announce` already\n * uses in this package for the same category of finding — something a human may want to know about\n * and is not required to act on.\n /\n private warnUnknownKeys(found: string[], allowed: readonly string[], prefix: string): void {\n for (const key of found) {\n if (allowed.includes(key)) continue;\n const near = this.nearestKnownKey(key, allowed);\n const guess = near !== ''\n ? ` Did you mean \"${prefix}${near}\"?`\n : this.nearRetiredHint(`${prefix}${key}`)\n \|\| ' If it is a typo, fix the spelling; if it is from a NEWER @webpieces than this repo pins, upgrade this repo to use it.';\n this.warn(\n `\"${prefix}${key}\" is not a key this @webpieces release understands, so it was IGNORED ` +\n `and had NO effect.${guess} Understood here: ${this.quotedKeys(allowed, prefix)}.`);\n }\n }\n\n /\n A near-miss of a RETIRED key, pointed at its migration — or '' when nothing retired is close.\n \n The gap this closes: `assertNotRetired` matches a retired key EXACTLY, so `captureBuildGateLog`\n * throws with its rename instruction while `captureBuildGateLogg` — one stray character away, and a\n * far likelier thing to type — falls through to the generic \"IGNORED, might be from a newer release\"\n * line. That is the least helpful of the three answers offered to the reader whose intent is the\n * clearest, so the retired table is consulted here too, at the same distance-2 threshold.\n \n It only ever produces a WARNING, never a throw: this release cannot know whether the reader meant\n * the retired key or a newer one, and guessing wrong in the throwing direction is what the whole\n * change is about. Known keys are matched first, so a typo of a LIVE key is never answered with a\n * dead one.\n /\n private nearRetiredHint(dottedKey: string): string {\n for (const entry of RETIRED_HOME_CONFIG_KEYS) {\n if (this.editDistance(dottedKey.toLowerCase(), entry.key.toLowerCase()) > 2) continue;\n const destination = entry.movedTo === ''\n ? 'it was removed with no replacement'\n : `it moved to \"${entry.movedTo}\"`;\n return ` Did you mean the RETIRED key \"${entry.key}\"? If so, ${destination}. ${entry.instruction}`;\n }\n return '';\n }\n\n // One shape for every non-fatal finding, matching state-dir-migration's `[webpieces] <what>:` prefix\n // so a reader can tell at a glance which subsystem is talking.\n private warn(message: string): void {\n process.stderr.write(`[webpieces] ~/.webpieces/config.json: ${message}\\n`);\n }\n\n /\n The closest understood key within two edits, or '' when nothing is close.\n \n This used to be a case-insensitive EQUALITY test, which was adequate while an unknown key was a\n * hard error — the error itself was the signal, and the suggestion only saved a reading. Now the\n * suggestion IS the signal, so it has to catch the typos an equality test misses: a doubled letter,\n * a dropped one, a transposition, a stray trailing `d` (`buildGateLogCaptured`). Two is the useful\n * threshold — it covers every one of those and still refuses to guess for a genuinely new key, which\n * is the case that must NOT be dressed up as a typo.\n /\n private nearestKnownKey(key: string, allowed: readonly string[]): string {\n let best = '';\n let bestDistance = 3;\n for (const candidate of allowed) {\n const distance = this.editDistance(key.toLowerCase(), candidate.toLowerCase());\n if (distance >= bestDistance) continue;\n bestDistance = distance;\n best = candidate;\n }\n return best;\n }\n\n /* Ordinary Levenshtein distance, one row at a time — the key names are short and this runs once. */\n private editDistance(a: string, b: string): number {\n let previous: number[] = [];\n for (let j = 0; j <= b.length; j += 1) previous.push(j);\n for (let i = 1; i <= a.length; i += 1) {\n const current: number[] = [i];\n for (let j = 1; j <= b.length; j += 1) {\n const substitution = previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1);\n current.push(Math.min(substitution, previous[j] + 1, current[j - 1] + 1));\n }\n previous = current;\n }\n return previous[b.length];\n }\n\n // One shape for every rejection: what is wrong, in which file, and the fact that deleting the file is\n // always a legal fix — because the file is optional, and \"no file\" is a fully supported state.\n private error(file: string, detail: string): string {\n return `[~/.webpieces/config.json] ${detail}\\n\\n` +\n `File: ${file}\\n` +\n `This machine-local preference file is OPTIONAL and EXPERIMENTAL. Editing it is always ` +\n `permitted, even while it is invalid, and deleting it outright is a valid fix — with no such ` +\n `file every webpieces command behaves exactly as it does by default.`;\n }\n}\n"]}
1	+ {"version":3,"file":"home-config.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/home-config.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport * as os from 'os';\nimport * as path from 'path';\nimport { injectable, bindingScopeValues } from 'inversify';\n\nimport { InformAiError } from './inform-ai-error';\nimport { toError } from './to-error';\n\n/*\n `~/.webpieces/config.json` — the MACHINE-GLOBAL preference file, and a different thing from the repo's\n * tracked `webpieces.config.json`. It is EXPERIMENTAL and entirely OPTIONAL.\n \n ─── ABSENT IS THE NORMAL STATE, AND IT IS NEVER AN ERROR ─────────────────────────────────────────────\n * Essentially every consumer of these packages has no such file, and for them every `wp-` command must\n behave byte-for-byte as it did before this file was ever read: no error, no warning, no log line, no\n * extra file, nothing. `load()` therefore treats EVERY failure to READ the bytes — the file missing, the\n * `~/.webpieces` directory missing, a permission error, a path component that is not a directory — as\n * \"not opted in\", and returns all-defaults silently. That is not a fallback for a wrong shape; it is the\n * definition of \"the user did not create this file\".\n \n ─── THE STANDING RULE, FOR WHOEVER EDITS THIS FILE NEXT ──────────────────────────────────────────────\n * This file is MACHINE-GLOBAL: ONE document on the disk, read by EVERY repo on the machine, and those\n * repos are pinned to DIFFERENT webpieces releases. Two rules follow, and they are not negotiable:\n \n (a) NO KEY MAY EVER BE REQUIRED. `readOptionalBoolean` and `readOptionalPositiveInteger` are the\n * ONLY readers, and BOTH are optional-by-construction. There is no `readRequiredBoolean`, no\n * `RequiredHomeFlag`, no `REQUIRED_HOME_FLAGS` — those existed once and were deleted; do not\n * reintroduce them under any name, in any type.\n * (b) AN UNKNOWN KEY IS IGNORED, never rejected. `warnUnknownKeys` warns; nothing throws.\n \n Both halves are needed, and either one alone still leaves a file that some installed release rejects:\n \n (a) covers the OLD FILE on a NEW release — a document written before a key existed, missing it.\n * (b) covers the NEW FILE on an OLD release — a document carrying a key that release never heard of.\n \n Break either one and every repo on the machine that is not on the newest release hard-blocks: a\n * rejection here fails config load, and that denies every tool call in that repo until somebody upgrades\n * all of them in lockstep. That is the outage this design exists to make impossible, and it is not\n * hypothetical — it is the shape of the incident recorded at the bottom of this docblock.\n \n `home-config.spec.ts` pins both halves, and pins them by ENUMERATING `ALLOWED_EXPERIMENTAL` rather\n * than by a hand-written list, so a key added later is covered by the invariant automatically instead of\n * silently escaping it.\n \n ─── PRESENT IS STRICT ABOUT WHAT IT UNDERSTANDS, AND FORWARD-COMPATIBLE ABOUT WHAT IT DOES NOT ───────\n * Once the bytes are readable, someone DELIBERATELY created this file, and three of the four failure\n * modes are REJECTED exactly as webpieces.config.json rejects them (see `retired-config-keys.ts`), with\n * an error naming the exact fix and no `??` fallback anywhere:\n \n UNPARSEABLE not JSON, or not a single JSON object → REJECT\n * RETIRED KEY listed in RETIRED_HOME_CONFIG_KEYS → REJECT, carrying the migration\n * WRONG TYPE a KNOWN key holding a value of the wrong type → REJECT\n * (a non-boolean for a boolean key; anything but a positive whole number for a\n * numeric one — see `readOptionalPositiveInteger`)\n * UNKNOWN KEY a key no version of this validator has heard of → IGNORED, with a warning\n \n ─── WHY THE LAST ROW DIFFERS FROM webpieces.config.json, WHICH STAYS STRICT ──────────────────────────\n * The difference is not a softening of policy; it is that the two files have different CARDINALITY.\n \n webpieces.config.json is REPO-TRACKED. One repo, one file, one pinned @webpieces release, and the\n * file moves through git in lockstep with the code that reads it. \"One version reads this document\" is\n * true by construction, so an unknown key there can only be a typo or a dead key — and rejecting it is\n * right, because it is the delivery mechanism for the migration.\n \n THIS file is MACHINE-GLOBAL. ONE document, read by EVERY repo on the machine, and those repos pin\n * DIFFERENT releases — deliberately, since a repo's pin is tracked and moves when its own PR lands.\n * So \"an unknown key\" here has a second, entirely legitimate cause that cannot occur in the repo file:\n * a key a NEWER release added, being read by an OLDER one. Rejecting it means adding any key to this\n * file hard-blocks every repo on the machine that has not yet been upgraded — an outage produced by\n * opting IN to an experimental flag, which is the same shape of failure that moved these flags out of\n * webpieces.config.json in the first place (see the section below).\n \n This is the exact mirror of the already-settled rule that no key here may be REQUIRED. Both halves fall\n * out of one fact: the set of valid documents must be non-empty for EVERY release on the machine at once.\n * • omit a new key → an old release must not demand it (already true: every key is optional)\n * • add a new key → an old release must not reject it (this change)\n * With only the first half, the set of valid files was still empty the moment a key was added.\n \n ─── WHAT THAT COSTS, AND WHAT PAYS FOR IT ────────────────────────────────────────────────────────────\n * The cost is real and worth stating plainly: a TYPO now silently does nothing. `\"whole-repo-build-gaurd\"`\n * used to be a loud rejection; it is now a key nothing reads, so the flag keeps its default and nothing\n * about the machine's behaviour reveals the mistake.\n \n Every key here is an OPT-IN that defaults OFF, so a typo costs the author the feature they meant to\n * switch on: misspell `whole-repo-build-guard` and the guard stays inert while they believe they armed\n * it. That is the milder of the two failures — nothing they were doing stops working — but it is still\n * invisible without a signal, which is why the warning below is not optional decoration, and why\n * `nearestKnownKey` had to get fuzzier than the case-insensitive match it replaced: `gaurd` is a\n * transposition, exactly the class of typo an equality test cannot see.\n \n That is mitigated, not eliminated, by making the ignore VISIBLE: every unknown key is printed once per\n * load as a `[webpieces]` warning on stderr, and `nearestKnownKey` upgrades that line with a \"did you\n * mean\" whenever the key is within a two-character edit of a known one — which is what a typo is, and\n * what a key from a newer release is not. A warning naming a close match is the strongest signal\n * available that does not also block a colleague on an older pin.\n \n The trade was taken this way round because the two mistakes are not symmetric. A typo costs its author\n * one flag that did not turn on, discoverable the moment they check whether the feature is doing\n * anything, on their own machine. A rejection costs every repo on the machine every tool call, and the\n * person it blocks is usually not the person who edited the file.\n \n An unknown TOP-LEVEL key is ignored on the identical argument, and it is the more important half: a\n * future release adding a second section (`preferences`, say) beside `experimental` would otherwise be\n * unreadable by every older release on the machine, which is precisely the sequencing being deleted here.\n \n ─── REJECTING IS STILL SELF-RECOVERABLE, FOR THE THREE ROWS THAT STILL REJECT ────────────────────────\n * A Write/Edit targeting THIS path is an unconditional PASS in the hook guards (see `isHomeConfigPath`,\n * wired into ai-hook-rules' runner beside the webpieces.config.json pass), so an agent can always repair\n * the file the loader just rejected.\n \n ─── WHY A MACHINE-LOCAL SWITCH LIVES HERE AND NOT IN webpieces.config.json ───────────────────────────\n * `whole-repo-build-guard` first shipped as an ordinary validated guard: `mode: 'ON'` by default AND an\n * entry required under `hookGuards`. The consequence on upgrade was an outage — a consumer repo that had\n * not yet added the entry hit fault Y, which blocks EVERY Bash call, for a feature nobody had opted into.\n \n The rule that buys back: a switch that lives HERE needs no file, no key and no edit to be in its\n * default state. A repo-tracked config key cannot express that — an entry there is something every\n * consumer must add, on a schedule set by whoever bumps the release.\n \n Note which half of that was the outage. It was the REQUIRED KEY: the failure was at config LOAD,\n * before any command was judged. That is why every key here stays OPTIONAL and why an absent file\n * returns all-defaults silently.\n \n The DEFAULT is settled separately, by a standing policy this file does not get to re-litigate: EVERY\n * `experimental.` flag ships OFF and stays OFF for two years. `whole-repo-build-guard` is one of them,\n so it is OFF unless a machine writes `{\"experimental\": {\"whole-repo-build-guard\": true}}`. A flag that\n * defaults ON is not an experiment — it is a shipped behaviour that skipped its soak period, and it\n * changes what every agent on every machine can do the moment they upgrade. Low uptake of an opt-in\n * experiment is information ABOUT the experiment; it is not a licence to force it on everybody.\n /\nexport const HOME_CONFIG_DIR = '.webpieces';\nexport const HOME_CONFIG_FILE = 'config.json';\n\n// The `experimental` section and its keys. Named as constants because both the validator and its error\n// text must spell them identically — a validator whose message names a different key than the one it\n// checks is worse than no message.\nexport const HOME_EXPERIMENTAL_SECTION = 'experimental';\nexport const HOME_KEY_BUILD_GATE_LOG_CAPTURE = 'buildGateLogCapture';\n// The on/off switch for `whole-repo-build-guard`. Spelled with the GUARD's own name, hyphens and all,\n// so `grep -rn whole-repo-build-guard` finds the switch beside the guard — and so nobody has to learn a\n// second name for one thing. It is a DIFFERENT key from buildGateLogCapture, which is #620's build-log\n// feature and merely selects WHICH refusal this guard prints.\nexport const HOME_KEY_WHOLE_REPO_BUILD_GUARD = 'whole-repo-build-guard';\n// The on/off switch for the orphan-directory sweep `wp-checkout-clean-main` runs. Named for the thing\n// it switches, exactly as the guard key above is — one name, greppable from either end.\nexport const HOME_KEY_ORPHAN_DIR_SWEEP = 'orphan-dir-sweep';\n/\n How many builds may be live on this machine before `pnpm wp-build` refuses to start another. The FIRST\n * NUMERIC key in this file — see `readOptionalPositiveInteger` for why \"known key, wrong type → REJECT\"\n * applies to it exactly as it applies to the booleans.\n /\nexport const HOME_KEY_MAX_CONCURRENT_BUILDS = 'maxConcurrentBuilds';\n\n/\n EVERY key's value when it is not named — including on the machine with no such file at all, which is\n * essentially every machine. False, for all of them, with no exceptions and no per-key table.\n \n That uniformity is the policy, not a coincidence: every `experimental.` flag ships OFF and stays OFF\n for two years, so \"this machine never opted in\" is byte-for-byte the behaviour of having no file. ON\n * requires an explicit `true`; absent, and an explicit `false`, are the same state.\n \n Named rather than written as a bare `false` at each call site so the reason travels with the value —\n * and there is deliberately exactly ONE such constant, because a second one would be a second place a\n * default is stated, free to disagree with this one.\n /\nconst GUARD_OFF_WHEN_ABSENT = false;\n\n/\n The one NON-boolean default, and the one key whose absent value is not `GUARD_OFF_WHEN_ABSENT`.\n \n Three, because contention between agents running full sweeps at once was measured at ~3.2x total test\n * time (CLAUDE.md § \"What actually makes builds slow\"), and a fourth simultaneous build is well past the\n * point where anybody gains anything. It is a NUMBER rather than an on/off flag because the useful\n * machine-to-machine difference here is core count, not opinion — which is also why it is the one key in\n * this file with a non-false default: \"0 builds allowed\" would be a machine that cannot build at all.\n /\nexport const DEFAULT_MAX_CONCURRENT_BUILDS = 3;\n\n/\n The complete UNDERSTOOD shape. A key not on these lists is ignored with a warning rather than\n * rejected (see the class docblock: this document is machine-global and older releases must survive\n * meeting a newer release's key), so adding a key still means adding it here — a key absent from these\n * lists is never read at all, and the flag it was meant to set keeps the default above.\n \n EXPORTED so `home-config.spec.ts` can ENUMERATE them rather than restate them. The cross-version\n * invariant (\"every key is independently omittable\") is only as good as the list the test walks, and a\n * hand-written copy of that list means a NEW key silently escapes the invariant on the day it is added —\n * which is the one failure mode nobody would notice until an older release started rejecting files.\n * Walking the real constant makes the test cover a new key the moment it appears here.\n /\nexport const ALLOWED_TOP_LEVEL: readonly string[] = [HOME_EXPERIMENTAL_SECTION];\n/\n The understood `experimental.` keys, SPLIT BY VALUE TYPE — because the spec walks these lists to build\n a sample document, and a sample that wrote `false` into a numeric key would be rejected by the very\n * loader it is testing. Splitting them means a key added to either list is covered by the cross-version\n * invariants automatically, with the right sample value, which is the whole reason the lists are exported.\n \n `ALLOWED_EXPERIMENTAL` stays the ONE list the validator warns against — derived from the two, never\n * hand-maintained beside them, so it cannot fall out of step.\n /\nexport const ALLOWED_EXPERIMENTAL_BOOLEANS: readonly string[] = [\n HOME_KEY_WHOLE_REPO_BUILD_GUARD, HOME_KEY_BUILD_GATE_LOG_CAPTURE, HOME_KEY_ORPHAN_DIR_SWEEP,\n];\nexport const ALLOWED_EXPERIMENTAL_NUMBERS: readonly string[] = [HOME_KEY_MAX_CONCURRENT_BUILDS];\nexport const ALLOWED_EXPERIMENTAL: readonly string[] = [\n ...ALLOWED_EXPERIMENTAL_BOOLEANS, ...ALLOWED_EXPERIMENTAL_NUMBERS,\n];\n\n/\n ─── EVERY KEY IS OPTIONAL, AND THAT IS A HARD REQUIREMENT OF WHERE THIS FILE LIVES ───────────────────\n * This file is MACHINE-GLOBAL: one document, read by every repo on the machine, and those repos pin\n * DIFFERENT webpieces releases. A REQUIRED key cannot survive that, because it makes the set of valid\n * files EMPTY:\n \n • omit the new key → the NEW release rejects the file (\"REQUIRED and not set\")\n * • add the new key → every OLDER release rejects the file (\"not a known key\")\n \n There is no third option, and both rejections block. `whole-repo-build-guard` was required for the\n * reason recorded in #627 — a flag that decides whether a command RUNS should not be inferred — and that\n * reasoning was sound for a single version and wrong for a shared file. It is optional now, along with\n * every other key.\n \n Absent then reads as the ONE declared default, `GUARD_OFF_WHEN_ABSENT`: false, for every key without\n * exception, which is byte-for-byte the behaviour of having no file at all.\n \n The other half of cross-version safety — an OLD release IGNORING a key a NEW one added, rather than\n * rejecting it — is solved by `warnUnknownKeys` below. The two halves are one invariant: for the set of\n * valid documents to be non-empty across every release installed on the machine, neither omitting a key\n * nor adding one may be an error.\n /\n\n// Read errors that mean \"the file is not there / not reachable\" rather than \"the file is wrong\". Every\n// one of these resolves to the all-defaults config, silently. Widened deliberately past ENOENT: the\n// parent `~/.webpieces` may not exist (ENOENT), may be a file (ENOTDIR), may be unreadable (EACCES /\n// EPERM), and the path itself may be a directory (EISDIR). None of those is a user who opted in.\nconst ABSENT_ERROR_CODES: readonly string[] = ['ENOENT', 'ENOTDIR', 'EACCES', 'EPERM', 'EISDIR', 'ELOOP', 'ENAMETOOLONG'];\n\n/* The parsed `~/.webpieces/config.json`. Data-only (per CLAUDE.md — classes, not interfaces, for data). /\nexport class HomeConfig {\n /\n EXPERIMENTAL, under test, not a supported knob. When true, the pr-gate build gate captures its full\n * output to `.webpieces/logs/` and hands a failing build's pointer to that file to the AI instead of\n * an instruction to rebuild. Default false — i.e. the behaviour every consumer has today.\n /\n buildGateLogCapture: boolean;\n\n /\n EXPERIMENTAL, and OFF unless this machine opts IN with an explicit `true`. When true,\n * `whole-repo-build-guard` BLOCKS a Bash command that would build the WHOLE monorepo and hands back\n * the repo's own scoped build command (`pnpm wp-build`). False — and absent, and no file at all —\n * makes the guard completely inert: no block, no log, no message.\n \n This is the guard's ONLY switch, and it is an OPT-IN. There is deliberately no\n * webpieces.config.json entry for it (see RETIRED_CONFIG_KEYS): a guard that every consumer must\n * ADD A KEY to avoid being blocked by is a guard that ships an outage on upgrade, which is exactly\n * what happened once. Living here means the default state needs no file, no key and no edit.\n /\n wholeRepoBuildGuard: boolean;\n\n /\n EXPERIMENTAL. When true, `wp-checkout-clean-main` ARCHIVES the orphan directories it finds — the\n * package directories left behind on every clone by an `nx g move`, which git cannot remove because\n * an ignored `dist/` or `node_modules/` survives the deletion of every tracked file under them.\n \n False — and the all-defaults value for a machine with no such file — means the sweep only REPORTS\n * what it found and moves nothing. That asymmetry is the point of shipping this behind the home\n * config at all: the author can run it live across their own clones for a release while every\n * colleague's repo is untouched, and neither state depends on a tracked key anybody must add.\n \n The sweep itself never deletes (see OrphanDirArchiver): directories move under `.webpieces/trash/`\n * with a printed `recover=`, so the worst case for a false positive is a `mv` somebody undoes. The\n * ARCHIVE is reaped after 30 days, which is a real deletion — of the second copy, on a timer long\n * enough that anything still wanted has been noticed.\n /\n orphanDirSweep: boolean;\n\n /\n How many builds may be live on this MACHINE before `pnpm wp-build` refuses to start another. Live\n * is counted from `~/.webpieces/builds.log` — see `builds-log.ts`, and\n * `decisions/0006-the-build-ledger-is-machine-global.md` for why that file lives outside any repo.\n \n `DEFAULT_MAX_CONCURRENT_BUILDS` when absent. The gate stages (`wp-review-upsert-pr`,\n * `wp-finish-upsert-pr`) are NEVER refused whatever this says — blocking the sanctioned path is how\n * you wedge a PR — though their builds do count toward what refuses an ad-hoc `wp-build`.\n /\n maxConcurrentBuilds: number;\n\n // ALL FOUR required, no defaults. A defaulted parameter would leave `new HomeConfig(true)` compiling\n // after this class grew a second flag, silently meaning \"guard off\" — an old spelling that still\n // typechecks with a changed meaning is exactly the shim this repo does not ship. The 3-arg arity this\n // class had before `maxConcurrentBuilds` is DELETED rather than overloaded, per CLAUDE.md § \"NO\n // webpieces surface is released backwards-compatible\": the compile errors ARE the migration. The\n // absent-file state is constructed in exactly one place — load()'s absent-file branch.\n constructor(\n buildGateLogCapture: boolean, wholeRepoBuildGuard: boolean, orphanDirSweep: boolean,\n maxConcurrentBuilds: number,\n ) {\n this.buildGateLogCapture = buildGateLogCapture;\n this.wholeRepoBuildGuard = wholeRepoBuildGuard;\n this.orphanDirSweep = orphanDirSweep;\n this.maxConcurrentBuilds = maxConcurrentBuilds;\n }\n}\n\n/\n One retired `~/.webpieces/config.json` key and the mechanical edit that replaces it. Data-only.\n \n This mirrors `RetiredConfigKey` rather than reusing it: that table's entries carry a `scope`\n * (rule-name vs key-in-section) that describes webpieces.config.json's two-level layout and means\n * nothing here, and its `label` convention names that file's sections. One shared class covering both\n * would be a type with fields that are dead for half its instances.\n /\nexport class RetiredHomeConfigKey {\n // Dotted path exactly as it appears in the file, e.g. `experimental.captureBuildGateLog`.\n key: string;\n // Where the value goes now. Empty when the key is deleted outright.\n movedTo: string;\n // The imperative fix, written for the agent that will apply it verbatim.\n instruction: string;\n\n constructor(key: string, movedTo: string, instruction: string) {\n this.key = key;\n this.movedTo = movedTo;\n this.instruction = instruction;\n }\n}\n\n/\n Every retired home-config key — the ONE place in the codebase where a dead home-config key may be\n * named, exactly as `RETIRED_CONFIG_KEYS` is for webpieces.config.json. Newest at the bottom.\n \n When you retire a key here, DELETE its read path in the same change. `home-config.spec.ts` asserts\n * every entry below actually FAILS the load, so a fallback that quietly accepts one turns it red.\n /\nexport const RETIRED_HOME_CONFIG_KEYS: readonly RetiredHomeConfigKey[] = [\n // `captureBuildGateLog` was the working name while this feature was being built, and it appears in\n // the branch history and in in-flight drafts, so it is exactly the spelling an agent reconstructing\n // the file from memory will type. It never shipped in a release; it is listed so that typing it\n // produces the rename instruction rather than a bare \"unknown key\".\n new RetiredHomeConfigKey(\n 'experimental.captureBuildGateLog', 'experimental.buildGateLogCapture',\n 'Rename the key to \"buildGateLogCapture\" inside the same \"experimental\" object. Its boolean value ' +\n 'carries over unchanged.',\n ),\n];\n\n/\n Loads and validates `~/.webpieces/config.json`, and resolves whether a path IS that file (for the\n * guard carve-out that keeps a rejection repairable).\n \n Strict about everything it UNDERSTANDS (a retired key, a known key of the wrong type, and a document\n * that is not JSON all throw); forward-compatible about everything it does not (an unknown key is\n * ignored with a warning). The class docblock at the top of this file has the reasoning.\n /\n@injectable(bindingScopeValues.Singleton)\nexport class HomeConfigService {\n /* Absolute path to the preference file. `homeDir` is a parameter so specs never touch a real HOME. /\n configPath(homeDir: string = os.homedir()): string {\n return path.join(homeDir, HOME_CONFIG_DIR, HOME_CONFIG_FILE);\n }\n\n /\n The preferences. Returns all-defaults, silently and without touching anything, when the file is not\n * there. THROWS InformAiError, naming the fix, when a file that IS there is wrong in a way this\n * release can be sure about — unparseable, a RETIRED key, or a KNOWN key of the wrong type. A key it\n * simply does not recognise is ignored with a warning, because it may be a newer release's key and\n * this file is shared by every repo on the machine.\n /\n load(homeDir: string = os.homedir()): HomeConfig {\n const raw = this.readIfPresent(this.configPath(homeDir));\n // THE ABSENT-FILE STATE, and the ONE place it is constructed. Every flag is off — the same value\n // a present file that does not name the key gets, so \"no file\" and \"file that ignores this key\"\n // can never disagree. Spelled out rather than defaulted in the constructor — see the note there\n // on why a defaulted parameter is a shim.\n if (raw === null) {\n return new HomeConfig(\n GUARD_OFF_WHEN_ABSENT, GUARD_OFF_WHEN_ABSENT, GUARD_OFF_WHEN_ABSENT,\n DEFAULT_MAX_CONCURRENT_BUILDS);\n }\n return this.validate(this.parse(raw, this.configPath(homeDir)), this.configPath(homeDir));\n }\n\n /\n True when `candidate` names `~/.webpieces/config.json`, in any of the forms an agent writes it:\n * an absolute path, a `~/`-prefixed path, or one still spelled `$HOME/…` / `${HOME}/…`.\n \n This is what the hook guards call to grant the file an unconditional Write/Edit PASS. Without it a\n * strict loader could reject the file while the guards blocked the edit that would fix it — the one\n * wedge webpieces.config.json is already immune to, and the reason its own carve-out exists.\n /\n isHomeConfigPath(candidate: string, homeDir: string = os.homedir()): boolean {\n if (candidate.trim() === '') return false;\n return path.resolve(this.expandHome(candidate.trim(), homeDir)) === path.resolve(this.configPath(homeDir));\n }\n\n // `~`, `$HOME` and `${HOME}` at the FRONT only — a home reference anywhere else is not a home path.\n private expandHome(candidate: string, homeDir: string): string {\n if (candidate === '~') return homeDir;\n for (const prefix of ['~/', '$HOME/', '${HOME}/']) {\n if (candidate.startsWith(prefix)) return path.join(homeDir, candidate.slice(prefix.length));\n }\n return candidate;\n }\n\n /\n The file's bytes, or null meaning \"no such file — the user did not opt in\".\n \n EVERY read failure is null. This is the single most important behaviour in the file: the absent\n * path is the path every consumer of these packages is on, and it may never reach an error branch.\n * An error code outside ABSENT_ERROR_CODES is genuinely exceptional (EIO, EBUSY) and is rethrown,\n * because silently disabling on a failing disk would be its own kind of lie.\n /\n private readIfPresent(file: string): string \| null {\n // webpieces-disable no-unmanaged-exceptions -- chokepoint: this catch IS the \"you have no such file\"\n // decision, and that decision may never surface as a failure to a user who never created the file\n // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n try {\n return fs.readFileSync(file, 'utf8');\n } catch (err: unknown) {\n const error = toError(err);\n if (this.isAbsent(error)) return null;\n throw error;\n }\n }\n\n private isAbsent(error: Error): boolean {\n // webpieces-disable no-any-unknown -- node attaches `code` to fs errors without typing it on Error\n const code = (error as unknown as Record<string, unknown>)['code'];\n return typeof code === 'string' && ABSENT_ERROR_CODES.includes(code);\n }\n\n // A readable file that is not a JSON object is a WRONG file, not an absent one — hence the throw.\n // webpieces-disable no-any-unknown -- an unvalidated user-authored document; every field is narrowed below\n private parse(raw: string, file: string): Record<string, unknown> {\n // webpieces-disable no-unmanaged-exceptions -- chokepoint: JSON.parse's own message is useless to an\n // agent on its own, so it is re-thrown as the InformAiError that names the file and the fix\n // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n try {\n // webpieces-disable no-any-unknown -- opaque parsed JSON, narrowed immediately below\n const parsed: unknown = JSON.parse(raw);\n if (typeof parsed !== 'object' \|\| parsed === null \|\| Array.isArray(parsed)) {\n throw new InformAiError(this.error(file, 'the file must contain a single JSON OBJECT, e.g. {}.'));\n }\n // webpieces-disable no-any-unknown -- narrowed to a non-null, non-array object one line above\n return parsed as Record<string, unknown>;\n } catch (err: unknown) {\n const error = toError(err);\n if (error instanceof InformAiError) throw error;\n throw new InformAiError(this.error(file, `the file is not valid JSON (${error.message}).`), { cause: error });\n }\n }\n\n // webpieces-disable no-any-unknown -- see parse(); the document is user-authored and unvalidated\n private validate(raw: Record<string, unknown>, file: string): HomeConfig {\n this.assertNotRetired(raw, file);\n this.warnUnknownKeys(Object.keys(raw), ALLOWED_TOP_LEVEL, '');\n const section = raw[HOME_EXPERIMENTAL_SECTION];\n if (section !== undefined && (typeof section !== 'object' \|\| section === null \|\| Array.isArray(section))) {\n throw new InformAiError(this.error(file, `\"${HOME_EXPERIMENTAL_SECTION}\" must be a JSON object.`));\n }\n // webpieces-disable no-any-unknown -- narrowed to a non-null, non-array object one line above\n const experimental = (section ?? {}) as Record<string, unknown>;\n this.warnUnknownKeys(Object.keys(experimental), ALLOWED_EXPERIMENTAL, `${HOME_EXPERIMENTAL_SECTION}.`);\n return new HomeConfig(\n this.readOptionalBoolean(experimental, HOME_KEY_BUILD_GATE_LOG_CAPTURE, file, GUARD_OFF_WHEN_ABSENT),\n this.readOptionalBoolean(experimental, HOME_KEY_WHOLE_REPO_BUILD_GUARD, file, GUARD_OFF_WHEN_ABSENT),\n this.readOptionalBoolean(experimental, HOME_KEY_ORPHAN_DIR_SWEEP, file, GUARD_OFF_WHEN_ABSENT),\n this.readOptionalPositiveInteger(\n experimental, HOME_KEY_MAX_CONCURRENT_BUILDS, file, DEFAULT_MAX_CONCURRENT_BUILDS),\n );\n }\n\n /\n The NUMERIC sibling of {@link readOptionalBoolean}, and the same three rules apply unchanged: the\n * key is OPTIONAL (absent → `whenAbsent`, stated out loud by the caller), a PRESENT value of the\n * wrong type is an ERROR, and nothing here ever guesses.\n \n \"Wrong type\" is stricter than `typeof value === 'number'`, because for this key the wrong NUMBERS\n * are as meaningless as the wrong types: `0` is a machine that may never build, `-1` and `2.5` are\n * not counts of anything, and `NaN` compares false against every threshold and would silently\n * disable the check. A positive integer is the only value that means something, so it is the only\n * value accepted — and the rejection names the offending value, exactly as the boolean one does.\n \n This does NOT soften the machine-global forward-compatibility rule: an UNKNOWN key is still\n * ignored with a warning. Only a key THIS release understands is type-checked, and no release of\n * webpieces has ever given `maxConcurrentBuilds` a non-numeric meaning.\n /\n // webpieces-disable no-any-unknown -- see parse()\n // eslint-disable-next-line @typescript-eslint/max-params\n private readOptionalPositiveInteger(\n experimental: Record<string, unknown>, key: string, file: string, whenAbsent: number,\n ): number {\n const value = experimental[key];\n if (value === undefined) return whenAbsent;\n if (typeof value !== 'number' \|\| !Number.isInteger(value) \|\| value < 1) {\n throw new InformAiError(this.error(file,\n `\"${HOME_EXPERIMENTAL_SECTION}.${key}\" must be a POSITIVE WHOLE NUMBER (1 or more), not ` +\n `${JSON.stringify(value)}. Write it as a bare JSON number, e.g. ` +\n `\"${key}\": ${String(whenAbsent)} — or delete the key to use the default of ` +\n `${String(whenAbsent)}.`));\n }\n return value;\n }\n\n /\n An absent key falls back to `whenAbsent`, which every caller states OUT LOUD by passing\n * `GUARD_OFF_WHEN_ABSENT` — an implicit \"absent means false\" buried in this method would put the\n * default and the key that carries it in different places, free to drift apart.\n \n A PRESENT key of the wrong type is still an ERROR, and that is the line neither the unknown-key change\n * nor this one moved: `\"whole-repo-build-guard\": \"yes\"` is a file somebody wrote wrongly, not\n * a file written for a different release. No release of webpieces has ever given this key a string\n * meaning, so there is no forward-compatibility story to protect and nothing is gained by guessing —\n * whereas guessing would turn a typed value into a silent fallback to the default, which is the very\n * cost the unknown-key warning exists to bound.\n \n This is the ONLY reader; see the every-key-is-optional note above for why there is no required\n * variant.\n /\n // webpieces-disable no-any-unknown -- see parse()\n // eslint-disable-next-line @typescript-eslint/max-params\n private readOptionalBoolean(\n experimental: Record<string, unknown>, key: string, file: string, whenAbsent: boolean,\n ): boolean {\n const value = experimental[key];\n if (value === undefined) return whenAbsent;\n return this.asBoolean(value, key, file, ' Remove the quotes, or delete the key.');\n }\n\n // webpieces-disable no-any-unknown -- see parse()\n // eslint-disable-next-line @typescript-eslint/max-params\n private asBoolean(value: unknown, key: string, file: string, fix: string): boolean {\n if (typeof value !== 'boolean') {\n throw new InformAiError(this.error(file,\n `\"${HOME_EXPERIMENTAL_SECTION}.${key}\" must be the boolean ` +\n `true or false, not ${JSON.stringify(value)}.${fix}`));\n }\n return value;\n }\n\n // Retired keys are checked BEFORE unknown-key reporting: \"unknown key\" would send an agent deleting a\n // key whose value it should be MOVING, which is the whole reason the retirement table exists.\n // webpieces-disable no-any-unknown -- see parse()\n private assertNotRetired(raw: Record<string, unknown>, file: string): void {\n for (const entry of RETIRED_HOME_CONFIG_KEYS) {\n if (!this.isPresentAt(raw, entry.key)) continue;\n const destination = entry.movedTo === ''\n ? 'It was removed with no replacement.'\n : `It moved to \"${entry.movedTo}\".`;\n throw new InformAiError(this.error(file,\n `\"${entry.key}\" is RETIRED. ${destination} ${entry.instruction}`));\n }\n }\n\n // Is `dotted` (one or two segments — the file is two levels deep by construction) actually present?\n // webpieces-disable no-any-unknown -- see parse()\n private isPresentAt(raw: Record<string, unknown>, dotted: string): boolean {\n const parts = dotted.split('.');\n if (parts.length === 1) return raw[parts[0]] !== undefined;\n const section = raw[parts[0]];\n if (typeof section !== 'object' \|\| section === null \|\| Array.isArray(section)) return false;\n // webpieces-disable no-any-unknown -- narrowed to a non-null, non-array object one line above\n return (section as Record<string, unknown>)[parts[1]] !== undefined;\n }\n\n /\n The understood keys AT ONE LEVEL, rendered from the allow-list rather than hand-listed — and\n * rendered at the level the reader's key was actually found, so a mistyped SECTION is answered with\n * the sections and a mistyped FLAG with the flags. The hand-listed version named two keys and went\n * stale the moment a third arrived, telling an agent its brand-new key was not accepted while the\n * validator right above accepted it.\n /\n private quotedKeys(allowed: readonly string[], prefix: string): string {\n return allowed.map((key: string): string => `\"${prefix}${key}\"`).join(', ');\n }\n\n /\n An unknown key is IGNORED — see the class docblock for why this one file cannot reject it — but it\n * is never SILENT. The warning is the entire mitigation for the cost of ignoring, so it says both\n * things a reader needs: that the key did nothing, and what the understood keys are.\n \n ─── WHY THIS IS NOT THE \"console side channel\" SHAPE ────────────────────────────────────────────\n * That shape is a rule or a library reporting a FAILURE — or a cure for one — by printing it instead\n * of throwing a structured value to the one top-level handler. This is the opposite case, and the\n * distinction is the entire subject of this change: an unknown key here is NOT a failure. The load\n * SUCCEEDS, a valid HomeConfig is returned, every caller proceeds normally, and there is no cure the\n * reader is obliged to apply — a key from a newer release is a CORRECT file being read by an older\n * validator. There is no throw this could be, because throwing is precisely the behaviour being\n * deleted here; and returning it would mean inventing a warnings channel through `load()` that no\n * caller has any reason to render.\n \n stderr, not stdout, for the usual reason: this runs inside hooks whose stdout is a JSON decision\n * and inside `wp-` commands whose stdout is their real output, and neither may be polluted. It is\n the same channel, with the same `[webpieces]` prefix, that `state-dir-migration.announce` already\n * uses in this package for the same category of finding — something a human may want to know about\n * and is not required to act on.\n /\n private warnUnknownKeys(found: string[], allowed: readonly string[], prefix: string): void {\n for (const key of found) {\n if (allowed.includes(key)) continue;\n const near = this.nearestKnownKey(key, allowed);\n const guess = near !== ''\n ? ` Did you mean \"${prefix}${near}\"?`\n : this.nearRetiredHint(`${prefix}${key}`)\n \|\| ' If it is a typo, fix the spelling; if it is from a NEWER @webpieces than this repo pins, upgrade this repo to use it.';\n this.warn(\n `\"${prefix}${key}\" is not a key this @webpieces release understands, so it was IGNORED ` +\n `and had NO effect.${guess} Understood here: ${this.quotedKeys(allowed, prefix)}.`);\n }\n }\n\n /\n A near-miss of a RETIRED key, pointed at its migration — or '' when nothing retired is close.\n \n The gap this closes: `assertNotRetired` matches a retired key EXACTLY, so `captureBuildGateLog`\n * throws with its rename instruction while `captureBuildGateLogg` — one stray character away, and a\n * far likelier thing to type — falls through to the generic \"IGNORED, might be from a newer release\"\n * line. That is the least helpful of the three answers offered to the reader whose intent is the\n * clearest, so the retired table is consulted here too, at the same distance-2 threshold.\n \n It only ever produces a WARNING, never a throw: this release cannot know whether the reader meant\n * the retired key or a newer one, and guessing wrong in the throwing direction is what the whole\n * change is about. Known keys are matched first, so a typo of a LIVE key is never answered with a\n * dead one.\n /\n private nearRetiredHint(dottedKey: string): string {\n for (const entry of RETIRED_HOME_CONFIG_KEYS) {\n if (this.editDistance(dottedKey.toLowerCase(), entry.key.toLowerCase()) > 2) continue;\n const destination = entry.movedTo === ''\n ? 'it was removed with no replacement'\n : `it moved to \"${entry.movedTo}\"`;\n return ` Did you mean the RETIRED key \"${entry.key}\"? If so, ${destination}. ${entry.instruction}`;\n }\n return '';\n }\n\n // One shape for every non-fatal finding, matching state-dir-migration's `[webpieces] <what>:` prefix\n // so a reader can tell at a glance which subsystem is talking.\n private warn(message: string): void {\n process.stderr.write(`[webpieces] ~/.webpieces/config.json: ${message}\\n`);\n }\n\n /\n The closest understood key within two edits, or '' when nothing is close.\n \n This used to be a case-insensitive EQUALITY test, which was adequate while an unknown key was a\n * hard error — the error itself was the signal, and the suggestion only saved a reading. Now the\n * suggestion IS the signal, so it has to catch the typos an equality test misses: a doubled letter,\n * a dropped one, a transposition, a stray trailing `d` (`buildGateLogCaptured`). Two is the useful\n * threshold — it covers every one of those and still refuses to guess for a genuinely new key, which\n * is the case that must NOT be dressed up as a typo.\n /\n private nearestKnownKey(key: string, allowed: readonly string[]): string {\n let best = '';\n let bestDistance = 3;\n for (const candidate of allowed) {\n const distance = this.editDistance(key.toLowerCase(), candidate.toLowerCase());\n if (distance >= bestDistance) continue;\n bestDistance = distance;\n best = candidate;\n }\n return best;\n }\n\n /* Ordinary Levenshtein distance, one row at a time — the key names are short and this runs once. */\n private editDistance(a: string, b: string): number {\n let previous: number[] = [];\n for (let j = 0; j <= b.length; j += 1) previous.push(j);\n for (let i = 1; i <= a.length; i += 1) {\n const current: number[] = [i];\n for (let j = 1; j <= b.length; j += 1) {\n const substitution = previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1);\n current.push(Math.min(substitution, previous[j] + 1, current[j - 1] + 1));\n }\n previous = current;\n }\n return previous[b.length];\n }\n\n // One shape for every rejection: what is wrong, in which file, and the fact that deleting the file is\n // always a legal fix — because the file is optional, and \"no file\" is a fully supported state.\n private error(file: string, detail: string): string {\n return `[~/.webpieces/config.json] ${detail}\\n\\n` +\n `File: ${file}\\n` +\n `This machine-local preference file is OPTIONAL and EXPERIMENTAL. Editing it is always ` +\n `permitted, even while it is invalid, and deleting it outright is a valid fix — with no such ` +\n `file every webpieces command behaves exactly as it does by default.`;\n }\n}\n"]}

package/src/index.d.ts CHANGED Viewed

@@ -33,7 +33,8 @@ export { unknownKeyErrors, isCommentKey, validateTopLevelKeys, COMMENT_KEY_SUFFI
 export { RETIRED_CONFIG_KEYS, RETIRED_SCOPE_KEY, RETIRED_SCOPE_RULE, RetiredConfigKey, isRetiredKey, retiredEntry, retiredKeyError, retiredKeyErrorsIn, retiredRuleFor } from './retired-config-keys';
 export { ConfigPruner, PruneResult, PrunedKey } from './config-pruner';
 export { validateChecklistDocs } from './checklist-docs-validator';
-export { HomeConfig, HomeConfigService, RetiredHomeConfigKey, RETIRED_HOME_CONFIG_KEYS, HOME_CONFIG_DIR, HOME_CONFIG_FILE, HOME_EXPERIMENTAL_SECTION, HOME_KEY_BUILD_GATE_LOG_CAPTURE, HOME_KEY_ORPHAN_DIR_SWEEP, HOME_KEY_WHOLE_REPO_BUILD_GUARD, } from './home-config';
+export { HomeConfig, HomeConfigService, RetiredHomeConfigKey, RETIRED_HOME_CONFIG_KEYS, HOME_CONFIG_DIR, HOME_CONFIG_FILE, HOME_EXPERIMENTAL_SECTION, HOME_KEY_BUILD_GATE_LOG_CAPTURE, HOME_KEY_ORPHAN_DIR_SWEEP, HOME_KEY_WHOLE_REPO_BUILD_GUARD, HOME_KEY_MAX_CONCURRENT_BUILDS, DEFAULT_MAX_CONCURRENT_BUILDS, } from './home-config';
+export { BuildsLog, BuildTicket, RunningBuild, BUILDS_LOG_FILE, BUILDS_LOCK_FILE, BUILD_START, BUILD_DONE_SUCCESS, BUILD_DONE_FAIL, MAX_BUILDS_LOG_BYTES, BUILDS_LOG_GENERATIONS, MAX_ROW_BYTES, } from './builds-log';
 export { OrphanDirScanner, OrphanCandidate } from './orphan-dir-scan';
 export { OrphanDirArchiver, ArchivedOrphan, FailedOrphan, OrphanSweepResult, OrphanSweepManifest, TRASH_STATE_DIR, TRASH_MANIFEST_FILE, TRASH_RETENTION_DAYS, } from './orphan-dir-archive';
 export { OrphanDirSweeper, OrphanSweepReport } from './orphan-dir-sweep';