@webpieces/pr-gate 0.4.565 → 0.4.566

package/bin/wp-finish-push-dev.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// Plain JS shim -> delegates to the compiled TypeScript entry point.
+//
+// Must NOT be converted to TypeScript. pnpm chmods every `bin` target while it links a
+// package, and in THIS workspace a `workspace:*` sibling is linked from its SOURCE dir,
+// long before any build has produced `src/scripts/wp-finish-push-dev.js`. Pointing `bin` straight at the
+// compiled path therefore makes every `pnpm install` print
+// `WARN Failed to create bin ... ENOENT ... chmod` — noise indistinguishable from a real
+// bin-link failure. This file exists in git, so the chmod always succeeds.
+//
+// See setupDebugging.md (Attempt 8) and bin-targets-exist.spec.ts, which fails if any
+// `bin` target in the workspace does not exist on disk.
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+const compiled = path.join(__dirname, '..', 'src', 'scripts', 'wp-finish-push-dev.js');
+
+if (!fs.existsSync(compiled)) {
+    console.error(
+        '  [pr-gate] wp-finish-push-dev: package not built yet. Run the build first, or install from npm.',
+    );
+    process.exit(1);
+}
+
+require(compiled);

package/bin/wp-push-dev.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// Plain JS shim -> delegates to the compiled TypeScript entry point.
+//
+// Must NOT be converted to TypeScript. pnpm chmods every `bin` target while it links a
+// package, and in THIS workspace a `workspace:*` sibling is linked from its SOURCE dir,
+// long before any build has produced `src/scripts/wp-push-dev.js`. Pointing `bin` straight at the
+// compiled path therefore makes every `pnpm install` print
+// `WARN Failed to create bin ... ENOENT ... chmod` — noise indistinguishable from a real
+// bin-link failure. This file exists in git, so the chmod always succeeds.
+//
+// See setupDebugging.md (Attempt 8) and bin-targets-exist.spec.ts, which fails if any
+// `bin` target in the workspace does not exist on disk.
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+const compiled = path.join(__dirname, '..', 'src', 'scripts', 'wp-push-dev.js');
+
+if (!fs.existsSync(compiled)) {
+    console.error(
+        '  [pr-gate] wp-push-dev: package not built yet. Run the build first, or install from npm.',
+    );
+    process.exit(1);
+}
+
+require(compiled);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/pr-gate",
-  "version": "0.4.565",
+  "version": "0.4.566",
   "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",
@@ -12,7 +12,9 @@
     "wp-cleanup": "./bin/wp-cleanup.js",
     "wp-land-pr": "./bin/wp-land-pr.js",
     "wp-check-pr": "./bin/wp-check-pr.js",
-    "wp-review-upsert-pr": "./bin/wp-review-upsert-pr.js"
+    "wp-review-upsert-pr": "./bin/wp-review-upsert-pr.js",
+    "wp-push-dev": "./bin/wp-push-dev.js",
+    "wp-finish-push-dev": "./bin/wp-finish-push-dev.js"
   },
   "files": [
     "src/**/*",
@@ -26,7 +28,7 @@
     "directory": "packages/tooling/pr-gate"
   },
   "dependencies": {
-    "@webpieces/rules-config": "0.4.565",
+    "@webpieces/rules-config": "0.4.566",
     "@inversifyjs/binding-decorators": "1.1.5",
     "inversify": "7.10.4",
     "reflect-metadata": "0.2.2"

package/src/scripts/commands/finish-push-dev-command.d.ts

@@ -0,0 +1,28 @@
+import { RepoRootFinder } from '@webpieces/rules-config';
+import { PushDevStateStore } from '../workflow/push-dev-state';
+import { DevResolveRunner } from '../workflow/dev-resolve-runner';
+/** What `wp-finish-push-dev` was asked to do. Data-only (per CLAUDE.md). */
+export declare class FinishPushDevOptions {
+    /** Throw the whole resolve away and restore the original checkout. */
+    abort: boolean;
+    constructor(abort?: boolean);
+}
+/**
+ * `wp-finish-push-dev` — stage ② of the dev-deploy flow, needed ONLY when a merge stopped.
+ *
+ * It mirrors `wp-start-update` → `wp-finish-update` on purpose: the repo already has a two-phase
+ * start/finish idiom for exactly this shape ("the tool merges, you resolve, the tool commits"), and a
+ * `--continue` idiom invented here would be a second vocabulary for one concept. A clean `wp-push-dev
+ * --resolve` finalizes itself and this command is never needed.
+ *
+ * The command owns the commit because the AI cannot make it: `redirect-how-to-merge-main` blocks
+ * `git merge --continue` and `merge-in-progress-guard` blocks `git commit`. Editing the conflicted files
+ * and `git add`-ing them is the AI's whole job, and neither is blocked.
+ */
+export declare class FinishPushDevCommand {
+    private readonly repoRootFinder;
+    private readonly store;
+    private readonly runner;
+    constructor(repoRootFinder: RepoRootFinder, store: PushDevStateStore, runner: DevResolveRunner);
+    run(opts: FinishPushDevOptions): Promise<void>;
+}

package/src/scripts/commands/finish-push-dev-command.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FinishPushDevCommand = exports.FinishPushDevOptions = void 0;
+const tslib_1 = require("tslib");
+const rules_config_1 = require("@webpieces/rules-config");
+const inversify_1 = require("inversify");
+const push_dev_state_1 = require("../workflow/push-dev-state");
+const dev_resolve_runner_1 = require("../workflow/dev-resolve-runner");
+/** What `wp-finish-push-dev` was asked to do. Data-only (per CLAUDE.md). */
+class FinishPushDevOptions {
+    /** Throw the whole resolve away and restore the original checkout. */
+    abort = false;
+    constructor(abort = false) {
+        this.abort = abort;
+    }
+}
+exports.FinishPushDevOptions = FinishPushDevOptions;
+/**
+ * `wp-finish-push-dev` — stage ② of the dev-deploy flow, needed ONLY when a merge stopped.
+ *
+ * It mirrors `wp-start-update` → `wp-finish-update` on purpose: the repo already has a two-phase
+ * start/finish idiom for exactly this shape ("the tool merges, you resolve, the tool commits"), and a
+ * `--continue` idiom invented here would be a second vocabulary for one concept. A clean `wp-push-dev
+ * --resolve` finalizes itself and this command is never needed.
+ *
+ * The command owns the commit because the AI cannot make it: `redirect-how-to-merge-main` blocks
+ * `git merge --continue` and `merge-in-progress-guard` blocks `git commit`. Editing the conflicted files
+ * and `git add`-ing them is the AI's whole job, and neither is blocked.
+ */
+let FinishPushDevCommand = class FinishPushDevCommand {
+    repoRootFinder;
+    store;
+    runner;
+    constructor(repoRootFinder, store, runner) {
+        this.repoRootFinder = repoRootFinder;
+        this.store = store;
+        this.runner = runner;
+    }
+    async run(opts) {
+        const repoRoot = this.repoRootFinder.resolveRepoRoot(process.cwd());
+        (0, rules_config_1.writeTemplate)(repoRoot, 'webpieces.git-workflow.md');
+        // Refuses with the one-command publish form when nothing is in flight, so a mistaken call here
+        // does not read as "the flow is broken".
+        const state = this.store.require(repoRoot);
+        if (opts.abort) {
+            this.runner.abort(repoRoot, state);
+            return Promise.resolve();
+        }
+        // Refuses (and re-prints the unresolved files) before committing anything, then resumes the
+        // queue — a LATER ref can conflict too, so this may legitimately stop again.
+        this.runner.resume(repoRoot, state);
+        return Promise.resolve();
+    }
+};
+exports.FinishPushDevCommand = FinishPushDevCommand;
+exports.FinishPushDevCommand = FinishPushDevCommand = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton),
+    tslib_1.__metadata("design:paramtypes", [rules_config_1.RepoRootFinder,
+        push_dev_state_1.PushDevStateStore,
+        dev_resolve_runner_1.DevResolveRunner])
+], FinishPushDevCommand);
+//# sourceMappingURL=finish-push-dev-command.js.map

