@webpieces/pr-gate 0.4.565 → 0.4.567

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

@@ -13,6 +13,10 @@ 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");
 const reap_worktree_command_1 = require("./commands/reap-worktree-command");
+const push_dev_command_1 = require("./commands/push-dev-command");
+const finish_push_dev_command_1 = require("./commands/finish-push-dev-command");
+const push_dev_state_1 = require("./workflow/push-dev-state");
+const rules_config_2 = require("@webpieces/rules-config");
 /**
  * The pr-gate application root. `container.get(PrGateApp)` resolves the entire workflow DAG (the command
  * classes → the injected git/merge/dashboard services). `@DocumentDesign` marks it the
@@ -29,7 +33,11 @@ let PrGateApp = class PrGateApp {
     checkPrCommand;
     reviewUpsertPrCommand;
     reapWorktreeCommand;
-    constructor(startUpdateCommand, finishUpdateCommand, startUpsertPrCommand, finishUpsertPrCommand, cleanupCommand, landPrCommand, checkPrCommand, reviewUpsertPrCommand, reapWorktreeCommand) {
+    pushDevCommand;
+    finishPushDevCommand;
+    pushDevStateStore;
+    repoRootFinder;
+    constructor(startUpdateCommand, finishUpdateCommand, startUpsertPrCommand, finishUpsertPrCommand, cleanupCommand, landPrCommand, checkPrCommand, reviewUpsertPrCommand, reapWorktreeCommand, pushDevCommand, finishPushDevCommand, pushDevStateStore, repoRootFinder) {
         this.startUpdateCommand = startUpdateCommand;
         this.finishUpdateCommand = finishUpdateCommand;
         this.startUpsertPrCommand = startUpsertPrCommand;
@@ -39,6 +47,31 @@ let PrGateApp = class PrGateApp {
         this.checkPrCommand = checkPrCommand;
         this.reviewUpsertPrCommand = reviewUpsertPrCommand;
         this.reapWorktreeCommand = reapWorktreeCommand;
+        this.pushDevCommand = pushDevCommand;
+        this.finishPushDevCommand = finishPushDevCommand;
+        this.pushDevStateStore = pushDevStateStore;
+        this.repoRootFinder = repoRootFinder;
+    }
+    /**
+     * Refuse `command` while a `wp-push-dev --resolve` is half-finished.
+     *
+     * Enforced HERE, at the one place every bin funnels through, rather than in each command: a resolve
+     * parks the checkout on a throwaway branch, so every command below would act on a branch that is not
+     * the one it thinks it is. Putting the check in nine constructors is nine chances to forget it in the
+     * tenth. PushDevStateStore owns the blocked list AND renders the hint from it, so the two cannot drift.
+     */
+    assertNoResolveInProgress(command) {
+        if (!this.pushDevStateStore.isBlockedDuringResolve(command))
+            return;
+        this.pushDevStateStore.assertIdle(this.repoRootFinder.resolveRepoRoot(process.cwd()), command);
+    }
+    /** `wp-push-dev`: publish a DISPOSABLE copy of this branch for the shared dev environment. No PR, no build. */
+    pushDev(opts = new push_dev_command_1.PushDevOptions()) {
+        return this.pushDevCommand.run(opts);
+    }
+    /** `wp-finish-push-dev`: commit a resolved dev composition and publish it (conflict path only). */
+    finishPushDev(opts = new finish_push_dev_command_1.FinishPushDevOptions()) {
+        return this.finishPushDevCommand.run(opts);
     }
     /**
      * INTERNAL (`wp-reap-worktree.js`, no `bin` entry): remove ONE named worktree and its branch.
@@ -50,26 +83,32 @@ let PrGateApp = class PrGateApp {
     }
     /** `wp-start-update`: 3-point squash-update from main (no PR). */
     startUpdate() {
+        this.assertNoResolveInProgress('wp-start-update');
         return this.startUpdateCommand.run();
     }
     /** `wp-finish-update`: validate + finalize a resolved 3-point merge (no PR). */
     finishUpdate() {
+        this.assertNoResolveInProgress('wp-finish-update');
         return this.finishUpdateCommand.run();
     }
     /** `wp-start-upsert-pr`: update from main (3-point merge), hand off review.json. No build gate, no push. */
     startUpsertPr() {
+        this.assertNoResolveInProgress('wp-start-upsert-pr');
         return this.startUpsertPrCommand.run();
     }
     /** `wp-finish-upsert-pr`: finalize merge, authoritative build gate, dashboard, create/update PR. */
     finishUpsertPr() {
+        this.assertNoResolveInProgress('wp-finish-upsert-pr');
         return this.finishUpsertPrCommand.run();
     }
     /** `wp-cleanup`: reap what is provably merged, and ASK about everything that merely looks dead. */
     cleanup() {
+        this.assertNoResolveInProgress('wp-cleanup');
         return this.cleanupCommand.run();
     }
     /** `wp-land-pr`: squash-merge this branch's PR into main with the compact commit body. */
     landPr() {
+        this.assertNoResolveInProgress('wp-land-pr');
         return this.landPrCommand.run();
     }
     /**
@@ -78,6 +117,7 @@ let PrGateApp = class PrGateApp {
      * fail — before any reviewer is spawned, so a broken branch costs no reviewer tokens.
      */
     reviewUpsertPr(opts = new review_upsert_pr_command_1.ReviewUpsertPrOptions()) {
+        this.assertNoResolveInProgress('wp-review-upsert-pr');
         return this.reviewUpsertPrCommand.run(opts);
     }
     /** `wp-check-pr`: READ-ONLY CI check — verify the PR body carries a valid HMAC gate token for its head sha. */
