@databricks-solutions/lakebase-scm-utils 0.3.6 → 0.3.7

package/scripts/lakebase/scm-abandon-feature.ts

@@ -13,28 +13,19 @@
 // completes the state reset.
 
 import { deletePairedBranch } from "./paired-branch.js";
-import { getCurrentBranch } from "../git/inspect.js";
-import { isDirty } from "../git/status.js";
-import { exec } from "../util/exec.js";
+import { type ScmWorkflowState } from "./scm-workflow-state.js";
 import {
-  readWorkflowState,
-  writeWorkflowState,
-  type ScmWorkflowState,
-} from "./scm-workflow-state.js";
+  ScmReleaseError,
+  prepareClaimRelease,
+  resetToScaffoldComplete,
+} from "./scm-release-claim.js";
 
-export class ScmAbandonError extends Error {
-  constructor(
-    message: string,
-    public readonly code:
-      | "no-state-file"
-      | "bad-precondition"
-      | "dirty-working-tree"
-      | "missing-claim-fields",
-  ) {
-    super(message);
-    this.name = "ScmAbandonError";
-  }
-}
+export { ScmReleaseError };
+
+/** Back-compat alias: abandon historically threw its own error class. It is now a subclass of the
+ *  shared `ScmReleaseError` so existing `instanceof ScmAbandonError` checks still narrow, while the
+ *  shared release core (which both abandon and park use) throws the base. */
+export class ScmAbandonError extends ScmReleaseError {}
 
 export interface AbandonFeatureArgs {
   projectDir: string;
@@ -64,76 +55,21 @@ export interface AbandonFeatureResult {
 export async function abandonFeatureBranch(
   args: AbandonFeatureArgs,
 ): Promise<AbandonFeatureResult> {
-  const current = readWorkflowState(args.projectDir);
-  if (!current) {
-    throw new ScmAbandonError(
-      `No SCM workflow state found at ${args.projectDir}/.lakebase/workflow-state.json.`,
-      "no-state-file",
-    );
-  }
-  if (current.state !== "feature-claimed") {
-    throw new ScmAbandonError(
-      `abandon refuses state "${current.state}". Only feature-claimed is abandonable; later states must complete or be reverted via gh.`,
-      "bad-precondition",
-    );
-  }
-  if (
-    !current.feature_id ||
-    !current.branch ||
-    !current.parent_branch ||
-    !current.lakebase_branch_uid
-  ) {
-    throw new ScmAbandonError(
-      "feature-claimed row is missing required invariants. Cannot abandon safely; consider re-adopting state first.",
-      "missing-claim-fields",
-    );
-  }
-
-  if (!args.force) {
-    const dirty = await isDirty({ cwd: args.projectDir });
-    if (dirty) {
-      throw new ScmAbandonError(
-        "Working tree has uncommitted changes; refusing to abandon (the branch delete would lose them). Commit / stash / discard first, or pass --force.",
-        "dirty-working-tree",
-      );
-    }
-  }
-
-  const instance = args.instance ?? current.project_id;
-  const switchTo = args.switchTo ?? current.parent_branch;
-  const warnings: string[] = [];
-
-  // Switch HEAD off the feature branch first so deletePairedBranch can
-  // delete the local git branch (it skips when the branch is checked out).
-  const headBranch = await getCurrentBranch({ cwd: args.projectDir });
-  if (headBranch === current.branch) {
-    try {
-      await exec(`git checkout ${JSON.stringify(switchTo)}`, {
-        cwd: args.projectDir,
-        timeout: 10_000,
-      });
-    } catch (err) {
-      warnings.push(
-        `git checkout ${switchTo} failed: ${err instanceof Error ? err.message : String(err)}. Local branch delete may be skipped.`,
-      );
-    }
-  }
+  // Shared preamble: validate the claim is releasable + switch HEAD off the feature branch.
+  const { current, warnings } = await prepareClaimRelease(
+    { projectDir: args.projectDir, force: args.force, switchTo: args.switchTo },
+    "abandon",
+  );
 
+  // Abandon's distinguishing step: tear down the paired Lakebase + git branch.
   const del = await deletePairedBranch({
-    instance,
+    instance: args.instance ?? current.project_id,
     branch: current.branch,
     cwd: args.projectDir,
   });
   warnings.push(...del.warnings);
 
-  const reset: ScmWorkflowState = {
-    $schema: current.$schema,
-    version: 1,
-    state: "scaffold-complete",
-    tier_topology: current.tier_topology,
-    project_id: current.project_id,
-  };
-  writeWorkflowState(args.projectDir, reset);
+  const reset: ScmWorkflowState = resetToScaffoldComplete(args.projectDir, current);
 
   return {
     state: reset,

package/scripts/lakebase/scm-park-feature.cli.ts

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// CLI: park the in-flight feature claim (free it, KEEP the branch) and reset to scaffold-complete.
+// The resume-later counterpart to abandon. phase B+.
+
+import * as path from "node:path";
+import { isCliEntry } from "../util/cli-entry.js";
+import { ScmReleaseError } from "./scm-release-claim.js";
+import {
+  parkFeatureBranch,
+  type ParkFeatureResult,
+} from "./scm-park-feature.js";
+
+interface ParsedArgs {
+  projectDir?: string;
+  switchTo?: string;
+  force?: boolean;
+  json?: boolean;
+  pretty?: boolean;
+  help?: boolean;
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const out: ParsedArgs = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case "--project-dir":
+      case "--cwd":
+        out.projectDir = argv[++i];
+        break;
+      case "--switch-to":
+        out.switchTo = argv[++i];
+        break;
+      case "--force":
+        out.force = true;
+        break;
+      case "--json":
+        out.json = true;
+        break;
+      case "--pretty":
+        out.pretty = true;
+        break;
+      case "--help":
+      case "-h":
+        out.help = true;
+        break;
+    }
+  }
+  return out;
+}
+
+const HELP = `lakebase-scm-park-feature (phase B+)
+
+Release a feature claim but KEEP its paired branch: switch HEAD to the parent
+tier, reset workflow-state to scaffold-complete, leave the Lakebase + git
+branch intact. Frees the single SCM claim so another feature can be claimed
+and driven; resume the parked feature later with
+'lakebase-scm-claim-feature-branch <feature>' (it reuses the kept branch).
+
+Usage:
+  lakebase-scm-park-feature [flags]
+
+Flags:
+  --project-dir <dir>   Project root (default: cwd)
+  --switch-to <branch>  Branch to checkout after releasing (default: parent_branch)
+  --force               Allow park even with a dirty working tree
+                        (edits are kept but stranded on the feature branch)
+  --json                Machine-readable JSON output
+  --pretty              Pretty-print JSON (only with --json)
+  -h, --help            Show this help
+
+Exit codes:
+  0 = parked (claim freed, branch kept, state reset to scaffold-complete)
+  1 = no state file
+  2 = precondition refused (wrong state, dirty tree without --force, missing fields)
+  3 = substrate failure
+`;
+
+interface ParkReport {
+  ok: boolean;
+  result?: ParkFeatureResult;
+  error?: { code: string; message: string };
+}
+
+function renderHuman(report: ParkReport): string {
+  if (!report.ok) {
+    return `lakebase-scm-park-feature: ${report.error?.code}\n\n  ${report.error?.message}`;
+  }
+  const r = report.result!;
+  const lines: string[] = ["Feature parked (branch kept):"];
+  lines.push(`  state          : ${r.state.state}`);
+  lines.push(`  parked_feature : ${r.parkedFeatureId}`);
+  lines.push(`  kept_branch    : ${r.keptBranch}`);
+  lines.push(`  switched_to    : ${r.switchedTo}`);
+  lines.push("");
+  lines.push(`  resume with    : lakebase-scm-claim-feature-branch ${r.parkedFeatureId}`);
+  if (r.warnings.length > 0) {
+    lines.push("");
+    lines.push("warnings:");
+    for (const w of r.warnings) lines.push(`  - ${w}`);
+  }
+  return lines.join("\n");
+}
+
+function exitCodeForError(err: Error): number {
+  if (err instanceof ScmReleaseError) {
+    if (err.code === "no-state-file") return 1;
+    return 2;
+  }
+  return 3;
+}
+
+export async function runScmParkFeatureCli(argv: string[]): Promise<number> {
+  const args = parseArgs(argv);
+  if (args.help) {
+    process.stdout.write(`${HELP}\n`);
+    return 0;
+  }
+  const projectDir = path.resolve(args.projectDir ?? process.cwd());
+  try {
+    const result = await parkFeatureBranch({
+      projectDir,
+      switchTo: args.switchTo,
+      force: args.force,
+    });
+    const report: ParkReport = { ok: true, result };
+    if (args.json) {
+      const indent = args.pretty ? 2 : 0;
+      process.stdout.write(`${JSON.stringify(report, null, indent)}\n`);
+    } else {
+      process.stdout.write(`${renderHuman(report)}\n`);
+    }
+    return 0;
+  } catch (e) {
+    const err = e as Error;
+    const code = err instanceof ScmReleaseError ? err.code : "substrate-failure";
+    const report: ParkReport = { ok: false, error: { code, message: err.message } };
+    if (args.json) {
+      const indent = args.pretty ? 2 : 0;
+      process.stdout.write(`${JSON.stringify(report, null, indent)}\n`);
+    } else {
+      process.stderr.write(`${renderHuman(report)}\n`);
+    }
+    return exitCodeForError(err);
+  }
+}
+
+if (isCliEntry(import.meta.url)) {
+  void runScmParkFeatureCli(process.argv.slice(2)).then((c) => process.exit(c));
+}

package/scripts/lakebase/scm-park-feature.ts

@@ -0,0 +1,71 @@
+// SCM workflow park (phase B+): release a feature claim WITHOUT tearing down the branch.
+//
+// Transitions feature-claimed -> scaffold-complete and switches HEAD to the parent tier, but — unlike
+// abandon — KEEPS the paired Lakebase + git branch intact. This frees the single SCM claim so another
+// feature can be claimed and driven, while the parked feature's work sits safely on its branch. The
+// claim model makes RESUMING free: `lakebase-scm-claim-feature-branch <same-feature>` re-claims from
+// scaffold-complete and `createFeaturePairedBranch` reuses the existing paired branch as-is (DB and
+// all), picking the feature back up where it stopped.
+//
+// Use when a feature is built but NOT yet deployed/merged and you want to shelve it and go work on
+// another. (Abandon is the throwaway counterpart: it deletes the branch.) Refuses on a dirty working
+// tree by default (switching HEAD would strand uncommitted edits) unless --force.
+//
+// The preamble (precondition + dirty-guard + HEAD switch) and the scaffold-complete reset are the
+// shared release core in scm-release-claim.ts, so park and abandon cannot drift.
+
+import { type ScmWorkflowState } from "./scm-workflow-state.js";
+import {
+  ScmReleaseError,
+  prepareClaimRelease,
+  resetToScaffoldComplete,
+} from "./scm-release-claim.js";
+
+export { ScmReleaseError };
+
+export interface ParkFeatureArgs {
+  /** Project root (must contain .lakebase/workflow-state.json + .git/). */
+  projectDir: string;
+  /**
+   * Skip the dirty-working-tree refusal. Uncommitted edits are NOT lost (the branch is kept), but
+   * switching HEAD off the feature branch would leave them stranded on it, so the default refuses.
+   */
+  force?: boolean;
+  /**
+   * Switch HEAD to this branch after releasing the claim. Defaults to the workflow row's
+   * parent_branch (the tier the feature forked from).
+   */
+  switchTo?: string;
+}
+
+export interface ParkFeatureResult {
+  state: ScmWorkflowState;
+  /** The branch left intact (git name) — resume with `lakebase-scm-claim-feature-branch`. */
+  keptBranch: string;
+  /** The feature id that was parked (for logging / the consort bookkeeping repoint). */
+  parkedFeatureId: string;
+  switchedTo: string;
+  warnings: string[];
+}
+
+export async function parkFeatureBranch(
+  args: ParkFeatureArgs,
+): Promise<ParkFeatureResult> {
+  // Shared preamble: validate the claim is releasable + switch HEAD off the feature branch.
+  const { current, switchTo, warnings } = await prepareClaimRelease(
+    { projectDir: args.projectDir, force: args.force, switchTo: args.switchTo },
+    "park",
+  );
+
+  // Park's distinguishing (non-)step: the paired branch is DELIBERATELY left in place — this is the
+  // whole point. Just reset the claim row so the next feature can be claimed.
+  const reset = resetToScaffoldComplete(args.projectDir, current);
+
+  return {
+    state: reset,
+    keptBranch: current.branch,
+    parkedFeatureId: current.feature_id,
+    switchedTo: switchTo,
+    warnings,
+  };
+}

package/scripts/lakebase/scm-release-claim.ts

@@ -0,0 +1,146 @@
+// Shared core for the two ways to RELEASE an in-flight feature claim back to scaffold-complete:
+//   - abandon (scm-abandon-feature): free the claim AND tear down the paired branch.
+//   - park    (scm-park-feature):    free the claim but KEEP the paired branch, so the feature can
+//                                     be resumed later (a re-claim reuses the existing branch as-is).
+//
+// Both share the exact same preamble — read state, require feature-claimed, require the claim's
+// invariants, refuse a dirty tree (switching HEAD or deleting the branch would strand uncommitted
+// work) unless --force, then switch HEAD off the feature branch — and the exact same tail: reset the
+// workflow-state row to a bare scaffold-complete. The ONLY difference is whether the paired branch is
+// deleted in between. Factored here so the two commands cannot drift (DRY); each command owns only its
+// middle step and its own CLI surface.
+
+import { getCurrentBranch } from "../git/inspect.js";
+import { isDirty } from "../git/status.js";
+import { exec } from "../util/exec.js";
+import {
+  readWorkflowState,
+  writeWorkflowState,
+  type ScmWorkflowState,
+} from "./scm-workflow-state.js";
+
+export type ScmReleaseErrorCode =
+  | "no-state-file"
+  | "bad-precondition"
+  | "dirty-working-tree"
+  | "missing-claim-fields";
+
+/** The shared error for a claim release. `abandon` keeps its own `ScmAbandonError` as a subclass for
+ *  back-compat; CLIs that map codes to exit statuses check `instanceof ScmReleaseError` (the base). */
+export class ScmReleaseError extends Error {
+  constructor(
+    message: string,
+    public readonly code: ScmReleaseErrorCode,
+  ) {
+    super(message);
+    this.name = "ScmReleaseError";
+  }
+}
+
+export interface ReleaseClaimArgs {
+  /** Project root (must contain .lakebase/workflow-state.json + .git/). */
+  projectDir: string;
+  /** Skip the dirty-working-tree refusal. */
+  force?: boolean;
+  /** Branch to checkout before releasing. Defaults to the workflow row's parent_branch. */
+  switchTo?: string;
+}
+
+/** A feature-claimed row with its claim invariants proven present, plus the resolved HEAD target. */
+export interface PreparedRelease {
+  current: ScmWorkflowState & {
+    feature_id: string;
+    branch: string;
+    parent_branch: string;
+    lakebase_branch_uid: string;
+  };
+  switchTo: string;
+  warnings: string[];
+}
+
+/**
+ * The shared preamble for abandon + park: validate the claim is releasable and switch HEAD off the
+ * feature branch so the next step (delete, or just reset) is safe. `verb` ("abandon" | "park") only
+ * shapes the human-facing refusal messages. Throws `ScmReleaseError` on any precondition failure.
+ */
+export async function prepareClaimRelease(
+  args: ReleaseClaimArgs,
+  verb: "abandon" | "park",
+): Promise<PreparedRelease> {
+  const current = readWorkflowState(args.projectDir);
+  if (!current) {
+    throw new ScmReleaseError(
+      `No SCM workflow state found at ${args.projectDir}/.lakebase/workflow-state.json.`,
+      "no-state-file",
+    );
+  }
+  if (current.state !== "feature-claimed") {
+    throw new ScmReleaseError(
+      `${verb} refuses state "${current.state}". Only feature-claimed is ${verb}able; later states must complete or be reverted via gh.`,
+      "bad-precondition",
+    );
+  }
+  if (
+    !current.feature_id ||
+    !current.branch ||
+    !current.parent_branch ||
+    !current.lakebase_branch_uid
+  ) {
+    throw new ScmReleaseError(
+      `feature-claimed row is missing required invariants. Cannot ${verb} safely; consider re-adopting state first.`,
+      "missing-claim-fields",
+    );
+  }
+
+  if (!args.force) {
+    const dirty = await isDirty({ cwd: args.projectDir });
+    if (dirty) {
+      throw new ScmReleaseError(
+        `Working tree has uncommitted changes; refusing to ${verb} (switching HEAD off the feature branch would strand them). Commit / stash / discard first, or pass --force.`,
+        "dirty-working-tree",
+      );
+    }
+  }
+
+  const switchTo = args.switchTo ?? current.parent_branch;
+  const warnings: string[] = [];
+
+  // Switch HEAD off the feature branch first: abandon needs it so the local git branch can be
+  // deleted (delete skips a checked-out branch); park needs it so the tree sits on the tier, ready
+  // for the next claim. Best-effort — a checkout failure is a warning, not a hard stop.
+  const headBranch = await getCurrentBranch({ cwd: args.projectDir });
+  if (headBranch === current.branch) {
+    try {
+      await exec(`git checkout ${JSON.stringify(switchTo)}`, {
+        cwd: args.projectDir,
+        timeout: 10_000,
+      });
+    } catch (err) {
+      warnings.push(
+        `git checkout ${switchTo} failed: ${err instanceof Error ? err.message : String(err)}. Local branch state may be left on the feature branch.`,
+      );
+    }
+  }
+
+  return { current: current as PreparedRelease["current"], switchTo, warnings };
+}
+
+/**
+ * Reset the workflow-state row to a bare scaffold-complete (no feature in flight), preserving only
+ * the project-scoped facts (tier topology, project id). The shared tail of both abandon and park:
+ * after this the next claim can proceed.
+ */
+export function resetToScaffoldComplete(
+  projectDir: string,
+  current: ScmWorkflowState,
+): ScmWorkflowState {
+  const reset: ScmWorkflowState = {
+    $schema: current.$schema,
+    version: 1,
+    state: "scaffold-complete",
+    tier_topology: current.tier_topology,
+    project_id: current.project_id,
+  };
+  writeWorkflowState(projectDir, reset);
+  return reset;
+}