@databricks-solutions/lakebase-scm-utils 0.2.47 → 0.2.48

package/dist/scripts/lakebase/scm-merge.cli.js

@@ -8609,6 +8609,84 @@ function wrap(err, context) {
   }
   throw new GitHubPullRequestError(context);
 }
+async function getPullRequest(ownerRepo, headBranch) {
+  try {
+    const { owner, repo } = parseOwnerRepo(ownerRepo);
+    const ok = await octokit();
+    const { data: pulls } = await ok.rest.pulls.list({
+      owner,
+      repo,
+      state: "open",
+      head: `${owner}:${headBranch}`,
+      per_page: 1
+    });
+    if (pulls.length === 0) return void 0;
+    const { data: pr } = await ok.rest.pulls.get({
+      owner,
+      repo,
+      pull_number: pulls[0].number
+    });
+    if (pr.state !== "open") return void 0;
+    let checks = [];
+    let ciStatus = "pending";
+    const headSha = pr.head?.sha;
+    if (headSha) {
+      try {
+        const { data: checksData } = await ok.rest.checks.listForRef({
+          owner,
+          repo,
+          ref: headSha
+        });
+        const runs = checksData.check_runs || [];
+        checks = runs.map((c) => ({
+          name: c.name || "unknown",
+          status: (c.status || "").toUpperCase(),
+          conclusion: (c.conclusion || "").toUpperCase(),
+          detailsUrl: c.details_url || void 0
+        }));
+        ciStatus = parseCiStatus(runs);
+      } catch {
+        ciStatus = "pending";
+      }
+    }
+    return {
+      number: pr.number,
+      title: pr.title,
+      url: pr.html_url || "",
+      state: (pr.state || "open").toUpperCase(),
+      isDraft: pr.draft || false,
+      ciStatus,
+      checks,
+      mergeable: pr.mergeable,
+      mergeableState: pr.mergeable_state,
+      headBranch: pr.head?.ref || headBranch,
+      baseBranch: pr.base?.ref || "",
+      body: pr.body || void 0,
+      additions: pr.additions,
+      deletions: pr.deletions,
+      changedFiles: pr.changed_files
+    };
+  } catch {
+    return void 0;
+  }
+}
+function parseCiStatus(rawChecks) {
+  if (rawChecks.length === 0) return "pending";
+  const latestByName = /* @__PURE__ */ new Map();
+  for (const c of rawChecks) {
+    latestByName.set(c.name || "unknown", c);
+  }
+  const states = Array.from(latestByName.values()).map(
+    (c) => (c.conclusion || c.status || "").toUpperCase()
+  );
+  if (states.some((s) => s === "FAILURE" || s === "ERROR" || s === "ACTION_REQUIRED")) {
+    return "failure";
+  }
+  if (states.every((s) => s === "SUCCESS" || s === "NEUTRAL" || s === "SKIPPED")) {
+    return "success";
+  }
+  return "pending";
+}
 async function mergePullRequest(args) {
   const method = args.method ?? "merge";
   const deleteRemoteBranch = args.deleteRemoteBranch !== false;
@@ -9303,6 +9381,48 @@ function shaMigratePredicate(mergeCommitSha) {
     return !!run.headSha && run.headSha === mergeCommitSha;
   };
 }