package/src/scripts/commands/finish-push-dev-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"finish-push-dev-command.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/commands/finish-push-dev-command.ts"],"names":[],"mappings":";;;;AAAA,0DAAwE;AACxE,yCAA2D;AAE3D,+DAA+D;AAC/D,uEAAkE;AAElE,4EAA4E;AAC5E,MAAa,oBAAoB;IAC7B,sEAAsE;IACtE,KAAK,GAAG,KAAK,CAAC;IAEd,YAAY,KAAK,GAAG,KAAK;QACrB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACvB,CAAC;CACJ;AAPD,oDAOC;AAED;;;;;;;;;;;GAWG;AAEI,IAAM,oBAAoB,GAA1B,MAAM,oBAAoB;IAER;IACA;IACA;IAHrB,YACqB,cAA8B,EAC9B,KAAwB,EACxB,MAAwB;QAFxB,mBAAc,GAAd,cAAc,CAAgB;QAC9B,UAAK,GAAL,KAAK,CAAmB;QACxB,WAAM,GAAN,MAAM,CAAkB;IAC1C,CAAC;IAEJ,KAAK,CAAC,GAAG,CAAC,IAA0B;QAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,eAAe,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACpE,IAAA,4BAAa,EAAC,QAAQ,EAAE,2BAA2B,CAAC,CAAC;QACrD,+FAA+F;QAC/F,yCAAyC;QACzC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAE3C,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACb,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;YACnC,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC7B,CAAC;QACD,4FAA4F;QAC5F,6EAA6E;QAC7E,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QACpC,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC7B,CAAC;CACJ,CAAA;AAvBY,oDAAoB;+BAApB,oBAAoB;IADhC,IAAA,sBAAU,EAAC,8BAAkB,CAAC,SAAS,CAAC;6CAGA,6BAAc;QACvB,kCAAiB;QAChB,qCAAgB;GAJpC,oBAAoB,CAuBhC","sourcesContent":["import { RepoRootFinder, writeTemplate } from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\n\nimport { PushDevStateStore } from '../workflow/push-dev-state';\nimport { DevResolveRunner } from '../workflow/dev-resolve-runner';\n\n/** What `wp-finish-push-dev` was asked to do. Data-only (per CLAUDE.md). */\nexport class FinishPushDevOptions {\n    /** Throw the whole resolve away and restore the original checkout. */\n    abort = false;\n\n    constructor(abort = false) {\n        this.abort = abort;\n    }\n}\n\n/**\n * `wp-finish-push-dev` — stage ② of the dev-deploy flow, needed ONLY when a merge stopped.\n *\n * It mirrors `wp-start-update` → `wp-finish-update` on purpose: the repo already has a two-phase\n * start/finish idiom for exactly this shape (\"the tool merges, you resolve, the tool commits\"), and a\n * `--continue` idiom invented here would be a second vocabulary for one concept. A clean `wp-push-dev\n * --resolve` finalizes itself and this command is never needed.\n *\n * The command owns the commit because the AI cannot make it: `redirect-how-to-merge-main` blocks\n * `git merge --continue` and `merge-in-progress-guard` blocks `git commit`. Editing the conflicted files\n * and `git add`-ing them is the AI's whole job, and neither is blocked.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class FinishPushDevCommand {\n    constructor(\n        private readonly repoRootFinder: RepoRootFinder,\n        private readonly store: PushDevStateStore,\n        private readonly runner: DevResolveRunner,\n    ) {}\n\n    async run(opts: FinishPushDevOptions): Promise<void> {\n        const repoRoot = this.repoRootFinder.resolveRepoRoot(process.cwd());\n        writeTemplate(repoRoot, 'webpieces.git-workflow.md');\n        // Refuses with the one-command publish form when nothing is in flight, so a mistaken call here\n        // does not read as \"the flow is broken\".\n        const state = this.store.require(repoRoot);\n\n        if (opts.abort) {\n            this.runner.abort(repoRoot, state);\n            return Promise.resolve();\n        }\n        // Refuses (and re-prints the unresolved files) before committing anything, then resumes the\n        // queue — a LATER ref can conflict too, so this may legitimately stop again.\n        this.runner.resume(repoRoot, state);\n        return Promise.resolve();\n    }\n}\n"]}

