@webpieces/pr-gate 0.3.201 → 0.3.203

package/src/scripts/workflow/build-affected.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_BUILD_COMMAND = void 0;
+exports.BuildGateOptions = exports.DEFAULT_BUILD_COMMAND = void 0;
 exports.resolveBuildCommand = resolveBuildCommand;
 exports.runBuildAffected = runBuildAffected;
 exports.runConfiguredBuildGate = runConfiguredBuildGate;
+exports.runBuildGate = runBuildGate;
 const child_process_1 = require("child_process");
 const rules_config_1 = require("@webpieces/rules-config");
 // Single source of truth for the build gate. Both `wp-build-affected` (CI + local) and the
@@ -44,4 +45,41 @@ function runBuildAffected(repoRoot, buildCommand) {
 function runConfiguredBuildGate(repoRoot) {
     return runBuildAffected(repoRoot, (0, rules_config_1.loadAndValidate)(repoRoot).prGate.buildCommand);
 }
+const SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n';
+/**
+ * The two facts that differ between the wp-start (advisory) and wp-finish (authoritative) build
+ * gates. Everything else — resolve command, run it, print the re-run hint, exit non-zero on failure
+ * — is identical, so it lives once in runBuildGate and the difference is passed in here. A class (not
+ * an object literal) per the codebase's data-structure convention.
+ */
+class BuildGateOptions {
+    label; // section header shown above the gate
+    rerunCommand; // command the AI re-runs after fixing the build
+    failureHeadline; // first line printed on failure
+    constructor(label, rerunCommand, failureHeadline) {
+        this.label = label;
+        this.rerunCommand = rerunCommand;
+        this.failureHeadline = failureHeadline;
+    }
+}
+exports.BuildGateOptions = BuildGateOptions;
+/**
+ * Run the configured build gate with consistent framing, exiting the process on failure. Single
+ * source of truth: wp-start-upsert-pr and wp-finish-upsert-pr both call THIS (only the BuildGateOptions
+ * differ) so a fix to the gate flow is made once, not in two near-identical copies.
+ */
+function runBuildGate(repoRoot, opts) {
+    const buildCommand = resolveBuildCommand(repoRoot);
+    process.stdout.write('\n' + SEP + opts.label + '\n' + SEP + '\n');
+    process.stdout.write(`Running the build gate. To get it passing, run the SAME command yourself and fix everything it reports:\n\n` +
+        `    ${buildCommand}\n\n`);
+    const buildCode = runConfiguredBuildGate(repoRoot);
+    if (buildCode !== 0) {
+        process.stderr.write(`\n❌ ${opts.failureHeadline}\n\n` +
+            `Run THIS exact command to reproduce and fix all errors, then re-run ${opts.rerunCommand}:\n\n` +
+            `    ${buildCommand}\n\n`);
+        process.exit(buildCode);
+    }
+    process.stdout.write('\n✅ Build passed.\n');
+}
 //# sourceMappingURL=build-affected.js.map

package/src/scripts/workflow/build-affected.js.map

@@ -1 +1 @@
-{"version":3,"file":"build-affected.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/build-affected.ts"],"names":[],"mappings":";;;AAkBA,kDAGC;AAOD,4CAKC;AAQD,wDAEC;AA3CD,iDAA0C;AAC1C,0DAA0D;AAE1D,2FAA2F;AAC3F,0FAA0F;AAC1F,0FAA0F;AAC1F,kCAAkC;AAClC,gGAAgG;AAChG,kGAAkG;AAClG,kGAAkG;AAClG,0FAA0F;AAC7E,QAAA,qBAAqB,GAAG,wEAAwE,CAAC;AAE9G;;;;GAIG;AACH,SAAgB,mBAAmB,CAAC,QAAgB;IAChD,MAAM,UAAU,GAAG,IAAA,8BAAe,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC;IACjE,OAAO,UAAU,KAAK,SAAS,IAAI,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,6BAAqB,CAAC;AACrG,CAAC;AAED;;;;GAIG;AACH,SAAgB,gBAAgB,CAAC,QAAgB,EAAE,YAAqB;IACpE,MAAM,GAAG,GAAG,YAAY,KAAK,SAAS,IAAI,YAAY,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,6BAAqB,CAAC;IAC5G,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mBAAmB,GAAG,MAAM,CAAC,CAAC;IACnD,MAAM,MAAM,GAAG,IAAA,yBAAS,EAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAChF,OAAO,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;GAKG;AACH,SAAgB,sBAAsB,CAAC,QAAgB;IACnD,OAAO,gBAAgB,CAAC,QAAQ,EAAE,IAAA,8BAAe,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;AACrF,CAAC","sourcesContent":["import { spawnSync } from 'child_process';\nimport { loadAndValidate } from '@webpieces/rules-config';\n\n// Single source of truth for the build gate. Both `wp-build-affected` (CI + local) and the\n// merge validation gate (`wp-finish-upsert-pr`) run THIS, so \"what CI runs\" and \"what the\n// PR command runs\" can never drift. nx `affected` only rebuilds changed projects, so this\n// stays fast on a large monorepo.\n// `--base=$(git merge-base origin/main HEAD)` (the fork point) instead of `--base=origin/main`:\n// origin/main rebuilds projects touched by OTHER people's merged PRs (your branch still holds the\n// pre-merge versions, so nx sees them as \"affected\"). The fork point scopes affected to only YOUR\n// branch's changes. The `$(...)` resolves because runBuildAffected runs with shell: true.\nexport const DEFAULT_BUILD_COMMAND = 'pnpm nx affected --target=ci --base=$(git merge-base origin/main HEAD)';\n\n/**\n * Resolve the exact build command this gate will run for a repo: the project's configured\n * PrGateConfig.buildCommand, or the default affected-ci command when none is set. Callers\n * print this so the AI knows precisely which command to run locally to get the gate passing.\n */\nexport function resolveBuildCommand(repoRoot: string): string {\n    const configured = loadAndValidate(repoRoot).prGate.buildCommand;\n    return configured !== undefined && configured.trim() !== '' ? configured : DEFAULT_BUILD_COMMAND;\n}\n\n/**\n * Run the build gate. Returns the process exit code (0 = pass). `buildCommand` overrides\n * the default (sourced from PrGateConfig.buildCommand by callers); empty/undefined uses the\n * default affected-ci command.\n */\nexport function runBuildAffected(repoRoot: string, buildCommand?: string): number {\n    const cmd = buildCommand !== undefined && buildCommand.trim() !== '' ? buildCommand : DEFAULT_BUILD_COMMAND;\n    process.stdout.write(`\\n▶ Build gate: ${cmd}\\n\\n`);\n    const result = spawnSync(cmd, { stdio: 'inherit', cwd: repoRoot, shell: true });\n    return result.status ?? 1;\n}\n\n/**\n * Run the build gate using the project's configured command (PrGateConfig.buildCommand). The\n * finish-upsert-pr gate and wp-start-upsert-pr both call THIS so they provably build with the same\n * command — the resolution the AI validates is built exactly as the PR command builds it.\n * Returns the exit code; callers print their own re-run hint.\n */\nexport function runConfiguredBuildGate(repoRoot: string): number {\n    return runBuildAffected(repoRoot, loadAndValidate(repoRoot).prGate.buildCommand);\n}\n"]}
+{"version":3,"file":"build-affected.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/build-affected.ts"],"names":[],"mappings":";;;AAkBA,kDAGC;AAOD,4CAKC;AAQD,wDAEC;AA2BD,oCAiBC;AAvFD,iDAA0C;AAC1C,0DAA0D;AAE1D,2FAA2F;AAC3F,0FAA0F;AAC1F,0FAA0F;AAC1F,kCAAkC;AAClC,gGAAgG;AAChG,kGAAkG;AAClG,kGAAkG;AAClG,0FAA0F;AAC7E,QAAA,qBAAqB,GAAG,wEAAwE,CAAC;AAE9G;;;;GAIG;AACH,SAAgB,mBAAmB,CAAC,QAAgB;IAChD,MAAM,UAAU,GAAG,IAAA,8BAAe,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC;IACjE,OAAO,UAAU,KAAK,SAAS,IAAI,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,6BAAqB,CAAC;AACrG,CAAC;AAED;;;;GAIG;AACH,SAAgB,gBAAgB,CAAC,QAAgB,EAAE,YAAqB;IACpE,MAAM,GAAG,GAAG,YAAY,KAAK,SAAS,IAAI,YAAY,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,6BAAqB,CAAC;IAC5G,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mBAAmB,GAAG,MAAM,CAAC,CAAC;IACnD,MAAM,MAAM,GAAG,IAAA,yBAAS,EAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAChF,OAAO,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;GAKG;AACH,SAAgB,sBAAsB,CAAC,QAAgB;IACnD,OAAO,gBAAgB,CAAC,QAAQ,EAAE,IAAA,8BAAe,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;AACrF,CAAC;AAED,MAAM,GAAG,GAAG,0DAA0D,CAAC;AAEvE;;;;;GAKG;AACH,MAAa,gBAAgB;IACzB,KAAK,CAAS,CAAY,sCAAsC;IAChE,YAAY,CAAS,CAAK,gDAAgD;IAC1E,eAAe,CAAS,CAAE,gCAAgC;IAE1D,YAAY,KAAa,EAAE,YAAoB,EAAE,eAAuB;QACpE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;IAC3C,CAAC;CACJ;AAVD,4CAUC;AAED;;;;GAIG;AACH,SAAgB,YAAY,CAAC,QAAgB,EAAE,IAAsB;IACjE,MAAM,YAAY,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IACnD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC,KAAK,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC;IAClE,OAAO,CAAC,MAAM,CAAC,KAAK,CAChB,6GAA6G;QAC7G,OAAO,YAAY,MAAM,CAC5B,CAAC;IACF,MAAM,SAAS,GAAG,sBAAsB,CAAC,QAAQ,CAAC,CAAC;IACnD,IAAI,SAAS,KAAK,CAAC,EAAE,CAAC;QAClB,OAAO,CAAC,MAAM,CAAC,KAAK,CAChB,OAAO,IAAI,CAAC,eAAe,MAAM;YACjC,uEAAuE,IAAI,CAAC,YAAY,OAAO;YAC/F,OAAO,YAAY,MAAM,CAC5B,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;AAChD,CAAC","sourcesContent":["import { spawnSync } from 'child_process';\nimport { loadAndValidate } from '@webpieces/rules-config';\n\n// Single source of truth for the build gate. Both `wp-build-affected` (CI + local) and the\n// merge validation gate (`wp-finish-upsert-pr`) run THIS, so \"what CI runs\" and \"what the\n// PR command runs\" can never drift. nx `affected` only rebuilds changed projects, so this\n// stays fast on a large monorepo.\n// `--base=$(git merge-base origin/main HEAD)` (the fork point) instead of `--base=origin/main`:\n// origin/main rebuilds projects touched by OTHER people's merged PRs (your branch still holds the\n// pre-merge versions, so nx sees them as \"affected\"). The fork point scopes affected to only YOUR\n// branch's changes. The `$(...)` resolves because runBuildAffected runs with shell: true.\nexport const DEFAULT_BUILD_COMMAND = 'pnpm nx affected --target=ci --base=$(git merge-base origin/main HEAD)';\n\n/**\n * Resolve the exact build command this gate will run for a repo: the project's configured\n * PrGateConfig.buildCommand, or the default affected-ci command when none is set. Callers\n * print this so the AI knows precisely which command to run locally to get the gate passing.\n */\nexport function resolveBuildCommand(repoRoot: string): string {\n    const configured = loadAndValidate(repoRoot).prGate.buildCommand;\n    return configured !== undefined && configured.trim() !== '' ? configured : DEFAULT_BUILD_COMMAND;\n}\n\n/**\n * Run the build gate. Returns the process exit code (0 = pass). `buildCommand` overrides\n * the default (sourced from PrGateConfig.buildCommand by callers); empty/undefined uses the\n * default affected-ci command.\n */\nexport function runBuildAffected(repoRoot: string, buildCommand?: string): number {\n    const cmd = buildCommand !== undefined && buildCommand.trim() !== '' ? buildCommand : DEFAULT_BUILD_COMMAND;\n    process.stdout.write(`\\n▶ Build gate: ${cmd}\\n\\n`);\n    const result = spawnSync(cmd, { stdio: 'inherit', cwd: repoRoot, shell: true });\n    return result.status ?? 1;\n}\n\n/**\n * Run the build gate using the project's configured command (PrGateConfig.buildCommand). The\n * finish-upsert-pr gate and wp-start-upsert-pr both call THIS so they provably build with the same\n * command — the resolution the AI validates is built exactly as the PR command builds it.\n * Returns the exit code; callers print their own re-run hint.\n */\nexport function runConfiguredBuildGate(repoRoot: string): number {\n    return runBuildAffected(repoRoot, loadAndValidate(repoRoot).prGate.buildCommand);\n}\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\n/**\n * The two facts that differ between the wp-start (advisory) and wp-finish (authoritative) build\n * gates. Everything else — resolve command, run it, print the re-run hint, exit non-zero on failure\n * — is identical, so it lives once in runBuildGate and the difference is passed in here. A class (not\n * an object literal) per the codebase's data-structure convention.\n */\nexport class BuildGateOptions {\n    label: string;            // section header shown above the gate\n    rerunCommand: string;     // command the AI re-runs after fixing the build\n    failureHeadline: string;  // first line printed on failure\n\n    constructor(label: string, rerunCommand: string, failureHeadline: string) {\n        this.label = label;\n        this.rerunCommand = rerunCommand;\n        this.failureHeadline = failureHeadline;\n    }\n}\n\n/**\n * Run the configured build gate with consistent framing, exiting the process on failure. Single\n * source of truth: wp-start-upsert-pr and wp-finish-upsert-pr both call THIS (only the BuildGateOptions\n * differ) so a fix to the gate flow is made once, not in two near-identical copies.\n */\nexport function runBuildGate(repoRoot: string, opts: BuildGateOptions): void {\n    const buildCommand = resolveBuildCommand(repoRoot);\n    process.stdout.write('\\n' + SEP + opts.label + '\\n' + SEP + '\\n');\n    process.stdout.write(\n        `Running the build gate. To get it passing, run the SAME command yourself and fix everything it reports:\\n\\n` +\n        `    ${buildCommand}\\n\\n`,\n    );\n    const buildCode = runConfiguredBuildGate(repoRoot);\n    if (buildCode !== 0) {\n        process.stderr.write(\n            `\\n❌ ${opts.failureHeadline}\\n\\n` +\n            `Run THIS exact command to reproduce and fix all errors, then re-run ${opts.rerunCommand}:\\n\\n` +\n            `    ${buildCommand}\\n\\n`,\n        );\n        process.exit(buildCode);\n    }\n    process.stdout.write('\\n✅ Build passed.\\n');\n}\n"]}