@@ -97,6 +137,10 @@ exports.PrGateApp = PrGateApp = tslib_1.__decorate([
         land_pr_command_1.LandPrCommand,
         check_pr_command_1.CheckPrCommand,
         review_upsert_pr_command_1.ReviewUpsertPrCommand,
-        reap_worktree_command_1.ReapWorktreeCommand])
+        reap_worktree_command_1.ReapWorktreeCommand,
+        push_dev_command_1.PushDevCommand,
+        finish_push_dev_command_1.FinishPushDevCommand,
+        push_dev_state_1.PushDevStateStore,
+        rules_config_2.RepoRootFinder])
 ], PrGateApp);
 //# sourceMappingURL=pr-gate-app.js.map

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":";;;;AAAA,0DAAyD;AACzD,yCAA2D;AAC3D,0EAAqE;AACrE,4EAAuE;AACvE,gFAA0E;AAC1E,kFAA4E;AAC5E,gEAA4D;AAC5D,gEAA2D;AAC3D,kEAA6D;AAC7D,kFAAmG;AACnG,4EAAuE;AAEvE;;;;;GAKG;AAGI,IAAM,SAAS,GAAf,MAAM,SAAS;IAEG;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IATrB,YACqB,kBAAsC,EACtC,mBAAwC,EACxC,oBAA0C,EAC1C,qBAA4C,EAC5C,cAA8B,EAC9B,aAA4B,EAC5B,cAA8B,EAC9B,qBAA4C,EAC5C,mBAAwC;QARxC,uBAAkB,GAAlB,kBAAkB,CAAoB;QACtC,wBAAmB,GAAnB,mBAAmB,CAAqB;QACxC,yBAAoB,GAApB,oBAAoB,CAAsB;QAC1C,0BAAqB,GAArB,qBAAqB,CAAuB;QAC5C,mBAAc,GAAd,cAAc,CAAgB;QAC9B,kBAAa,GAAb,aAAa,CAAe;QAC5B,mBAAc,GAAd,cAAc,CAAgB;QAC9B,0BAAqB,GAArB,qBAAqB,CAAuB;QAC5C,wBAAmB,GAAnB,mBAAmB,CAAqB;IAC1D,CAAC;IAEJ;;;;OAIG;IACH,YAAY,CAAC,IAAc;QACvB,OAAO,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9C,CAAC;IAED,kEAAkE;IAClE,WAAW;QACP,OAAO,IAAI,CAAC,kBAAkB,CAAC,GAAG,EAAE,CAAC;IACzC,CAAC;IAED,gFAAgF;IAChF,YAAY;QACR,OAAO,IAAI,CAAC,mBAAmB,CAAC,GAAG,EAAE,CAAC;IAC1C,CAAC;IAED,4GAA4G;IAC5G,aAAa;QACT,OAAO,IAAI,CAAC,oBAAoB,CAAC,GAAG,EAAE,CAAC;IAC3C,CAAC;IAED,oGAAoG;IACpG,cAAc;QACV,OAAO,IAAI,CAAC,qBAAqB,CAAC,GAAG,EAAE,CAAC;IAC5C,CAAC;IAED,mGAAmG;IACnG,OAAO;QACH,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,EAAE,CAAC;IACrC,CAAC;IAED,0FAA0F;IAC1F,MAAM;QACF,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,CAAC;IACpC,CAAC;IAED;;;;OAIG;IACH,cAAc,CAAC,OAA8B,IAAI,gDAAqB,EAAE;QACpE,OAAO,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChD,CAAC;IAED,+GAA+G;IAC/G,OAAO;QACH,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,EAAE,CAAC;IACrC,CAAC;CACJ,CAAA;AAjEY,8BAAS;oBAAT,SAAS;IAFrB,IAAA,6BAAc,GAAE;IAChB,IAAA,sBAAU,EAAC,8BAAkB,CAAC,SAAS,CAAC;6CAGI,yCAAkB;QACjB,2CAAmB;QAClB,8CAAoB;QACnB,gDAAqB;QAC5B,gCAAc;QACf,+BAAa;QACZ,iCAAc;QACP,gDAAqB;QACvB,2CAAmB;GAVpD,SAAS,CAiErB","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';\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    ) {}\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        return this.startUpdateCommand.run();\n    }\n\n    /** `wp-finish-update`: validate + finalize a resolved 3-point merge (no PR). */\n    finishUpdate(): Promise<void> {\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        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        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        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        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        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 { 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"]}

package/src/scripts/workflow/dev-deploy-refs.d.ts

@@ -0,0 +1,74 @@
+import { DevDeployConfig } from '@webpieces/rules-config';
+import { GitExec } from './git-exec';
+/**
+ * One live copy in the dev namespace: the remote ref and the sha it points at. Data-only per CLAUDE.md —
+ * `--list` prints it and the clobber guard compares against `sha`, and neither should be re-parsing
+ * `ls-remote` output.
+ */
+export declare class DevCopy {
+    /** The full ref name WITHOUT `refs/heads/`, e.g. `dev-include/dean/ONE-2275`. */
+    ref: string;
+    sha: string;
+    /** The feature branch this is a copy OF — `ref` with the namespace prefix stripped. */
+    sourceBranch: string;
+    constructor(ref: string, sha: string, sourceBranch: string);
+}
+/**
+ * Ref derivation and preconditions for the dev-deploy flow — the half of `wp-push-dev` that decides WHICH
+ * refs are in play, kept out of the commands so both `wp-push-dev` and `wp-finish-push-dev` answer those
+ * questions identically.
+ *
+ * THE INVARIANT THIS FILE EXISTS TO PROTECT: the feature branch is the PR head, so it must never acquire
+ * another developer's commits — landing that PR would ship their unreviewed work to production. Every
+ * write this flow performs therefore targets either the `<namespace>/<feature>` copy or a local throwaway
+ * branch, and NOTHING here ever moves `<feature>` itself. That is why a conflict resolution needs the copy
+ * to live in: it is the only place the resolution can be recorded without contaminating the PR.
+ */
+export declare class DevDeployRefs {
+    private readonly gitExec;
+    constructor(gitExec: GitExec);
+    /** The `pr-gate.devDeploy` block — `dev-include` / `dev` unless the consumer overrode it. */
+    config(repoRoot: string): DevDeployConfig;
+    /** The checked-out branch name, or `'HEAD'` on a detached HEAD (which {@link assertPushable} refuses). */
+    currentBranch(repoRoot: string): string;
+    /**
+     * Refuse every branch that must never be the SOURCE of a dev copy, before anything is fetched or
+     * pushed.
+     *
+     * `main` and the composed dev branch are refused for the same reason from opposite ends: `main` is the
+     * trunk (whatever is on it already deploys, so copying it is meaningless), and the dev branch is a
+     * BUILD ARTIFACT that CI recomputes from `origin/main` on every run — copying it would publish a
+     * composition of everyone's work under one developer's name, and it would be wiped on the next CI run
+     * anyway. A branch already inside the namespace is refused because publishing a copy of a copy nests
+     * the prefix (`dev-include/dev-include/…`) and nothing would ever clean it up.
+     */
+    assertPushable(cfg: DevDeployConfig, branch: string): void;
+    /**
+     * Every live copy in the namespace, sorted by ref name.
+     *
+     * The sort is not cosmetic: `--resolve` with no argument queues these in exactly this order, and the
+     * consumer's CI composes `dev` in the same order, so what a developer resolves locally is the
+     * composition CI will actually build. A different order can produce a different (still valid) merge
+     * result, which would make the local resolution a guess about CI rather than a rehearsal of it.
+     */
+    liveCopies(repoRoot: string, cfg: DevDeployConfig): DevCopy[];
+    /**
+     * The sha of a local ref (default HEAD).
+     *
+     * Read AFTER a push so the watch hints quote the sha that is provably published. Quoting the copy
+     * REF instead would be a moving target — it advances the next time anybody publishes — and the whole
+     * value of the "did my code land in dev" check is that it is a claim about one specific commit.
+     */
+    headSha(repoRoot: string, ref?: string): string;
+    /** The remote sha of one copy, or '' when that copy does not exist yet. */
+    remoteSha(repoRoot: string, ref: string): string;
+    /**
+     * Fetch the named copy refs into `refs/remotes/origin/<ref>` so the local merges below run against
+     * fresh state. A no-op for an empty list, and a hard failure otherwise: a resolve queued against
+     * stale refs rehearses a composition CI will not build.
+     */
+    fetchCopies(repoRoot: string, refs: string[]): void;
+    /** How many commits `origin/<ref>` has that `HEAD` does not — the clobber signal. 0 = safe to publish. */
+    commitsOnlyOnRemote(repoRoot: string, ref: string): number;
+    private refusal;
+}