package/src/scripts/commands/push-dev-command.d.ts

@@ -0,0 +1,89 @@
+import { RepoRootFinder } from '@webpieces/rules-config';
+import { GitExec } from '../workflow/git-exec';
+import { DevDeployRefs } from '../workflow/dev-deploy-refs';
+import { PushDevStateStore } from '../workflow/push-dev-state';
+import { DevResolveRunner } from '../workflow/dev-resolve-runner';
+/**
+ * Which of `wp-push-dev`'s modes was asked for. Data-only (per CLAUDE.md) with plain assigned fields
+ * rather than a seven-argument constructor — the bin sets what argv carried and nothing else.
+ */
+export declare class PushDevOptions {
+    /** Delete the remote copy — the rollback. */
+    remove: boolean;
+    /** List the live copies and stop. The one mode that needs no branch preconditions. */
+    list: boolean;
+    /** Discard a conflict resolution already published on the copy, and overwrite it. */
+    force: boolean;
+    /** Replay that resolution on top of the new local commits instead of discarding it. */
+    rebaseResolution: boolean;
+    /** Compose the other copies onto this one so the shared environment can build them together. */
+    resolve: boolean;
+    /** With `--resolve`: merge ONLY this developer's branch. Empty ⇒ every other copy. */
+    resolveTarget: string;
+}
+/**
+ * `wp-push-dev` — publish a DISPOSABLE copy of this branch so a shared dev environment can build it,
+ * without landing anything on `main` and without opening a PR.
+ *
+ * WHY THIS COMMAND HAS TO EXIST AT ALL: `pr-creation-or-push-guard` blocks every `git push`, no
+ * exceptions, by design. Its own fix-hint offers "ask a human to run the push" for out-of-band cases —
+ * which is the right answer for a genuine exception and the wrong one for a routine daily action. Without
+ * a gated command there is simply no legal way for an AI to get a branch onto a dev server, so the
+ * feature was undoable rather than merely awkward.
+ *
+ * WHY THERE IS NO BUILD, deliberately unlike `wp-start-upsert-pr`: the shared environment's CI builds the
+ * COMPOSED tree (main + every listed branch). A local build here proves the branch compiles against
+ * `main` alone, which is not the question — it would be both slower and reassuring about the wrong thing.
+ * The gate that matters runs on the composition, in CI, where it belongs.
+ *
+ * WHAT IT NEVER DOES: touch the feature branch. See DevDeployRefs for the invariant and why the copy
+ * exists to hold conflict resolutions that must not reach the PR.
+ */
+export declare class PushDevCommand {
+    private readonly repoRootFinder;
+    private readonly gitExec;
+    private readonly refs;
+    private readonly store;
+    private readonly runner;
+    constructor(repoRootFinder: RepoRootFinder, gitExec: GitExec, refs: DevDeployRefs, store: PushDevStateStore, runner: DevResolveRunner);
+    run(opts: PushDevOptions): Promise<void>;
+    /** `--list`: exactly the live copies, straight from the remote — never a cached local view. */
+    private list;
+    /** `--remove`: delete the remote copy. This IS the rollback — nothing else has to be undone. */
+    private remove;
+    /**
+     * The ordinary path: publish HEAD as `<namespace>/<branch>`.
+     *
+     * THE CLOBBER GUARD is the whole of the interesting logic here. If the remote copy holds commits the
+     * local branch does not, somebody (quite possibly this developer, days ago) resolved a real conflict
+     * over there. A silent force-push destroys work that cost a human a genuine merge resolution, so the
+     * default is refusal with two named ways forward — never a "use --force" one-liner, which is how a
+     * warning becomes a reflex.
+     */
+    private publish;
+    /**
+     * `--rebase-resolution`: keep the published resolution, replay it on top of the new commits.
+     *
+     * Implemented as a resolve whose BASE is the local HEAD and whose queue is the copy itself, so a
+     * replay that conflicts again lands in exactly the same halt/`wp-finish-push-dev` state machine as
+     * any other conflict, rather than inventing a second way to be stuck.
+     */
+    private rebaseResolution;
+    /**
+     * `--resolve`: compose the other copies onto this one, so what is published is what CI will build.
+     *
+     * With no argument the queue is EVERY other copy, in the same sorted order CI composes them — the
+     * local resolution is then a rehearsal of the real composition, not a guess at it. With an argument
+     * (the branch a CI conflict message names) it is just that one.
+     */
+    private startResolve;
+    private resolveQueue;
+    /**
+     * `--force-with-lease` pinned to the sha we just inspected, so the clobber guard's verdict cannot go
+     * stale between the check and the push. Plain `--force` only when the caller explicitly asked to
+     * discard, and no force at all for a brand-new copy.
+     */
+    private pushSafety;
+    private refuseClobber;
+    private assertNoResolveInProgress;
+}

package/src/scripts/commands/push-dev-command.js

