git-release-manager 0.0.13 → 0.6.0

package/dist/modules/flow/FlowController.js

@@ -0,0 +1,764 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowController = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const semver_1 = __importDefault(require("semver"));
+const simple_git_1 = __importDefault(require("simple-git"));
+const BumpDeriver_1 = require("../version/BumpDeriver");
+const lineTags_1 = require("../git/lineTags");
+const BUMP_RANK = { patch: 0, minor: 1, major: 2 };
+/**
+ * The higher of a derived and a declared bump, treating a missing declaration
+ * as "no opinion" (DECISIONS D3).
+ *
+ * A floor is a MAXIMUM against the derived level, never a replacement for it: a
+ * declared `minor` must not pull a `major:` in the range down, which is exactly
+ * what the override reading would have done.
+ */
+function maxBump(derived, declared) {
+    if (!declared)
+        return derived;
+    if (!derived)
+        return declared;
+    return BUMP_RANK[declared] > BUMP_RANK[derived] ? declared : derived;
+}
+/**
+ * FlowController — run a declared phase: promote a branch, derive the version
+ * from the commits, tag it.
+ *
+ * ── THE NUMBER COMES FROM THE HISTORY, NOT FROM A NAME ──
+ *
+ * This is the one property the existing flow surfaces do not have.
+ * `branch finish` reads the version out of the branch name
+ * (`release/1.4.0` → `1.4.0`), which means the bump derivation — the whole
+ * commitTypes/noteTypes taxonomy a project configures for its changelog — is
+ * bypassed on the only path where it matters. Here the range is
+ * `<latest tag on this line>..<the phase's branch>` and `deriveBump` grades it,
+ * so `feat:` moves the minor whether or not anybody typed a number.
+ *
+ * ── AND IT IS COMPUTED AFTER THE MERGE, DELIBERATELY ──
+ *
+ * A promotion's version must describe the work it promotes. Derive before the
+ * merge and the range is empty (the target branch has not moved yet), so the
+ * derivation falls to the default and a release full of features gets a patch
+ * bump. Every step still reports success. So: merge, then derive, then tag —
+ * and the tag lands on the merge commit, which is the commit that carries the
+ * work.
+ *
+ * ── WHAT IT REFUSES ──
+ *
+ * · an unknown phase, listing the ones the project declared
+ * · a promotion with nothing to promote (the source carries no commit the
+ *   target lacks) — that would mint a version for no change
+ * · a fast-forward merge unless the phase asked for `ff` in writing: a
+ *   fast-forward creates no commit, so a pre-merge hook never runs and every
+ *   gate hung on the promotion silently does not execute
+ * · deleting the source branch unless the phase asked for it. On a long-lived
+ *   integration line that is not a cleanup, it is an outage.
+ */
+const OWNER_TOKEN = "FlowController/v1";
+class FlowController {
+    constructor(config, root = process.cwd()) {
+        this.config = config;
+        this.root = root;
+        this.git = (0, simple_git_1.default)(this.root);
+    }
+    /** The phase declaration, or a refusal that names what IS declared. */
+    phase(name) {
+        var _a, _b;
+        const phases = (_b = (_a = this.config) === null || _a === void 0 ? void 0 : _a.flow) === null || _b === void 0 ? void 0 : _b.phases;
+        if (!phases || Object.keys(phases).length === 0) {
+            throw new Error("No flow is declared. Add a `flow.phases` block to the config " +
+                "(see src/config/types/Flow.ts) naming each phase's branch.");
+        }
+        const p = phases[name];
+        if (!p) {
+            throw new Error(`Unknown phase '${name}'. Declared: ${Object.keys(phases).join(", ")}`);
+        }
+        if (!p.branch) {
+            throw new Error(`Phase '${name}' declares no branch.`);
+        }
+        return p;
+    }
+    /**
+     * The phase's branch must EXIST before any question about it means anything.
+     *
+     * 🔴 WITHOUT THIS A MISSING BRANCH ANSWERS A VERSION. Every tag walk filters
+     * on `merge-base --is-ancestor <tag> <branch>`, which simply fails for a
+     * branch that is not there — so no tag is reachable, the baseline falls to
+     * 0.0.0, and the phase confidently reports `v0.0.1` for a line it cannot see.
+     * Measured 2026-08-06 in a `git clone --branch dev` of a repository at v1.3.0:
+     * `main` existed only as a remote-tracking ref, and `flow next prod` answered
+     * v0.0.1 while the sibling driver answered v1.0.0. A number that names nothing
+     * is worse than a refusal, because a caller substitutes it into a tag.
+     */
+    async assertBranch(branch, role) {
+        const ok = await this.git
+            .raw(["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`])
+            .then(out => String(out).trim() !== "")
+            .catch(() => false);
+        if (!ok) {
+            throw new Error(`${role} '${branch}' does not exist in this repository ` +
+                `(a remote-tracking ref is not enough — create the local branch).`);
+        }
+    }
+    prefixOf(p) {
+        var _a, _b, _c, _d;
+        return (_d = (_a = p.prefix) !== null && _a !== void 0 ? _a : (_c = (_b = this.config) === null || _b === void 0 ? void 0 : _b.tag) === null || _c === void 0 ? void 0 : _c.prefix) !== null && _d !== void 0 ? _d : "";
+    }
+    strategyOf(p) {
+        return p.merge === "ff" ? "ff" : "no-ff";
+    }
+    /**
+     * The highest tag on THIS line, reachable from the phase's branch.
+     *
+     * The line is `lineTags` (annotated + reachable + version-sorted); this adds
+     * the one filter that is specific to the baseline question. A phase with a
+     * channel wants that channel's newest tag; a stable phase must not adopt a
+     * prerelease as its baseline, or every stable cut would inherit `-dev.N` and
+     * never leave it.
+     */
+    async currentVersion(p) {
+        const prefix = this.prefixOf(p);
+        for (const name of await this.lineTags(p)) {
+            const core = name.slice(prefix.length);
+            if (p.channel) {
+                if (!core.includes(`-${p.channel}.`))
+                    continue;
+            }
+            else if (core.includes("-")) {
+                continue;
+            }
+            return name;
+        }
+        return "";
+    }
+    /**
+     * Every annotated tag on this line, newest-version first, reachable from the
+     * phase's branch. One walk; the baseline questions above and in
+     * `nextVersion` filter it.
+     *
+     * THE WALK ITSELF MOVED to modules/git/lineTags (2026-08-24), because a
+     * version TRACK asks the same question about its own branch and the answer
+     * must not exist twice. Everything below — why annotated-only, why
+     * `--merged`, why a version sort, and why the answer is read from stdout
+     * rather than from an exit code — is kept THERE, with the code it governs.
+     *
+     * Three filters, and each one is load-bearing. ANNOTATED only
+     * (`%(objecttype)` is `tag`): a lightweight tag carries no tagger, so it
+     * records nothing about who cut it. REACHABLE from the branch (`--merged`):
+     * a tag on a side branch names code this line never carried. Sorted by
+     * VERSION, not lexically — `-v:refname`, because a lexical sort puts
+     * v1.10.0 below v1.9.0 and the baseline would walk backwards on the tenth
+     * minor.
+     *
+     * ── 🔴 REACHABILITY IS READ FROM STDOUT, NEVER FROM AN EXIT CODE ──
+     *
+     * This used to enumerate every tag and then ask, per tag,
+     * `merge-base --is-ancestor <tag>^{commit} <branch>`, mapping a resolved
+     * promise to `true` and a rejection to `false`. That command answers ONLY
+     * through its exit status: 0 ancestor, 1 not an ancestor, and it prints
+     * nothing either way. simple-git 3.27.0 RESOLVES a non-zero exit whose
+     * stderr is empty — measured, and `git tag --merged` in FlowManager already
+     * avoids the idiom — so `.then(() => true)` fired for BOTH answers and the
+     * filter passed every tag. Consequence on the repository this tool manages:
+     * `flow next prod` baselined on v1.6.0, a tag that lives only on `dev`, and
+     * answered v1.7.0 where the release line stood at v1.0.8 and the correct
+     * answer was v1.1.0 — six minor versions ahead, reported as a success.
+     * VersionController.resolveBaselineRef carries the same warning for
+     * `rev-parse --verify --quiet`: THE ANSWER IS THE OUTPUT, NOT THE ABSENCE
+     * OF A THROW.
+     *
+     * `for-each-ref --merged=<branch>` moves the answer onto stdout, and it
+     * costs ONE process instead of one per tag. Both failure directions now
+     * converge on the SAME safe answer: if git fails, and whether the wrapper
+     * rejects (the catch below) or resolves with empty output, the result is an
+     * empty set — no baseline rather than a foreign one. A phase whose branch
+     * does not exist yet lands here too, which is the answer it had before.
+     */
+    async lineTags(p) {
+        return (0, lineTags_1.lineTags)(this.git, p.branch, this.prefixOf(p));
+    }
+    /**
+     * The version this phase would cut next.
+     *
+     * `at` overrides the ref the range ENDS at — the runner passes the merge
+     * commit, because after a promotion the branch ref may not have moved yet
+     * (a worktree merge lands on a detached HEAD).
+     *
+     * ── A PRERELEASE HAS TWO BASELINES, AND THEY ARE DIFFERENT QUESTIONS ──
+     *
+     * The CORE comes from the release line — the newest STABLE tag — because
+     * `1.2.0-dev.3` is a preview of the 1.2.0 that is coming, and a preview whose
+     * core is derived from another preview drifts away from the line it previews.
+     * The COUNTER comes from the newest tag already in this channel AT THAT CORE.
+     *
+     * Conflating them is not theoretical: with one baseline this method answered
+     * `v0.0.1-dev.1` on a repository whose release line was at v1.1.0 (no stable
+     * tag matched the channel filter, so the base fell to 0.0.0), and the second
+     * cut then recomputed the SAME string and died on an existing tag. Measured
+     * 2026-08-06. The bump is applied to the stable core exactly once, and the
+     * channel counter never bumps the core again.
+     */
+    async nextVersion(p, at) {
+        var _a, _b, _c, _d, _e, _f, _g, _h;
+        await this.assertBranch(p.branch, "the phase's branch");
+        const prefix = this.prefixOf(p);
+        const tags = await this.lineTags(p);
+        const core = (t) => t.slice(prefix.length);
+        const stable = (_a = tags.find(t => !core(t).includes("-"))) !== null && _a !== void 0 ? _a : "";
+        const current = p.channel
+            ? ((_b = tags.find(t => core(t).includes(`-${p.channel}.`))) !== null && _b !== void 0 ? _b : stable)
+            : stable;
+        // The core is ALWAYS built from the stable line; see the note above.
+        const base = stable ? core(stable) : "0.0.0";
+        let bump = (_f = (_c = p.bump) !== null && _c !== void 0 ? _c : (_e = (_d = this.config) === null || _d === void 0 ? void 0 : _d.versioning) === null || _e === void 0 ? void 0 : _e.defaultBump) !== null && _f !== void 0 ? _f : "patch";
+        let why;
+        if (p.derive !== false && stable) {
+            // ── THE RANGE, AND WHY IT IS A UNION BEFORE THE MERGE ──
+            //
+            // After a promotion the target branch contains the source, so one
+            // range `current..<merge commit>` is the whole story — that is the
+            // `at` case, passed by the runner.
+            //
+            // BEFORE the merge it is not. `current..main` is EMPTY (main has not
+            // moved yet), so a plan that used it derived nothing, fell to
+            // defaultBump, and answered `v1.0.1` for a promotion the run then
+            // correctly cut as `v1.1.0` — the plan and the act disagreeing about
+            // the number, which is the one thing a plan may never do. Measured
+            // 2026-08-06 on a two-commit fixture with a `feat:` in it.
+            //
+            // `current..main` alone is wrong and `current..dev` alone is too: the
+            // target may carry commits since the tag that the source lacks (the
+            // divergence the plan reports as `behind`). `git log A..B A..C` is the
+            // UNION of both, which is exactly what the merge will produce, so the
+            // plan grades the same set the run will.
+            const ends = at ? [at] : (p.mergeFrom ? [p.branch, p.mergeFrom] : [p.branch]);
+            // From the STABLE tag, not from the channel's newest: a prerelease
+            // counter moving does not mean the work was already graded.
+            const ranges = ends.map(e => `${stable}..${e}`);
+            const pathspecs = ((_g = p.paths) !== null && _g !== void 0 ? _g : "").split(/\s+/).filter(Boolean);
+            // --no-merges: a merge commit carries no type and never could — its
+            // content is the commits it joins, and those are in this range too.
+            const args = [
+                ...ranges.slice(1),
+                "--no-merges",
+                ...(pathspecs.length ? ["--", ...pathspecs] : []),
+            ];
+            const commits = await this.logCommits([...ranges, ...args]);
+            if (commits === null || commits === void 0 ? void 0 : commits.length) {
+                const evidence = (0, BumpDeriver_1.deriveBump)(commits, this.config);
+                why = (0, BumpDeriver_1.explainBump)(evidence);
+                // ── A DECLARED phase.bump IS A FLOOR (DECISIONS D3) ──────────
+                //
+                // Derive from the commits, then never go BELOW what the phase
+                // declared. Three readings were possible and this is the one
+                // taken:
+                //
+                //   override  the declaration always wins — then a `major:` in
+                //             the range is silently downgraded to the declared
+                //             level, which is worse than either alternative
+                //   fallback  the declaration applies only when the range is
+                //             empty — what this did until now, and the opposite
+                //             of what "a phase may override the level" reads like
+                //   floor     derive, then raise to the declaration if it asked
+                //             for more. A project writing `minor` on a phase
+                //             means every promotion through it is AT LEAST a
+                //             minor, and a `feat!:` can still make it a major.
+                //
+                // Measured before this: on a one-commit fixture `prod.bump=minor`
+                // yielded v1.1.0 and on a repository with a real range the same
+                // declaration yielded a patch — the declaration won exactly where
+                // it mattered least.
+                bump = maxBump(evidence.bump, p.bump);
+                if (p.bump && bump !== evidence.bump) {
+                    // SAID OUT LOUD. Without this the operator reads "derived
+                    // patch from 3 commits" beside a minor version and has no
+                    // way to tell which input produced it.
+                    why = `${why} — raised to ${bump} by the phase's declared floor (phase.bump = ${p.bump})`;
+                }
+            }
+        }
+        const nextCore = (_h = semver_1.default.inc(base, bump !== null && bump !== void 0 ? bump : "patch")) !== null && _h !== void 0 ? _h : base;
+        if (!p.channel) {
+            return { version: `${prefix}${nextCore}`, current: current || "none", why };
+        }
+        // The counter continues within THIS core. A new core restarts at 1, which
+        // is what makes `1.2.0-dev.1` follow `1.1.0-dev.7` rather than `.8`.
+        const inChannel = tags.filter(t => core(t).startsWith(`${nextCore}-${p.channel}.`));
+        let n = 0;
+        for (const t of inChannel) {
+            const m = core(t).match(new RegExp(`^${this.escapeRe(nextCore)}-${this.escapeRe(p.channel)}\\.(\\d+)$`));
+            if (m)
+                n = Math.max(n, parseInt(m[1], 10));
+        }
+        return { version: `${prefix}${nextCore}-${p.channel}.${n + 1}`, current: current || "none", why };
+    }
+    /**
+     * Remove one worktree this tool created, and deregister it.
+     *
+     * `keep: true` leaves it for inspection — of the run that just happened. The
+     * next run reclaims it (see reclaimWorktrees), because `keep` is a debugging
+     * aid and not a licence to hoard checkouts. With back-merges or routes in the
+     * same run, that means the LAST merge's worktree is the one left standing:
+     * each merge reclaims the leftovers it finds before starting. Bounded on
+     * purpose — the alternative is one full checkout per branch, kept forever.
+     *
+     * `worktree remove` can refuse (a lock, a file it cannot delete), and a
+     * refusal that leaves the directory behind is exactly the accumulation this
+     * guards against — so the removal falls back to deleting the directory, and
+     * `prune` then clears the registration git is left holding.
+     */
+    async removeWorktree(dir) {
+        var _a, _b, _c;
+        if (((_c = (_b = (_a = this.config) === null || _a === void 0 ? void 0 : _a.flow) === null || _b === void 0 ? void 0 : _b.worktree) === null || _c === void 0 ? void 0 : _c.keep) === true)
+            return;
+        // SAFE to swallow: nothing reads this call's outcome. Whether it removed
+        // the worktree is re-measured on the next line by LOOKING — existsSync —
+        // so a wrapper that misreports the exit status changes nothing.
+        await this.git.raw(["worktree", "remove", "--force", dir]).catch(() => { });
+        if ((0, fs_1.existsSync)(dir)) {
+            try {
+                (0, fs_1.rmSync)(dir, { recursive: true, force: true });
+            }
+            catch ( /* reported by prune */_d) { /* reported by prune */ }
+        }
+        // SAFE to swallow: housekeeping with no answer. Nothing branches on
+        // whether the registration was cleared, and a stale registration is
+        // reclaimed by the next run.
+        await this.git.raw(["worktree", "prune"]).catch(() => { });
+    }
+    /**
+     * Reclaim leftovers before starting: this phase's directory and any other
+     * `flow-*` under the configured root that carries OUR owner marker.
+     *
+     * A killed process (a laptop closing, a CI timeout, a SIGKILL) leaves a
+     * worktree no finally ever runs for. Without this they pile up one full
+     * checkout at a time, and the only symptom is a disk that fills.
+     *
+     * ⚠️ AN UNOWNED DIRECTORY IS REFUSED, NOT RECLAIMED — and the refusal comes
+     * FIRST. A directory that merely looks like ours may hold somebody's
+     * in-flight work; two sessions have already been lost to a tool removing
+     * worktrees it did not create.
+     */
+    async reclaimWorktrees(current) {
+        if ((0, fs_1.existsSync)(current) && !(0, fs_1.existsSync)((0, path_1.join)(current, ".grm-flow", "owner"))) {
+            throw new Error(`${current} exists and carries no owner marker — refusing to reuse it.`);
+        }
+        const rootDir = (0, path_1.join)(current, "..");
+        let entries = [];
+        try {
+            entries = (0, fs_1.readdirSync)(rootDir).filter(e => e.startsWith("flow-"));
+        }
+        catch (_a) {
+            return; // the root does not exist yet
+        }
+        for (const e of entries) {
+            const dir = (0, path_1.join)(rootDir, e);
+            if (!(0, fs_1.existsSync)((0, path_1.join)(dir, ".grm-flow", "owner")))
+                continue; // not ours
+            // SAFE to swallow, for the same reason as removeWorktree: the
+            // outcome is re-measured by existsSync rather than inferred.
+            await this.git.raw(["worktree", "remove", "--force", dir]).catch(() => { });
+            if ((0, fs_1.existsSync)(dir)) {
+                try {
+                    (0, fs_1.rmSync)(dir, { recursive: true, force: true });
+                }
+                catch ( /* prune reports */_b) { /* prune reports */ }
+            }
+        }
+        // SAFE to swallow: housekeeping with no answer. Nothing branches on
+        // whether the registration was cleared, and a stale registration is
+        // reclaimed by the next run.
+        await this.git.raw(["worktree", "prune"]).catch(() => { });
+    }
+    /**
+     * The commits in a range, read from THIS controller's repository.
+     *
+     * 🔴 NOT `getGitLogAsJson`. That helper constructs `simpleGit()` with no
+     * working directory, so it reads whatever `process.cwd()` happens to be —
+     * which is the repository under management only by coincidence. Measured
+     * 2026-08-06: seven cases of this suite failed because the derivation was
+     * grading the commits of the grm checkout the tests run from instead of the
+     * fixture repository it was handed. The CLI never noticed, because there cwd
+     * IS the repository. A class that takes a `root` has to honour it.
+     */
+    async logCommits(args) {
+        try {
+            const log = await this.git.log(args);
+            return log.all.map(c => ({
+                hash: c.hash,
+                shortHash: c.hash.substring(0, 7),
+                message: c.message,
+                body: c.body,
+                authorName: c.author_name,
+                authorEmail: c.author_email,
+                date: c.date,
+            }));
+        }
+        catch (_a) {
+            // SAFE to swallow: `git log` answers with its OUTPUT, so this is not
+            // the exit-code shape lineTags warns about. An empty range and a
+            // failed one both produce no commits, and `nextVersion` then falls to
+            // the configured defaultBump — a smaller bump than the history would
+            // have justified, never a larger one.
+            return [];
+        }
+    }
+    escapeRe(s) {
+        return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }
+    /** What `run` would do. Reads only. */
+    async plan(name) {
+        var _a, _b, _c, _d;
+        const p = this.phase(name);
+        let ahead = 0, behind = 0;
+        if (p.mergeFrom) {
+            ahead = await this.count(`${p.branch}..${p.mergeFrom}`);
+            behind = await this.count(`${p.mergeFrom}..${p.branch}`);
+        }
+        const { version, current, why } = await this.nextVersion(p);
+        return {
+            phase: name,
+            branch: p.branch,
+            channel: p.channel,
+            mergeFrom: p.mergeFrom,
+            ahead, behind,
+            current, next: version, bumpWhy: why,
+            willTag: p.tag !== false,
+            willDeleteSource: p.deleteSource === true,
+            mergeStrategy: this.strategyOf(p),
+            backMerge: (_a = p.backMerge) !== null && _a !== void 0 ? _a : [],
+            worktree: ((_d = (_c = (_b = this.config) === null || _b === void 0 ? void 0 : _b.flow) === null || _c === void 0 ? void 0 : _c.worktree) === null || _d === void 0 ? void 0 : _d.enabled) ? this.worktreeDir(name) : undefined,
+        };
+    }
+    async count(range) {
+        // SAFE to swallow: `rev-list --count` PRINTS its answer, so the number is
+        // read out of stdout and not out of an exit status — see lineTags for
+        // the shape that is not safe. Both failure directions land on 0: the
+        // catch returns "0", and a wrapper that resolved an error with empty
+        // output gives NaN, which the guard below also turns into 0. Zero is the
+        // fail-CLOSED direction — `run` refuses a promotion it measures as
+        // carrying nothing, so a broken measurement mints no version.
+        const out = await this.git.raw(["rev-list", "--count", range]).catch(() => "0");
+        const n = parseInt(String(out).trim(), 10);
+        return Number.isFinite(n) ? n : 0;
+    }
+    worktreeDir(phase) {
+        var _a, _b, _c, _d;
+        const dir = (_d = (_c = (_b = (_a = this.config) === null || _a === void 0 ? void 0 : _a.flow) === null || _b === void 0 ? void 0 : _b.worktree) === null || _c === void 0 ? void 0 : _c.dir) !== null && _d !== void 0 ? _d : ".grm/worktrees";
+        return (0, path_1.resolve)(this.root, dir, `flow-${phase}`.replace(/[^A-Za-z0-9_.-]/g, "-"));
+    }
+    /**
+     * mergeInto — carry `source` into `target`, and move `target`'s ref.
+     *
+     * THE ONE MECHANISM. A promotion, a back-merge and a route are the same act
+     * with different names, and writing them three times is how they drift: the
+     * promotion would keep its worktree isolation and its expected-value
+     * update-ref while a back-merge quietly did a `checkout` in the shared tree.
+     * Every caller gets both properties or neither.
+     *
+     * Returns the merge commit, or "" when there was nothing to merge — the
+     * callers treat "nothing to do" differently, so this does not decide it.
+     */
+    /**
+     * THE MERGE ENGINE, exposed so that the only other thing in this codebase
+     * that carries a branch into another one does not grow a second copy.
+     *
+     * `TrackController.forwardPort` cascades a maintenance fix up the tracks,
+     * and every hazard `mergeInto` handles applies there identically: a target
+     * held in another worktree, `update-ref` desyncing a checked-out branch, a
+     * dirty tree that would carry changes across a checkout, `--no-ff` so the
+     * pre-merge hooks actually run. Re-implementing that for tracks would put
+     * those four decisions in two places, and the first one to drift would do
+     * it silently — every step still reporting success.
+     *
+     * Returns the merge commit, or "" when the target already contains the
+     * source (nothing to do is not a failure).
+     */
+    async mergeBranch(target, source, strategy, label) {
+        return this.mergeInto(target, source, strategy, label);
+    }
+    async mergeInto(target, source, strategy, label) {
+        var _a, _b, _c;
+        // Both ends must exist. `rev-list --count a..b` FAILS for a missing ref and
+        // count() maps a failure to 0, which reads as "nothing to merge" — so a
+        // route pointing at a branch that is not there would be reported as
+        // skipped-because-already-current.
+        await this.assertBranch(target, "the merge target");
+        await this.assertBranch(source, "the merge source");
+        const ahead = await this.count(`${target}..${source}`);
+        if (ahead === 0)
+            return "";
+        // ── WHO HOLDS THE TARGET DECIDES WHERE THE MERGE HAPPENS ──
+        //
+        // 🔴 `update-ref` ON A CHECKED-OUT BRANCH DESYNCS THAT CHECKOUT. The ref
+        // moves, HEAD follows it, and the working tree and index do NOT — so every
+        // file that differs between the old and new commit shows up as a local
+        // modification or deletion in a checkout the operator was not even looking
+        // at. The promotion path never hit this because its target (the release
+        // line) is not the branch anyone stands on; a BACK-MERGE targets the
+        // integration line, which is exactly the branch everyone stands on.
+        //
+        // So: held HERE → merge in place, which is the only way that working tree
+        // stays consistent (git updates it as part of the merge). Held in ANOTHER
+        // worktree → refuse by name; moving somebody else's checked-out branch is
+        // not ours to do.
+        const holder = await this.worktreeHolding(target);
+        const heldHere = holder !== "" && (0, path_1.resolve)(holder) === (0, path_1.resolve)(this.root);
+        if (holder && !heldHere) {
+            throw new Error(`${target} is checked out in another worktree (${holder}), so its ref cannot be ` +
+                `moved from here without desyncing that checkout. Run the merge there, or detach it.`);
+        }
+        const useWorktree = ((_c = (_b = (_a = this.config) === null || _a === void 0 ? void 0 : _a.flow) === null || _b === void 0 ? void 0 : _b.worktree) === null || _c === void 0 ? void 0 : _c.enabled) === true && !heldHere;
+        let workGit = this.git;
+        let createdDir = "";
+        // The branch to return to when this merge did not happen in a worktree.
+        let restoreTo = "";
+        try {
+            if (!useWorktree) {
+                // ── WITHOUT A WORKTREE THE TARGET HAS TO BE CHECKED OUT ──
+                //
+                // `git merge <source>` merges into HEAD, so merging into a branch
+                // you are not standing on is not a merge at all: with HEAD on main
+                // and the target dev, `merge main` answers "Already up to date",
+                // dev's ref never moves, and the caller is told it succeeded.
+                // Measured 2026-08-06 — five cases of the back-merge and route
+                // suites failed exactly here, and the promotion path had hidden it
+                // because its target was always the branch you were on.
+                const head = (await this.git.raw(["rev-parse", "--abbrev-ref", "HEAD"])).trim();
+                if (head !== target) {
+                    // A checkout across a dirty tree either refuses or carries the
+                    // changes onto the other branch. Neither belongs in a
+                    // promotion, so it is refused by name — and this is the reason
+                    // `worktree.enabled` exists.
+                    const dirty = (await this.git.raw(["status", "--porcelain", "--untracked-files=no"])).trim();
+                    if (dirty) {
+                        throw new Error(`${target} is not checked out and the tree is not clean, so it cannot be ` +
+                            `checked out to merge ${source} into it. Enable flow.worktree, or clean the tree.`);
+                    }
+                    await this.git.raw(["checkout", target]);
+                    restoreTo = head;
+                }
+            }
+            if (useWorktree) {
+                const wtDir = this.worktreeDir(label);
+                await this.reclaimWorktrees(wtDir);
+                (0, fs_1.mkdirSync)((0, path_1.join)(wtDir, ".."), { recursive: true });
+                // DETACHED, because git refuses the same branch in two worktrees
+                // and the target is very often checked out where you are standing.
+                await this.git.raw(["worktree", "add", "--detach", wtDir, target]);
+                createdDir = wtDir;
+                (0, fs_1.mkdirSync)((0, path_1.join)(wtDir, ".grm-flow"), { recursive: true });
+                (0, fs_1.writeFileSync)((0, path_1.join)(wtDir, ".grm-flow", "owner"), OWNER_TOKEN + "\n");
+                workGit = (0, simple_git_1.default)(wtDir);
+            }
+            const args = ["merge", "--no-edit", source];
+            // See FlowPhase.merge: `ff` has to be asked for in writing.
+            if (strategy === "no-ff")
+                args.splice(1, 0, "--no-ff");
+            await workGit.raw(args);
+            // ── 🔴 A CONFLICT IS NOT AN ERROR HERE. IT IS A RESOLVED PROMISE. ──
+            //
+            // `git merge` exits 1 on a conflict and writes "CONFLICT (add/add):
+            // …" to STDOUT, leaving stderr empty; simple-git 3.27.0 RESOLVES a
+            // non-zero exit whose stderr is empty. Measured 2026-08-24 against
+            // this repository's own simple-git: the promise resolved with the
+            // conflict text as its VALUE and the tree was left at `AA <file>`.
+            //
+            // So the await above cannot be trusted to have merged anything, and
+            // nothing downstream would notice: the promotion goes on to cut a
+            // tag over an unmerged index, and every step reports success. This
+            // is the same class the lineTags header describes — THE ANSWER IS
+            // THE OUTPUT, NOT THE ABSENCE OF A THROW — reaching the write path.
+            //
+            // The state is read from git rather than from the merge's text,
+            // because the text is localised and the index is not.
+            const unmerged = (await workGit.raw(["ls-files", "--unmerged"])).trim();
+            if (unmerged) {
+                // ABORT RATHER THAN LEAVE IT. A caller that continues past this
+                // is walking a cascade, and each later step would merge from a
+                // branch whose working tree is mid-conflict. Worse on a shared
+                // checkout, where the half-merged state belongs to whoever else
+                // is standing on that branch.
+                await workGit.raw(["merge", "--abort"]).catch(() => { });
+                throw new Error(`merging ${source} into ${target} conflicts (${unmerged.split("\n").length} unmerged path(s)); the merge was aborted and nothing moved`);
+            }
+            const head = (await workGit.revparse(["HEAD"])).trim();
+            if (useWorktree) {
+                // The worktree is DETACHED, so the merge did not move the branch.
+                // `update-ref` with the OLD value as the expected one, so a peer
+                // that advanced it in the meantime makes this FAIL rather than
+                // silently discarding their work.
+                const before = (await this.git.revparse([target])).trim();
+                await this.git.raw([
+                    "update-ref", "-m", `grm flow ${label}: merge ${source}`,
+                    `refs/heads/${target}`, head, before,
+                ]);
+            }
+            return head;
+        }
+        finally {
+            if (createdDir)
+                await this.removeWorktree(createdDir);
+            // Put the operator back where they were, even on the throw path: a
+            // failed promotion that also leaves you on another branch turns one
+            // problem into two.
+            if (restoreTo)
+                await this.git.raw(["checkout", restoreTo]).catch(() => { });
+        }
+    }
+    /** The route declaration, or a refusal that names what IS declared. */
+    route(name) {
+        var _a, _b, _c;
+        const routes = (_b = (_a = this.config) === null || _a === void 0 ? void 0 : _a.flow) === null || _b === void 0 ? void 0 : _b.routes;
+        if (!routes || !routes[name]) {
+            throw new Error(`Unknown route '${name}'. Declared: ${routes && Object.keys(routes).length ? Object.keys(routes).join(", ") : "(none)"}`);
+        }
+        const r = routes[name];
+        if (!r.from || !((_c = r.into) === null || _c === void 0 ? void 0 : _c.length)) {
+            throw new Error(`Route '${name}' needs both 'from' and a non-empty 'into'.`);
+        }
+        this.checkDirection(name, r);
+        return r;
+    }
+    /** What `syncRoute` would carry, per target. Reads only. */
+    async planRoute(name) {
+        const r = this.route(name);
+        const ahead = {};
+        for (const t of r.into)
+            ahead[t] = await this.count(`${t}..${r.from}`);
+        return { route: name, ahead };
+    }
+    /**
+     * The worktree path that has `branch` checked out, or "" if none does.
+     *
+     * `git worktree list --porcelain` is the only surface that answers this for
+     * EVERY checkout including the main one; `rev-parse --abbrev-ref HEAD` only
+     * ever answers about the directory you asked in, so a branch held by a
+     * sibling worktree would read as free.
+     */
+    async worktreeHolding(branch) {
+        const out = await this.git.raw(["worktree", "list", "--porcelain"]).catch(() => "");
+        let path = "";
+        for (const line of String(out).split("\n")) {
+            if (line.startsWith("worktree "))
+                path = line.slice("worktree ".length).trim();
+            else if (line.startsWith("branch ")) {
+                const ref = line.slice("branch ".length).trim();
+                if (ref === `refs/heads/${branch}`)
+                    return path;
+            }
+        }
+        return "";
+    }
+    /**
+     * Run a declared route: carry one branch's content to the others, with no
+     * version involved. This is the hotfix/bugfix shape.
+     *
+     * The DIRECTION is checked against `flow.lines` when both are declared. A
+     * hotfix route that says `down` but points up would merge the whole
+     * integration line into the release line — a release nobody planned, which
+     * every step would report as success.
+     */
+    async syncRoute(name) {
+        const r = this.route(name);
+        const merged = {};
+        const skipped = [];
+        for (const target of r.into) {
+            const head = await this.mergeInto(target, r.from, r.merge === "ff" ? "ff" : "no-ff", `route-${name}-${target}`);
+            if (head)
+                merged[target] = head;
+            else
+                skipped.push(target);
+        }
+        return { route: name, merged, skipped };
+    }
+    /**
+     * The declared direction has to match the ladder. A branch not on the ladder
+     * is not an error — topic branches are not lines — so it is simply not checked.
+     */
+    checkDirection(name, r) {
+        var _a, _b;
+        const lines = (_b = (_a = this.config) === null || _a === void 0 ? void 0 : _a.flow) === null || _b === void 0 ? void 0 : _b.lines;
+        if (!(lines === null || lines === void 0 ? void 0 : lines.length) || !r.direction)
+            return;
+        const from = lines.indexOf(r.from);
+        if (from === -1)
+            return;
+        for (const target of r.into) {
+            const to = lines.indexOf(target);
+            if (to === -1)
+                continue;
+            const actual = to > from ? "down" : to < from ? "up" : "same";
+            if (actual !== r.direction) {
+                throw new Error(`Route '${name}' declares direction '${r.direction}' but ${r.from} -> ${target} ` +
+                    `is '${actual}' on the declared ladder [${lines.join(" > ")}].`);
+            }
+        }
+    }
+    /**
+     * Execute the phase.
+     *
+     * Returns the plan it acted on, with `tagged` set when a tag was created.
+     */
+    async run(name) {
+        var _a;
+        const p = this.phase(name);
+        const plan = await this.plan(name);
+        if (p.mergeFrom && plan.ahead === 0) {
+            throw new Error(`${p.mergeFrom} carries nothing that ${p.branch} does not already have. ` +
+                `There is nothing to promote.`);
+        }
+        const mergeCommit = p.mergeFrom
+            // The label IS the phase name, so the directory `plan` reports
+            // (`flow-<phase>`) is the directory `run` creates. A prettier label
+            // here made the plan advertise a path nothing ever used.
+            ? await this.mergeInto(p.branch, p.mergeFrom, this.strategyOf(p), name)
+            : "";
+        // AFTER the merge — see the header. The range now contains the work.
+        const { version, current, why } = await this.nextVersion(p, mergeCommit || p.branch);
+        plan.next = version;
+        plan.current = current;
+        plan.bumpWhy = why;
+        // The tag is created from the MAIN repository, not from the worktree that
+        // performed the merge: the merge commit is in the object database and the
+        // branch already points at it, so the worktree has no part left to play —
+        // and it has been removed by now. Naming the commit explicitly, because
+        // HEAD here is whatever the operator has checked out.
+        if (p.tag !== false) {
+            await this.git.raw([
+                "tag", "-a", version, "-m", `${version}\n\ngrm flow ${name}`,
+                ...(mergeCommit ? [mergeCommit] : [p.branch]),
+            ]);
+        }
+        // ── BACK-MERGE, AFTER THE TAG ──
+        //
+        // After the tag, so every branch that receives the merge also receives the
+        // tag and can describe it. Before deleteSource, because a source that is
+        // about to be deleted may itself be one of the branches that needs it.
+        const backMerged = {};
+        for (const target of (_a = p.backMerge) !== null && _a !== void 0 ? _a : []) {
+            if (target === p.branch)
+                continue; // merging a branch into itself
+            const head = await this.mergeInto(target, p.branch, this.strategyOf(p), `back-${name}-${target}`);
+            if (head)
+                backMerged[target] = head;
+        }
+        if (p.deleteSource === true && p.mergeFrom) {
+            await this.git.raw(["branch", "-d", p.mergeFrom]);
+        }
+        return {
+            ...plan,
+            tagged: p.tag !== false ? plan.next : undefined,
+            mergeCommit: mergeCommit || undefined,
+            backMerged: Object.keys(backMerged).length ? backMerged : undefined,
+        };
+    }
+}
+exports.FlowController = FlowController;
+//# sourceMappingURL=FlowController.js.map