package/src/scripts/workflow/dev-deploy-refs.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DevDeployRefs = exports.DevCopy = void 0;
+const tslib_1 = require("tslib");
+const rules_config_1 = require("@webpieces/rules-config");
+const inversify_1 = require("inversify");
+const git_exec_1 = require("./git-exec");
+const SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n';
+const MAIN = 'main';
+const DETACHED = 'HEAD';
+/**
+ * One live copy in the dev namespace: the remote ref and the sha it points at. Data-only per CLAUDE.md —
+ * `--list` prints it and the clobber guard compares against `sha`, and neither should be re-parsing
+ * `ls-remote` output.
+ */
+class DevCopy {
+    /** The full ref name WITHOUT `refs/heads/`, e.g. `dev-include/dean/ONE-2275`. */
+    ref;
+    sha;
+    /** The feature branch this is a copy OF — `ref` with the namespace prefix stripped. */
+    sourceBranch;
+    constructor(ref, sha, sourceBranch) {
+        this.ref = ref;
+        this.sha = sha;
+        this.sourceBranch = sourceBranch;
+    }
+}
+exports.DevCopy = DevCopy;
+/**
+ * Ref derivation and preconditions for the dev-deploy flow — the half of `wp-push-dev` that decides WHICH
+ * refs are in play, kept out of the commands so both `wp-push-dev` and `wp-finish-push-dev` answer those
+ * questions identically.
+ *
+ * THE INVARIANT THIS FILE EXISTS TO PROTECT: the feature branch is the PR head, so it must never acquire
+ * another developer's commits — landing that PR would ship their unreviewed work to production. Every
+ * write this flow performs therefore targets either the `<namespace>/<feature>` copy or a local throwaway
+ * branch, and NOTHING here ever moves `<feature>` itself. That is why a conflict resolution needs the copy
+ * to live in: it is the only place the resolution can be recorded without contaminating the PR.
+ */
+let DevDeployRefs = class DevDeployRefs {
+    gitExec;
+    constructor(gitExec) {
+        this.gitExec = gitExec;
+    }
+    /** The `pr-gate.devDeploy` block — `dev-include` / `dev` unless the consumer overrode it. */
+    config(repoRoot) {
+        return (0, rules_config_1.loadAndValidate)(repoRoot).prGate.devDeploy;
+    }
+    /** The checked-out branch name, or `'HEAD'` on a detached HEAD (which {@link assertPushable} refuses). */
+    currentBranch(repoRoot) {
+        return this.gitExec.gitQuery(['rev-parse', '--abbrev-ref', 'HEAD'], repoRoot, 'Failed to read the current branch (git rev-parse --abbrev-ref HEAD).');
+    }
+    /**
+     * Refuse every branch that must never be the SOURCE of a dev copy, before anything is fetched or
+     * pushed.
+     *
+     * `main` and the composed dev branch are refused for the same reason from opposite ends: `main` is the
+     * trunk (whatever is on it already deploys, so copying it is meaningless), and the dev branch is a
+     * BUILD ARTIFACT that CI recomputes from `origin/main` on every run — copying it would publish a
+     * composition of everyone's work under one developer's name, and it would be wiped on the next CI run
+     * anyway. A branch already inside the namespace is refused because publishing a copy of a copy nests
+     * the prefix (`dev-include/dev-include/…`) and nothing would ever clean it up.
+     */
+    assertPushable(cfg, branch) {
+        if (branch === DETACHED || branch === '') {
+            throw new rules_config_1.CliExitError(2, this.refusal('Detached HEAD', 'There is no branch name to derive the dev copy from. Check out your feature branch first:\n'
+                + '  git checkout <your-feature-branch>\n'));
+        }
+        if (branch === MAIN) {
+            throw new rules_config_1.CliExitError(2, this.refusal(`Refusing to publish a dev copy of \`${MAIN}\``, `\`${MAIN}\` is the trunk — whatever is on it already deploys, so a dev copy of it means nothing.\n`
+                + 'Check out the feature branch you actually want on the dev server and re-run.\n'));
+        }
+        if (branch === cfg.devBranch) {
+            throw new rules_config_1.CliExitError(2, this.refusal(`Refusing to publish a dev copy of \`${cfg.devBranch}\``, `\`${cfg.devBranch}\` is a BUILD ARTIFACT, not a source branch: your CI resets it to origin/${MAIN},\n`
+                + `merges every \`${cfg.copyRefGlob()}\` ref into it, and force-pushes — every run. Copying it would\n`
+                + "publish a composition of everybody's work under your branch's name, and the next CI run would\n"
+                + 'wipe it. Check out your own feature branch and re-run.\n'));
+        }
+        if (branch === cfg.branchNamespace || branch.startsWith(`${cfg.branchNamespace}/`)) {
+            throw new rules_config_1.CliExitError(2, this.refusal(`Refusing to publish a dev copy of a dev copy (\`${branch}\`)`, `\`${cfg.branchNamespace}/\` holds the disposable copies this command WRITES; you are standing on one.\n`
+                + `Publishing from here would nest the prefix (\`${cfg.branchNamespace}/${branch}\`) and nothing ever\n`
+                + 'cleans that up. Check out the real feature branch and re-run.\n'));
+        }
+    }
+    /**
+     * Every live copy in the namespace, sorted by ref name.
+     *
+     * The sort is not cosmetic: `--resolve` with no argument queues these in exactly this order, and the
+     * consumer's CI composes `dev` in the same order, so what a developer resolves locally is the
+     * composition CI will actually build. A different order can produce a different (still valid) merge
+     * result, which would make the local resolution a guess about CI rather than a rehearsal of it.
+     */
+    liveCopies(repoRoot, cfg) {
+        const out = this.gitExec.gitQuery(['ls-remote', '--heads', 'origin', cfg.copyRefGlob()], repoRoot, `Failed to list the dev copies (git ls-remote --heads origin '${cfg.copyRefGlob()}').`);
+        const copies = [];
+        for (const line of out.split('\n')) {
+            if (line.trim() === '')
+                continue;
+            const fields = line.split(/\s+/);
+            const sha = fields[0];
+            const ref = fields[1];
+            if (sha === undefined || ref === undefined || !ref.startsWith('refs/heads/'))
+                continue;
+            const shortRef = ref.slice('refs/heads/'.length);
+            copies.push(new DevCopy(shortRef, sha, shortRef.slice(cfg.branchNamespace.length + 1)));
+        }
+        return copies.sort((a, b) => (a.ref < b.ref ? -1 : a.ref > b.ref ? 1 : 0));
+    }
+    /**
+     * The sha of a local ref (default HEAD).
+     *
+     * Read AFTER a push so the watch hints quote the sha that is provably published. Quoting the copy
+     * REF instead would be a moving target — it advances the next time anybody publishes — and the whole
+     * value of the "did my code land in dev" check is that it is a claim about one specific commit.
+     */
+    headSha(repoRoot, ref = 'HEAD') {
+        return this.gitExec.gitQuery(['-C', repoRoot, 'rev-parse', ref], repoRoot, `Failed to read the sha of ${ref} (git rev-parse).`);
+    }
+    /** The remote sha of one copy, or '' when that copy does not exist yet. */
+    remoteSha(repoRoot, ref) {
+        const out = this.gitExec.gitQuery(['ls-remote', '--heads', 'origin', ref], repoRoot, `Failed to look up origin/${ref} (git ls-remote).`);
+        const line = out.split('\n').find((l) => l.trim() !== '');
+        if (line === undefined)
+            return '';
+        return line.split(/\s+/)[0] ?? '';
+    }
+    /**
+     * Fetch the named copy refs into `refs/remotes/origin/<ref>` so the local merges below run against
+     * fresh state. A no-op for an empty list, and a hard failure otherwise: a resolve queued against
+     * stale refs rehearses a composition CI will not build.
+     */
+    fetchCopies(repoRoot, refs) {
+        if (refs.length === 0)
+            return;
+        const specs = refs.map((r) => `+refs/heads/${r}:refs/remotes/origin/${r}`);
+        this.gitExec.runGitChecked(['-C', repoRoot, 'fetch', 'origin', ...specs], 'Failed to fetch the dev copy refs from origin');
+    }
+    /** How many commits `origin/<ref>` has that `HEAD` does not — the clobber signal. 0 = safe to publish. */
+    commitsOnlyOnRemote(repoRoot, ref) {
+        const out = this.gitExec.gitQuery(['rev-list', '--count', `HEAD..refs/remotes/origin/${ref}`], repoRoot, `Failed to compare HEAD against origin/${ref} (git rev-list --count).`);
+        const count = Number(out);
+        return Number.isInteger(count) ? count : 0;
+    }
+    refusal(headline, body) {
+        return '\n' + SEP + `⛔ ${headline}\n` + SEP + '\n' + body + `\nRun \`${rules_config_1.WP_PUSH_DEV} --help\` for the full command.\n`;
+    }
+};
+exports.DevDeployRefs = DevDeployRefs;
+exports.DevDeployRefs = DevDeployRefs = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton),
+    tslib_1.__metadata("design:paramtypes", [git_exec_1.GitExec])
+], DevDeployRefs);
+//# sourceMappingURL=dev-deploy-refs.js.map