@@ -0,0 +1,249 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PushDevCommand = exports.PushDevOptions = 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("../workflow/git-exec");
+const dev_deploy_refs_1 = require("../workflow/dev-deploy-refs");
+const push_dev_state_1 = require("../workflow/push-dev-state");
+const dev_resolve_runner_1 = require("../workflow/dev-resolve-runner");
+const SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n';
+/**
+ * Which of `wp-push-dev`'s modes was asked for. Data-only (per CLAUDE.md) with plain assigned fields
+ * rather than a seven-argument constructor — the bin sets what argv carried and nothing else.
+ */
+class PushDevOptions {
+    /** Delete the remote copy — the rollback. */
+    remove = false;
+    /** List the live copies and stop. The one mode that needs no branch preconditions. */
+    list = false;
+    /** Discard a conflict resolution already published on the copy, and overwrite it. */
+    force = false;
+    /** Replay that resolution on top of the new local commits instead of discarding it. */
+    rebaseResolution = false;
+    /** Compose the other copies onto this one so the shared environment can build them together. */
+    resolve = false;
+    /** With `--resolve`: merge ONLY this developer's branch. Empty ⇒ every other copy. */
+    resolveTarget = '';
+}
+exports.PushDevOptions = PushDevOptions;
+/**
+ * `wp-push-dev` — publish a DISPOSABLE copy of this branch so a shared dev environment can build it,
+ * without landing anything on `main` and without opening a PR.
+ *
+ * WHY THIS COMMAND HAS TO EXIST AT ALL: `pr-creation-or-push-guard` blocks every `git push`, no
+ * exceptions, by design. Its own fix-hint offers "ask a human to run the push" for out-of-band cases —
+ * which is the right answer for a genuine exception and the wrong one for a routine daily action. Without
+ * a gated command there is simply no legal way for an AI to get a branch onto a dev server, so the
+ * feature was undoable rather than merely awkward.
+ *
+ * WHY THERE IS NO BUILD, deliberately unlike `wp-start-upsert-pr`: the shared environment's CI builds the
+ * COMPOSED tree (main + every listed branch). A local build here proves the branch compiles against
+ * `main` alone, which is not the question — it would be both slower and reassuring about the wrong thing.
+ * The gate that matters runs on the composition, in CI, where it belongs.
+ *
+ * WHAT IT NEVER DOES: touch the feature branch. See DevDeployRefs for the invariant and why the copy
+ * exists to hold conflict resolutions that must not reach the PR.
+ */
+let PushDevCommand = class PushDevCommand {
+    repoRootFinder;
+    gitExec;
+    refs;
+    store;
+    runner;
+    constructor(repoRootFinder, gitExec, refs, store, runner) {
+        this.repoRootFinder = repoRootFinder;
+        this.gitExec = gitExec;
+        this.refs = refs;
+        this.store = store;
+        this.runner = runner;
+    }
+    async run(opts) {
+        const repoRoot = this.repoRootFinder.resolveRepoRoot(process.cwd());
+        // Refresh the AI-facing workflow doc so it is present + current for any failure message to cite —
+        // same reason every other wp-* command opens this way.
+        (0, rules_config_1.writeTemplate)(repoRoot, 'webpieces.git-workflow.md');
+        const cfg = this.refs.config(repoRoot);
+        // A resolve already in flight owns the checkout; starting a second one would strand the first.
+        this.assertNoResolveInProgress(repoRoot);
+        if (opts.list) {
+            this.list(repoRoot, cfg);
+            return Promise.resolve();
+        }
+        const branch = this.refs.currentBranch(repoRoot);
+        this.refs.assertPushable(cfg, branch);
+        const targetRef = cfg.copyRefFor(branch);
+        if (opts.remove) {
+            this.remove(repoRoot, cfg, branch, targetRef);
+            return Promise.resolve();
+        }
+        // Every remaining mode commits or merges, so the tree must be the AI's committed work and nothing
+        // else. The tooling never commits for you.
+        this.gitExec.assertCleanTree(repoRoot);
+        if (opts.resolve) {
+            this.startResolve(repoRoot, cfg, branch, targetRef, opts.resolveTarget);
+            return Promise.resolve();
+        }
+        this.publish(repoRoot, cfg, branch, targetRef, opts);
+        return Promise.resolve();
+    }
+    /** `--list`: exactly the live copies, straight from the remote — never a cached local view. */
+    list(repoRoot, cfg) {
+        const copies = this.refs.liveCopies(repoRoot, cfg);
+        if (copies.length === 0) {
+            process.stdout.write(`\nNo dev copies published — nothing matches \`${cfg.copyRefGlob()}\` on origin.\n`
+                + `Publish this branch's with: ${rules_config_1.WP_PUSH_DEV}\n`);
+            return;
+        }
+        let out = '\n' + SEP + `📋 ${String(copies.length)} dev cop${copies.length === 1 ? 'y' : 'ies'} on origin\n` + SEP + '\n';
+        for (const copy of copies)
+            out += `  ${copy.sha.slice(0, 8)}  ${copy.ref}\n`;
+        out += `\nYour CI composes \`${cfg.devBranch}\` from origin/main plus every ref above, on every run.\n`
+            + `Remove yours with: ${rules_config_1.WP_PUSH_DEV} --remove\n`;
+        process.stdout.write(out);
+    }
+    /** `--remove`: delete the remote copy. This IS the rollback — nothing else has to be undone. */
+    remove(repoRoot, cfg, branch, targetRef) {
+        if (this.refs.remoteSha(repoRoot, targetRef) === '') {
+            process.stdout.write(`\nNothing to remove — \`${targetRef}\` is not published.\n`
+                + `List what IS published with: ${rules_config_1.WP_PUSH_DEV} --list\n`);
+            return;
+        }
+        this.gitExec.runGitChecked(['-C', repoRoot, 'push', 'origin', '--delete', `refs/heads/${targetRef}`], `Failed to delete the dev copy ${targetRef}`);
+        process.stdout.write('\n' + SEP + `🗑️  Removed ${targetRef}\n` + SEP + '\n'
+            + `\`${branch}\` will drop out of \`${cfg.devBranch}\` on its next composition run. Your branch and any\n`
+            + 'PR on it are untouched.\n');
+    }
+    /**
+     * The ordinary path: publish HEAD as `<namespace>/<branch>`.
+     *
+     * THE CLOBBER GUARD is the whole of the interesting logic here. If the remote copy holds commits the
+     * local branch does not, somebody (quite possibly this developer, days ago) resolved a real conflict
+     * over there. A silent force-push destroys work that cost a human a genuine merge resolution, so the
+     * default is refusal with two named ways forward — never a "use --force" one-liner, which is how a
+     * warning becomes a reflex.
+     */
+    publish(repoRoot, cfg, branch, targetRef, opts) {
+        const remoteSha = this.refs.remoteSha(repoRoot, targetRef);
+        if (remoteSha !== '') {
+            this.refs.fetchCopies(repoRoot, [targetRef]);
+            const ahead = this.refs.commitsOnlyOnRemote(repoRoot, targetRef);
+            if (ahead > 0 && opts.rebaseResolution) {
+                this.rebaseResolution(repoRoot, branch, targetRef);
+                return;
+            }
+            if (ahead > 0 && !opts.force)
+                this.refuseClobber(cfg, branch, targetRef, ahead);
+        }
+        this.gitExec.runGitChecked(['-C', repoRoot, 'push', ...this.pushSafety(targetRef, remoteSha, opts.force),
+            'origin', `HEAD:refs/heads/${targetRef}`], `Failed to publish the dev copy ${targetRef}`);
+        process.stdout.write('\n' + SEP + `✅ Published ${targetRef}\n` + SEP + '\n'
+            + `\`${branch}\` is now in the pool your CI composes \`${cfg.devBranch}\` from — it will be picked up on\n`
+            + 'the next composition run. No PR was opened and nothing landed on main.\n\n'
+            + `  ${rules_config_1.WP_PUSH_DEV} --list      ← what else is in the pool\n`
+            + `  ${rules_config_1.WP_PUSH_DEV} --remove    ← take this branch back out\n`);
+    }
+    /**
+     * `--rebase-resolution`: keep the published resolution, replay it on top of the new commits.
+     *
+     * Implemented as a resolve whose BASE is the local HEAD and whose queue is the copy itself, so a
+     * replay that conflicts again lands in exactly the same halt/`wp-finish-push-dev` state machine as
+     * any other conflict, rather than inventing a second way to be stuck.
+     */
+    rebaseResolution(repoRoot, branch, targetRef) {
+        const state = new push_dev_state_1.PushDevState(branch, this.runner.tmpBranchFor(branch), targetRef, [targetRef]);
+        process.stdout.write('\n' + SEP + `♻️  Replaying the published resolution onto \`${branch}\`\n` + SEP + '\n'
+            + `Merging \`${targetRef}\` (which holds the resolution) into your new commits on a throwaway branch.\n`
+            + `Your feature branch \`${branch}\` is not touched.\n\n`);
+        this.runner.start(repoRoot, state, 'HEAD', [targetRef]);
+    }
+    /**
+     * `--resolve`: compose the other copies onto this one, so what is published is what CI will build.
+     *
+     * With no argument the queue is EVERY other copy, in the same sorted order CI composes them — the
+     * local resolution is then a rehearsal of the real composition, not a guess at it. With an argument
+     * (the branch a CI conflict message names) it is just that one.
+     */
+    startResolve(repoRoot, cfg, branch, targetRef, only) {
+        if (this.refs.remoteSha(repoRoot, targetRef) === '') {
+            throw new rules_config_1.CliExitError(2, '\n' + SEP + `⛔ \`${targetRef}\` is not published yet\n` + SEP + '\n'
+                + 'There is nothing to compose against. Publish your copy first, then resolve:\n'
+                + `  ${rules_config_1.WP_PUSH_DEV}\n  ${rules_config_1.WP_PUSH_DEV} --resolve\n`);
+        }
+        const queue = this.resolveQueue(repoRoot, cfg, targetRef, only);
+        if (queue.length === 0) {
+            process.stdout.write(`\nNothing to compose — \`${targetRef}\` is the only copy in \`${cfg.copyRefGlob()}\`.\n`
+                + `Your CI will merge it onto origin/main by itself; there is no other branch to conflict with.\n`);
+            return;
+        }
+        const state = new push_dev_state_1.PushDevState(branch, this.runner.tmpBranchFor(branch), targetRef, queue);
+        process.stdout.write(this.runner.announce(cfg, state));
+        this.runner.start(repoRoot, state, `refs/remotes/origin/${targetRef}`, [targetRef, ...queue]);
+    }
+    // The refs to merge: one named copy, or every copy that is not mine. A named branch is accepted with
+    // or without the namespace prefix, because the CI message that names it may print either.
+    resolveQueue(repoRoot, cfg, targetRef, only) {
+        const copies = this.refs.liveCopies(repoRoot, cfg);
+        if (only === '') {
+            return copies.filter((c) => c.ref !== targetRef).map((c) => c.ref);
+        }
+        const wanted = only.startsWith(`${cfg.branchNamespace}/`) ? only : cfg.copyRefFor(only);
+        if (wanted === targetRef) {
+            throw new rules_config_1.CliExitError(2, `\n⛔ \`${only}\` is your own copy — there is nothing to compose it with.\n`);
+        }
+        if (!copies.some((c) => c.ref === wanted)) {
+            throw new rules_config_1.CliExitError(2, '\n' + SEP + `⛔ No published copy \`${wanted}\`\n` + SEP + '\n'
+                + `Live copies (${rules_config_1.WP_PUSH_DEV} --list):\n`
+                + copies.map((c) => `  ${c.ref}`).join('\n') + '\n');
+        }
+        return [wanted];
+    }
+    /**
+     * `--force-with-lease` pinned to the sha we just inspected, so the clobber guard's verdict cannot go
+     * stale between the check and the push. Plain `--force` only when the caller explicitly asked to
+     * discard, and no force at all for a brand-new copy.
+     */
+    pushSafety(targetRef, remoteSha, force) {
+        if (remoteSha === '')
+            return [];
+        if (force)
+            return ['--force'];
+        return [`--force-with-lease=refs/heads/${targetRef}:${remoteSha}`];
+    }
+    refuseClobber(cfg, branch, targetRef, ahead) {
+        throw new rules_config_1.CliExitError(2, '\n' + SEP + `⛔ \`${targetRef}\` holds ${String(ahead)} commit(s) your branch does not\n` + SEP + '\n'
+            + 'That is what a CONFLICT RESOLUTION looks like: somebody composed this copy against another\n'
+            + `developer's branch so \`${cfg.devBranch}\` could build, and that work exists ONLY on the copy —\n`
+            + 'by design, because it must never reach your feature branch or your PR.\n\n'
+            + 'Publishing now would force-push over it and destroy it, so this command refuses. Pick one:\n\n'
+            + `  ${rules_config_1.WP_PUSH_DEV} --rebase-resolution\n`
+            + '      Replay that resolution on top of your new commits. Keeps the work; may ask you to\n'
+            + '      re-resolve the parts your new commits actually changed.\n\n'
+            + `  ${rules_config_1.WP_PUSH_DEV} --force\n`
+            + '      Discard it and publish your branch as-is. The composition breaks again until someone\n'
+            + `      re-resolves it with \`${rules_config_1.WP_PUSH_DEV} --resolve\`.\n\n`
+            + `See what is on the copy:  git log --oneline ${branch}..refs/remotes/origin/${targetRef}\n`);
+    }
+    // A half-finished resolve owns the checkout — it is parked on a throwaway branch, so "the current
+    // branch" is not the feature branch this command would otherwise act on.
+    assertNoResolveInProgress(repoRoot) {
+        const state = this.store.read(repoRoot);
+        if (state === null)
+            return;
+        throw new rules_config_1.CliExitError(2, '\n' + SEP + '⛔ A dev-deploy resolve is already in progress\n' + SEP + '\n'
+            + `You are on the throwaway branch \`${state.tmpBranch}\`, mid-composition. Finish it or bail out:\n`
+            + `  ${rules_config_1.WP_FINISH_PUSH_DEV}            ← commit the resolution, resume the queue, publish\n`
+            + `  ${rules_config_1.WP_FINISH_PUSH_DEV} --abort    ← throw it away and go back to \`${state.originalBranch}\`\n`);
+    }
+};
+exports.PushDevCommand = PushDevCommand;
+exports.PushDevCommand = PushDevCommand = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton),
+    tslib_1.__metadata("design:paramtypes", [rules_config_1.RepoRootFinder,
+        git_exec_1.GitExec,
+        dev_deploy_refs_1.DevDeployRefs,
+        push_dev_state_1.PushDevStateStore,
+        dev_resolve_runner_1.DevResolveRunner])
+], PushDevCommand);
+//# sourceMappingURL=push-dev-command.js.map