package/src/scripts/workflow/git-exec.d.ts

@@ -4,3 +4,9 @@
  * would operate on stale or wrong state.
  */
 export declare function runGitChecked(args: string[], errMsg: string): void;
+/**
+ * Push HEAD to origin/<currentBranch>. Single source of truth shared by wp-start-upsert-pr and
+ * wp-finish-upsert-pr (they pushed with identical copy-pasted logic). Uses --force-with-lease for an
+ * existing remote branch (the 3-point squash rewrites history) and -u for a brand-new branch.
+ */
+export declare function ensurePushed(currentBranch: string): void;

package/src/scripts/workflow/git-exec.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runGitChecked = runGitChecked;
+exports.ensurePushed = ensurePushed;
 const child_process_1 = require("child_process");
 /**
  * Run a git command that is expected to succeed; abort the process with a clear message
@@ -14,4 +15,18 @@ function runGitChecked(args, errMsg) {
         process.exit(1);
     }
 }
+/**
+ * Push HEAD to origin/<currentBranch>. Single source of truth shared by wp-start-upsert-pr and
+ * wp-finish-upsert-pr (they pushed with identical copy-pasted logic). Uses --force-with-lease for an
+ * existing remote branch (the 3-point squash rewrites history) and -u for a brand-new branch.
+ */
+function ensurePushed(currentBranch) {
+    const remoteExists = (0, child_process_1.spawnSync)('git', ['ls-remote', '--exit-code', '--heads', 'origin', currentBranch]).status === 0;
+    if (remoteExists) {
+        runGitChecked(['push', '--force-with-lease', 'origin', `HEAD:${currentBranch}`], 'Failed to push branch');
+    }
+    else {
+        runGitChecked(['push', '-u', 'origin', `HEAD:${currentBranch}`], 'Failed to push new branch');
+    }
+}
 //# sourceMappingURL=git-exec.js.map

package/src/scripts/workflow/git-exec.js.map

