@webpieces/pr-gate 0.4.662 → 0.4.664

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/pr-gate",
-  "version": "0.4.662",
+  "version": "0.4.664",
   "description": "Gated PR system: 3-point squash-merge, merge validation gate, and red/yellow/green PR dashboard. Standalone scripts, no Nx dependency required.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -15,7 +15,7 @@
     "directory": "packages/tooling/pr-gate"
   },
   "dependencies": {
-    "@webpieces/rules-config": "0.4.662",
+    "@webpieces/rules-config": "0.4.664",
     "@inversifyjs/binding-decorators": "1.1.5",
     "inversify": "7.10.4",
     "reflect-metadata": "0.2.2"
@@ -30,6 +30,7 @@
     "wp-start-update": "./src/scripts/wp-start-update.js",
     "wp-finish-update": "./src/scripts/wp-finish-update.js",
     "wp-cleanup": "./src/scripts/wp-cleanup.js",
+    "wp-checkout-clean-main": "./src/scripts/wp-checkout-clean-main.js",
     "wp-land-pr": "./src/scripts/wp-land-pr.js",
     "wp-check-pr": "./src/scripts/wp-check-pr.js",
     "wp-review-upsert-pr": "./src/scripts/wp-review-upsert-pr.js",

package/src/scripts/commands/checkout-clean-main-command.d.ts

@@ -0,0 +1,80 @@
+import { OrphanDirSweeper, RepoRootFinder } from '@webpieces/rules-config';
+import { CleanupCommand } from './cleanup-command';
+/**
+ * `wp-checkout-clean-main` — go to main, get main, and take out the trash. ONE command, because the three
+ * are one intention and splitting them is what let the third never happen.
+ *
+ * ─── ITS RELATIONSHIP TO `git checkout main && git pull origin main` (READ BEFORE "DELETING" THAT) ────
+ * That pair was already the enforced spelling: bare `git checkout main` is blocked precisely so the pull
+ * rides along. This command is the same pairing with cleanup and the sweep welded on, and the WORKFLOW
+ * messages should prescribe this instead — two spellings where one sweeps and one does not is shim shape
+ * #1, an agent types whichever is accepted and the corpses accumulate forever.
+ *
+ * That swap is NOT in this change, and the reason is a constraint that outranks the shim rule: the raw
+ * pair is a TERMINAL ENTRY ON THE L0 ALLOWLIST (`CHECKOUT_MAIN_PULL_CMD` in ai-hook-rules
+ * `src/bin/l0-allowlist.ts`, consumed as an L0 cure in `src/core/l0-matrix.ts`) — one of
+ * the few commands still permitted while an L0 block denies every other tool call. In exactly that
+ * state, `node_modules` is the thing that is untrustworthy, so a `pnpm wp-*` bin is the one kind of cure
+ * that cannot be relied on to run. The same reasoning covers the L0 shim's own fix option in
+ * `templates/ai-hook.sh`.
+ *
+ * So the end state is TWO LAYERS, not a deletion:
+ *   • L0 recovery (l0-allowlist, ai-hook.sh, l0-matrix)  → keeps the raw pair. It is not a shim there;
+ *     it is the only thing that works when the package manager's output is what is in doubt.
+ *   • the WORKFLOW layer (stale-main-bash-guard's preferred cure, merged-branch-message, tree-recovery,
+ *     the L2 rows/doc, CLAUDE.md's "Finishing a Feature") → prescribes `pnpm wp-checkout-clean-main`,
+ *     and stops printing the pair.
+ *
+ * The second bullet is ~20 files of intertwined guard text with specs pinning exact strings, and it
+ * lands as its own change — deliberately after this one, so the bin exists in a published release
+ * before any guard names it. Until then both spellings work and only this one sweeps; that is a known,
+ * recorded gap, not an oversight.
+ *
+ * ─── WHY GOING TO MAIN IS THE RIGHT MOMENT TO SWEEP ───────────────────────────────────────────────────
+ * The corpses appear when git moves the working tree onto a base where the tracked files under some
+ * directory are gone. Landing a PR and returning to main is when every developer does that, on every
+ * clone, roughly once per merged PR — so a sweep bolted here converges the whole team's machines with no
+ * new trigger, no git hook to distribute, and no background daemon. It is also the quietest moment in the
+ * day to move directories: nothing is building, no dev server is watching files.
+ *
+ * ─── WHY THE ORDER IS FIXED AND NOT PARALLEL ──────────────────────────────────────────────────────────
+ * Cleanup runs BEFORE the sweep and not beside it. `wp-cleanup` removes dead worktrees, which changes
+ * what is on disk, and a scan racing that would be reading a tree mid-demolition. The scan is one
+ * ignore-walk and costs about a second; there is no wall-clock worth buying with that race.
+ */
+export declare class CheckoutCleanMainCommand {
+    private readonly repoRootFinder;
+    private readonly cleanupCommand;
+    private readonly orphanDirSweeper;
+    constructor(repoRootFinder: RepoRootFinder, cleanupCommand: CleanupCommand, orphanDirSweeper: OrphanDirSweeper);
+    run(): Promise<void>;
+    /**
+     * A linked worktree has no main to check out — `git checkout main` FATALS there with "main is already
+     * checked out at <primary clone>", which is a footgun CLAUDE.md currently has to warn about in prose.
+     * So the command does the half that IS meaningful here (worktrees accumulate corpses too, if a
+     * long-lived one keeps merging main in) and says plainly where the other half lives.
+     */
+    private sweepOnly;
+    private isLinkedWorktree;
+    /**
+     * Refuse on a dirty tree instead of carrying the changes onto main. `git checkout` would happily
+     * bring uncommitted work along, and the one place nobody wants to discover their work is on main.
+     */
+    private assertTreeIsClean;
+    /**
+     * Checkout main and fast-forward it. `--ff-only` rather than a `reset --hard`, deliberately: a
+     * developer or an agent that accidentally committed to local main would have that work silently
+     * destroyed by a reset, and the whole point of this command is that it is safe to run without
+     * thinking. A refusal to fast-forward is a real condition a human should see and decide about.
+     */
+    private goToMain;
+    /**
+     * Sweep, then print. Never throws: the checkout and pull above already succeeded, and a tidier is not
+     * permitted to turn somebody's completed sync into a failed command.
+     */
+    private sweep;
+    /** Captured git output, or null when git could not be run or exited non-zero. */
+    private git;
+    /** git with its output going straight to the terminal — for the commands whose progress is the point. */
+    private run_;
+}

package/src/scripts/commands/checkout-clean-main-command.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CheckoutCleanMainCommand = void 0;
+const tslib_1 = require("tslib");
+const child_process_1 = require("child_process");
+const inversify_1 = require("inversify");
+const rules_config_1 = require("@webpieces/rules-config");
+const cleanup_command_1 = require("./cleanup-command");
+const SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n';
+/**
+ * `wp-checkout-clean-main` — go to main, get main, and take out the trash. ONE command, because the three
+ * are one intention and splitting them is what let the third never happen.
+ *
+ * ─── ITS RELATIONSHIP TO `git checkout main && git pull origin main` (READ BEFORE "DELETING" THAT) ────
+ * That pair was already the enforced spelling: bare `git checkout main` is blocked precisely so the pull
+ * rides along. This command is the same pairing with cleanup and the sweep welded on, and the WORKFLOW
+ * messages should prescribe this instead — two spellings where one sweeps and one does not is shim shape
+ * #1, an agent types whichever is accepted and the corpses accumulate forever.
+ *
+ * That swap is NOT in this change, and the reason is a constraint that outranks the shim rule: the raw
+ * pair is a TERMINAL ENTRY ON THE L0 ALLOWLIST (`CHECKOUT_MAIN_PULL_CMD` in ai-hook-rules
+ * `src/bin/l0-allowlist.ts`, consumed as an L0 cure in `src/core/l0-matrix.ts`) — one of
+ * the few commands still permitted while an L0 block denies every other tool call. In exactly that
+ * state, `node_modules` is the thing that is untrustworthy, so a `pnpm wp-*` bin is the one kind of cure
+ * that cannot be relied on to run. The same reasoning covers the L0 shim's own fix option in
+ * `templates/ai-hook.sh`.
+ *
+ * So the end state is TWO LAYERS, not a deletion:
+ *   • L0 recovery (l0-allowlist, ai-hook.sh, l0-matrix)  → keeps the raw pair. It is not a shim there;
+ *     it is the only thing that works when the package manager's output is what is in doubt.
+ *   • the WORKFLOW layer (stale-main-bash-guard's preferred cure, merged-branch-message, tree-recovery,
+ *     the L2 rows/doc, CLAUDE.md's "Finishing a Feature") → prescribes `pnpm wp-checkout-clean-main`,
+ *     and stops printing the pair.
+ *
+ * The second bullet is ~20 files of intertwined guard text with specs pinning exact strings, and it
+ * lands as its own change — deliberately after this one, so the bin exists in a published release
+ * before any guard names it. Until then both spellings work and only this one sweeps; that is a known,
+ * recorded gap, not an oversight.
+ *
+ * ─── WHY GOING TO MAIN IS THE RIGHT MOMENT TO SWEEP ───────────────────────────────────────────────────
+ * The corpses appear when git moves the working tree onto a base where the tracked files under some
+ * directory are gone. Landing a PR and returning to main is when every developer does that, on every
+ * clone, roughly once per merged PR — so a sweep bolted here converges the whole team's machines with no
+ * new trigger, no git hook to distribute, and no background daemon. It is also the quietest moment in the
+ * day to move directories: nothing is building, no dev server is watching files.
+ *
+ * ─── WHY THE ORDER IS FIXED AND NOT PARALLEL ──────────────────────────────────────────────────────────
+ * Cleanup runs BEFORE the sweep and not beside it. `wp-cleanup` removes dead worktrees, which changes
+ * what is on disk, and a scan racing that would be reading a tree mid-demolition. The scan is one
+ * ignore-walk and costs about a second; there is no wall-clock worth buying with that race.
+ */
+let CheckoutCleanMainCommand = class CheckoutCleanMainCommand {
+    repoRootFinder;
+    cleanupCommand;
+    orphanDirSweeper;
+    constructor(repoRootFinder, cleanupCommand, orphanDirSweeper) {
+        this.repoRootFinder = repoRootFinder;
+        this.cleanupCommand = cleanupCommand;
+        this.orphanDirSweeper = orphanDirSweeper;
+    }
+    async run() {
+        const repoRoot = this.repoRootFinder.resolveRepoRoot(process.cwd());
+        process.stdout.write(`${SEP}🧹 Checkout main, pull, clean\n${SEP}\n`);
+        if (this.isLinkedWorktree(repoRoot)) {
+            await this.sweepOnly(repoRoot);
+            return;
+        }
+        this.assertTreeIsClean(repoRoot);
+        this.goToMain(repoRoot);
+        await this.cleanupCommand.run();
+        this.sweep(repoRoot);
+    }
+    /**
+     * A linked worktree has no main to check out — `git checkout main` FATALS there with "main is already
+     * checked out at <primary clone>", which is a footgun CLAUDE.md currently has to warn about in prose.
+     * So the command does the half that IS meaningful here (worktrees accumulate corpses too, if a
+     * long-lived one keeps merging main in) and says plainly where the other half lives.
+     */
+    async sweepOnly(repoRoot) {
+        process.stdout.write('This is a linked WORKTREE. main is checked out in the primary clone, so there is nothing\n'
+            + 'here to check out or pull — sweeping this tree only.\n\n'
+            + 'Most worktrees never need this: `wp-cleanup` removes the whole directory once its branch\n'
+            + 'lands, which takes any orphan directories inside it along. Run this command again from the\n'
+            + 'primary clone to go to main there.\n\n');
+        this.sweep(repoRoot);
+        return Promise.resolve();
+    }
+    isLinkedWorktree(repoRoot) {
+        const dirs = rules_config_1.dotWebpieces.gitDirs(repoRoot);
+        return dirs !== null && dirs.isLinkedWorktree;
+    }
+    /**
+     * Refuse on a dirty tree instead of carrying the changes onto main. `git checkout` would happily
+     * bring uncommitted work along, and the one place nobody wants to discover their work is on main.
+     */
+    assertTreeIsClean(repoRoot) {
+        const status = this.git(repoRoot, ['status', '--porcelain']);
+        if (status === null || status.trim() === '')
+            return;
+        throw new rules_config_1.CliExitError(1, `${SEP}❌ Uncommitted or untracked changes\n${SEP}\n`
+            + 'Going to main would carry them along. Commit them on this branch, or stash them, then\n'
+            + 're-run. The webpieces tooling never commits your work for you.\n\n'
+            + `${status}`);
+    }
+    /**
+     * Checkout main and fast-forward it. `--ff-only` rather than a `reset --hard`, deliberately: a
+     * developer or an agent that accidentally committed to local main would have that work silently
+     * destroyed by a reset, and the whole point of this command is that it is safe to run without
+     * thinking. A refusal to fast-forward is a real condition a human should see and decide about.
+     */
+    goToMain(repoRoot) {
+        this.run_(repoRoot, ['fetch', 'origin', 'main']);
+        if (this.run_(repoRoot, ['checkout', 'main']) !== 0) {
+            throw new rules_config_1.CliExitError(1, `${SEP}❌ Could not check out main\n${SEP}\n`
+                + 'git refused the checkout — its message is above.\n');
+        }
+        if (this.run_(repoRoot, ['pull', '--ff-only', 'origin', 'main']) !== 0) {
+            throw new rules_config_1.CliExitError(1, `${SEP}❌ Local main could not fast-forward\n${SEP}\n`
+                + 'Local main has commits that origin/main does not, so it is not a clean copy of the\n'
+                + 'remote. Nothing was reset — those commits may be the only copy. Inspect them with\n'
+                + '`git log origin/main..main` and decide what they are before going further.\n');
+        }
+    }
+    /**
+     * Sweep, then print. Never throws: the checkout and pull above already succeeded, and a tidier is not
+     * permitted to turn somebody's completed sync into a failed command.
+     */
+    sweep(repoRoot) {
+        const report = this.orphanDirSweeper.sweep(repoRoot, new Date());
+        const rendered = report.render();
+        if (rendered === '')
+            return;
+        process.stdout.write(`\n${rendered}`);
+    }
+    /** Captured git output, or null when git could not be run or exited non-zero. */
+    git(repoRoot, args) {
+        const result = (0, child_process_1.spawnSync)('git', ['-C', repoRoot, ...args], {
+            encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        if (result.error !== undefined || result.status !== 0)
+            return null;
+        return result.stdout;
+    }
+    /** git with its output going straight to the terminal — for the commands whose progress is the point. */
+    run_(repoRoot, args) {
+        const result = (0, child_process_1.spawnSync)('git', ['-C', repoRoot, ...args], { encoding: 'utf8', stdio: 'inherit' });
+        return result.status === null ? 1 : result.status;
+    }
+};
+exports.CheckoutCleanMainCommand = CheckoutCleanMainCommand;
+exports.CheckoutCleanMainCommand = CheckoutCleanMainCommand = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton),
+    tslib_1.__metadata("design:paramtypes", [rules_config_1.RepoRootFinder,
+        cleanup_command_1.CleanupCommand,
+        rules_config_1.OrphanDirSweeper])
+], CheckoutCleanMainCommand);
+//# sourceMappingURL=checkout-clean-main-command.js.map