package/src/scripts/commands/push-dev-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-dev-command.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/commands/push-dev-command.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n    CliExitError,\n    DevDeployConfig,\n    RepoRootFinder,\n    WP_FINISH_PUSH_DEV,\n    WP_PUSH_DEV,\n    writeTemplate,\n} from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\n\nimport { GitExec } from '../workflow/git-exec';\nimport { DevCopy, DevDeployRefs } from '../workflow/dev-deploy-refs';\nimport { PushDevState, PushDevStateStore } from '../workflow/push-dev-state';\nimport { DevResolveRunner } from '../workflow/dev-resolve-runner';\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\n/**\n * Which of `wp-push-dev`'s modes was asked for. Data-only (per CLAUDE.md) with plain assigned fields\n * rather than a seven-argument constructor — the bin sets what argv carried and nothing else.\n */\nexport class PushDevOptions {\n    /** Delete the remote copy — the rollback. */\n    remove = false;\n    /** List the live copies and stop. The one mode that needs no branch preconditions. */\n    list = false;\n    /** Discard a conflict resolution already published on the copy, and overwrite it. */\n    force = false;\n    /** Replay that resolution on top of the new local commits instead of discarding it. */\n    rebaseResolution = false;\n    /** Compose the other copies onto this one so the shared environment can build them together. */\n    resolve = false;\n    /** With `--resolve`: merge ONLY this developer's branch. Empty ⇒ every other copy. */\n    resolveTarget = '';\n}\n\n/**\n * `wp-push-dev` — publish a DISPOSABLE copy of this branch so a shared dev environment can build it,\n * without landing anything on `main` and without opening a PR.\n *\n * WHY THIS COMMAND HAS TO EXIST AT ALL: `pr-creation-or-push-guard` blocks every `git push`, no\n * exceptions, by design. Its own fix-hint offers \"ask a human to run the push\" for out-of-band cases —\n * which is the right answer for a genuine exception and the wrong one for a routine daily action. Without\n * a gated command there is simply no legal way for an AI to get a branch onto a dev server, so the\n * feature was undoable rather than merely awkward.\n *\n * WHY THERE IS NO BUILD, deliberately unlike `wp-start-upsert-pr`: the shared environment's CI builds the\n * COMPOSED tree (main + every listed branch). A local build here proves the branch compiles against\n * `main` alone, which is not the question — it would be both slower and reassuring about the wrong thing.\n * The gate that matters runs on the composition, in CI, where it belongs.\n *\n * WHAT IT NEVER DOES: touch the feature branch. See DevDeployRefs for the invariant and why the copy\n * exists to hold conflict resolutions that must not reach the PR.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class PushDevCommand {\n    constructor(\n        private readonly repoRootFinder: RepoRootFinder,\n        private readonly gitExec: GitExec,\n        private readonly refs: DevDeployRefs,\n        private readonly store: PushDevStateStore,\n        private readonly runner: DevResolveRunner,\n    ) {}\n\n    async run(opts: PushDevOptions): Promise<void> {\n        const repoRoot = this.repoRootFinder.resolveRepoRoot(process.cwd());\n        // Refresh the AI-facing workflow doc so it is present + current for any failure message to cite —\n        // same reason every other wp-* command opens this way.\n        writeTemplate(repoRoot, 'webpieces.git-workflow.md');\n        const cfg = this.refs.config(repoRoot);\n\n        // A resolve already in flight owns the checkout; starting a second one would strand the first.\n        this.assertNoResolveInProgress(repoRoot);\n\n        if (opts.list) {\n            this.list(repoRoot, cfg);\n            return Promise.resolve();\n        }\n\n        const branch = this.refs.currentBranch(repoRoot);\n        this.refs.assertPushable(cfg, branch);\n        const targetRef = cfg.copyRefFor(branch);\n\n        if (opts.remove) {\n            this.remove(repoRoot, cfg, branch, targetRef);\n            return Promise.resolve();\n        }\n        // Every remaining mode commits or merges, so the tree must be the AI's committed work and nothing\n        // else. The tooling never commits for you.\n        this.gitExec.assertCleanTree(repoRoot);\n\n        if (opts.resolve) {\n            this.startResolve(repoRoot, cfg, branch, targetRef, opts.resolveTarget);\n            return Promise.resolve();\n        }\n        this.publish(repoRoot, cfg, branch, targetRef, opts);\n        return Promise.resolve();\n    }\n\n    /** `--list`: exactly the live copies, straight from the remote — never a cached local view. */\n    private list(repoRoot: string, cfg: DevDeployConfig): void {\n        const copies = this.refs.liveCopies(repoRoot, cfg);\n        if (copies.length === 0) {\n            process.stdout.write(\n                `\\nNo dev copies published — nothing matches \\`${cfg.copyRefGlob()}\\` on origin.\\n`\n                + `Publish this branch's with: ${WP_PUSH_DEV}\\n`);\n            return;\n        }\n        let out = '\\n' + SEP + `📋 ${String(copies.length)} dev cop${copies.length === 1 ? 'y' : 'ies'} on origin\\n` + SEP + '\\n';\n        for (const copy of copies) out += `  ${copy.sha.slice(0, 8)}  ${copy.ref}\\n`;\n        out += `\\nYour CI composes \\`${cfg.devBranch}\\` from origin/main plus every ref above, on every run.\\n`\n            + `Remove yours with: ${WP_PUSH_DEV} --remove\\n`;\n        process.stdout.write(out);\n    }\n\n    /** `--remove`: delete the remote copy. This IS the rollback — nothing else has to be undone. */\n    private remove(repoRoot: string, cfg: DevDeployConfig, branch: string, targetRef: string): void {\n        if (this.refs.remoteSha(repoRoot, targetRef) === '') {\n            process.stdout.write(\n                `\\nNothing to remove — \\`${targetRef}\\` is not published.\\n`\n                + `List what IS published with: ${WP_PUSH_DEV} --list\\n`);\n            return;\n        }\n        this.gitExec.runGitChecked(['-C', repoRoot, 'push', 'origin', '--delete', `refs/heads/${targetRef}`],\n            `Failed to delete the dev copy ${targetRef}`);\n        process.stdout.write(\n            '\\n' + SEP + `🗑️  Removed ${targetRef}\\n` + SEP + '\\n'\n            + `\\`${branch}\\` will drop out of \\`${cfg.devBranch}\\` on its next composition run. Your branch and any\\n`\n            + 'PR on it are untouched.\\n');\n    }\n\n    /**\n     * The ordinary path: publish HEAD as `<namespace>/<branch>`.\n     *\n     * THE CLOBBER GUARD is the whole of the interesting logic here. If the remote copy holds commits the\n     * local branch does not, somebody (quite possibly this developer, days ago) resolved a real conflict\n     * over there. A silent force-push destroys work that cost a human a genuine merge resolution, so the\n     * default is refusal with two named ways forward — never a \"use --force\" one-liner, which is how a\n     * warning becomes a reflex.\n     */\n    private publish(repoRoot: string, cfg: DevDeployConfig, branch: string, targetRef: string, opts: PushDevOptions): void {\n        const remoteSha = this.refs.remoteSha(repoRoot, targetRef);\n        if (remoteSha !== '') {\n            this.refs.fetchCopies(repoRoot, [targetRef]);\n            const ahead = this.refs.commitsOnlyOnRemote(repoRoot, targetRef);\n            if (ahead > 0 && opts.rebaseResolution) {\n                this.rebaseResolution(repoRoot, branch, targetRef);\n                return;\n            }\n            if (ahead > 0 && !opts.force) this.refuseClobber(cfg, branch, targetRef, ahead);\n        }\n        this.gitExec.runGitChecked(\n            ['-C', repoRoot, 'push', ...this.pushSafety(targetRef, remoteSha, opts.force),\n                'origin', `HEAD:refs/heads/${targetRef}`],\n            `Failed to publish the dev copy ${targetRef}`);\n        process.stdout.write(\n            '\\n' + SEP + `✅ Published ${targetRef}\\n` + SEP + '\\n'\n            + `\\`${branch}\\` is now in the pool your CI composes \\`${cfg.devBranch}\\` from — it will be picked up on\\n`\n            + 'the next composition run. No PR was opened and nothing landed on main.\\n\\n'\n            + `  ${WP_PUSH_DEV} --list      ← what else is in the pool\\n`\n            + `  ${WP_PUSH_DEV} --remove    ← take this branch back out\\n`);\n    }\n\n    /**\n     * `--rebase-resolution`: keep the published resolution, replay it on top of the new commits.\n     *\n     * Implemented as a resolve whose BASE is the local HEAD and whose queue is the copy itself, so a\n     * replay that conflicts again lands in exactly the same halt/`wp-finish-push-dev` state machine as\n     * any other conflict, rather than inventing a second way to be stuck.\n     */\n    private rebaseResolution(repoRoot: string, branch: string, targetRef: string): void {\n        const state = new PushDevState(branch, this.runner.tmpBranchFor(branch), targetRef, [targetRef]);\n        process.stdout.write(\n            '\\n' + SEP + `♻️  Replaying the published resolution onto \\`${branch}\\`\\n` + SEP + '\\n'\n            + `Merging \\`${targetRef}\\` (which holds the resolution) into your new commits on a throwaway branch.\\n`\n            + `Your feature branch \\`${branch}\\` is not touched.\\n\\n`);\n        this.runner.start(repoRoot, state, 'HEAD', [targetRef]);\n    }\n\n    /**\n     * `--resolve`: compose the other copies onto this one, so what is published is what CI will build.\n     *\n     * With no argument the queue is EVERY other copy, in the same sorted order CI composes them — the\n     * local resolution is then a rehearsal of the real composition, not a guess at it. With an argument\n     * (the branch a CI conflict message names) it is just that one.\n     */\n    private startResolve(repoRoot: string, cfg: DevDeployConfig, branch: string, targetRef: string, only: string): void {\n        if (this.refs.remoteSha(repoRoot, targetRef) === '') {\n            throw new CliExitError(2,\n                '\\n' + SEP + `⛔ \\`${targetRef}\\` is not published yet\\n` + SEP + '\\n'\n                + 'There is nothing to compose against. Publish your copy first, then resolve:\\n'\n                + `  ${WP_PUSH_DEV}\\n  ${WP_PUSH_DEV} --resolve\\n`);\n        }\n        const queue = this.resolveQueue(repoRoot, cfg, targetRef, only);\n        if (queue.length === 0) {\n            process.stdout.write(\n                `\\nNothing to compose — \\`${targetRef}\\` is the only copy in \\`${cfg.copyRefGlob()}\\`.\\n`\n                + `Your CI will merge it onto origin/main by itself; there is no other branch to conflict with.\\n`);\n            return;\n        }\n        const state = new PushDevState(branch, this.runner.tmpBranchFor(branch), targetRef, queue);\n        process.stdout.write(this.runner.announce(cfg, state));\n        this.runner.start(repoRoot, state, `refs/remotes/origin/${targetRef}`, [targetRef, ...queue]);\n    }\n\n    // The refs to merge: one named copy, or every copy that is not mine. A named branch is accepted with\n    // or without the namespace prefix, because the CI message that names it may print either.\n    private resolveQueue(repoRoot: string, cfg: DevDeployConfig, targetRef: string, only: string): string[] {\n        const copies = this.refs.liveCopies(repoRoot, cfg);\n        if (only === '') {\n            return copies.filter((c: DevCopy): boolean => c.ref !== targetRef).map((c: DevCopy): string => c.ref);\n        }\n        const wanted = only.startsWith(`${cfg.branchNamespace}/`) ? only : cfg.copyRefFor(only);\n        if (wanted === targetRef) {\n            throw new CliExitError(2, `\\n⛔ \\`${only}\\` is your own copy — there is nothing to compose it with.\\n`);\n        }\n        if (!copies.some((c: DevCopy): boolean => c.ref === wanted)) {\n            throw new CliExitError(2,\n                '\\n' + SEP + `⛔ No published copy \\`${wanted}\\`\\n` + SEP + '\\n'\n                + `Live copies (${WP_PUSH_DEV} --list):\\n`\n                + copies.map((c: DevCopy): string => `  ${c.ref}`).join('\\n') + '\\n');\n        }\n        return [wanted];\n    }\n\n    /**\n     * `--force-with-lease` pinned to the sha we just inspected, so the clobber guard's verdict cannot go\n     * stale between the check and the push. Plain `--force` only when the caller explicitly asked to\n     * discard, and no force at all for a brand-new copy.\n     */\n    private pushSafety(targetRef: string, remoteSha: string, force: boolean): string[] {\n        if (remoteSha === '') return [];\n        if (force) return ['--force'];\n        return [`--force-with-lease=refs/heads/${targetRef}:${remoteSha}`];\n    }\n\n    private refuseClobber(cfg: DevDeployConfig, branch: string, targetRef: string, ahead: number): never {\n        throw new CliExitError(2,\n            '\\n' + SEP + `⛔ \\`${targetRef}\\` holds ${String(ahead)} commit(s) your branch does not\\n` + SEP + '\\n'\n            + 'That is what a CONFLICT RESOLUTION looks like: somebody composed this copy against another\\n'\n            + `developer's branch so \\`${cfg.devBranch}\\` could build, and that work exists ONLY on the copy —\\n`\n            + 'by design, because it must never reach your feature branch or your PR.\\n\\n'\n            + 'Publishing now would force-push over it and destroy it, so this command refuses. Pick one:\\n\\n'\n            + `  ${WP_PUSH_DEV} --rebase-resolution\\n`\n            + '      Replay that resolution on top of your new commits. Keeps the work; may ask you to\\n'\n            + '      re-resolve the parts your new commits actually changed.\\n\\n'\n            + `  ${WP_PUSH_DEV} --force\\n`\n            + '      Discard it and publish your branch as-is. The composition breaks again until someone\\n'\n            + `      re-resolves it with \\`${WP_PUSH_DEV} --resolve\\`.\\n\\n`\n            + `See what is on the copy:  git log --oneline ${branch}..refs/remotes/origin/${targetRef}\\n`);\n    }\n\n    // A half-finished resolve owns the checkout — it is parked on a throwaway branch, so \"the current\n    // branch\" is not the feature branch this command would otherwise act on.\n    private assertNoResolveInProgress(repoRoot: string): void {\n        const state = this.store.read(repoRoot);\n        if (state === null) return;\n        throw new CliExitError(2,\n            '\\n' + SEP + '⛔ A dev-deploy resolve is already in progress\\n' + SEP + '\\n'\n            + `You are on the throwaway branch \\`${state.tmpBranch}\\`, mid-composition. Finish it or bail out:\\n`\n            + `  ${WP_FINISH_PUSH_DEV}            ← commit the resolution, resume the queue, publish\\n`\n            + `  ${WP_FINISH_PUSH_DEV} --abort    ← throw it away and go back to \\`${state.originalBranch}\\`\\n`);\n    }\n}\n"]}

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