@@ -1 +1 @@
-{"version":3,"file":"git-exec.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/git-exec.ts"],"names":[],"mappings":";;AAOA,sCAMC;AAbD,iDAA0C;AAE1C;;;;GAIG;AACH,SAAgB,aAAa,CAAC,IAAc,EAAE,MAAc;IACxD,MAAM,MAAM,GAAG,IAAA,yBAAS,EAAC,KAAK,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IAC5D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,MAAM,SAAS,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC9F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;AACL,CAAC","sourcesContent":["import { spawnSync } from 'child_process';\n\n/**\n * Run a git command that is expected to succeed; abort the process with a clear message\n * if it fails. Used for fetch/pull/checkout/commit where silently continuing on failure\n * would operate on stale or wrong state.\n */\nexport function runGitChecked(args: string[], errMsg: string): void {\n    const result = spawnSync('git', args, { stdio: 'inherit' });\n    if (result.status !== 0) {\n        process.stderr.write(`❌ ${errMsg} (git ${args.join(' ')} exited ${String(result.status)})\\n`);\n        process.exit(1);\n    }\n}\n"]}
+{"version":3,"file":"git-exec.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/git-exec.ts"],"names":[],"mappings":";;AAOA,sCAMC;AAOD,oCAOC;AA3BD,iDAA0C;AAE1C;;;;GAIG;AACH,SAAgB,aAAa,CAAC,IAAc,EAAE,MAAc;IACxD,MAAM,MAAM,GAAG,IAAA,yBAAS,EAAC,KAAK,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IAC5D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,MAAM,SAAS,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC9F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,SAAgB,YAAY,CAAC,aAAqB;IAC9C,MAAM,YAAY,GAAG,IAAA,yBAAS,EAAC,KAAK,EAAE,CAAC,WAAW,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC;IACrH,IAAI,YAAY,EAAE,CAAC;QACf,aAAa,CAAC,CAAC,MAAM,EAAE,oBAAoB,EAAE,QAAQ,EAAE,QAAQ,aAAa,EAAE,CAAC,EAAE,uBAAuB,CAAC,CAAC;IAC9G,CAAC;SAAM,CAAC;QACJ,aAAa,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,aAAa,EAAE,CAAC,EAAE,2BAA2B,CAAC,CAAC;IAClG,CAAC;AACL,CAAC","sourcesContent":["import { spawnSync } from 'child_process';\n\n/**\n * Run a git command that is expected to succeed; abort the process with a clear message\n * if it fails. Used for fetch/pull/checkout/commit where silently continuing on failure\n * would operate on stale or wrong state.\n */\nexport function runGitChecked(args: string[], errMsg: string): void {\n    const result = spawnSync('git', args, { stdio: 'inherit' });\n    if (result.status !== 0) {\n        process.stderr.write(`❌ ${errMsg} (git ${args.join(' ')} exited ${String(result.status)})\\n`);\n        process.exit(1);\n    }\n}\n\n/**\n * Push HEAD to origin/<currentBranch>. Single source of truth shared by wp-start-upsert-pr and\n * wp-finish-upsert-pr (they pushed with identical copy-pasted logic). Uses --force-with-lease for an\n * existing remote branch (the 3-point squash rewrites history) and -u for a brand-new branch.\n */\nexport function ensurePushed(currentBranch: string): void {\n    const remoteExists = spawnSync('git', ['ls-remote', '--exit-code', '--heads', 'origin', currentBranch]).status === 0;\n    if (remoteExists) {\n        runGitChecked(['push', '--force-with-lease', 'origin', `HEAD:${currentBranch}`], 'Failed to push branch');\n    } else {\n        runGitChecked(['push', '-u', 'origin', `HEAD:${currentBranch}`], 'Failed to push new branch');\n    }\n}\n"]}

package/src/scripts/workflow/git-findForkPoint.js

@@ -8,6 +8,7 @@ const fs = tslib_1.__importStar(require("fs"));
 const path = tslib_1.__importStar(require("path"));
 const rules_config_1 = require("@webpieces/rules-config");
 const git_readAiBranchName_1 = require("./git-readAiBranchName");