package/src/scripts/commands/checkout-clean-main-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout-clean-main-command.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/commands/checkout-clean-main-command.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawnSync } from 'child_process';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport {\n    CliExitError,\n    OrphanDirSweeper,\n    RepoRootFinder,\n    dotWebpieces,\n} from '@webpieces/rules-config';\n\nimport { CleanupCommand } from './cleanup-command';\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\n/**\n * `wp-checkout-clean-main` — go to main, get main, and take out the trash. ONE command, because the three\n * are one intention and splitting them is what let the third never happen.\n *\n * ─── ITS RELATIONSHIP TO `git checkout main && git pull origin main` (READ BEFORE \"DELETING\" THAT) ────\n * That pair was already the enforced spelling: bare `git checkout main` is blocked precisely so the pull\n * rides along. This command is the same pairing with cleanup and the sweep welded on, and the WORKFLOW\n * messages should prescribe this instead — two spellings where one sweeps and one does not is shim shape\n * #1, an agent types whichever is accepted and the corpses accumulate forever.\n *\n * That swap is NOT in this change, and the reason is a constraint that outranks the shim rule: the raw\n * pair is a TERMINAL ENTRY ON THE L0 ALLOWLIST (`CHECKOUT_MAIN_PULL_CMD` in ai-hook-rules\n * `src/bin/l0-allowlist.ts`, consumed as an L0 cure in `src/core/l0-matrix.ts`) — one of\n * the few commands still permitted while an L0 block denies every other tool call. In exactly that\n * state, `node_modules` is the thing that is untrustworthy, so a `pnpm wp-*` bin is the one kind of cure\n * that cannot be relied on to run. The same reasoning covers the L0 shim's own fix option in\n * `templates/ai-hook.sh`.\n *\n * So the end state is TWO LAYERS, not a deletion:\n *   • L0 recovery (l0-allowlist, ai-hook.sh, l0-matrix)  → keeps the raw pair. It is not a shim there;\n *     it is the only thing that works when the package manager's output is what is in doubt.\n *   • the WORKFLOW layer (stale-main-bash-guard's preferred cure, merged-branch-message, tree-recovery,\n *     the L2 rows/doc, CLAUDE.md's \"Finishing a Feature\") → prescribes `pnpm wp-checkout-clean-main`,\n *     and stops printing the pair.\n *\n * The second bullet is ~20 files of intertwined guard text with specs pinning exact strings, and it\n * lands as its own change — deliberately after this one, so the bin exists in a published release\n * before any guard names it. Until then both spellings work and only this one sweeps; that is a known,\n * recorded gap, not an oversight.\n *\n * ─── WHY GOING TO MAIN IS THE RIGHT MOMENT TO SWEEP ───────────────────────────────────────────────────\n * The corpses appear when git moves the working tree onto a base where the tracked files under some\n * directory are gone. Landing a PR and returning to main is when every developer does that, on every\n * clone, roughly once per merged PR — so a sweep bolted here converges the whole team's machines with no\n * new trigger, no git hook to distribute, and no background daemon. It is also the quietest moment in the\n * day to move directories: nothing is building, no dev server is watching files.\n *\n * ─── WHY THE ORDER IS FIXED AND NOT PARALLEL ──────────────────────────────────────────────────────────\n * Cleanup runs BEFORE the sweep and not beside it. `wp-cleanup` removes dead worktrees, which changes\n * what is on disk, and a scan racing that would be reading a tree mid-demolition. The scan is one\n * ignore-walk and costs about a second; there is no wall-clock worth buying with that race.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class CheckoutCleanMainCommand {\n    constructor(\n        private readonly repoRootFinder: RepoRootFinder,\n        private readonly cleanupCommand: CleanupCommand,\n        private readonly orphanDirSweeper: OrphanDirSweeper,\n    ) {}\n\n    async run(): Promise<void> {\n        const repoRoot = this.repoRootFinder.resolveRepoRoot(process.cwd());\n        process.stdout.write(`${SEP}🧹 Checkout main, pull, clean\\n${SEP}\\n`);\n        if (this.isLinkedWorktree(repoRoot)) {\n            await this.sweepOnly(repoRoot);\n            return;\n        }\n        this.assertTreeIsClean(repoRoot);\n        this.goToMain(repoRoot);\n        await this.cleanupCommand.run();\n        this.sweep(repoRoot);\n    }\n\n    /**\n     * A linked worktree has no main to check out — `git checkout main` FATALS there with \"main is already\n     * checked out at <primary clone>\", which is a footgun CLAUDE.md currently has to warn about in prose.\n     * So the command does the half that IS meaningful here (worktrees accumulate corpses too, if a\n     * long-lived one keeps merging main in) and says plainly where the other half lives.\n     */\n    private async sweepOnly(repoRoot: string): Promise<void> {\n        process.stdout.write(\n            'This is a linked WORKTREE. main is checked out in the primary clone, so there is nothing\\n'\n            + 'here to check out or pull — sweeping this tree only.\\n\\n'\n            + 'Most worktrees never need this: `wp-cleanup` removes the whole directory once its branch\\n'\n            + 'lands, which takes any orphan directories inside it along. Run this command again from the\\n'\n            + 'primary clone to go to main there.\\n\\n');\n        this.sweep(repoRoot);\n        return Promise.resolve();\n    }\n\n    private isLinkedWorktree(repoRoot: string): boolean {\n        const dirs = dotWebpieces.gitDirs(repoRoot);\n        return dirs !== null && dirs.isLinkedWorktree;\n    }\n\n    /**\n     * Refuse on a dirty tree instead of carrying the changes onto main. `git checkout` would happily\n     * bring uncommitted work along, and the one place nobody wants to discover their work is on main.\n     */\n    private assertTreeIsClean(repoRoot: string): void {\n        const status = this.git(repoRoot, ['status', '--porcelain']);\n        if (status === null || status.trim() === '') return;\n        throw new CliExitError(1,\n            `${SEP}❌ Uncommitted or untracked changes\\n${SEP}\\n`\n            + 'Going to main would carry them along. Commit them on this branch, or stash them, then\\n'\n            + 're-run. The webpieces tooling never commits your work for you.\\n\\n'\n            + `${status}`);\n    }\n\n    /**\n     * Checkout main and fast-forward it. `--ff-only` rather than a `reset --hard`, deliberately: a\n     * developer or an agent that accidentally committed to local main would have that work silently\n     * destroyed by a reset, and the whole point of this command is that it is safe to run without\n     * thinking. A refusal to fast-forward is a real condition a human should see and decide about.\n     */\n    private goToMain(repoRoot: string): void {\n        this.run_(repoRoot, ['fetch', 'origin', 'main']);\n        if (this.run_(repoRoot, ['checkout', 'main']) !== 0) {\n            throw new CliExitError(1, `${SEP}❌ Could not check out main\\n${SEP}\\n`\n                + 'git refused the checkout — its message is above.\\n');\n        }\n        if (this.run_(repoRoot, ['pull', '--ff-only', 'origin', 'main']) !== 0) {\n            throw new CliExitError(1, `${SEP}❌ Local main could not fast-forward\\n${SEP}\\n`\n                + 'Local main has commits that origin/main does not, so it is not a clean copy of the\\n'\n                + 'remote. Nothing was reset — those commits may be the only copy. Inspect them with\\n'\n                + '`git log origin/main..main` and decide what they are before going further.\\n');\n        }\n    }\n\n    /**\n     * Sweep, then print. Never throws: the checkout and pull above already succeeded, and a tidier is not\n     * permitted to turn somebody's completed sync into a failed command.\n     */\n    private sweep(repoRoot: string): void {\n        const report = this.orphanDirSweeper.sweep(repoRoot, new Date());\n        const rendered = report.render();\n        if (rendered === '') return;\n        process.stdout.write(`\\n${rendered}`);\n    }\n\n    /** Captured git output, or null when git could not be run or exited non-zero. */\n    private git(repoRoot: string, args: string[]): string | null {\n        const result = spawnSync('git', ['-C', repoRoot, ...args], {\n            encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],\n        });\n        if (result.error !== undefined || result.status !== 0) return null;\n        return result.stdout;\n    }\n\n    /** git with its output going straight to the terminal — for the commands whose progress is the point. */\n    private run_(repoRoot: string, args: string[]): number {\n        const result = spawnSync('git', ['-C', repoRoot, ...args], { encoding: 'utf8', stdio: 'inherit' });\n        return result.status === null ? 1 : result.status;\n    }\n}\n"]}