@@ -7,6 +7,10 @@ import { LandPrCommand } from './commands/land-pr-command';
 import { CheckPrCommand } from './commands/check-pr-command';
 import { ReviewUpsertPrCommand, ReviewUpsertPrOptions } from './commands/review-upsert-pr-command';
 import { ReapWorktreeCommand } from './commands/reap-worktree-command';
+import { PushDevCommand, PushDevOptions } from './commands/push-dev-command';
+import { FinishPushDevCommand, FinishPushDevOptions } from './commands/finish-push-dev-command';
+import { PushDevStateStore } from './workflow/push-dev-state';
+import { RepoRootFinder } from '@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
@@ -23,7 +27,24 @@ export declare class PrGateApp {
     private readonly checkPrCommand;
     private readonly reviewUpsertPrCommand;
     private readonly reapWorktreeCommand;
-    constructor(startUpdateCommand: StartUpdateCommand, finishUpdateCommand: FinishUpdateCommand, startUpsertPrCommand: StartUpsertPrCommand, finishUpsertPrCommand: FinishUpsertPrCommand, cleanupCommand: CleanupCommand, landPrCommand: LandPrCommand, checkPrCommand: CheckPrCommand, reviewUpsertPrCommand: ReviewUpsertPrCommand, reapWorktreeCommand: ReapWorktreeCommand);
+    private readonly pushDevCommand;
+    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);
+    /**
+     * 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.
+     */
+    private assertNoResolveInProgress;
+    /** `wp-push-dev`: publish a DISPOSABLE copy of this branch for the shared dev environment. No PR, no build. */
+    pushDev(opts?: PushDevOptions): Promise<void>;
+    /** `wp-finish-push-dev`: commit a resolved dev composition and publish it (conflict path only). */
+    finishPushDev(opts?: FinishPushDevOptions): Promise<void>;
     /**
      * INTERNAL (`wp-reap-worktree.js`, no `bin` entry): remove ONE named worktree and its branch.
      * `wp-land-pr` spawns it with cwd = the primary clone so the tree it just landed from can be