package/src/scripts/workflow/dev-deploy-refs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-deploy-refs.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/dev-deploy-refs.ts"],"names":[],"mappings":"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","sourcesContent":["import { CliExitError, DevDeployConfig, loadAndValidate, WP_PUSH_DEV } from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\n\nimport { GitExec } from './git-exec';\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\nconst MAIN = 'main';\nconst DETACHED = 'HEAD';\n\n/**\n * One live copy in the dev namespace: the remote ref and the sha it points at. Data-only per CLAUDE.md —\n * `--list` prints it and the clobber guard compares against `sha`, and neither should be re-parsing\n * `ls-remote` output.\n */\nexport class DevCopy {\n    /** The full ref name WITHOUT `refs/heads/`, e.g. `dev-include/dean/ONE-2275`. */\n    ref: string;\n    sha: string;\n    /** The feature branch this is a copy OF — `ref` with the namespace prefix stripped. */\n    sourceBranch: string;\n\n    constructor(ref: string, sha: string, sourceBranch: string) {\n        this.ref = ref;\n        this.sha = sha;\n        this.sourceBranch = sourceBranch;\n    }\n}\n\n/**\n * Ref derivation and preconditions for the dev-deploy flow — the half of `wp-push-dev` that decides WHICH\n * refs are in play, kept out of the commands so both `wp-push-dev` and `wp-finish-push-dev` answer those\n * questions identically.\n *\n * THE INVARIANT THIS FILE EXISTS TO PROTECT: the feature branch is the PR head, so it must never acquire\n * another developer's commits — landing that PR would ship their unreviewed work to production. Every\n * write this flow performs therefore targets either the `<namespace>/<feature>` copy or a local throwaway\n * branch, and NOTHING here ever moves `<feature>` itself. That is why a conflict resolution needs the copy\n * to live in: it is the only place the resolution can be recorded without contaminating the PR.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class DevDeployRefs {\n    constructor(private readonly gitExec: GitExec) {}\n\n    /** The `pr-gate.devDeploy` block — `dev-include` / `dev` unless the consumer overrode it. */\n    config(repoRoot: string): DevDeployConfig {\n        return loadAndValidate(repoRoot).prGate.devDeploy;\n    }\n\n    /** The checked-out branch name, or `'HEAD'` on a detached HEAD (which {@link assertPushable} refuses). */\n    currentBranch(repoRoot: string): string {\n        return this.gitExec.gitQuery(['rev-parse', '--abbrev-ref', 'HEAD'], repoRoot,\n            'Failed to read the current branch (git rev-parse --abbrev-ref HEAD).');\n    }\n\n    /**\n     * Refuse every branch that must never be the SOURCE of a dev copy, before anything is fetched or\n     * pushed.\n     *\n     * `main` and the composed dev branch are refused for the same reason from opposite ends: `main` is the\n     * trunk (whatever is on it already deploys, so copying it is meaningless), and the dev branch is a\n     * BUILD ARTIFACT that CI recomputes from `origin/main` on every run — copying it would publish a\n     * composition of everyone's work under one developer's name, and it would be wiped on the next CI run\n     * anyway. A branch already inside the namespace is refused because publishing a copy of a copy nests\n     * the prefix (`dev-include/dev-include/…`) and nothing would ever clean it up.\n     */\n    assertPushable(cfg: DevDeployConfig, branch: string): void {\n        if (branch === DETACHED || branch === '') {\n            throw new CliExitError(2, this.refusal(\n                'Detached HEAD',\n                'There is no branch name to derive the dev copy from. Check out your feature branch first:\\n'\n                + '  git checkout <your-feature-branch>\\n'));\n        }\n        if (branch === MAIN) {\n            throw new CliExitError(2, this.refusal(\n                `Refusing to publish a dev copy of \\`${MAIN}\\``,\n                `\\`${MAIN}\\` is the trunk — whatever is on it already deploys, so a dev copy of it means nothing.\\n`\n                + 'Check out the feature branch you actually want on the dev server and re-run.\\n'));\n        }\n        if (branch === cfg.devBranch) {\n            throw new CliExitError(2, this.refusal(\n                `Refusing to publish a dev copy of \\`${cfg.devBranch}\\``,\n                `\\`${cfg.devBranch}\\` is a BUILD ARTIFACT, not a source branch: your CI resets it to origin/${MAIN},\\n`\n                + `merges every \\`${cfg.copyRefGlob()}\\` ref into it, and force-pushes — every run. Copying it would\\n`\n                + \"publish a composition of everybody's work under your branch's name, and the next CI run would\\n\"\n                + 'wipe it. Check out your own feature branch and re-run.\\n'));\n        }\n        if (branch === cfg.branchNamespace || branch.startsWith(`${cfg.branchNamespace}/`)) {\n            throw new CliExitError(2, this.refusal(\n                `Refusing to publish a dev copy of a dev copy (\\`${branch}\\`)`,\n                `\\`${cfg.branchNamespace}/\\` holds the disposable copies this command WRITES; you are standing on one.\\n`\n                + `Publishing from here would nest the prefix (\\`${cfg.branchNamespace}/${branch}\\`) and nothing ever\\n`\n                + 'cleans that up. Check out the real feature branch and re-run.\\n'));\n        }\n    }\n\n    /**\n     * Every live copy in the namespace, sorted by ref name.\n     *\n     * The sort is not cosmetic: `--resolve` with no argument queues these in exactly this order, and the\n     * consumer's CI composes `dev` in the same order, so what a developer resolves locally is the\n     * composition CI will actually build. A different order can produce a different (still valid) merge\n     * result, which would make the local resolution a guess about CI rather than a rehearsal of it.\n     */\n    liveCopies(repoRoot: string, cfg: DevDeployConfig): DevCopy[] {\n        const out = this.gitExec.gitQuery(['ls-remote', '--heads', 'origin', cfg.copyRefGlob()], repoRoot,\n            `Failed to list the dev copies (git ls-remote --heads origin '${cfg.copyRefGlob()}').`);\n        const copies: DevCopy[] = [];\n        for (const line of out.split('\\n')) {\n            if (line.trim() === '') continue;\n            const fields = line.split(/\\s+/);\n            const sha = fields[0];\n            const ref = fields[1];\n            if (sha === undefined || ref === undefined || !ref.startsWith('refs/heads/')) continue;\n            const shortRef = ref.slice('refs/heads/'.length);\n            copies.push(new DevCopy(shortRef, sha, shortRef.slice(cfg.branchNamespace.length + 1)));\n        }\n        return copies.sort((a: DevCopy, b: DevCopy): number => (a.ref < b.ref ? -1 : a.ref > b.ref ? 1 : 0));\n    }\n\n    /**\n     * The sha of a local ref (default HEAD).\n     *\n     * Read AFTER a push so the watch hints quote the sha that is provably published. Quoting the copy\n     * REF instead would be a moving target — it advances the next time anybody publishes — and the whole\n     * value of the \"did my code land in dev\" check is that it is a claim about one specific commit.\n     */\n    headSha(repoRoot: string, ref = 'HEAD'): string {\n        return this.gitExec.gitQuery(['-C', repoRoot, 'rev-parse', ref], repoRoot,\n            `Failed to read the sha of ${ref} (git rev-parse).`);\n    }\n\n    /** The remote sha of one copy, or '' when that copy does not exist yet. */\n    remoteSha(repoRoot: string, ref: string): string {\n        const out = this.gitExec.gitQuery(['ls-remote', '--heads', 'origin', ref], repoRoot,\n            `Failed to look up origin/${ref} (git ls-remote).`);\n        const line = out.split('\\n').find((l: string): boolean => l.trim() !== '');\n        if (line === undefined) return '';\n        return line.split(/\\s+/)[0] ?? '';\n    }\n\n    /**\n     * Fetch the named copy refs into `refs/remotes/origin/<ref>` so the local merges below run against\n     * fresh state. A no-op for an empty list, and a hard failure otherwise: a resolve queued against\n     * stale refs rehearses a composition CI will not build.\n     */\n    fetchCopies(repoRoot: string, refs: string[]): void {\n        if (refs.length === 0) return;\n        const specs = refs.map((r: string): string => `+refs/heads/${r}:refs/remotes/origin/${r}`);\n        this.gitExec.runGitChecked(['-C', repoRoot, 'fetch', 'origin', ...specs],\n            'Failed to fetch the dev copy refs from origin');\n    }\n\n    /** How many commits `origin/<ref>` has that `HEAD` does not — the clobber signal. 0 = safe to publish. */\n    commitsOnlyOnRemote(repoRoot: string, ref: string): number {\n        const out = this.gitExec.gitQuery(['rev-list', '--count', `HEAD..refs/remotes/origin/${ref}`], repoRoot,\n            `Failed to compare HEAD against origin/${ref} (git rev-list --count).`);\n        const count = Number(out);\n        return Number.isInteger(count) ? count : 0;\n    }\n\n    private refusal(headline: string, body: string): string {\n        return '\\n' + SEP + `⛔ ${headline}\\n` + SEP + '\\n' + body + `\\nRun \\`${WP_PUSH_DEV} --help\\` for the full command.\\n`;\n    }\n}\n"]}

package/src/scripts/workflow/dev-deploy-watch-hints.d.ts

@@ -0,0 +1,35 @@
+import { DevDeployConfig } from '@webpieces/rules-config';
+/**
+ * The "now go watch it deploy" block printed after a copy is published.
+ *
+ * WHY THIS IS TEXT AND NOT A FEATURE: webpieces cannot know the consumer's CD. The composed branch might
+ * be built by GitHub Actions, by Jenkins, by a cron job on a box — so polling for "the run" would mean
+ * either a config key naming their workflow, or a heuristic that is wrong for somebody. Handing the AI
+ * the exact commands costs nothing, degrades gracefully (an empty `gh run list` is itself an answer), and
+ * keeps webpieces out of the business of modelling someone else's pipeline.
+ *
+ * The commands are pre-substituted with the real sha and refs — an AI given a template with blanks to
+ * fill in gets one of them wrong eventually, and a wrong `git merge-base` argument answers the question
+ * confidently and incorrectly.
+ *
+ * All of them are READ-ONLY and none is blocked: `git fetch`/`merge-base` are queries, and
+ * `gh run list|view|watch` is on the guards' allowed list.
+ */
+export declare class DevDeployWatchHints {
+    /**
+     * @param sha the commit that was just published — the ONLY thing that makes step 1 a proof rather
+     *   than a guess, since `<copyRef>` itself moves the next time anyone publishes.
+     */
+    render(cfg: DevDeployConfig, copyRef: string, sha: string): string;
+    /**
+     * Step 1 — pure git, works with ANY CI, and is the only claim provably about YOUR code.
+     *
+     * `<devBranch>` is recomposed from `origin/main` plus every copy on each CI run, so your published
+     * sha is an ancestor of it if and only if the composition included you.
+     */
+    private landedSection;
+    /** Step 2 — GitHub Actions, if that is where this repo's dev deploy lives. Empty output is an answer. */
+    private runSection;
+    /** The trap worth one sentence: a green run on a SHARED branch is not a statement about your code. */
+    private orderingWarning;
+}

package/src/scripts/workflow/dev-deploy-watch-hints.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DevDeployWatchHints = void 0;
+const tslib_1 = require("tslib");
+const inversify_1 = require("inversify");
+const SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n';
+/**
+ * The "now go watch it deploy" block printed after a copy is published.
+ *
+ * WHY THIS IS TEXT AND NOT A FEATURE: webpieces cannot know the consumer's CD. The composed branch might
+ * be built by GitHub Actions, by Jenkins, by a cron job on a box — so polling for "the run" would mean
+ * either a config key naming their workflow, or a heuristic that is wrong for somebody. Handing the AI
+ * the exact commands costs nothing, degrades gracefully (an empty `gh run list` is itself an answer), and
+ * keeps webpieces out of the business of modelling someone else's pipeline.
+ *
+ * The commands are pre-substituted with the real sha and refs — an AI given a template with blanks to
+ * fill in gets one of them wrong eventually, and a wrong `git merge-base` argument answers the question
+ * confidently and incorrectly.
+ *
+ * All of them are READ-ONLY and none is blocked: `git fetch`/`merge-base` are queries, and
+ * `gh run list|view|watch` is on the guards' allowed list.
+ */
+let DevDeployWatchHints = class DevDeployWatchHints {
+    /**
+     * @param sha the commit that was just published — the ONLY thing that makes step 1 a proof rather
+     *   than a guess, since `<copyRef>` itself moves the next time anyone publishes.
+     */
+    render(cfg, copyRef, sha) {
+        return '\n' + SEP + '👀 Is it on the dev server yet? — two questions, in this order\n' + SEP + '\n'
+            + this.landedSection(cfg, sha)
+            + '\n'
+            + this.runSection(cfg, copyRef)
+            + '\n'
+            + this.orderingWarning(cfg);
+    }
+    /**
+     * Step 1 — pure git, works with ANY CI, and is the only claim provably about YOUR code.
+     *
+     * `<devBranch>` is recomposed from `origin/main` plus every copy on each CI run, so your published
+     * sha is an ancestor of it if and only if the composition included you.
+     */
+    landedSection(cfg, sha) {
+        return `1. Did YOUR code land in \`${cfg.devBranch}\`?  (pure git — works whatever your CI is)\n`
+            + `     git fetch origin ${cfg.devBranch}\n`
+            + `     git merge-base --is-ancestor ${sha} origin/${cfg.devBranch} && echo IN || echo "not yet"\n`
+            + `   \`${cfg.devBranch}\` is rebuilt from origin/main + every \`${cfg.copyRefGlob()}\` ref on each run, so\n`
+            + '   ancestry IS inclusion. Re-run after the next composition if it says "not yet".\n';
+    }
+    /** Step 2 — GitHub Actions, if that is where this repo's dev deploy lives. Empty output is an answer. */
+    runSection(cfg, copyRef) {
+        const rows = [
+            [`gh run list --branch ${copyRef} --limit 5`, 'the run your push triggered, if any'],
+            [`gh run list --branch ${cfg.devBranch} --limit 5`, 'the composition / deploy run'],
+            ['gh run watch <run-id>', 'follow one to completion'],
+            ['gh run view <run-id> --log-failed', 'read why it failed'],
+        ];
+        // Aligned off the longest command, because the ref names are consumer-configurable and any
+        // hand-counted padding would go crooked the moment somebody renames the namespace.
+        const width = Math.max(...rows.map((row) => row[0].length));
+        return '2. Is the CI/CD run finished?  (GitHub Actions — all read-only, none of it is blocked)\n'
+            + rows.map((row) => `     ${row[0].padEnd(width)}   ← ${row[1]}\n`).join('')
+            + '   Empty output is not a bug: it means this repo deploys from somewhere other than Actions.\n'
+            + '   Ask the human where the dev deploy runs, and do not guess.\n';
+    }
+    /** The trap worth one sentence: a green run on a SHARED branch is not a statement about your code. */
+    orderingWarning(cfg) {
+        return `A green run on \`${cfg.devBranch}\` is NOT proof your change deployed — that branch carries everyone's\n`
+            + 'copies, and the composition may have excluded yours. Question 1 is the one that answers for YOUR\n'
+            + 'code; question 2 only tells you whether the machinery finished.\n';
+    }
+};
+exports.DevDeployWatchHints = DevDeployWatchHints;
+exports.DevDeployWatchHints = DevDeployWatchHints = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton)
+], DevDeployWatchHints);
+//# sourceMappingURL=dev-deploy-watch-hints.js.map