+var PROMOTE_RUNSTATE_CONFLICT = /(^|\/)\.consort\/(features\/[^/]+\/)?pipeline\.json$/;
+async function reconcilePromoteRunState(projectDir, baseBranch) {
+  const o = { cwd: projectDir, timeout: 3e4 };
+  const dirty = (await exec2("git status --porcelain", o).catch(() => "")).split("\n").map((l) => l.slice(3).trim()).filter(Boolean);
+  const nonRunStateDirty = dirty.filter((p) => !p.startsWith(".consort/"));
+  if (nonRunStateDirty.length > 0) {
+    throw new ScmMergeError(
+      `working tree has uncommitted non-run-state changes (${nonRunStateDirty.slice(0, 5).join(", ")}${nonRunStateDirty.length > 5 ? ", \u2026" : ""}); commit or stash before promoting.`,
+      "promote-conflict"
+    );
+  }
+  if (dirty.length > 0) {
+    await exec2(`git add ${shellEscape(".consort")}`, o);
+    await exec2(`git commit -m ${shellEscape("chore(run): checkpoint run state before promotion")}`, o);
+  }
+  await exec2(`git fetch origin ${shellEscape(baseBranch)}`, o).catch(() => {
+  });
+  let conflicted = false;
+  try {
+    await exec2(`git merge --no-ff -m ${shellEscape(`merge ${baseBranch} for promotion`)} ${shellEscape(`origin/${baseBranch}`)}`, o);
+  } catch {
+    conflicted = true;
+  }
+  if (!conflicted) return { reconciled: false };
+  const u = (await exec2("git diff --name-only --diff-filter=U", o).catch(() => "")).split("\n").map((s) => s.trim()).filter(Boolean);
+  const other = u.filter((p) => !PROMOTE_RUNSTATE_CONFLICT.test(p));
+  if (u.length === 0 || other.length > 0) {
+    await exec2("git merge --abort", o).catch(() => {
+    });
+    throw new ScmMergeError(
+      other.length > 0 ? `promotion conflicts on non-ledger file(s): ${other.join(", ")}. Resolve the real divergence manually, then re-run the promote.` : `promotion merge failed with no resolvable conflicts; resolve manually and re-run.`,
+      "promote-conflict"
+    );
+  }
+  for (const p of u) {
+    await exec2(`git checkout --ours -- ${shellEscape(p)}`, o);
+    await exec2(`git add -- ${shellEscape(p)}`, o);
+  }
+  await exec2(`git commit -m ${shellEscape(`merge ${baseBranch} for promotion (pipeline.json ledger kept at run state)`)}`, o);
+  await pushCurrentBranchForPr({ cwd: projectDir });
+  return { reconciled: true, detail: `reconciled ${u.length} ledger path(s) to the run side + pushed` };
+}
 async function defaultRefreshPromoteWorkflows(projectDir) {
   const drift = detectWorkflowDrift({ projectDir });
   const touched = drift.files.filter((f) => f.status === "drifted").map((f) => f.name);
@@ -9392,6 +9512,15 @@ async function mergeFeature(args) {
       );
     }
   }