+const merge_state_1 = require("./merge-state");
 const SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n';
 function printMergeFromMainError(commit, parent, featureName, currentBranch) {
     process.stderr.write('\n');
@@ -75,7 +76,14 @@ async function findForkPoint(workflow) {
     const featureName = (0, git_readAiBranchName_1.getFeatureName)();
     const currentBranch = (0, child_process_1.execSync)('git branch --show-current', { encoding: 'utf8' }).trim();
     const repoRoot = (0, child_process_1.execSync)('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
-    const outputDir = path.join(repoRoot, rules_config_1.WEBPIECES_TMP_DIR, `${workflow}-${featureName}`);
+    // Single source of truth for the per-feature dir — the SAME nested home the readers use
+    // (git-gatherInfo / merge-start read updatemain-hashes.json from mergeDirFor). Previously this
+    // wrote to the legacy flat `.webpieces/<workflow>-<feature>/` while readers looked under
+    // `.webpieces/merge-info/<feature>/`, so the hash file was written to one path and read from
+    // another. Route both through mergeDirFor/prDirFor so they can never diverge again.
+    const outputDir = workflow === 'review'
+        ? (0, rules_config_1.prDirFor)(repoRoot, featureName)
+        : (0, merge_state_1.mergeDirFor)(repoRoot, featureName);
     const prefix = workflow === 'review' ? 'review-' : 'updatemain-';
     fs.mkdirSync(outputDir, { recursive: true });
     (0, child_process_1.spawnSync)('git', ['fetch', 'origin', 'main'], { stdio: 'ignore' });

package/src/scripts/workflow/git-findForkPoint.js.map

@@ -1 +1 @@
-{"version":3,"file":"git-findForkPoint.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/git-findForkPoint.ts"],"names":[],"mappings":"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","sourcesContent":["import { execSync, spawnSync } from 'child_process';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { WEBPIECES_TMP_DIR } from '@webpieces/rules-config';\nimport { getFeatureName } from './git-readAiBranchName';\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\nfunction printMergeFromMainError(commit: string, parent: string, featureName: string, currentBranch: string): void {\n    process.stderr.write('\\n');\n    process.stderr.write(SEP);\n    process.stderr.write('❌ This branch merged main without pnpm wp-git-update\\n');\n    process.stderr.write(SEP);\n    process.stderr.write('\\n');\n    process.stderr.write(`Merge commit detected: ${commit}\\n`);\n    process.stderr.write(`Parent from main:      ${parent}\\n`);\n    process.stderr.write('\\n');\n    process.stderr.write('This prevents clean squash-merge. To recover, follow these steps:\\n');\n    process.stderr.write('\\n');\n    process.stderr.write('1. Switch to main branch:\\n');\n    process.stderr.write('   git checkout main\\n');\n    process.stderr.write('\\n');\n    process.stderr.write('2. Pull latest changes:\\n');\n    process.stderr.write('   git pull\\n');\n    process.stderr.write('\\n');\n    process.stderr.write('3. Create new branch with a new name:\\n');\n    process.stderr.write(`   git checkout -b ${featureName}-v2\\n`);\n    process.stderr.write('\\n');\n    process.stderr.write('4. Squash merge your old branch:\\n');\n    process.stderr.write(`   git merge --squash ${currentBranch}\\n`);\n    process.stderr.write('\\n');\n    process.stderr.write('5. Commit the squashed changes:\\n');\n    process.stderr.write(`   git add -A && git commit -m \"Squashed from ${currentBranch}\"\\n`);\n    process.stderr.write('\\n');\n    process.stderr.write('6. If you have an existing PR:\\n');\n    process.stderr.write(`   - Create a NEW PR for ${featureName}-v2\\n`);\n    process.stderr.write(`   - Close the old PR for ${currentBranch}\\n`);\n    process.stderr.write('\\n');\n    process.stderr.write(SEP);\n    process.stderr.write('\\n');\n}\n\nfunction checkMergeCommits(mergeCommits: string[], outputDir: string, prefix: string, featureName: string, currentBranch: string): void {\n    process.stderr.write(`Found ${mergeCommits.length} merge commit(s) to check...\\n`);\n\n    for (const commit of mergeCommits) {\n        const parentsResult = spawnSync('git', ['rev-list', '--parents', '-n', '1', commit], { encoding: 'utf8' });\n        const parents = (parentsResult.stdout ?? '').trim().split(' ').slice(1);\n\n        for (const parent of parents) {\n            const ancestorCheck = spawnSync('git', ['merge-base', '--is-ancestor', parent, 'origin/main']);\n            const reverseCheck = spawnSync('git', ['merge-base', '--is-ancestor', 'origin/main', parent]);\n\n            if (ancestorCheck.status === 0 && reverseCheck.status === 0) {\n                const errorJson = JSON.stringify({\n                    error: 'Merge from main detected',\n                    mergeCommit: commit,\n                    parentFromMain: parent,\n                    timestamp: new Date().toISOString(),\n                }, null, 2);\n\n                fs.writeFileSync(path.join(outputDir, `${prefix}forkpoint-error.json`), errorJson + '\\n');\n                printMergeFromMainError(commit, parent, featureName, currentBranch);\n                process.exit(1);\n            }\n        }\n    }\n    process.stderr.write('✅ No improper merges from main detected\\n');\n}\n\nexport async function findForkPoint(workflow: string): Promise<void> {\n    if (workflow !== 'review' && workflow !== 'merge') {\n        process.stderr.write('ERROR: Workflow argument required\\n');\n        process.stderr.write('Usage: git-findForkPoint <workflow>\\n');\n        process.stderr.write(\"  workflow: 'review' or 'merge'\\n\");\n        process.exit(1);\n    }\n\n    const featureName = getFeatureName();\n    const currentBranch = execSync('git branch --show-current', { encoding: 'utf8' }).trim();\n    const repoRoot = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();\n\n    const outputDir = path.join(repoRoot, WEBPIECES_TMP_DIR, `${workflow}-${featureName}`);\n    const prefix = workflow === 'review' ? 'review-' : 'updatemain-';\n    fs.mkdirSync(outputDir, { recursive: true });\n\n    spawnSync('git', ['fetch', 'origin', 'main'], { stdio: 'ignore' });\n\n    const featureHead = execSync('git rev-parse HEAD', { encoding: 'utf8' }).trim();\n    const originMain = execSync('git rev-parse origin/main', { encoding: 'utf8' }).trim();\n\n    process.stderr.write('Finding fork point using git merge-base...\\n');\n\n    const forkPointResult = spawnSync('git', ['merge-base', 'origin/main', 'HEAD'], { encoding: 'utf8' });\n    const forkPoint = (forkPointResult.stdout ?? '').trim();\n\n    if (!forkPoint || forkPointResult.status !== 0) {\n        process.stderr.write('ERROR: Could not find common ancestor with origin/main\\n');\n        process.exit(1);\n    }\n\n    process.stderr.write(`✅ Fork point found: ${forkPoint.slice(0, 7)}\\n`);\n    process.stderr.write('Checking for improper merges from main...\\n');\n\n    const mergeCommitsResult = spawnSync('git', ['log', `${forkPoint}..HEAD`, '--merges', '--format=%H'], { encoding: 'utf8' });\n    const mergeCommitsRaw = (mergeCommitsResult.stdout ?? '').trim();\n    const mergeCommits = mergeCommitsRaw ? mergeCommitsRaw.split('\\n') : [];\n\n    if (mergeCommits.length > 0) {\n        checkMergeCommits(mergeCommits, outputDir, prefix, featureName, currentBranch);\n    } else {\n        process.stderr.write('✅ No merge commits found (clean history)\\n');\n    }\n\n    const hashesJson = JSON.stringify({\n        hashForkPoint: forkPoint,\n        hashFeatureHead: featureHead,\n        hashMainHead: originMain,\n        timestamp: new Date().toISOString(),\n    }, null, 2);\n\n    fs.writeFileSync(path.join(outputDir, `${prefix}hashes.json`), hashesJson + '\\n');\n    process.stderr.write(`✅ Hash points written to: ${outputDir}/${prefix}hashes.json\\n`);\n}\n\nexport async function main(): Promise<void> {\n    await findForkPoint(process.argv[2] ?? '');\n}\n\nif (require.main === module) {\n    main().catch((err) => {\n        const message = err instanceof Error ? err.message : String(err);\n        process.stderr.write(message + '\\n');\n        process.exit(1);\n    });\n}\n"]}
+{"version":3,"file":"git-findForkPoint.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/git-findForkPoint.ts"],"names":[],"mappings":";;AAuEA,sCA4DC;AAED,oBAEC;;AAvID,iDAAoD;AACpD,+CAAyB;AACzB,mDAA6B;AAC7B,0DAAmD;AACnD,iEAAwD;AACxD,+CAA4C;AAE5C,MAAM,GAAG,GAAG,0DAA0D,CAAC;AAEvE,SAAS,uBAAuB,CAAC,MAAc,EAAE,MAAc,EAAE,WAAmB,EAAE,aAAqB;IACvG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC/E,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,0BAA0B,MAAM,IAAI,CAAC,CAAC;IAC3D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,0BAA0B,MAAM,IAAI,CAAC,CAAC;IAC3D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qEAAqE,CAAC,CAAC;IAC5F,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACpD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC/C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAClD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IACtC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAChE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,sBAAsB,WAAW,OAAO,CAAC,CAAC;IAC/D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;IAC3D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,yBAAyB,aAAa,IAAI,CAAC,CAAC;IACjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAC;IAC1D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iDAAiD,aAAa,KAAK,CAAC,CAAC;IAC1F,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACzD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,4BAA4B,WAAW,OAAO,CAAC,CAAC;IACrE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,6BAA6B,aAAa,IAAI,CAAC,CAAC;IACrE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,iBAAiB,CAAC,YAAsB,EAAE,SAAiB,EAAE,MAAc,EAAE,WAAmB,EAAE,aAAqB;IAC5H,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,YAAY,CAAC,MAAM,gCAAgC,CAAC,CAAC;IAEnF,KAAK,MAAM,MAAM,IAAI,YAAY,EAAE,CAAC;QAChC,MAAM,aAAa,GAAG,IAAA,yBAAS,EAAC,KAAK,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;QAC3G,MAAM,OAAO,GAAG,CAAC,aAAa,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAExE,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC3B,MAAM,aAAa,GAAG,IAAA,yBAAS,EAAC,KAAK,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;YAC/F,MAAM,YAAY,GAAG,IAAA,yBAAS,EAAC,KAAK,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,CAAC,CAAC,CAAC;YAE9F,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC1D,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;oBAC7B,KAAK,EAAE,0BAA0B;oBACjC,WAAW,EAAE,MAAM;oBACnB,cAAc,EAAE,MAAM;oBACtB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;iBACtC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;gBAEZ,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,MAAM,sBAAsB,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC,CAAC;gBAC1F,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC;gBACpE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACpB,CAAC;QACL,CAAC;IACL,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;AACtE,CAAC;AAEM,KAAK,UAAU,aAAa,CAAC,QAAgB;IAChD,IAAI,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QAChD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qCAAqC,CAAC,CAAC;QAC5D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAC9D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAC;QAC1D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IAED,MAAM,WAAW,GAAG,IAAA,qCAAc,GAAE,CAAC;IACrC,MAAM,aAAa,GAAG,IAAA,wBAAQ,EAAC,2BAA2B,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACzF,MAAM,QAAQ,GAAG,IAAA,wBAAQ,EAAC,+BAA+B,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAExF,wFAAwF;IACxF,+FAA+F;IAC/F,yFAAyF;IACzF,6FAA6F;IAC7F,oFAAoF;IACpF,MAAM,SAAS,GAAG,QAAQ,KAAK,QAAQ;QACnC,CAAC,CAAC,IAAA,uBAAQ,EAAC,QAAQ,EAAE,WAAW,CAAC;QACjC,CAAC,CAAC,IAAA,yBAAW,EAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC;IACjE,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE7C,IAAA,yBAAS,EAAC,KAAK,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;IAEnE,MAAM,WAAW,GAAG,IAAA,wBAAQ,EAAC,oBAAoB,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAChF,MAAM,UAAU,GAAG,IAAA,wBAAQ,EAAC,2BAA2B,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAEtF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAErE,MAAM,eAAe,GAAG,IAAA,yBAAS,EAAC,KAAK,EAAE,CAAC,YAAY,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IACtG,MAAM,SAAS,GAAG,CAAC,eAAe,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAExD,IAAI,CAAC,SAAS,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,0DAA0D,CAAC,CAAC;QACjF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uBAAuB,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IACvE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,6CAA6C,CAAC,CAAC;IAEpE,MAAM,kBAAkB,GAAG,IAAA,yBAAS,EAAC,KAAK,EAAE,CAAC,KAAK,EAAE,GAAG,SAAS,QAAQ,EAAE,UAAU,EAAE,aAAa,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5H,MAAM,eAAe,GAAG,CAAC,kBAAkB,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACjE,MAAM,YAAY,GAAG,eAAe,CAAC,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAExE,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,iBAAiB,CAAC,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC;IACnF,CAAC;SAAM,CAAC;QACJ,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,4CAA4C,CAAC,CAAC;IACvE,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9B,aAAa,EAAE,SAAS;QACxB,eAAe,EAAE,WAAW;QAC5B,YAAY,EAAE,UAAU;QACxB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACtC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAEZ,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,MAAM,aAAa,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC,CAAC;IAClF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,6BAA6B,SAAS,IAAI,MAAM,eAAe,CAAC,CAAC;AAC1F,CAAC;AAEM,KAAK,UAAU,IAAI;IACtB,MAAM,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;IAC1B,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QACjB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;QACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC,CAAC,CAAC;AACP,CAAC","sourcesContent":["import { execSync, spawnSync } from 'child_process';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { prDirFor } from '@webpieces/rules-config';\nimport { getFeatureName } from './git-readAiBranchName';\nimport { mergeDirFor } from './merge-state';\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\nfunction printMergeFromMainError(commit: string, parent: string, featureName: string, currentBranch: string): void {\n    process.stderr.write('\\n');\n    process.stderr.write(SEP);\n    process.stderr.write('❌ This branch merged main without pnpm wp-git-update\\n');\n    process.stderr.write(SEP);\n    process.stderr.write('\\n');\n    process.stderr.write(`Merge commit detected: ${commit}\\n`);\n    process.stderr.write(`Parent from main:      ${parent}\\n`);\n    process.stderr.write('\\n');\n    process.stderr.write('This prevents clean squash-merge. To recover, follow these steps:\\n');\n    process.stderr.write('\\n');\n    process.stderr.write('1. Switch to main branch:\\n');\n    process.stderr.write('   git checkout main\\n');\n    process.stderr.write('\\n');\n    process.stderr.write('2. Pull latest changes:\\n');\n    process.stderr.write('   git pull\\n');\n    process.stderr.write('\\n');\n    process.stderr.write('3. Create new branch with a new name:\\n');\n    process.stderr.write(`   git checkout -b ${featureName}-v2\\n`);\n    process.stderr.write('\\n');\n    process.stderr.write('4. Squash merge your old branch:\\n');\n    process.stderr.write(`   git merge --squash ${currentBranch}\\n`);\n    process.stderr.write('\\n');\n    process.stderr.write('5. Commit the squashed changes:\\n');\n    process.stderr.write(`   git add -A && git commit -m \"Squashed from ${currentBranch}\"\\n`);\n    process.stderr.write('\\n');\n    process.stderr.write('6. If you have an existing PR:\\n');\n    process.stderr.write(`   - Create a NEW PR for ${featureName}-v2\\n`);\n    process.stderr.write(`   - Close the old PR for ${currentBranch}\\n`);\n    process.stderr.write('\\n');\n    process.stderr.write(SEP);\n    process.stderr.write('\\n');\n}\n\nfunction checkMergeCommits(mergeCommits: string[], outputDir: string, prefix: string, featureName: string, currentBranch: string): void {\n    process.stderr.write(`Found ${mergeCommits.length} merge commit(s) to check...\\n`);\n\n    for (const commit of mergeCommits) {\n        const parentsResult = spawnSync('git', ['rev-list', '--parents', '-n', '1', commit], { encoding: 'utf8' });\n        const parents = (parentsResult.stdout ?? '').trim().split(' ').slice(1);\n\n        for (const parent of parents) {\n            const ancestorCheck = spawnSync('git', ['merge-base', '--is-ancestor', parent, 'origin/main']);\n            const reverseCheck = spawnSync('git', ['merge-base', '--is-ancestor', 'origin/main', parent]);\n\n            if (ancestorCheck.status === 0 && reverseCheck.status === 0) {\n                const errorJson = JSON.stringify({\n                    error: 'Merge from main detected',\n                    mergeCommit: commit,\n                    parentFromMain: parent,\n                    timestamp: new Date().toISOString(),\n                }, null, 2);\n\n                fs.writeFileSync(path.join(outputDir, `${prefix}forkpoint-error.json`), errorJson + '\\n');\n                printMergeFromMainError(commit, parent, featureName, currentBranch);\n                process.exit(1);\n            }\n        }\n    }\n    process.stderr.write('✅ No improper merges from main detected\\n');\n}\n\nexport async function findForkPoint(workflow: string): Promise<void> {\n    if (workflow !== 'review' && workflow !== 'merge') {\n        process.stderr.write('ERROR: Workflow argument required\\n');\n        process.stderr.write('Usage: git-findForkPoint <workflow>\\n');\n        process.stderr.write(\"  workflow: 'review' or 'merge'\\n\");\n        process.exit(1);\n    }\n\n    const featureName = getFeatureName();\n    const currentBranch = execSync('git branch --show-current', { encoding: 'utf8' }).trim();\n    const repoRoot = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();\n\n    // Single source of truth for the per-feature dir — the SAME nested home the readers use\n    // (git-gatherInfo / merge-start read updatemain-hashes.json from mergeDirFor). Previously this\n    // wrote to the legacy flat `.webpieces/<workflow>-<feature>/` while readers looked under\n    // `.webpieces/merge-info/<feature>/`, so the hash file was written to one path and read from\n    // another. Route both through mergeDirFor/prDirFor so they can never diverge again.\n    const outputDir = workflow === 'review'\n        ? prDirFor(repoRoot, featureName)\n        : mergeDirFor(repoRoot, featureName);\n    const prefix = workflow === 'review' ? 'review-' : 'updatemain-';\n    fs.mkdirSync(outputDir, { recursive: true });\n\n    spawnSync('git', ['fetch', 'origin', 'main'], { stdio: 'ignore' });\n\n    const featureHead = execSync('git rev-parse HEAD', { encoding: 'utf8' }).trim();\n    const originMain = execSync('git rev-parse origin/main', { encoding: 'utf8' }).trim();\n\n    process.stderr.write('Finding fork point using git merge-base...\\n');\n\n    const forkPointResult = spawnSync('git', ['merge-base', 'origin/main', 'HEAD'], { encoding: 'utf8' });\n    const forkPoint = (forkPointResult.stdout ?? '').trim();\n\n    if (!forkPoint || forkPointResult.status !== 0) {\n        process.stderr.write('ERROR: Could not find common ancestor with origin/main\\n');\n        process.exit(1);\n    }\n\n    process.stderr.write(`✅ Fork point found: ${forkPoint.slice(0, 7)}\\n`);\n    process.stderr.write('Checking for improper merges from main...\\n');\n\n    const mergeCommitsResult = spawnSync('git', ['log', `${forkPoint}..HEAD`, '--merges', '--format=%H'], { encoding: 'utf8' });\n    const mergeCommitsRaw = (mergeCommitsResult.stdout ?? '').trim();\n    const mergeCommits = mergeCommitsRaw ? mergeCommitsRaw.split('\\n') : [];\n\n    if (mergeCommits.length > 0) {\n        checkMergeCommits(mergeCommits, outputDir, prefix, featureName, currentBranch);\n    } else {\n        process.stderr.write('✅ No merge commits found (clean history)\\n');\n    }\n\n    const hashesJson = JSON.stringify({\n        hashForkPoint: forkPoint,\n        hashFeatureHead: featureHead,\n        hashMainHead: originMain,\n        timestamp: new Date().toISOString(),\n    }, null, 2);\n\n    fs.writeFileSync(path.join(outputDir, `${prefix}hashes.json`), hashesJson + '\\n');\n    process.stderr.write(`✅ Hash points written to: ${outputDir}/${prefix}hashes.json\\n`);\n}\n\nexport async function main(): Promise<void> {\n    await findForkPoint(process.argv[2] ?? '');\n}\n\nif (require.main === module) {\n    main().catch((err) => {\n        const message = err instanceof Error ? err.message : String(err);\n        process.stderr.write(message + '\\n');\n        process.exit(1);\n    });\n}\n"]}

package/src/scripts/workflow/merge-end.d.ts

@@ -0,0 +1,7 @@
+import { MergeContext } from './merge-start';
+/**
+ * Complete a 3-point squash merge. `conflictedFiles` non-null means a conflict was resolved by the AI
+ * and must be validated + committed before finalizing; null means a clean merge that merge-START
+ * already committed (finalize only). Either way the merge ends fully finalized on the feature branch.
+ */
+export declare function mergeEnd(repoRoot: string, mergeDir: string, ctx: MergeContext, conflictedFiles: string[] | null): Promise<void>;

package/src/scripts/workflow/merge-end.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeEnd = mergeEnd;
+const tslib_1 = require("tslib");
+const child_process_1 = require("child_process");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const rules_config_1 = require("@webpieces/rules-config");
+const cleanTmp_1 = require("./cleanTmp");
+const git_exec_1 = require("./git-exec");
+const merge_state_1 = require("./merge-state");
+// merge-END: the second half of the 3-point squash-merge lifecycle, symmetric with merge-START. Given
+// the branch context, it (optionally) validates + commits the AI's conflict resolution, then ALWAYS
+// finalizes the merge — swaps `<branch>Squash` back over the feature branch, force-pushes, stamps a
+// clean main-sync status, clears the marker and sweeps stale tmp. Both wp-git-update (clean path /
+// validated resume) and wp-finish-upsert-pr (conflict resolution) call THIS, so finalization happens
+// in exactly one place and the conflict path can no longer post a PR from the un-swapped squash branch.
+const SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n';
+// Validate the AI's resolution of the conflicted files — the part of the process the AI owns
+// (branch creation/finalization is the script's job, so it is not re-checked here). Exits the
+// process with a fix instruction on any failure; returns only when all three checks pass.
+function validateResolution(repoRoot, mergeDir, conflictedFiles) {
+    // 1. Scoped conflict-marker scan (only the conflicted files — O(conflicts), not O(repo)).
+    const scan = (0, merge_state_1.scanConflictMarkers)(repoRoot, conflictedFiles);
+    if (!scan.clean) {
+        process.stderr.write('❌ Unresolved conflict markers (<<<<<<< / ======= / >>>>>>>) remain in:\n');
+        for (const file of scan.filesWithMarkers)
+            process.stderr.write(`  - ${file}\n`);
+        process.stderr.write('\nResolve them, then re-run: pnpm wp-finish-upsert-pr\n');
+        process.exit(1);
+    }
+    // 2. Ensure git itself has no remaining unmerged entries.
+    const unmerged = (0, child_process_1.execSync)('git diff --name-only --diff-filter=U', { encoding: 'utf8' }).trim();
+    if (unmerged !== '') {
+        process.stderr.write('❌ Git still reports unmerged files:\n' + unmerged + '\n');
+        process.stderr.write('\nResolve and `git add` them, then re-run: pnpm wp-finish-upsert-pr\n');
+        process.exit(1);
+    }
+    process.stdout.write('✅ No conflict markers in resolved files.\n');
+    // 3. Explanation check — every conflicted file must have a non-empty merge-explanation.md in
+    // its per-file context dir, proving the AI deliberately 3-point merged it (and recording how)
+    // rather than blindly taking one side. A sidecar file works for any type, incl. JSON/deletes.
+    const explanations = (0, merge_state_1.scanMergeExplanations)(mergeDir, conflictedFiles);
+    if (!explanations.clean) {
+        process.stderr.write(`❌ Missing/empty merge explanation (${rules_config_1.MERGE_EXPLANATION_FILE}) for:\n`);
+        for (const file of explanations.filesWithMarkers) {
+            process.stderr.write(`  - ${file}\n      → ${path.join((0, merge_state_1.perFileContextDir)(mergeDir, file), rules_config_1.MERGE_EXPLANATION_FILE)}\n`);
+        }
+        process.stderr.write('\nWrite a few sentences on how you resolved each (which side, what you combined, why),\n' +
+            'then re-run: pnpm wp-finish-upsert-pr\n');
+        process.exit(1);
+    }
+    process.stdout.write('✅ Merge explanations present for all resolved files.\n');
+}
+// Swap the squash branch back over the feature branch, force-push, and stamp clean main-sync.
+function finalizeBranch(ctx) {
+    process.stdout.write('\n' + SEP + '🗑️  Finalizing\n' + SEP + '\n');
+    (0, git_exec_1.runGitChecked)(['branch', '-D', ctx.currentBranch], 'Failed to delete old feature branch');
+    const remoteExists = (0, child_process_1.spawnSync)('git', ['ls-remote', '--exit-code', '--heads', 'origin', ctx.currentBranch]).status === 0;
+    if (remoteExists) {
+        process.stdout.write(ctx.prNumber ? `Updating PR #${ctx.prNumber} (force-with-lease)...\n` : 'Updating remote branch (force-with-lease)...\n');
+        (0, git_exec_1.runGitChecked)(['push', '-u', '--force-with-lease', 'origin', `${ctx.squashBranch}:${ctx.currentBranch}`], 'Failed to push to origin');
+    }
+    else {
+        process.stdout.write('No remote branch — local only.\n');
+    }
+    (0, git_exec_1.runGitChecked)(['checkout', ctx.squashBranch], 'Failed to checkout squash branch');
+    (0, git_exec_1.runGitChecked)(['branch', '-m', ctx.currentBranch], 'Failed to rename squash branch');
+    // Branch now contains origin/main — stamp a clean main-sync status so the feature-branch-guard
+    // unblocks edits immediately (no wait for the async refresher).
+    (0, rules_config_1.stampCleanMainSyncStatus)((0, child_process_1.execSync)('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim());
+    process.stdout.write(`\n✅ Branch ${ctx.currentBranch} updated from main. Backup: ${ctx.backupBranch}\n`);
+    process.stdout.write(`   Delete backup when safe: git branch -D ${ctx.backupBranch}\n\n`);
+}
+/**
+ * Complete a 3-point squash merge. `conflictedFiles` non-null means a conflict was resolved by the AI
+ * and must be validated + committed before finalizing; null means a clean merge that merge-START
+ * already committed (finalize only). Either way the merge ends fully finalized on the feature branch.
+ */
+async function mergeEnd(repoRoot, mergeDir, ctx, conflictedFiles) {
+    if (conflictedFiles !== null) {
+        process.stdout.write('\n' + SEP + '🔎 Validating Merge Resolution\n' + SEP + '\n');
+        validateResolution(repoRoot, mergeDir, conflictedFiles);
+        (0, git_exec_1.runGitChecked)(['add', '-A'], 'Failed to stage resolved files');
+        const nothingStaged = (0, child_process_1.spawnSync)('git', ['diff-index', '--quiet', '--cached', 'HEAD', '--']).status === 0;
+        if (!nothingStaged) {
+            (0, git_exec_1.runGitChecked)(['commit', '-m', `Squash merge of ${ctx.currentBranch} (conflicts resolved)`], 'Failed to commit resolved merge');
+        }
+        fs.writeFileSync(path.join(mergeDir, 'conflicts-resolved'), '');
+        process.stdout.write('\n✅ Merge validated and committed.\n');
+    }
+    finalizeBranch(ctx);
+    (0, merge_state_1.clearMergeMarker)(mergeDir);
+    await (0, cleanTmp_1.main)();
+}
+//# sourceMappingURL=merge-end.js.map

package/src/scripts/workflow/merge-end.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-end.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/merge-end.ts"],"names":[],"mappings":"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","sourcesContent":["import { execSync, spawnSync } from 'child_process';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { MERGE_EXPLANATION_FILE, stampCleanMainSyncStatus } from '@webpieces/rules-config';\nimport { main as cleanTmp } from './cleanTmp';\nimport { runGitChecked } from './git-exec';\nimport { MergeContext } from './merge-start';\nimport { clearMergeMarker, perFileContextDir, scanConflictMarkers, scanMergeExplanations } from './merge-state';\n\n// merge-END: the second half of the 3-point squash-merge lifecycle, symmetric with merge-START. Given\n// the branch context, it (optionally) validates + commits the AI's conflict resolution, then ALWAYS\n// finalizes the merge — swaps `<branch>Squash` back over the feature branch, force-pushes, stamps a\n// clean main-sync status, clears the marker and sweeps stale tmp. Both wp-git-update (clean path /\n// validated resume) and wp-finish-upsert-pr (conflict resolution) call THIS, so finalization happens\n// in exactly one place and the conflict path can no longer post a PR from the un-swapped squash branch.\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\n// Validate the AI's resolution of the conflicted files — the part of the process the AI owns\n// (branch creation/finalization is the script's job, so it is not re-checked here). Exits the\n// process with a fix instruction on any failure; returns only when all three checks pass.\nfunction validateResolution(repoRoot: string, mergeDir: string, conflictedFiles: string[]): void {\n    // 1. Scoped conflict-marker scan (only the conflicted files — O(conflicts), not O(repo)).\n    const scan = scanConflictMarkers(repoRoot, conflictedFiles);\n    if (!scan.clean) {\n        process.stderr.write('❌ Unresolved conflict markers (<<<<<<< / ======= / >>>>>>>) remain in:\\n');\n        for (const file of scan.filesWithMarkers) process.stderr.write(`  - ${file}\\n`);\n        process.stderr.write('\\nResolve them, then re-run: pnpm wp-finish-upsert-pr\\n');\n        process.exit(1);\n    }\n\n    // 2. Ensure git itself has no remaining unmerged entries.\n    const unmerged = execSync('git diff --name-only --diff-filter=U', { encoding: 'utf8' }).trim();\n    if (unmerged !== '') {\n        process.stderr.write('❌ Git still reports unmerged files:\\n' + unmerged + '\\n');\n        process.stderr.write('\\nResolve and `git add` them, then re-run: pnpm wp-finish-upsert-pr\\n');\n        process.exit(1);\n    }\n    process.stdout.write('✅ No conflict markers in resolved files.\\n');\n\n    // 3. Explanation check — every conflicted file must have a non-empty merge-explanation.md in\n    // its per-file context dir, proving the AI deliberately 3-point merged it (and recording how)\n    // rather than blindly taking one side. A sidecar file works for any type, incl. JSON/deletes.\n    const explanations = scanMergeExplanations(mergeDir, conflictedFiles);\n    if (!explanations.clean) {\n        process.stderr.write(`❌ Missing/empty merge explanation (${MERGE_EXPLANATION_FILE}) for:\\n`);\n        for (const file of explanations.filesWithMarkers) {\n            process.stderr.write(`  - ${file}\\n      → ${path.join(perFileContextDir(mergeDir, file), MERGE_EXPLANATION_FILE)}\\n`);\n        }\n        process.stderr.write(\n            '\\nWrite a few sentences on how you resolved each (which side, what you combined, why),\\n' +\n            'then re-run: pnpm wp-finish-upsert-pr\\n',\n        );\n        process.exit(1);\n    }\n    process.stdout.write('✅ Merge explanations present for all resolved files.\\n');\n}\n\n// Swap the squash branch back over the feature branch, force-push, and stamp clean main-sync.\nfunction finalizeBranch(ctx: MergeContext): void {\n    process.stdout.write('\\n' + SEP + '🗑️  Finalizing\\n' + SEP + '\\n');\n    runGitChecked(['branch', '-D', ctx.currentBranch], 'Failed to delete old feature branch');\n\n    const remoteExists = spawnSync('git', ['ls-remote', '--exit-code', '--heads', 'origin', ctx.currentBranch]).status === 0;\n    if (remoteExists) {\n        process.stdout.write(ctx.prNumber ? `Updating PR #${ctx.prNumber} (force-with-lease)...\\n` : 'Updating remote branch (force-with-lease)...\\n');\n        runGitChecked(['push', '-u', '--force-with-lease', 'origin', `${ctx.squashBranch}:${ctx.currentBranch}`], 'Failed to push to origin');\n    } else {\n        process.stdout.write('No remote branch — local only.\\n');\n    }\n    runGitChecked(['checkout', ctx.squashBranch], 'Failed to checkout squash branch');\n    runGitChecked(['branch', '-m', ctx.currentBranch], 'Failed to rename squash branch');\n\n    // Branch now contains origin/main — stamp a clean main-sync status so the feature-branch-guard\n    // unblocks edits immediately (no wait for the async refresher).\n    stampCleanMainSyncStatus(execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim());\n\n    process.stdout.write(`\\n✅ Branch ${ctx.currentBranch} updated from main. Backup: ${ctx.backupBranch}\\n`);\n    process.stdout.write(`   Delete backup when safe: git branch -D ${ctx.backupBranch}\\n\\n`);\n}\n\n/**\n * Complete a 3-point squash merge. `conflictedFiles` non-null means a conflict was resolved by the AI\n * and must be validated + committed before finalizing; null means a clean merge that merge-START\n * already committed (finalize only). Either way the merge ends fully finalized on the feature branch.\n */\nexport async function mergeEnd(\n    repoRoot: string, mergeDir: string, ctx: MergeContext, conflictedFiles: string[] | null,\n): Promise<void> {\n    if (conflictedFiles !== null) {\n        process.stdout.write('\\n' + SEP + '🔎 Validating Merge Resolution\\n' + SEP + '\\n');\n        validateResolution(repoRoot, mergeDir, conflictedFiles);\n        runGitChecked(['add', '-A'], 'Failed to stage resolved files');\n\n        const nothingStaged = spawnSync('git', ['diff-index', '--quiet', '--cached', 'HEAD', '--']).status === 0;\n        if (!nothingStaged) {\n            runGitChecked(\n                ['commit', '-m', `Squash merge of ${ctx.currentBranch} (conflicts resolved)`],\n                'Failed to commit resolved merge',\n            );\n        }\n        fs.writeFileSync(path.join(mergeDir, 'conflicts-resolved'), '');\n        process.stdout.write('\\n✅ Merge validated and committed.\\n');\n    }\n\n    finalizeBranch(ctx);\n    clearMergeMarker(mergeDir);\n    await cleanTmp();\n}\n"]}

package/src/scripts/workflow/merge-start.d.ts

@@ -0,0 +1,13 @@
+export declare class MergeContext {
+    currentBranch: string;
+    squashBranch: string;
+    backupBranch: string;
+    prNumber: string;
+    constructor(currentBranch: string, squashBranch: string, backupBranch: string, prNumber: string);
+}
+export declare class MergeStartResult {
+    status: 'clean' | 'conflict';
+    context: MergeContext | null;
+    constructor(status: 'clean' | 'conflict', context: MergeContext | null);
+}
+export declare function mergeStart(repoRoot: string, mergeDir: string): Promise<MergeStartResult>;

package/src/scripts/workflow/merge-start.js

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MergeStartResult = exports.MergeContext = void 0;
+exports.mergeStart = mergeStart;
+const tslib_1 = require("tslib");
+const child_process_1 = require("child_process");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const rules_config_1 = require("@webpieces/rules-config");
+const git_gatherInfo_1 = require("../git-gatherInfo");
+const git_exec_1 = require("./git-exec");
+const merge_state_1 = require("./merge-state");
+// merge-START: the first half of the 3-point squash-merge lifecycle. Brings origin/main into a fresh
+// `<branch>Squash`, and on conflict writes the 3-point context files + the unvalidated marker + the
+// process doc, then hands control back to the AI. On a clean merge it commits the squash and returns
+// the branch context so the caller (wp-git-update) can run merge-END to finalize. It NEVER finalizes
+// or posts a PR — that is merge-END's / wp-finish-upsert-pr's job. Shared so wp-git-update (and, via
+// it, wp-start-upsert-pr) all set up a merge through one code path.
+const SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n';
+// The four branch names merge-END needs to finalize a merge (swap squash→feature, push, clean up).
+class MergeContext {
+    currentBranch;
+    squashBranch;
+    backupBranch;
+    prNumber;
+    constructor(currentBranch, squashBranch, backupBranch, prNumber) {
+        this.currentBranch = currentBranch;
+        this.squashBranch = squashBranch;
+        this.backupBranch = backupBranch;
+        this.prNumber = prNumber;
+    }
+}
+exports.MergeContext = MergeContext;
+// Outcome of merge-start: 'clean' carries the context for merge-END to finalize; 'conflict' means the
+// marker + context files were written and the caller should hand back to the AI (exit 2).
+class MergeStartResult {
+    status;
+    context;
+    constructor(status, context) {
+        this.status = status;
+        this.context = context;
+    }
+}
+exports.MergeStartResult = MergeStartResult;
+function detectPr(currentBranch) {
+    const result = (0, child_process_1.spawnSync)('gh', ['pr', 'list', '--head', currentBranch, '--json', 'number', '--jq', '.[0].number'], { encoding: 'utf8' });
+    return result.status === 0 ? (result.stdout ?? '').trim() : '';
+}
+function createBackup(currentBranch) {
+    process.stdout.write('\n' + SEP + '💾 Creating Incremental Backup\n' + SEP + '\n');
+    let n = 1;
+    while ((0, child_process_1.spawnSync)('git', ['show-ref', '--verify', '--quiet', `refs/heads/${currentBranch}Backup${n}`]).status === 0) {
+        n += 1;
+    }
+    const backupBranch = `${currentBranch}Backup${n}`;
+    (0, git_exec_1.runGitChecked)(['checkout', '-b', backupBranch], 'Failed to create backup branch');
+    (0, git_exec_1.runGitChecked)(['checkout', currentBranch], 'Failed to return to feature branch');
+    process.stdout.write(`✅ Backup created: ${backupBranch}\n\n`);
+    return backupBranch;
+}
+function saveConflictContext(conflictedFiles, mergeDir, forkPoint, featureHead, mainHead) {
+    for (const file of conflictedFiles) {
+        const fileDir = (0, merge_state_1.perFileContextDir)(mergeDir, file);
+        fs.mkdirSync(fileDir, { recursive: true });
+        const fork = (0, child_process_1.spawnSync)('git', ['show', `${forkPoint}:${file}`], { encoding: 'utf8' });
+        fs.writeFileSync(path.join(fileDir, 'A-forkpoint.txt'), fork.status === 0 ? (fork.stdout ?? '') : '(file did not exist)\n');
+        const feature = (0, child_process_1.spawnSync)('git', ['show', `${featureHead}:${file}`], { encoding: 'utf8' });
+        fs.writeFileSync(path.join(fileDir, 'B-feature.txt'), feature.status === 0 ? (feature.stdout ?? '') : '(file did not exist)\n');
+        const main = (0, child_process_1.spawnSync)('git', ['show', `${mainHead}:${file}`], { encoding: 'utf8' });
+        fs.writeFileSync(path.join(fileDir, 'C-main.txt'), main.status === 0 ? (main.stdout ?? '') : '(file did not exist)\n');
+        const ba = (0, child_process_1.spawnSync)('git', ['diff', forkPoint, featureHead, '--', file], { encoding: 'utf8' });
+        fs.writeFileSync(path.join(fileDir, 'B-A.diff'), ba.stdout ?? '');
+        const ca = (0, child_process_1.spawnSync)('git', ['diff', forkPoint, mainHead, '--', file], { encoding: 'utf8' });
+        fs.writeFileSync(path.join(fileDir, 'C-A.diff'), ca.stdout ?? '');
+    }
+}
+// Single source of truth for the merge process. The script WRITES it at conflict time (rather
+// than the AI relying on a separate hand-maintained doc), parameterized with the live MERGE_DIR
+// and conflicted-file list, so the instructions can never drift from the actual layout. The body
+// is a template constant with {{...}} placeholders so this stays a small filler function.
+const MERGE_PROCESS_TEMPLATE = `# AI-Assisted Squash-Merge Conflict Resolution (generated)
+
+This file was generated by \`pnpm wp-git-update\` when the 3-point squash-merge hit conflicts.
+It is the single source of truth for the merge process — follow it exactly.
+
+You are on branch \`{{SQUASH_BRANCH}}\` with conflict markers in the working tree.
+\`MERGE_DIR = {{MERGE_DIR}}\`
+
+## How the gate works
+
+- Resolve every conflicted file in the working tree.
+- Run **\`pnpm wp-finish-upsert-pr\`** — the validation + finish gate. It scans for leftover conflict
+  markers, checks each conflicted file has a written merge explanation, runs the \`nx affected\`
+  build, and — only if all pass — stages, commits, then renders the dashboard and creates/updates the PR.
+- **Do NOT run \`git add\` / \`git commit\` / \`git push\` / \`gh pr\` yourself.** They are blocked by
+  the \`merge-in-progress-guard\` hook until the gate validates. The gate does the commit.
+
+## STEP 1 — Load the merge context
+
+Per conflicted file, \`MERGE_DIR/updatemain-<safe_path>/\` holds (\`<safe_path>\` = path with \`/\`→\`__\`):
+
+\`\`\`
+A-forkpoint.txt   # file at fork point (base)
+B-feature.txt     # file on your feature branch
+C-main.txt        # file on main
+B-A.diff          # what your feature changed (B−A)
+C-A.diff          # what main changed (C−A)
+\`\`\`
+
+\`updatemain-hashes.json\` holds A/B/C commit hashes. To see why main changed:
+\`git log <A>..<C> --oneline\`.
+
+## STEP 2 — Resolve each conflicted file
+
+For each file: read the working-tree file (the markers) and its \`B-A.diff\` / \`C-A.diff\` (intent),
+then Edit to the resolved version, removing ALL conflict markers.
+
+Strategies: goals align & non-overlapping → merge both · one side removes what the other modifies
+→ prefer the removal · same lines, simple (imports/format) → merge both · same lines, complex or
+conflicting goals → ask the user · feature re-implements what main already squashed → prefer
+main's, then re-apply only the genuinely new feature work.
+
+**Then write a merge explanation** for each conflicted file — NOT a comment in the source (that
+breaks for JSON and deleted files). Write it next to that file's diffs, at:
+
+\`\`\`
+MERGE_DIR/updatemain-<safe_path>/{{EXPLANATION_FILE}}
+\`\`\`
+
+(\`<safe_path>\` = the conflict file path with \`/\` → \`__\`, the same dir that holds its
+\`A-forkpoint.txt\` / \`B-A.diff\` / \`C-A.diff\`.) In it, explain in a few sentences how you resolved
+this file: which side you took where, what you combined from B-A.diff vs C-A.diff, and why. The
+gate fails if any conflicted file's explanation is missing or empty. Do not paste A/B/C context
+blocks into the source code.
+
+## STEP 3 — Run the gate (validates the merge AND finishes the PR)
+
+\`\`\`
+pnpm wp-finish-upsert-pr
+\`\`\`
+
+- Leftover conflict markers → fix those files and re-run.
+- Missing merge explanation → write it (see STEP 2) and re-run.
+- Build failure → fix the TypeScript/lint errors and re-run (the gate re-stages for you).
+- Missing review.json → write it in the printed format (your PR review), then re-run.
+- On success it commits, renders the dashboard, and creates/updates the PR.
+
+## Conflicted files
+
+{{FILE_LIST}}
+
+## If you need to bail out
+
+A backup branch was created (e.g. \`<feature>Backup1\`). To abandon:
+
+\`\`\`
+git merge --abort 2>/dev/null; git checkout <feature> ; git branch -D {{SQUASH_BRANCH}}
+\`\`\`
+
+Then delete \`{{MERGE_DIR}}/\` for a clean slate.
+`;
+function mergeProcessDoc(mergeDir, squashBranch, conflictedFiles) {
+    const fileList = conflictedFiles.map((f) => `- \`${f}\``).join('\n');
+    return MERGE_PROCESS_TEMPLATE
+        .replace(/\{\{SQUASH_BRANCH\}\}/g, squashBranch)
+        .replace(/\{\{MERGE_DIR\}\}/g, mergeDir)
+        .replace(/\{\{EXPLANATION_FILE\}\}/g, rules_config_1.MERGE_EXPLANATION_FILE)
+        .replace(/\{\{FILE_LIST\}\}/g, fileList);
+}
+// Returns the absolute path of the written doc.
+function writeMergeProcessDoc(repoRoot, mergeDir, squashBranch, conflictedFiles) {
+    const docDir = path.join(repoRoot, rules_config_1.WEBPIECES_TMP_DIR, 'instruct-ai');
+    fs.mkdirSync(docDir, { recursive: true });
+    const docPath = path.join(docDir, 'webpieces.mergeprocess.md');
+    fs.writeFileSync(docPath, mergeProcessDoc(mergeDir, squashBranch, conflictedFiles));
+    return docPath;
+}
+function printConflictHandback(docPath, mergeDir, squashBranch, conflictedFiles) {
+    process.stdout.write('\n' + SEP + `⚠️  Conflicts in ${conflictedFiles.length} file(s) — handing control back to you\n` + SEP + '\n');
+    process.stdout.write(`You are on branch ${squashBranch} with conflicts in the working tree.\n\n`);
+    process.stdout.write(`FOLLOW THE MERGE PROCESS:  ${docPath}\n`);
+    process.stdout.write(`3-point context per file in: ${mergeDir}/updatemain-<file>/\n\n`);
+    process.stdout.write('Conflicted files:\n');
+    for (const file of conflictedFiles)
+        process.stdout.write(`  - ${file}\n`);
+    process.stdout.write('\n' + SEP);
+}
+// Write the conflict context files + the unvalidated marker + the process doc. Does NOT exit — the
+// caller decides (wp-git-update exits 2 to hand back to the AI).
+function handleConflictsHandback(repoRoot, mergeDir, currentBranch, squashBranch, backupBranch, prNumber, hashes) {
+    const raw = (0, child_process_1.execSync)('git diff --name-only --diff-filter=U', { encoding: 'utf8' }).trim();
+    const conflictedFiles = raw.split('\n').filter((f) => f.trim() !== '');
+    fs.writeFileSync(path.join(mergeDir, 'updatemain-conflicted-files.txt'), raw + '\n');
+    saveConflictContext(conflictedFiles, mergeDir, hashes.hashForkPoint, hashes.hashFeatureHead, hashes.hashMainHead);
+    const marker = new merge_state_1.MergeMarker(currentBranch, squashBranch, backupBranch, prNumber, conflictedFiles, hashes.hashForkPoint, hashes.hashFeatureHead, hashes.hashMainHead, false);
+    (0, merge_state_1.writeMergeMarker)(mergeDir, marker);
+    const docPath = writeMergeProcessDoc(repoRoot, mergeDir, squashBranch, conflictedFiles);
+    printConflictHandback(docPath, mergeDir, squashBranch, conflictedFiles);
+}
+async function mergeStart(repoRoot, mergeDir) {
+    const currentBranch = (0, child_process_1.execSync)('git branch --show-current', { encoding: 'utf8' }).trim();
+    if (currentBranch.endsWith('Squash')) {
+        process.stderr.write(`❌ On a leftover ${currentBranch} branch with no merge marker. Clean up: git branch -D ${currentBranch}\n`);
+        process.exit(1);
+    }
+    process.stdout.write('\n' + SEP + '🔄 Squash-Merge Update from Main\n' + SEP + '\n');
+    await (0, git_gatherInfo_1.main)();
+    const hashes = JSON.parse(fs.readFileSync(path.join(mergeDir, 'updatemain-hashes.json'), 'utf8'));
+    const prNumber = detectPr(currentBranch);
+    process.stdout.write(prNumber ? `Existing PR #${prNumber} will be updated.\n` : 'No existing PR (one can be created later).\n');
+    const backupBranch = createBackup(currentBranch);
+    const squashBranch = `${currentBranch}Squash`;
+    if ((0, child_process_1.spawnSync)('git', ['show-ref', '--verify', '--quiet', `refs/heads/${squashBranch}`]).status === 0) {
+        process.stderr.write(`❌ Stale ${squashBranch} from a previous run. Delete it: git branch -D ${squashBranch}\n`);
+        process.exit(1);
+    }
+    (0, git_exec_1.runGitChecked)(['checkout', 'main'], 'Failed to checkout main');
+    (0, git_exec_1.runGitChecked)(['pull', 'origin', 'main'], 'Failed to pull origin/main');
+    (0, git_exec_1.runGitChecked)(['checkout', '-b', squashBranch], 'Failed to create squash branch');
+    process.stdout.write('\n' + SEP + `🔀 Squash merging ${currentBranch}\n` + SEP + '\n');
+    const merge = (0, child_process_1.spawnSync)('git', ['merge', '--squash', currentBranch], { stdio: 'inherit' });
+    if (merge.status !== 0) {
+        handleConflictsHandback(repoRoot, mergeDir, currentBranch, squashBranch, backupBranch, prNumber, hashes);
+        return new MergeStartResult('conflict', null);
+    }
+    const nothingStaged = (0, child_process_1.spawnSync)('git', ['diff-index', '--quiet', '--cached', 'HEAD', '--']).status === 0;
+    if (nothingStaged) {
+        process.stdout.write('ℹ️  Already up-to-date with main (nothing to merge).\n');
+    }
+    else {
+        (0, git_exec_1.runGitChecked)(['commit', '-m', `Squash merge of ${currentBranch}`], 'Failed to commit squash merge');
+    }
+    return new MergeStartResult('clean', new MergeContext(currentBranch, squashBranch, backupBranch, prNumber));
+}
+//# sourceMappingURL=merge-start.js.map