package/src/scripts/workflow/dev-deploy-watch-hints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-deploy-watch-hints.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/dev-deploy-watch-hints.ts"],"names":[],"mappings":";;;;AACA,yCAA2D;AAE3D,MAAM,GAAG,GAAG,0DAA0D,CAAC;AAEvE;;;;;;;;;;;;;;;GAeG;AAEI,IAAM,mBAAmB,GAAzB,MAAM,mBAAmB;IAC5B;;;OAGG;IACH,MAAM,CAAC,GAAoB,EAAE,OAAe,EAAE,GAAW;QACrD,OAAO,IAAI,GAAG,GAAG,GAAG,kEAAkE,GAAG,GAAG,GAAG,IAAI;cAC7F,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC;cAC5B,IAAI;cACJ,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC;cAC7B,IAAI;cACJ,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;IAED;;;;;OAKG;IACK,aAAa,CAAC,GAAoB,EAAE,GAAW;QACnD,OAAO,8BAA8B,GAAG,CAAC,SAAS,+CAA+C;cAC3F,yBAAyB,GAAG,CAAC,SAAS,IAAI;cAC1C,qCAAqC,GAAG,WAAW,GAAG,CAAC,SAAS,iCAAiC;cACjG,QAAQ,GAAG,CAAC,SAAS,4CAA4C,GAAG,CAAC,WAAW,EAAE,0BAA0B;cAC5G,qFAAqF,CAAC;IAChG,CAAC;IAED,yGAAyG;IACjG,UAAU,CAAC,GAAoB,EAAE,OAAe;QACpD,MAAM,IAAI,GAAG;YACT,CAAC,wBAAwB,OAAO,YAAY,EAAE,qCAAqC,CAAC;YACpF,CAAC,wBAAwB,GAAG,CAAC,SAAS,YAAY,EAAE,8BAA8B,CAAC;YACnF,CAAC,uBAAuB,EAAE,0BAA0B,CAAC;YACrD,CAAC,mCAAmC,EAAE,oBAAoB,CAAC;SAC9D,CAAC;QACF,2FAA2F;QAC3F,mFAAmF;QACnF,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAa,EAAU,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;QAC9E,OAAO,0FAA0F;cAC3F,IAAI,CAAC,GAAG,CAAC,CAAC,GAAa,EAAU,EAAE,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;cAC5F,+FAA+F;cAC/F,iEAAiE,CAAC;IAC5E,CAAC;IAED,sGAAsG;IAC9F,eAAe,CAAC,GAAoB;QACxC,OAAO,oBAAoB,GAAG,CAAC,SAAS,yEAAyE;cAC3G,oGAAoG;cACpG,mEAAmE,CAAC;IAC9E,CAAC;CACJ,CAAA;AAnDY,kDAAmB;8BAAnB,mBAAmB;IAD/B,IAAA,sBAAU,EAAC,8BAAkB,CAAC,SAAS,CAAC;GAC5B,mBAAmB,CAmD/B","sourcesContent":["import { DevDeployConfig } from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\n/**\n * The \"now go watch it deploy\" block printed after a copy is published.\n *\n * WHY THIS IS TEXT AND NOT A FEATURE: webpieces cannot know the consumer's CD. The composed branch might\n * be built by GitHub Actions, by Jenkins, by a cron job on a box — so polling for \"the run\" would mean\n * either a config key naming their workflow, or a heuristic that is wrong for somebody. Handing the AI\n * the exact commands costs nothing, degrades gracefully (an empty `gh run list` is itself an answer), and\n * keeps webpieces out of the business of modelling someone else's pipeline.\n *\n * The commands are pre-substituted with the real sha and refs — an AI given a template with blanks to\n * fill in gets one of them wrong eventually, and a wrong `git merge-base` argument answers the question\n * confidently and incorrectly.\n *\n * All of them are READ-ONLY and none is blocked: `git fetch`/`merge-base` are queries, and\n * `gh run list|view|watch` is on the guards' allowed list.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class DevDeployWatchHints {\n    /**\n     * @param sha the commit that was just published — the ONLY thing that makes step 1 a proof rather\n     *   than a guess, since `<copyRef>` itself moves the next time anyone publishes.\n     */\n    render(cfg: DevDeployConfig, copyRef: string, sha: string): string {\n        return '\\n' + SEP + '👀 Is it on the dev server yet? — two questions, in this order\\n' + SEP + '\\n'\n            + this.landedSection(cfg, sha)\n            + '\\n'\n            + this.runSection(cfg, copyRef)\n            + '\\n'\n            + this.orderingWarning(cfg);\n    }\n\n    /**\n     * Step 1 — pure git, works with ANY CI, and is the only claim provably about YOUR code.\n     *\n     * `<devBranch>` is recomposed from `origin/main` plus every copy on each CI run, so your published\n     * sha is an ancestor of it if and only if the composition included you.\n     */\n    private landedSection(cfg: DevDeployConfig, sha: string): string {\n        return `1. Did YOUR code land in \\`${cfg.devBranch}\\`?  (pure git — works whatever your CI is)\\n`\n            + `     git fetch origin ${cfg.devBranch}\\n`\n            + `     git merge-base --is-ancestor ${sha} origin/${cfg.devBranch} && echo IN || echo \"not yet\"\\n`\n            + `   \\`${cfg.devBranch}\\` is rebuilt from origin/main + every \\`${cfg.copyRefGlob()}\\` ref on each run, so\\n`\n            + '   ancestry IS inclusion. Re-run after the next composition if it says \"not yet\".\\n';\n    }\n\n    /** Step 2 — GitHub Actions, if that is where this repo's dev deploy lives. Empty output is an answer. */\n    private runSection(cfg: DevDeployConfig, copyRef: string): string {\n        const rows = [\n            [`gh run list --branch ${copyRef} --limit 5`, 'the run your push triggered, if any'],\n            [`gh run list --branch ${cfg.devBranch} --limit 5`, 'the composition / deploy run'],\n            ['gh run watch <run-id>', 'follow one to completion'],\n            ['gh run view <run-id> --log-failed', 'read why it failed'],\n        ];\n        // Aligned off the longest command, because the ref names are consumer-configurable and any\n        // hand-counted padding would go crooked the moment somebody renames the namespace.\n        const width = Math.max(...rows.map((row: string[]): number => row[0].length));\n        return '2. Is the CI/CD run finished?  (GitHub Actions — all read-only, none of it is blocked)\\n'\n            + rows.map((row: string[]): string => `     ${row[0].padEnd(width)}   ← ${row[1]}\\n`).join('')\n            + '   Empty output is not a bug: it means this repo deploys from somewhere other than Actions.\\n'\n            + '   Ask the human where the dev deploy runs, and do not guess.\\n';\n    }\n\n    /** The trap worth one sentence: a green run on a SHARED branch is not a statement about your code. */\n    private orderingWarning(cfg: DevDeployConfig): string {\n        return `A green run on \\`${cfg.devBranch}\\` is NOT proof your change deployed — that branch carries everyone's\\n`\n            + 'copies, and the composition may have excluded yours. Question 1 is the one that answers for YOUR\\n'\n            + 'code; question 2 only tells you whether the machinery finished.\\n';\n    }\n}\n"]}

package/src/scripts/workflow/dev-resolve-runner.d.ts

@@ -0,0 +1,74 @@
+import { DevDeployConfig } from '@webpieces/rules-config';
+import { GitExec } from './git-exec';
+import { DevDeployRefs } from './dev-deploy-refs';
+import { PushDevState, PushDevStateStore } from './push-dev-state';
+import { DevDeployWatchHints } from './dev-deploy-watch-hints';
+/**
+ * The queue-draining engine behind `wp-push-dev --resolve` and `wp-finish-push-dev`.
+ *
+ * ONE class owns every git WRITE in the resolve flow, and that is a hard requirement rather than tidiness:
+ * `redirect-how-to-merge-main` blocks `git merge` in every form INCLUDING `--continue`, and
+ * `pr-creation-or-push-guard` blocks every `git push`. So an AI cannot be told "now run `git commit`" or
+ * "`git merge --continue`" — those instructions are unrunnable by the only party reading them. The command
+ * owns the merges, the commit and the push (as child processes the hooks never see); the AI's entire job is
+ * editing the conflicted files and `git add`-ing them, neither of which is blocked.
+ */
+export declare class DevResolveRunner {
+    private readonly gitExec;
+    private readonly refs;
+    private readonly store;
+    private readonly watchHints;
+    constructor(gitExec: GitExec, refs: DevDeployRefs, store: PushDevStateStore, watchHints: DevDeployWatchHints);
+    /**
+     * Start a resolve: park on a throwaway branch at the current copy, then drain the queue.
+     *
+     * The checkout is `-B <tmp> <base>` and NEVER the feature branch, which is the cardinal constraint made
+     * mechanical — every merge below lands on a branch that is deleted at the end, so no other developer's
+     * commits can reach the PR head even if the resolve is abandoned halfway.
+     *
+     * `base` differs between the two callers and the difference IS the semantics. `--resolve` starts at the
+     * published copy and merges the other copies in (compose what CI will build). `--rebase-resolution`
+     * starts at the LOCAL HEAD and merges the published copy in (replay an existing resolution on top of
+     * the new commits, instead of force-pushing over it).
+     *
+     * `fetchRefs` is passed separately from the queue because `--rebase-resolution` merges a ref that is
+     * also its push destination, so "everything to fetch" and "everything to merge" are not the same list.
+     */
+    start(repoRoot: string, state: PushDevState, base: string, fetchRefs: string[]): void;
+    /**
+     * Resume after the human/AI has resolved the halted merge: commit it, then keep draining.
+     *
+     * REFETCHES the remaining queue first. A resolution session can run long, and queuing against refs
+     * fetched an hour ago rehearses a composition CI will not build — the one freshness gap the sibling
+     * update flow is still known to have (only its stage ① ever fetches).
+     */
+    resume(repoRoot: string, state: PushDevState): void;
+    /**
+     * Throw the whole resolve away: undo any halted merge, go back to the original branch, delete the
+     * throwaway branch and the state file. Nothing published, nothing on the feature branch.
+     */
+    abort(repoRoot: string, state: PushDevState): void;
+    /**
+     * Merge queued refs until one conflicts (HALT, hand the tree over) or the queue empties (PUBLISH).
+     *
+     * A LATER ref can conflict too, which is why this is a loop resumed from a state file rather than a
+     * single pass: `wp-finish-push-dev` can legitimately stop again on the next ref in the queue.
+     */
+    private drain;
+    /** Stop with the conflicted files listed and the ONE command that continues. Exit 2 = "your turn". */
+    private halt;
+    /** Queue empty: force-push the composed result over the copy, then restore the original checkout. */
+    private publish;
+    /** Conflicted (unmerged-in-index) paths. Empty once every one has been resolved and `git add`ed. */
+    private unmergedPaths;
+    private assertNoUnmergedPaths;
+    /**
+     * The name of the throwaway branch for a resolve of `branch`.
+     *
+     * Suffixed rather than prefixed, matching the existing `<feature>Squash` / `<feature>PreMerge<n>`
+     * convention — and deliberately NOT inside the dev namespace, which holds REMOTE copies only.
+     */
+    tmpBranchFor(branch: string): string;
+    /** The banner `--resolve` prints before the first merge, so the queue is visible before it halts. */
+    announce(cfg: DevDeployConfig, state: PushDevState): string;
+}