+  {
+    const fetchState = args.fetchPrState ?? ((o, h) => getPullRequest(o, h));
+    const prState = await fetchState(ownerRepo, current.branch).catch(() => void 0);
+    if (prState?.mergeableState === "dirty") {
+      const reconcile = args.reconcileRunState ?? ((base) => reconcilePromoteRunState(args.projectDir, base));
+      const r = await reconcile(gitBase);
+      if (r.reconciled) preflightNotes.push(`Reconciled a pipeline.json-ledger promotion conflict to the run side${r.detail ? ` (${r.detail})` : ""}.`);
+    }
+  }
   let paired;
   try {
     paired = await mergePairedPullRequest({
@@ -9627,8 +9756,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.2.47".length > 0) {
-    cached = "0.2.47";
+  if ("0.2.48".length > 0) {
+    cached = "0.2.48";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/scm-reconcile-tier.cli.cjs

@@ -79288,8 +79288,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.2.47".length > 0) {
-    cached = "0.2.47";
+  if ("0.2.48".length > 0) {
+    cached = "0.2.48";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/scm-reconcile-tier.cli.js

@@ -389,8 +389,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.2.47".length > 0) {
-    cached = "0.2.47";
+  if ("0.2.48".length > 0) {
+    cached = "0.2.48";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/util/index.cjs

@@ -1661,8 +1661,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.2.47".length > 0) {
-    cached = "0.2.47";
+  if ("0.2.48".length > 0) {
+    cached = "0.2.48";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/util/index.js

@@ -1630,8 +1630,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.2.47".length > 0) {
-    cached = "0.2.47";
+  if ("0.2.48".length > 0) {
+    cached = "0.2.48";
     return cached;
   }
   cached = "unknown";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@databricks-solutions/lakebase-scm-utils",
-  "version": "0.2.47",
+  "version": "0.2.48",
   "description": "Lakebase SCM + substrate engine: database branching, paired-branch SCM workflows, connection/credential minting, schema migration, project scaffold + deploy primitives, and the git/github utility layer. Extracted from consort for portable, standalone consumption by lakebase-scm-extension and the SFTDD orchestration.",
   "type": "module",
   "private": false,

package/scripts/lakebase/scm-merge.ts

@@ -12,6 +12,7 @@
 // stable surface for that signal.
 
 import {
+  getPullRequest,
   listWorkflowRuns,
   mergePairedPullRequest,
   type WorkflowRunSummary,
@@ -68,6 +69,7 @@ export class ScmMergeError extends Error {
       | "no-pr-url"
       | "bad-pr-url"
       | "merge-failed"
+      | "promote-conflict"
       | "migrate-failed"
       | "migrate-timeout"
       | "migrate-auth",
@@ -166,6 +168,13 @@ export interface MergeArgs {
    * implementation ({@link defaultRefreshPromoteWorkflows}); injected in tests.
    */
   refreshWorkflows?: () => Promise<{ refreshed: boolean; detail?: string }>;
+  /** Pre-merge reconcile of a pipeline.json-ledger promotion conflict to the run side (keeps it
+   *  tracked). Called ONLY when the PR is CONFLICTING. Defaults to {@link reconcilePromoteRunState};
+   *  injected in tests. */
+  reconcileRunState?: (baseBranch: string) => Promise<{ reconciled: boolean; detail?: string }>;
+  /** Fetch the PR's mergeability (to gate the reconcile). Defaults to the real getPullRequest;
+   *  injected in tests so the gate is exercised without the network. */
+  fetchPrState?: (ownerRepo: string, headBranch: string) => Promise<{ mergeableState?: string } | undefined>;
 }
 
 export interface MergeResult {
@@ -248,6 +257,71 @@ function shaMigratePredicate(
  * working-tree changes. Callers invoke it BEST-EFFORT — a failure here must never
  * block the merge (the local migrate fallback still keeps git + schema in sync).
  */
+/** The ONLY paths a promotion merge may auto-resolve to the RUN (feature/head) side: the per-story
+ *  pipeline.json ledger (per-feature, and the legacy top-level pointer). It is the feature branch's
+ *  own durable bookkeeping — the tier has no authoritative copy — so on a promotion conflict the
+ *  head side always wins. Everything else is real divergence and must surface, never auto-resolve. */
+const PROMOTE_RUNSTATE_CONFLICT = /(^|\/)\.consort\/(features\/[^/]+\/)?pipeline\.json$/;
+
+/**
+ * Clear a promotion-merge conflict that is ONLY the pipeline.json ledger, so GitHub can dispatch CI
+ * and merge — WITHOUT untracking the ledger (it's durable run-state that must persist). Merges the
+ * base into the PR head and resolves the ledger path(s) to the head (run) side, then pushes. This is
+ * the merge-layer fix for the "pipeline.json conflict blocks promotion" defect, replacing the wrong
+ * earlier approach of gitignoring/untracking it. Behavior:
+ *   - a dirty tree under `.consort/` only is checkpointed first (the run's own bookkeeping);
+ *   - a dirty tree OUTSIDE `.consort/` aborts (never auto-commit app code);
+ *   - a conflict on any NON-ledger path aborts the merge + surfaces (real divergence isn't resolved);
+ *   - a clean merge (no conflict) is a no-op (reconciled:false).
+ * Only call this when the PR is actually CONFLICTING — a clean promote needs no merge commit.
+ */
+export async function reconcilePromoteRunState(
+  projectDir: string,
+  baseBranch: string,
+): Promise<{ reconciled: boolean; detail?: string }> {
+  const o = { cwd: projectDir, timeout: 30_000 };
+  // Working tree must be clean to merge. Checkpoint run-state (.consort/) if that's all that's dirty;
+  // refuse on anything else so we never auto-commit app code during a promotion.
+  const dirty = (await exec("git status --porcelain", o).catch(() => "")).split("\n").map((l) => l.slice(3).trim()).filter(Boolean);
+  const nonRunStateDirty = dirty.filter((p) => !p.startsWith(".consort/"));
+  if (nonRunStateDirty.length > 0) {
+    throw new ScmMergeError(
+      `working tree has uncommitted non-run-state changes (${nonRunStateDirty.slice(0, 5).join(", ")}${nonRunStateDirty.length > 5 ? ", …" : ""}); commit or stash before promoting.`,
+      "promote-conflict",
+    );
+  }
+  if (dirty.length > 0) {
+    await exec(`git add ${shellEscape(".consort")}`, o);
+    await exec(`git commit -m ${shellEscape("chore(run): checkpoint run state before promotion")}`, o);
+  }
+  await exec(`git fetch origin ${shellEscape(baseBranch)}`, o).catch(() => {});
+  let conflicted = false;
+  try {
+    await exec(`git merge --no-ff -m ${shellEscape(`merge ${baseBranch} for promotion`)} ${shellEscape(`origin/${baseBranch}`)}`, o);
+  } catch {
+    conflicted = true;
+  }
+  if (!conflicted) return { reconciled: false }; // clean merge (or already up to date) — nothing to resolve
+  const u = (await exec("git diff --name-only --diff-filter=U", o).catch(() => "")).split("\n").map((s) => s.trim()).filter(Boolean);
+  const other = u.filter((p) => !PROMOTE_RUNSTATE_CONFLICT.test(p));
+  if (u.length === 0 || other.length > 0) {
+    await exec("git merge --abort", o).catch(() => {});
+    throw new ScmMergeError(
+      other.length > 0
+        ? `promotion conflicts on non-ledger file(s): ${other.join(", ")}. Resolve the real divergence manually, then re-run the promote.`
+        : `promotion merge failed with no resolvable conflicts; resolve manually and re-run.`,
+      "promote-conflict",
+    );
+  }
+  for (const p of u) {
+    await exec(`git checkout --ours -- ${shellEscape(p)}`, o); // keep the run (feature) ledger
+    await exec(`git add -- ${shellEscape(p)}`, o);
+  }
+  await exec(`git commit -m ${shellEscape(`merge ${baseBranch} for promotion (pipeline.json ledger kept at run state)`)}`, o);
+  await pushCurrentBranchForPr({ cwd: projectDir });
+  return { reconciled: true, detail: `reconciled ${u.length} ledger path(s) to the run side + pushed` };
+}
+
 export async function defaultRefreshPromoteWorkflows(
   projectDir: string,
 ): Promise<{ refreshed: boolean; detail?: string }> {
@@ -376,6 +450,23 @@ export async function mergeFeature(args: MergeArgs): Promise<MergeResult> {
     }
   }
 
+  // ─── Pre-merge pipeline.json-ledger reconcile ───
+  // The per-feature pipeline.json ledger is TRACKED (durable run-state) and can diverge between the
+  // feature branch and its tier, so the promotion PR lands CONFLICTING — GitHub won't dispatch CI or
+  // merge. When that happens, reconcile the ledger to the run (head) side at the MERGE layer and push,
+  // so the PR goes mergeable WITHOUT untracking the ledger. Only runs when the PR is actually dirty;
+  // a non-ledger conflict throws (real divergence surfaces). This is the correct replacement for the
+  // withdrawn gitignore/untrack approach.
+  {
+    const fetchState = args.fetchPrState ?? ((o, h) => getPullRequest(o, h));
+    const prState = await fetchState(ownerRepo, current.branch).catch(() => undefined);
+    if (prState?.mergeableState === "dirty") {
+      const reconcile = args.reconcileRunState ?? ((base: string) => reconcilePromoteRunState(args.projectDir, base));
+      const r = await reconcile(gitBase); // throws ScmMergeError on a non-ledger conflict (surfaces)
+      if (r.reconciled) preflightNotes.push(`Reconciled a pipeline.json-ledger promotion conflict to the run side${r.detail ? ` (${r.detail})` : ""}.`);
+    }
+  }
+
   let paired: Awaited<ReturnType<typeof mergePairedPullRequest>>;
   try {
     paired = await mergePairedPullRequest({

package/templates/project/common/.gitignore.base

@@ -29,13 +29,11 @@ application-local.properties
 # it on the feature branch at each cut so the spec history survives for later stories).
 .consort/cycles/
 .consort/experiments/
-# The live build-pipeline pointer. It lives PER-FEATURE (.consort/features/<id>/pipeline.json);
-# the bare `.consort/pipeline.json` is kept for older layouts. Matching only the top-level path
-# left the per-feature file TRACKED — so it travelled onto staging/main and collided at the
-# promotion merge (two branches editing one run's gate-bookkeeping), the exact "pipeline.json
-# conflict blocks promotion" defect. Both forms are run-state, never the design corpus.
 .consort/pipeline.json
-.consort/features/*/pipeline.json
+# NOTE: the PER-FEATURE ledger .consort/features/<id>/pipeline.json is deliberately NOT ignored —
+# it is the durable per-story pipeline state (persisted on the feature branch so it survives across
+# sessions). Ignoring it lost the ledger. A promotion-merge conflict on it is resolved at the MERGE
+# layer (scm-merge reconciles it to the run side), never by untracking it.
 # The turn recorder's per-run observability: its internal file-hash map
 # (.recorder-state.json, used for delta computation), the routing-decision
 # diagnostic stream (routing-decisions.jsonl), and the per-turn record dirs