package/src/scripts/pr-gate-app.d.ts

@@ -3,6 +3,7 @@ import { FinishUpdateCommand } from './commands/finish-update-command';
 import { StartUpsertPrCommand } from './commands/start-upsert-pr-command';
 import { FinishUpsertPrCommand } from './commands/finish-upsert-pr-command';
 import { CleanupCommand } from './commands/cleanup-command';
+import { CheckoutCleanMainCommand } from './commands/checkout-clean-main-command';
 import { LandPrCommand } from './commands/land-pr-command';
 import { CheckPrCommand } from './commands/check-pr-command';
 import { ReviewUpsertPrCommand, ReviewUpsertPrOptions } from './commands/review-upsert-pr-command';
@@ -23,6 +24,7 @@ export declare class PrGateApp {
     private readonly startUpsertPrCommand;
     private readonly finishUpsertPrCommand;
     private readonly cleanupCommand;
+    private readonly checkoutCleanMainCommand;
     private readonly landPrCommand;
     private readonly checkPrCommand;
     private readonly reviewUpsertPrCommand;
@@ -31,7 +33,7 @@ export declare class PrGateApp {
     private readonly finishPushDevCommand;
     private readonly pushDevStateStore;
     private readonly repoRootFinder;
-    constructor(startUpdateCommand: StartUpdateCommand, finishUpdateCommand: FinishUpdateCommand, startUpsertPrCommand: StartUpsertPrCommand, finishUpsertPrCommand: FinishUpsertPrCommand, cleanupCommand: CleanupCommand, landPrCommand: LandPrCommand, checkPrCommand: CheckPrCommand, reviewUpsertPrCommand: ReviewUpsertPrCommand, reapWorktreeCommand: ReapWorktreeCommand, pushDevCommand: PushDevCommand, finishPushDevCommand: FinishPushDevCommand, pushDevStateStore: PushDevStateStore, repoRootFinder: RepoRootFinder);
+    constructor(startUpdateCommand: StartUpdateCommand, finishUpdateCommand: FinishUpdateCommand, startUpsertPrCommand: StartUpsertPrCommand, finishUpsertPrCommand: FinishUpsertPrCommand, cleanupCommand: CleanupCommand, checkoutCleanMainCommand: CheckoutCleanMainCommand, landPrCommand: LandPrCommand, checkPrCommand: CheckPrCommand, reviewUpsertPrCommand: ReviewUpsertPrCommand, reapWorktreeCommand: ReapWorktreeCommand, pushDevCommand: PushDevCommand, finishPushDevCommand: FinishPushDevCommand, pushDevStateStore: PushDevStateStore, repoRootFinder: RepoRootFinder);
     /**
      * Refuse `command` while a `wp-push-dev --resolve` is half-finished.
      *
@@ -61,6 +63,13 @@ export declare class PrGateApp {
     finishUpsertPr(): Promise<void>;
     /** `wp-cleanup`: reap what is provably merged, and ASK about everything that merely looks dead. */
     cleanup(): Promise<void>;
+    /**
+     * `wp-checkout-clean-main`: go to main, fast-forward it, reap dead worktrees and branches, and sweep
+     * the orphan directories a project move leaves behind. Replaces `git checkout main && git pull
+     * origin main` outright — see CheckoutCleanMainCommand for why the old pair must stop being accepted
+     * rather than surviving beside this.
+     */
+    checkoutCleanMain(): Promise<void>;
     /** `wp-land-pr`: squash-merge this branch's PR into main with the compact commit body. */
     landPr(): Promise<void>;
     /**

package/src/scripts/pr-gate-app.js

@@ -9,6 +9,7 @@ const finish_update_command_1 = require("./commands/finish-update-command");
 const start_upsert_pr_command_1 = require("./commands/start-upsert-pr-command");
 const finish_upsert_pr_command_1 = require("./commands/finish-upsert-pr-command");
 const cleanup_command_1 = require("./commands/cleanup-command");
+const checkout_clean_main_command_1 = require("./commands/checkout-clean-main-command");
 const land_pr_command_1 = require("./commands/land-pr-command");
 const check_pr_command_1 = require("./commands/check-pr-command");
 const review_upsert_pr_command_1 = require("./commands/review-upsert-pr-command");
@@ -29,6 +30,7 @@ let PrGateApp = class PrGateApp {
     startUpsertPrCommand;
     finishUpsertPrCommand;
     cleanupCommand;
+    checkoutCleanMainCommand;
     landPrCommand;
     checkPrCommand;
     reviewUpsertPrCommand;
@@ -37,12 +39,13 @@ let PrGateApp = class PrGateApp {
     finishPushDevCommand;
     pushDevStateStore;
     repoRootFinder;
-    constructor(startUpdateCommand, finishUpdateCommand, startUpsertPrCommand, finishUpsertPrCommand, cleanupCommand, landPrCommand, checkPrCommand, reviewUpsertPrCommand, reapWorktreeCommand, pushDevCommand, finishPushDevCommand, pushDevStateStore, repoRootFinder) {
+    constructor(startUpdateCommand, finishUpdateCommand, startUpsertPrCommand, finishUpsertPrCommand, cleanupCommand, checkoutCleanMainCommand, landPrCommand, checkPrCommand, reviewUpsertPrCommand, reapWorktreeCommand, pushDevCommand, finishPushDevCommand, pushDevStateStore, repoRootFinder) {
         this.startUpdateCommand = startUpdateCommand;
         this.finishUpdateCommand = finishUpdateCommand;
         this.startUpsertPrCommand = startUpsertPrCommand;
         this.finishUpsertPrCommand = finishUpsertPrCommand;
         this.cleanupCommand = cleanupCommand;
+        this.checkoutCleanMainCommand = checkoutCleanMainCommand;
         this.landPrCommand = landPrCommand;
         this.checkPrCommand = checkPrCommand;
         this.reviewUpsertPrCommand = reviewUpsertPrCommand;
@@ -106,6 +109,16 @@ let PrGateApp = class PrGateApp {
         this.assertNoResolveInProgress('wp-cleanup');
         return this.cleanupCommand.run();
     }
+    /**
+     * `wp-checkout-clean-main`: go to main, fast-forward it, reap dead worktrees and branches, and sweep
+     * the orphan directories a project move leaves behind. Replaces `git checkout main && git pull
+     * origin main` outright — see CheckoutCleanMainCommand for why the old pair must stop being accepted
+     * rather than surviving beside this.
+     */
+    checkoutCleanMain() {
+        this.assertNoResolveInProgress('wp-checkout-clean-main');
+        return this.checkoutCleanMainCommand.run();
+    }
     /** `wp-land-pr`: squash-merge this branch's PR into main with the compact commit body. */
     landPr() {
         this.assertNoResolveInProgress('wp-land-pr');
@@ -134,6 +147,7 @@ exports.PrGateApp = PrGateApp = tslib_1.__decorate([
         start_upsert_pr_command_1.StartUpsertPrCommand,
         finish_upsert_pr_command_1.FinishUpsertPrCommand,
         cleanup_command_1.CleanupCommand,
+        checkout_clean_main_command_1.CheckoutCleanMainCommand,
         land_pr_command_1.LandPrCommand,
         check_pr_command_1.CheckPrCommand,
         review_upsert_pr_command_1.ReviewUpsertPrCommand,

package/src/scripts/pr-gate-app.js.map

@@ -1 +1 @@
-{"version":3,"file":"pr-gate-app.js","sourceRoot":"","sources":["../../../../../../packages/tooling/pr-gate/src/scripts/pr-gate-app.ts"],"names":[],"mappings":"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","sourcesContent":["import { DocumentDesign } from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { StartUpdateCommand } from './commands/start-update-command';\nimport { FinishUpdateCommand } from './commands/finish-update-command';\nimport { StartUpsertPrCommand } from './commands/start-upsert-pr-command';\nimport { FinishUpsertPrCommand } from './commands/finish-upsert-pr-command';\nimport { CleanupCommand } from './commands/cleanup-command';\nimport { LandPrCommand } from './commands/land-pr-command';\nimport { CheckPrCommand } from './commands/check-pr-command';\nimport { ReviewUpsertPrCommand, ReviewUpsertPrOptions } from './commands/review-upsert-pr-command';\nimport { ReapWorktreeCommand } from './commands/reap-worktree-command';\nimport { PushDevCommand, PushDevOptions } from './commands/push-dev-command';\nimport { FinishPushDevCommand, FinishPushDevOptions } from './commands/finish-push-dev-command';\nimport { PushDevStateStore } from './workflow/push-dev-state';\nimport { RepoRootFinder } from '@webpieces/rules-config';\n\n/**\n * The pr-gate application root. `container.get(PrGateApp)` resolves the entire workflow DAG (the command\n * classes → the injected git/merge/dashboard services). `@DocumentDesign` marks it the\n * top-of-DAG the DI-design analyzer roots on, so `role:app` pr-gate draws its design. Each `bin/*`\n * entry resolves THIS and calls the matching command method.\n */\n@DocumentDesign()\n@injectable(bindingScopeValues.Singleton)\nexport class PrGateApp {\n    constructor(\n        private readonly startUpdateCommand: StartUpdateCommand,\n        private readonly finishUpdateCommand: FinishUpdateCommand,\n        private readonly startUpsertPrCommand: StartUpsertPrCommand,\n        private readonly finishUpsertPrCommand: FinishUpsertPrCommand,\n        private readonly cleanupCommand: CleanupCommand,\n        private readonly landPrCommand: LandPrCommand,\n        private readonly checkPrCommand: CheckPrCommand,\n        private readonly reviewUpsertPrCommand: ReviewUpsertPrCommand,\n        private readonly reapWorktreeCommand: ReapWorktreeCommand,\n        private readonly pushDevCommand: PushDevCommand,\n        private readonly finishPushDevCommand: FinishPushDevCommand,\n        private readonly pushDevStateStore: PushDevStateStore,\n        private readonly repoRootFinder: RepoRootFinder,\n    ) {}\n\n    /**\n     * Refuse `command` while a `wp-push-dev --resolve` is half-finished.\n     *\n     * Enforced HERE, at the one place every bin funnels through, rather than in each command: a resolve\n     * parks the checkout on a throwaway branch, so every command below would act on a branch that is not\n     * the one it thinks it is. Putting the check in nine constructors is nine chances to forget it in the\n     * tenth. PushDevStateStore owns the blocked list AND renders the hint from it, so the two cannot drift.\n     */\n    private assertNoResolveInProgress(command: string): void {\n        if (!this.pushDevStateStore.isBlockedDuringResolve(command)) return;\n        this.pushDevStateStore.assertIdle(this.repoRootFinder.resolveRepoRoot(process.cwd()), command);\n    }\n\n    /** `wp-push-dev`: publish a DISPOSABLE copy of this branch for the shared dev environment. No PR, no build. */\n    pushDev(opts: PushDevOptions = new PushDevOptions()): Promise<void> {\n        return this.pushDevCommand.run(opts);\n    }\n\n    /** `wp-finish-push-dev`: commit a resolved dev composition and publish it (conflict path only). */\n    finishPushDev(opts: FinishPushDevOptions = new FinishPushDevOptions()): Promise<void> {\n        return this.finishPushDevCommand.run(opts);\n    }\n\n    /**\n     * INTERNAL (`wp-reap-worktree.js`, no `bin` entry): remove ONE named worktree and its branch.\n     * `wp-land-pr` spawns it with cwd = the primary clone so the tree it just landed from can be\n     * reaped by a process that is not standing in it.\n     */\n    reapWorktree(args: string[]): Promise<void> {\n        return this.reapWorktreeCommand.run(args);\n    }\n\n    /** `wp-start-update`: 3-point squash-update from main (no PR). */\n    startUpdate(): Promise<void> {\n        this.assertNoResolveInProgress('wp-start-update');\n        return this.startUpdateCommand.run();\n    }\n\n    /** `wp-finish-update`: validate + finalize a resolved 3-point merge (no PR). */\n    finishUpdate(): Promise<void> {\n        this.assertNoResolveInProgress('wp-finish-update');\n        return this.finishUpdateCommand.run();\n    }\n\n    /** `wp-start-upsert-pr`: update from main (3-point merge), hand off review.json. No build gate, no push. */\n    startUpsertPr(): Promise<void> {\n        this.assertNoResolveInProgress('wp-start-upsert-pr');\n        return this.startUpsertPrCommand.run();\n    }\n\n    /** `wp-finish-upsert-pr`: finalize merge, authoritative build gate, dashboard, create/update PR. */\n    finishUpsertPr(): Promise<void> {\n        this.assertNoResolveInProgress('wp-finish-upsert-pr');\n        return this.finishUpsertPrCommand.run();\n    }\n\n    /** `wp-cleanup`: reap what is provably merged, and ASK about everything that merely looks dead. */\n    cleanup(): Promise<void> {\n        this.assertNoResolveInProgress('wp-cleanup');\n        return this.cleanupCommand.run();\n    }\n\n    /** `wp-land-pr`: squash-merge this branch's PR into main with the compact commit body. */\n    landPr(): Promise<void> {\n        this.assertNoResolveInProgress('wp-land-pr');\n        return this.landPrCommand.run();\n    }\n\n    /**\n     * `wp-review-upsert-pr`: STAGE ② — validate the 3-point merge, run the build gate, extract this\n     * branch's diff, and brief the reviewer subagents. Unlike the report-only command it replaces, this CAN\n     * fail — before any reviewer is spawned, so a broken branch costs no reviewer tokens.\n     */\n    reviewUpsertPr(opts: ReviewUpsertPrOptions = new ReviewUpsertPrOptions()): Promise<void> {\n        this.assertNoResolveInProgress('wp-review-upsert-pr');\n        return this.reviewUpsertPrCommand.run(opts);\n    }\n\n    /** `wp-check-pr`: READ-ONLY CI check — verify the PR body carries a valid HMAC gate token for its head sha. */\n    checkPr(): Promise<void> {\n        return this.checkPrCommand.run();\n    }\n}\n"]}
+{"version":3,"file":"pr-gate-app.js","sourceRoot":"","sources":["../../../../../../packages/tooling/pr-gate/src/scripts/pr-gate-app.ts"],"names":[],"mappings":"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","sourcesContent":["import { DocumentDesign } from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { StartUpdateCommand } from './commands/start-update-command';\nimport { FinishUpdateCommand } from './commands/finish-update-command';\nimport { StartUpsertPrCommand } from './commands/start-upsert-pr-command';\nimport { FinishUpsertPrCommand } from './commands/finish-upsert-pr-command';\nimport { CleanupCommand } from './commands/cleanup-command';\nimport { CheckoutCleanMainCommand } from './commands/checkout-clean-main-command';\nimport { LandPrCommand } from './commands/land-pr-command';\nimport { CheckPrCommand } from './commands/check-pr-command';\nimport { ReviewUpsertPrCommand, ReviewUpsertPrOptions } from './commands/review-upsert-pr-command';\nimport { ReapWorktreeCommand } from './commands/reap-worktree-command';\nimport { PushDevCommand, PushDevOptions } from './commands/push-dev-command';\nimport { FinishPushDevCommand, FinishPushDevOptions } from './commands/finish-push-dev-command';\nimport { PushDevStateStore } from './workflow/push-dev-state';\nimport { RepoRootFinder } from '@webpieces/rules-config';\n\n/**\n * The pr-gate application root. `container.get(PrGateApp)` resolves the entire workflow DAG (the command\n * classes → the injected git/merge/dashboard services). `@DocumentDesign` marks it the\n * top-of-DAG the DI-design analyzer roots on, so `role:app` pr-gate draws its design. Each `bin/*`\n * entry resolves THIS and calls the matching command method.\n */\n@DocumentDesign()\n@injectable(bindingScopeValues.Singleton)\nexport class PrGateApp {\n    constructor(\n        private readonly startUpdateCommand: StartUpdateCommand,\n        private readonly finishUpdateCommand: FinishUpdateCommand,\n        private readonly startUpsertPrCommand: StartUpsertPrCommand,\n        private readonly finishUpsertPrCommand: FinishUpsertPrCommand,\n        private readonly cleanupCommand: CleanupCommand,\n        private readonly checkoutCleanMainCommand: CheckoutCleanMainCommand,\n        private readonly landPrCommand: LandPrCommand,\n        private readonly checkPrCommand: CheckPrCommand,\n        private readonly reviewUpsertPrCommand: ReviewUpsertPrCommand,\n        private readonly reapWorktreeCommand: ReapWorktreeCommand,\n        private readonly pushDevCommand: PushDevCommand,\n        private readonly finishPushDevCommand: FinishPushDevCommand,\n        private readonly pushDevStateStore: PushDevStateStore,\n        private readonly repoRootFinder: RepoRootFinder,\n    ) {}\n\n    /**\n     * Refuse `command` while a `wp-push-dev --resolve` is half-finished.\n     *\n     * Enforced HERE, at the one place every bin funnels through, rather than in each command: a resolve\n     * parks the checkout on a throwaway branch, so every command below would act on a branch that is not\n     * the one it thinks it is. Putting the check in nine constructors is nine chances to forget it in the\n     * tenth. PushDevStateStore owns the blocked list AND renders the hint from it, so the two cannot drift.\n     */\n    private assertNoResolveInProgress(command: string): void {\n        if (!this.pushDevStateStore.isBlockedDuringResolve(command)) return;\n        this.pushDevStateStore.assertIdle(this.repoRootFinder.resolveRepoRoot(process.cwd()), command);\n    }\n\n    /** `wp-push-dev`: publish a DISPOSABLE copy of this branch for the shared dev environment. No PR, no build. */\n    pushDev(opts: PushDevOptions = new PushDevOptions()): Promise<void> {\n        return this.pushDevCommand.run(opts);\n    }\n\n    /** `wp-finish-push-dev`: commit a resolved dev composition and publish it (conflict path only). */\n    finishPushDev(opts: FinishPushDevOptions = new FinishPushDevOptions()): Promise<void> {\n        return this.finishPushDevCommand.run(opts);\n    }\n\n    /**\n     * INTERNAL (`wp-reap-worktree.js`, no `bin` entry): remove ONE named worktree and its branch.\n     * `wp-land-pr` spawns it with cwd = the primary clone so the tree it just landed from can be\n     * reaped by a process that is not standing in it.\n     */\n    reapWorktree(args: string[]): Promise<void> {\n        return this.reapWorktreeCommand.run(args);\n    }\n\n    /** `wp-start-update`: 3-point squash-update from main (no PR). */\n    startUpdate(): Promise<void> {\n        this.assertNoResolveInProgress('wp-start-update');\n        return this.startUpdateCommand.run();\n    }\n\n    /** `wp-finish-update`: validate + finalize a resolved 3-point merge (no PR). */\n    finishUpdate(): Promise<void> {\n        this.assertNoResolveInProgress('wp-finish-update');\n        return this.finishUpdateCommand.run();\n    }\n\n    /** `wp-start-upsert-pr`: update from main (3-point merge), hand off review.json. No build gate, no push. */\n    startUpsertPr(): Promise<void> {\n        this.assertNoResolveInProgress('wp-start-upsert-pr');\n        return this.startUpsertPrCommand.run();\n    }\n\n    /** `wp-finish-upsert-pr`: finalize merge, authoritative build gate, dashboard, create/update PR. */\n    finishUpsertPr(): Promise<void> {\n        this.assertNoResolveInProgress('wp-finish-upsert-pr');\n        return this.finishUpsertPrCommand.run();\n    }\n\n    /** `wp-cleanup`: reap what is provably merged, and ASK about everything that merely looks dead. */\n    cleanup(): Promise<void> {\n        this.assertNoResolveInProgress('wp-cleanup');\n        return this.cleanupCommand.run();\n    }\n\n    /**\n     * `wp-checkout-clean-main`: go to main, fast-forward it, reap dead worktrees and branches, and sweep\n     * the orphan directories a project move leaves behind. Replaces `git checkout main && git pull\n     * origin main` outright — see CheckoutCleanMainCommand for why the old pair must stop being accepted\n     * rather than surviving beside this.\n     */\n    checkoutCleanMain(): Promise<void> {\n        this.assertNoResolveInProgress('wp-checkout-clean-main');\n        return this.checkoutCleanMainCommand.run();\n    }\n\n    /** `wp-land-pr`: squash-merge this branch's PR into main with the compact commit body. */\n    landPr(): Promise<void> {\n        this.assertNoResolveInProgress('wp-land-pr');\n        return this.landPrCommand.run();\n    }\n\n    /**\n     * `wp-review-upsert-pr`: STAGE ② — validate the 3-point merge, run the build gate, extract this\n     * branch's diff, and brief the reviewer subagents. Unlike the report-only command it replaces, this CAN\n     * fail — before any reviewer is spawned, so a broken branch costs no reviewer tokens.\n     */\n    reviewUpsertPr(opts: ReviewUpsertPrOptions = new ReviewUpsertPrOptions()): Promise<void> {\n        this.assertNoResolveInProgress('wp-review-upsert-pr');\n        return this.reviewUpsertPrCommand.run(opts);\n    }\n\n    /** `wp-check-pr`: READ-ONLY CI check — verify the PR body carries a valid HMAC gate token for its head sha. */\n    checkPr(): Promise<void> {\n        return this.checkPrCommand.run();\n    }\n}\n"]}

package/src/scripts/workflow/build-gate-log.js

@@ -11,10 +11,11 @@ const inversify_1 = require("inversify");
 // file runs for a user who has not created that OPTIONAL file — see `HomeConfigService`
 // (`@webpieces/rules-config`), which returns all-defaults silently when it is absent.
 //
-// That file has a second, REQUIRED key once it exists — `experimental.whole-repo-build-guard` — so the
-// smallest document enabling THIS feature is:
-//     { "experimental": { "whole-repo-build-guard": false, "buildGateLogCapture": true } }
-// `HomeConfigService` owns that rule and prints the same edit when the key is missing.
+// EVERY key in that file is optional, so the smallest document enabling THIS feature is just:
+//     { "experimental": { "buildGateLogCapture": true } }
+// Optional is not a convenience: the file is MACHINE-GLOBAL and the repos on one machine pin different
+// webpieces releases, so a REQUIRED key there has no satisfiable value — omitting it fails the new
+// release, adding it fails every older one. `HomeConfigService` owns that rule.
 //
 // ─── Why ───────────────────────────────────────────────────────────────────────────────────────────────
 // The build gate already builds everything. When it fails, the pre-existing message says "run THIS exact

package/src/scripts/workflow/build-gate-log.js.map

@@ -1 +1 @@
-{"version":3,"file":"build-gate-log.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/build-gate-log.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawnSync } from 'child_process';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { dotWebpieces } from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\n\n// EXPERIMENTAL (opt-in via `~/.webpieces/config.json` → experimental.buildGateLogCapture). Nothing in this\n// file runs for a user who has not created that OPTIONAL file — see `HomeConfigService`\n// (`@webpieces/rules-config`), which returns all-defaults silently when it is absent.\n//\n// That file has a second, REQUIRED key once it exists — `experimental.whole-repo-build-guard` — so the\n// smallest document enabling THIS feature is:\n//     { \"experimental\": { \"whole-repo-build-guard\": false, \"buildGateLogCapture\": true } }\n// `HomeConfigService` owns that rule and prints the same edit when the key is missing.\n//\n// ─── Why ───────────────────────────────────────────────────────────────────────────────────────────────\n// The build gate already builds everything. When it fails, the pre-existing message says \"run THIS exact\n// command to reproduce\", and an AI agent obeys it — so the repo is built a SECOND time purely to see the\n// errors that scrolled past the first time. This captures the first build's output instead.\n//\n// ─── Why a shell `tee` and not spawnSync's pipes ───────────────────────────────────────────────────────\n// spawnSync BUFFERS a piped stream and hands it over only after the child exits, so the human would watch\n// a silent terminal for the length of a full build. The output has to be split at the OS level, which is\n// what `tee` is. The gate keeps `stdio: 'inherit'`, so the terminal is byte-identical to today.\n//\n// ─── Why an exit-status side file and not `pipefail` ───────────────────────────────────────────────────\n// In a pipeline the shell reports the LAST command's status, i.e. tee's, which is 0 whether the build\n// passed or failed. `set -o pipefail` and `${PIPESTATUS[0]}` are bash/zsh, and spawnSync's `shell: true`\n// gives `/bin/sh` — dash on Debian. Writing `$?` to a side file inside the group is plain POSIX and works\n// under every one of them. The redirect keeps it out of the pipe, so it never lands in the log.\nconst STATUS_SUFFIX = '.status';\n\n/**\n * Which stage's gate is being captured. The value is part of the log FILENAME, so review and finish never\n * write the same file even at the same commit on the same branch.\n */\nexport const REVIEW_STAGE = 'review';\nexport const FINISH_STAGE = 'finish';\n\n/**\n * Captures the build gate's full output to `.webpieces/logs/`, and renders the small pointer the AI is\n * handed instead of a rebuild instruction.\n *\n * ─── Why the filename cannot collide ───────────────────────────────────────────────────────────────────\n * The path is `dotWebpieces.logsFile(repoRoot, 'build-gate-<stage>-<branch>-<shortSha>.log')`, and each\n * component rules out one class of concurrent writer:\n *   • the DIRECTORY is `dotWebpieces.local()`-scoped — `<primary>/.webpieces/worktrees/<git worktree\n *     name>/logs/` in a linked worktree. Every worktree therefore has its own log directory already, which\n *     is what makes \"N agents in N worktrees\" safe by construction rather than by naming.\n *   • `<stage>` separates review from finish, the two gates that CAN run against one commit.\n *   • `<branch>` — a branch can be checked out in at most one worktree (git enforces it), so within one\n *     log directory the branch is effectively constant; it is in the name so a human reading the directory\n *     can tell whose log is whose, and so switching branches never appends to a stale file.\n *   • `<shortSha>` — a re-run at a NEW commit gets a new file, so the log a failure message points at is\n *     always the build for the code that failed. A re-run at the SAME commit deliberately TRUNCATES: it is\n *     the same build of the same tree, and the fresh one is the one worth reading.\n * The residual case is two agents running the same stage, at the same commit, in the SAME worktree,\n * simultaneously. That is already unsupported — both would be driving one git index and one merge state —\n * and it is the only case this scheme does not separate.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class BuildGateLog {\n    /** Absolute path of the log for `stage` at the current HEAD, creating the log directory. */\n    pathFor(repoRoot: string, stage: string): string {\n        const file = dotWebpieces.logsFile(repoRoot, this.fileNameFor(repoRoot, stage));\n        fs.mkdirSync(path.dirname(file), { recursive: true });\n        return file;\n    }\n\n    /** The same path WITHOUT creating anything, and '' when no such log exists. Used by finish's skip path. */\n    existingLogFor(repoRoot: string, stage: string): string {\n        const file = dotWebpieces.logsFile(repoRoot, this.fileNameFor(repoRoot, stage));\n        return fs.existsSync(file) ? file : '';\n    }\n\n    /** `build-gate-<stage>-<branch>-<shortSha>.log` — see the class docstring for why this cannot collide. */\n    fileNameFor(repoRoot: string, stage: string): string {\n        const branch = this.slug(this.git(repoRoot, ['rev-parse', '--abbrev-ref', 'HEAD']));\n        const sha = this.slug(this.git(repoRoot, ['rev-parse', '--short', 'HEAD']));\n        return `build-gate-${this.slug(stage)}-${branch === '' ? 'nobranch' : branch}-${sha === '' ? 'nosha' : sha}.log`;\n    }\n\n    /**\n     * Run `buildCommand` with its combined stdout+stderr streaming to the terminal AND appended in full to\n     * `logPath`. Returns the BUILD's exit code (not tee's). Nothing is truncated.\n     */\n    run(repoRoot: string, buildCommand: string, logPath: string): number {\n        const statusFile = `${logPath}${STATUS_SUFFIX}`;\n        fs.rmSync(statusFile, { force: true });\n        const result = spawnSync(this.wrap(buildCommand, logPath, statusFile),\n            { stdio: 'inherit', cwd: repoRoot, shell: true });\n        const fromFile = this.readStatus(statusFile);\n        fs.rmSync(statusFile, { force: true });\n        if (fromFile !== null) return fromFile;\n        // The side file never appeared ⇒ the shell died before the echo. The PIPELINE's status is tee's,\n        // which is 0, and reporting 0 there would call a dead build green — so fail CLOSED instead.\n        return result.status !== null && result.status !== 0 ? result.status : 1;\n    }\n\n    /**\n     * The ENTIRE message the AI gets on a captured failure. Deliberately tiny: the whole point is that the\n     * agent reads ONE file rather than carrying a build transcript in its context.\n     *\n     * The last sentence is not filler. If the log holds no visible failure then something upstream is wrong\n     * (a runner that died without printing, a truncated pipe), and the worst possible response is an agent\n     * guessing or rebuilding — so it is told to surface the contradiction to the human and stop.\n     */\n    failureMessage(buildCommand: string, logPath: string): string {\n        return `\\n❌ The CI build failed. We ran\\n\\n` +\n            `    ${buildCommand} > ${logPath}\\n\\n` +\n            `and it failed, so read that file for the failures. Do NOT re-run the build to see them.\\n` +\n            `If you do not see failures in that log, report that to the user and stop.\\n`;\n    }\n\n    /**\n     * `{ ( <build> ) ; echo $? > <status> ; } 2>&1 | tee <log>` — written across LINES so a build command\n     * ending in a `#` comment cannot swallow what follows it.\n     *\n     * The inner `( … )` is load-bearing, not decoration. The left side of a pipeline is already a subshell,\n     * so a build command containing a plain `exit 7` (or any script that calls `exit`) would terminate that\n     * subshell OUTRIGHT — `echo $?` never runs, the side file never appears, and the only status left is\n     * tee's 0. The nested subshell absorbs the `exit`, so `$?` is the build's code every time.\n     */\n    private wrap(buildCommand: string, logPath: string, statusFile: string): string {\n        return `{\\n(\\n${buildCommand}\\n)\\necho $? > ${this.quote(statusFile)}\\n} 2>&1 | tee ${this.quote(logPath)}`;\n    }\n\n    // The build's own exit code, or null when the side file never appeared (the shell died before the echo).\n    private readStatus(statusFile: string): number | null {\n        if (!fs.existsSync(statusFile)) return null;\n        const parsed = Number.parseInt(fs.readFileSync(statusFile, 'utf8').trim(), 10);\n        return Number.isNaN(parsed) ? null : parsed;\n    }\n\n    // POSIX single-quoting: everything is literal inside '…', and a literal ' is spelled '\\''.\n    private quote(value: string): string {\n        return `'${value.split(\"'\").join(`'\\\\''`)}'`;\n    }\n\n    // Anything that is not a filename-safe character becomes '-', so `dean/feat` cannot create directories.\n    private slug(value: string): string {\n        return value.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');\n    }\n\n    // One local git read. Fails SOFT to '' — a missing branch/sha degrades the FILENAME, and degrading a\n    // filename may never be the reason a build gate does not run.\n    private git(repoRoot: string, args: string[]): string {\n        const result = spawnSync('git', ['-C', repoRoot, ...args], { encoding: 'utf8' });\n        if (result.status !== 0) return '';\n        return (result.stdout ?? '').trim();\n    }\n}\n"]}
+{"version":3,"file":"build-gate-log.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/build-gate-log.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawnSync } from 'child_process';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { dotWebpieces } from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\n\n// EXPERIMENTAL (opt-in via `~/.webpieces/config.json` → experimental.buildGateLogCapture). Nothing in this\n// file runs for a user who has not created that OPTIONAL file — see `HomeConfigService`\n// (`@webpieces/rules-config`), which returns all-defaults silently when it is absent.\n//\n// EVERY key in that file is optional, so the smallest document enabling THIS feature is just:\n//     { \"experimental\": { \"buildGateLogCapture\": true } }\n// Optional is not a convenience: the file is MACHINE-GLOBAL and the repos on one machine pin different\n// webpieces releases, so a REQUIRED key there has no satisfiable value — omitting it fails the new\n// release, adding it fails every older one. `HomeConfigService` owns that rule.\n//\n// ─── Why ───────────────────────────────────────────────────────────────────────────────────────────────\n// The build gate already builds everything. When it fails, the pre-existing message says \"run THIS exact\n// command to reproduce\", and an AI agent obeys it — so the repo is built a SECOND time purely to see the\n// errors that scrolled past the first time. This captures the first build's output instead.\n//\n// ─── Why a shell `tee` and not spawnSync's pipes ───────────────────────────────────────────────────────\n// spawnSync BUFFERS a piped stream and hands it over only after the child exits, so the human would watch\n// a silent terminal for the length of a full build. The output has to be split at the OS level, which is\n// what `tee` is. The gate keeps `stdio: 'inherit'`, so the terminal is byte-identical to today.\n//\n// ─── Why an exit-status side file and not `pipefail` ───────────────────────────────────────────────────\n// In a pipeline the shell reports the LAST command's status, i.e. tee's, which is 0 whether the build\n// passed or failed. `set -o pipefail` and `${PIPESTATUS[0]}` are bash/zsh, and spawnSync's `shell: true`\n// gives `/bin/sh` — dash on Debian. Writing `$?` to a side file inside the group is plain POSIX and works\n// under every one of them. The redirect keeps it out of the pipe, so it never lands in the log.\nconst STATUS_SUFFIX = '.status';\n\n/**\n * Which stage's gate is being captured. The value is part of the log FILENAME, so review and finish never\n * write the same file even at the same commit on the same branch.\n */\nexport const REVIEW_STAGE = 'review';\nexport const FINISH_STAGE = 'finish';\n\n/**\n * Captures the build gate's full output to `.webpieces/logs/`, and renders the small pointer the AI is\n * handed instead of a rebuild instruction.\n *\n * ─── Why the filename cannot collide ───────────────────────────────────────────────────────────────────\n * The path is `dotWebpieces.logsFile(repoRoot, 'build-gate-<stage>-<branch>-<shortSha>.log')`, and each\n * component rules out one class of concurrent writer:\n *   • the DIRECTORY is `dotWebpieces.local()`-scoped — `<primary>/.webpieces/worktrees/<git worktree\n *     name>/logs/` in a linked worktree. Every worktree therefore has its own log directory already, which\n *     is what makes \"N agents in N worktrees\" safe by construction rather than by naming.\n *   • `<stage>` separates review from finish, the two gates that CAN run against one commit.\n *   • `<branch>` — a branch can be checked out in at most one worktree (git enforces it), so within one\n *     log directory the branch is effectively constant; it is in the name so a human reading the directory\n *     can tell whose log is whose, and so switching branches never appends to a stale file.\n *   • `<shortSha>` — a re-run at a NEW commit gets a new file, so the log a failure message points at is\n *     always the build for the code that failed. A re-run at the SAME commit deliberately TRUNCATES: it is\n *     the same build of the same tree, and the fresh one is the one worth reading.\n * The residual case is two agents running the same stage, at the same commit, in the SAME worktree,\n * simultaneously. That is already unsupported — both would be driving one git index and one merge state —\n * and it is the only case this scheme does not separate.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class BuildGateLog {\n    /** Absolute path of the log for `stage` at the current HEAD, creating the log directory. */\n    pathFor(repoRoot: string, stage: string): string {\n        const file = dotWebpieces.logsFile(repoRoot, this.fileNameFor(repoRoot, stage));\n        fs.mkdirSync(path.dirname(file), { recursive: true });\n        return file;\n    }\n\n    /** The same path WITHOUT creating anything, and '' when no such log exists. Used by finish's skip path. */\n    existingLogFor(repoRoot: string, stage: string): string {\n        const file = dotWebpieces.logsFile(repoRoot, this.fileNameFor(repoRoot, stage));\n        return fs.existsSync(file) ? file : '';\n    }\n\n    /** `build-gate-<stage>-<branch>-<shortSha>.log` — see the class docstring for why this cannot collide. */\n    fileNameFor(repoRoot: string, stage: string): string {\n        const branch = this.slug(this.git(repoRoot, ['rev-parse', '--abbrev-ref', 'HEAD']));\n        const sha = this.slug(this.git(repoRoot, ['rev-parse', '--short', 'HEAD']));\n        return `build-gate-${this.slug(stage)}-${branch === '' ? 'nobranch' : branch}-${sha === '' ? 'nosha' : sha}.log`;\n    }\n\n    /**\n     * Run `buildCommand` with its combined stdout+stderr streaming to the terminal AND appended in full to\n     * `logPath`. Returns the BUILD's exit code (not tee's). Nothing is truncated.\n     */\n    run(repoRoot: string, buildCommand: string, logPath: string): number {\n        const statusFile = `${logPath}${STATUS_SUFFIX}`;\n        fs.rmSync(statusFile, { force: true });\n        const result = spawnSync(this.wrap(buildCommand, logPath, statusFile),\n            { stdio: 'inherit', cwd: repoRoot, shell: true });\n        const fromFile = this.readStatus(statusFile);\n        fs.rmSync(statusFile, { force: true });\n        if (fromFile !== null) return fromFile;\n        // The side file never appeared ⇒ the shell died before the echo. The PIPELINE's status is tee's,\n        // which is 0, and reporting 0 there would call a dead build green — so fail CLOSED instead.\n        return result.status !== null && result.status !== 0 ? result.status : 1;\n    }\n\n    /**\n     * The ENTIRE message the AI gets on a captured failure. Deliberately tiny: the whole point is that the\n     * agent reads ONE file rather than carrying a build transcript in its context.\n     *\n     * The last sentence is not filler. If the log holds no visible failure then something upstream is wrong\n     * (a runner that died without printing, a truncated pipe), and the worst possible response is an agent\n     * guessing or rebuilding — so it is told to surface the contradiction to the human and stop.\n     */\n    failureMessage(buildCommand: string, logPath: string): string {\n        return `\\n❌ The CI build failed. We ran\\n\\n` +\n            `    ${buildCommand} > ${logPath}\\n\\n` +\n            `and it failed, so read that file for the failures. Do NOT re-run the build to see them.\\n` +\n            `If you do not see failures in that log, report that to the user and stop.\\n`;\n    }\n\n    /**\n     * `{ ( <build> ) ; echo $? > <status> ; } 2>&1 | tee <log>` — written across LINES so a build command\n     * ending in a `#` comment cannot swallow what follows it.\n     *\n     * The inner `( … )` is load-bearing, not decoration. The left side of a pipeline is already a subshell,\n     * so a build command containing a plain `exit 7` (or any script that calls `exit`) would terminate that\n     * subshell OUTRIGHT — `echo $?` never runs, the side file never appears, and the only status left is\n     * tee's 0. The nested subshell absorbs the `exit`, so `$?` is the build's code every time.\n     */\n    private wrap(buildCommand: string, logPath: string, statusFile: string): string {\n        return `{\\n(\\n${buildCommand}\\n)\\necho $? > ${this.quote(statusFile)}\\n} 2>&1 | tee ${this.quote(logPath)}`;\n    }\n\n    // The build's own exit code, or null when the side file never appeared (the shell died before the echo).\n    private readStatus(statusFile: string): number | null {\n        if (!fs.existsSync(statusFile)) return null;\n        const parsed = Number.parseInt(fs.readFileSync(statusFile, 'utf8').trim(), 10);\n        return Number.isNaN(parsed) ? null : parsed;\n    }\n\n    // POSIX single-quoting: everything is literal inside '…', and a literal ' is spelled '\\''.\n    private quote(value: string): string {\n        return `'${value.split(\"'\").join(`'\\\\''`)}'`;\n    }\n\n    // Anything that is not a filename-safe character becomes '-', so `dean/feat` cannot create directories.\n    private slug(value: string): string {\n        return value.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');\n    }\n\n    // One local git read. Fails SOFT to '' — a missing branch/sha degrades the FILENAME, and degrading a\n    // filename may never be the reason a build gate does not run.\n    private git(repoRoot: string, args: string[]): string {\n        const result = spawnSync('git', ['-C', repoRoot, ...args], { encoding: 'utf8' });\n        if (result.status !== 0) return '';\n        return (result.stdout ?? '').trim();\n    }\n}\n"]}

package/src/scripts/wp-checkout-clean-main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import 'reflect-metadata';

package/src/scripts/wp-checkout-clean-main.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+require("reflect-metadata");
+const inversify_1 = require("inversify");
+const rules_config_1 = require("@webpieces/rules-config");
+const pr_gate_app_1 = require("./pr-gate-app");
+// Composition root: build the container and resolve the app so inversify constructs the whole DAG.
+(0, rules_config_1.runMain)(async () => {
+    // autobind self-binds every @injectable(Singleton) tooling class (replaces the buildProviderModule registry scan)
+    const container = new inversify_1.Container({ autobind: true });
+    // Reject `--help`/bogus flags BEFORE the app touches git — an ignored flag must never start the flow.
+    container.get(rules_config_1.CliArgs).assertNoArgs(new rules_config_1.CliUsage('wp-checkout-clean-main', 'Go to main, fast-forward it, reap dead worktrees and branches, and sweep orphan directories.'));
+    await container.get(pr_gate_app_1.PrGateApp).checkoutCleanMain();
+});
+//# sourceMappingURL=wp-checkout-clean-main.js.map

package/src/scripts/wp-checkout-clean-main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wp-checkout-clean-main.js","sourceRoot":"","sources":["../../../../../../packages/tooling/pr-gate/src/scripts/wp-checkout-clean-main.ts"],"names":[],"mappings":";;;AACA,4BAA0B;AAC1B,yCAAsC;AACtC,0DAAqE;AACrE,+CAA0C;AAE1C,mGAAmG;AACnG,IAAA,sBAAO,EAAC,KAAK,IAAmB,EAAE;IAC9B,kHAAkH;IAClH,MAAM,SAAS,GAAG,IAAI,qBAAS,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,sGAAsG;IACtG,SAAS,CAAC,GAAG,CAAC,sBAAO,CAAC,CAAC,YAAY,CAAC,IAAI,uBAAQ,CAC5C,wBAAwB,EACxB,8FAA8F,CAAC,CAAC,CAAC;IACrG,MAAM,SAAS,CAAC,GAAG,CAAC,uBAAS,CAAC,CAAC,iBAAiB,EAAE,CAAC;AACvD,CAAC,CAAC,CAAC","sourcesContent":["#!/usr/bin/env node\nimport 'reflect-metadata';\nimport { Container } from 'inversify';\nimport { runMain, CliArgs, CliUsage } from '@webpieces/rules-config';\nimport { PrGateApp } from './pr-gate-app';\n\n// Composition root: build the container and resolve the app so inversify constructs the whole DAG.\nrunMain(async (): Promise<void> => {\n    // autobind self-binds every @injectable(Singleton) tooling class (replaces the buildProviderModule registry scan)\n    const container = new Container({ autobind: true });\n    // Reject `--help`/bogus flags BEFORE the app touches git — an ignored flag must never start the flow.\n    container.get(CliArgs).assertNoArgs(new CliUsage(\n        'wp-checkout-clean-main',\n        'Go to main, fast-forward it, reap dead worktrees and branches, and sweep orphan directories.'));\n    await container.get(PrGateApp).checkoutCleanMain();\n});\n"]}