gflows 0.1.17 → 1.0.0

package/src/commands/sync.ts

@@ -0,0 +1,160 @@
+/**
+ * Sync command: update current workflow branch from its base (fetch + merge or rebase).
+ * Stashes dirty work when needed; supports continue via run-state.
+ * @module commands/sync
+ */
+
+import { getBranchTypeMeta, resolveConfig } from "../config.js";
+import { EXIT_USER } from "../constants.js";
+import { DirtyWorkingTreeError } from "../errors.js";
+import { classifyBranch, getBaseBranchName } from "../flow.js";
+import {
+  assertNotDetached,
+  fetch,
+  getCurrentBranch,
+  isClean,
+  resolveRepoRoot,
+  resolveSha,
+  runGit,
+  stashPopRef,
+  stashPushMove,
+} from "../git.js";
+import { hint, success } from "../out.js";
+import {
+  completeRun,
+  type GflowsRunState,
+  startRun,
+  suspendRun,
+  writeActiveRun,
+} from "../run-state.js";
+import type { ParsedArgs } from "../types.js";
+
+/**
+ * Executes remaining sync steps (used by continue).
+ */
+export async function executeSyncSteps(
+  repoRoot: string,
+  state: GflowsRunState,
+  opts: { dryRun: boolean; verbose: boolean; quiet: boolean },
+): Promise<void> {
+  let i = state.nextStep;
+  while (i < state.steps.length) {
+    const step = state.steps[i];
+    if (!step) break;
+    try {
+      const base = String(state.context.base);
+      const rebase = Boolean(state.context.rebase);
+      if (step.id === "update") {
+        if (rebase) {
+          const r = await runGit(["rebase", base], { cwd: repoRoot, ...opts });
+          if (r.exitCode !== 0) {
+            throw new Error(`Rebase onto '${base}' conflicted.`);
+          }
+        } else {
+          const r = await runGit(["merge", base], { cwd: repoRoot, ...opts });
+          if (r.exitCode !== 0) {
+            throw new Error(`Merge from '${base}' conflicted.`);
+          }
+        }
+      } else if (step.id === "stash-pop") {
+        const ref = typeof state.undo.stashRef === "string" ? state.undo.stashRef : null;
+        if (ref) {
+          await stashPopRef(repoRoot, ref, opts).catch(() => undefined);
+        }
+      }
+      i += 1;
+      state.nextStep = i;
+      writeActiveRun(repoRoot, { ...state, status: "running" });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      suspendRun(repoRoot, { ...state, nextStep: i }, msg);
+      throw err;
+    }
+  }
+  completeRun(repoRoot, state);
+  if (!opts.quiet && !opts.dryRun) {
+    success(`gflows: synced with '${String(state.context.base)}'.`);
+  }
+}
+
+/**
+ * Runs sync on the current workflow branch.
+ */
+export async function run(args: ParsedArgs): Promise<void> {
+  const repoRoot = await resolveRepoRoot(args.cwd);
+  const config = resolveConfig(
+    repoRoot,
+    { main: args.main, dev: args.dev, remote: args.remote },
+    { verbose: args.verbose },
+  );
+  const opts = { dryRun: args.dryRun, verbose: args.verbose, quiet: args.quiet };
+
+  await assertNotDetached(repoRoot);
+  const current = await getCurrentBranch(repoRoot, opts);
+  if (!current) {
+    console.error("gflows sync: HEAD is detached.");
+    process.exit(EXIT_USER);
+  }
+
+  const classification = classifyBranch(current, config);
+  if (classification === "main" || classification === "dev") {
+    // Allow updating long-lived from remote tracking
+    await fetch(repoRoot, config.remote, opts);
+    const remoteRef = `${config.remote}/${current}`;
+    const r = await runGit(["merge", remoteRef], { cwd: repoRoot, ...opts });
+    if (r.exitCode !== 0) {
+      console.error(`gflows sync: could not update '${current}' from ${remoteRef}.`);
+      process.exit(2);
+    }
+    if (!args.quiet) success(`gflows: updated '${current}' from ${remoteRef}.`);
+    return;
+  }
+  if (classification === null) {
+    console.error(`gflows sync: '${current}' is not a known workflow branch.`);
+    hint("Use gflows start to create a typed branch, or checkout feature/bugfix/…");
+    process.exit(EXIT_USER);
+  }
+
+  const fromMain = classification === "bugfix" && args.fromMain;
+  const base = getBaseBranchName(classification, fromMain, config);
+  // For bugfix-from-main detection on sync: if type is bugfix, prefer meta base unless fromMain
+  const meta = getBranchTypeMeta(classification);
+  const baseBranch =
+    classification === "hotfix" || (classification === "bugfix" && args.fromMain)
+      ? config.main
+      : meta.base === "main"
+        ? config.main
+        : config.dev;
+
+  await fetch(repoRoot, config.remote, opts);
+
+  let stashed = false;
+  const clean = await isClean(repoRoot, opts);
+  if (!clean) {
+    if (!args.force && !args.yes && !process.stdin.isTTY) {
+      throw new DirtyWorkingTreeError(
+        "Working tree dirty. Commit, stash, or pass --force to stash automatically during sync.",
+      );
+    }
+    await stashPushMove(repoRoot, opts);
+    stashed = true;
+  }
+
+  const beforeSha = await resolveSha(repoRoot, current, opts);
+  const steps = [
+    { id: "update", label: args.rebase ? `Rebase onto ${baseBranch}` : `Merge ${baseBranch}` },
+    ...(stashed ? [{ id: "stash-pop", label: "Restore stash" }] : []),
+  ];
+
+  const state = startRun(
+    repoRoot,
+    "sync",
+    steps,
+    { base: baseBranch, rebase: args.rebase, branch: current },
+    { beforeSha, branch: current, stashRef: stashed ? "stash@{0}" : null },
+  );
+
+  // Prefer configured base; ensure local base exists
+  void base;
+  await executeSyncSteps(repoRoot, state, opts);
+}

package/src/commands/undo.ts

@@ -0,0 +1,78 @@
+/**
+ * Undo the last completed gflows operation when reversible.
+ * @module commands/undo
+ */
+
+import { EXIT_USER } from "../constants.js";
+import { checkout, deleteTag, resolveRepoRoot, runGit, tagExists } from "../git.js";
+import { hint, success } from "../out.js";
+import { clearLastRun, readLastRun } from "../run-state.js";
+import type { ParsedArgs } from "../types.js";
+
+/**
+ * Best-effort undo of the last completed gflows command.
+ */
+export async function run(args: ParsedArgs): Promise<void> {
+  const repoRoot = await resolveRepoRoot(args.cwd);
+  const last = readLastRun(repoRoot);
+  if (last?.status !== "completed") {
+    console.error("gflows undo: nothing to undo.");
+    process.exit(EXIT_USER);
+  }
+
+  const opts = { dryRun: args.dryRun, verbose: args.verbose };
+  const undo = last.undo;
+
+  if (last.command === "finish") {
+    const createdTag = typeof undo.createdTag === "string" ? undo.createdTag : null;
+    const mainName = typeof undo.main === "string" ? undo.main : "main";
+    const devName = typeof undo.dev === "string" ? undo.dev : "dev";
+    const branchName = typeof undo.branchName === "string" ? undo.branchName : null;
+    const branchSha = typeof undo.branchSha === "string" ? undo.branchSha : null;
+    const prevBranch = typeof undo.prevBranch === "string" ? undo.prevBranch : null;
+
+    if (createdTag && (await tagExists(repoRoot, createdTag, opts))) {
+      await deleteTag(repoRoot, createdTag, opts);
+      if (!args.quiet) success(`gflows: deleted tag '${createdTag}'.`);
+    }
+
+    if (typeof undo.mainSha === "string") {
+      await runGit(["branch", "-f", mainName, undo.mainSha], { cwd: repoRoot, ...opts });
+    }
+    if (typeof undo.devSha === "string") {
+      await runGit(["branch", "-f", devName, undo.devSha], { cwd: repoRoot, ...opts });
+    }
+
+    if (branchName && branchSha && undo.shouldDelete) {
+      await runGit(["branch", branchName, branchSha], { cwd: repoRoot, ...opts });
+      if (!args.quiet) success(`gflows: restored branch '${branchName}'.`);
+    }
+
+    if (prevBranch) {
+      await checkout(repoRoot, prevBranch, opts).catch(() => undefined);
+    }
+
+    clearLastRun(repoRoot);
+    if (!args.quiet) {
+      success("gflows: undid last finish (best effort). Remote was not modified.");
+    }
+    hint("If you had pushed, reset remotes manually.");
+    return;
+  }
+
+  if (last.command === "sync") {
+    const branch = typeof undo.branch === "string" ? undo.branch : null;
+    const beforeSha = typeof undo.beforeSha === "string" ? undo.beforeSha : null;
+    if (branch && beforeSha) {
+      await runGit(["checkout", branch], { cwd: repoRoot, ...opts });
+      await runGit(["reset", "--hard", beforeSha], { cwd: repoRoot, ...opts });
+      clearLastRun(repoRoot);
+      if (!args.quiet) success(`gflows: reset '${branch}' to pre-sync state.`);
+      return;
+    }
+  }
+
+  console.error(`gflows undo: cannot undo command '${last.command}' automatically.`);
+  hint("Inspect .git/gflows/last.json and recover with git reflog if needed.");
+  process.exit(EXIT_USER);
+}

package/src/commands/version.ts

@@ -3,25 +3,13 @@
  * @module commands/version
  */
 
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import type { ParsedArgs } from "../types.js";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
+import { getVersion } from "../version.js";
 
 /**
- * Runs the version command: reads version from package.json (repo root when
- * developing, package root when installed) and prints it to stdout.
+ * Runs the version command: prints package version to stdout.
  * @param _args - Parsed CLI args (unused; kept for command signature consistency).
  */
 export async function run(_args: ParsedArgs): Promise<void> {
-  const pkgPath = join(__dirname, "..", "..", "package.json");
-  try {
-    const raw = readFileSync(pkgPath, "utf-8");
-    const pkg = JSON.parse(raw) as { version?: string };
-    console.log(pkg.version ?? "0.0.0");
-  } catch {
-    console.log("0.0.0");
-  }
+  console.log(getVersion());
 }

package/src/commands/viz.ts

@@ -0,0 +1,18 @@
+/**
+ * Visual map of main/dev + workflow branches and “you are here” next steps.
+ * @module commands/viz
+ */
+
+import type { ParsedArgs } from "../types.js";
+import { printViz } from "../viz.js";
+
+/**
+ * Prints an interactive-friendly branch/flow visualization to stdout.
+ */
+export async function run(args: ParsedArgs): Promise<void> {
+  await printViz(args.cwd, {
+    main: args.main,
+    dev: args.dev,
+    remote: args.remote,
+  });
+}

package/src/dispatch.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared command dispatch for the hub and TUI (parse argv → command module).
+ * @module dispatch
+ */
+
+import { parse } from "./parse.js";
+import type { ParsedArgs } from "./types.js";
+
+/**
+ * Dispatches a command by re-parsing argv and calling the command module.
+ */
+export async function dispatch(cwd: string, argv: string[]): Promise<void> {
+  const args: ParsedArgs = parse(["-C", cwd, ...argv]);
+  if (args.command === "help") {
+    const { run } = await import("./commands/help.js");
+    await run(args);
+    return;
+  }
+  const mod = await import(`./commands/${args.command}.js`);
+  await mod.run(args);
+}

package/src/errors.ts

@@ -11,26 +11,39 @@ import { EXIT_GIT, EXIT_USER } from "./constants.js";
 export class GflowsError extends Error {
   /** Exit code to use when this error is thrown (1 = user, 2 = git). */
   readonly exitCode: number;
+  /** Optional remediation hint printed after the message. */
+  readonly hint?: string;
 
-  constructor(message: string, exitCode: number) {
+  constructor(message: string, exitCode: number, hint?: string) {
     super(message);
     this.name = this.constructor.name;
     Object.setPrototypeOf(this, new.target.prototype);
     this.exitCode = exitCode;
+    this.hint = hint;
   }
 }
 
 /** Thrown when cwd (or -C) is not a Git repository. */
 export class NotRepoError extends GflowsError {
-  constructor(message = "Not a Git repository.") {
-    super(message, EXIT_GIT);
+  constructor(
+    message = "Not a Git repository.",
+    hint = "Run from a directory that contains .git, or use -C <path> to point at the repo root.",
+  ) {
+    super(message, EXIT_GIT, hint);
   }
 }
 
 /** Thrown when a required branch does not exist (local or after fetch). */
 export class BranchNotFoundError extends GflowsError {
-  constructor(message: string) {
-    super(message, EXIT_GIT);
+  constructor(message: string, hint?: string) {
+    super(message, EXIT_GIT, hint);
+  }
+}
+
+/** Thrown when creating a branch that already exists. */
+export class BranchExistsError extends GflowsError {
+  constructor(message: string, hint?: string) {
+    super(message, EXIT_GIT, hint);
   }
 }
 
@@ -38,31 +51,40 @@ export class BranchNotFoundError extends GflowsError {
 export class DirtyWorkingTreeError extends GflowsError {
   constructor(
     message = "Working tree has uncommitted changes. Commit or stash them, or use --force.",
+    hint = "--force creates/finishes anyway and keeps uncommitted changes in the working tree.",
   ) {
-    super(message, EXIT_GIT);
+    super(message, EXIT_GIT, hint);
   }
 }
 
 /** Thrown when an operation requires a branch but HEAD is detached. */
 export class DetachedHeadError extends GflowsError {
-  constructor(message = "HEAD is detached. Checkout a branch first.") {
-    super(message, EXIT_GIT);
+  constructor(
+    message = "HEAD is detached. Checkout a branch first.",
+    hint = "Try: git checkout dev  (or main)",
+  ) {
+    super(message, EXIT_GIT, hint);
   }
 }
 
 /** Thrown when a rebase or merge is in progress; user must complete or abort first. */
 export class RebaseMergeInProgressError extends GflowsError {
   constructor(
-    message = "A rebase or merge is in progress. Complete or abort it before running this command.",
+    message = "A rebase or merge is in progress.",
+    hint = "Resolve conflicts then run gflows continue, or gflows abort / gflows undo.",
   ) {
-    super(message, EXIT_GIT);
+    super(message, EXIT_GIT, hint);
   }
 }
 
 /** Thrown when merge fails due to conflicts; user must resolve manually. */
 export class MergeConflictError extends GflowsError {
-  constructor(message: string) {
-    super(message, EXIT_GIT);
+  constructor(message: string, hint?: string) {
+    super(
+      message,
+      EXIT_GIT,
+      hint ?? "Resolve conflicts, then: gflows continue. Or: gflows abort / gflows undo.",
+    );
   }
 }
 
@@ -87,6 +109,13 @@ export class CannotDeleteMainOrDevError extends GflowsError {
   }
 }
 
+/** Thrown when finish has nothing to merge (0 commits ahead of target). */
+export class NothingToFinishError extends GflowsError {
+  constructor(message: string) {
+    super(message, EXIT_GIT, "Commit your changes on the workflow branch, then finish again.");
+  }
+}
+
 /**
  * Returns the exit code for an error: use error.exitCode if it's a GflowsError, else EXIT_GIT.
  */
@@ -96,3 +125,17 @@ export function exitCodeForError(error: unknown): number {
   }
   return EXIT_GIT;
 }
+
+/**
+ * Prints a GflowsError (or Error) message and optional remediation hint to stderr.
+ */
+export function printError(error: unknown): void {
+  if (error instanceof GflowsError) {
+    console.error("gflows:", error.message);
+    if (error.hint) {
+      console.error(`Hint: ${error.hint}`);
+    }
+    return;
+  }
+  console.error("gflows:", error instanceof Error ? error.message : String(error));
+}

package/src/flow.ts

@@ -0,0 +1,157 @@
+/**
+ * Shared branch classification and merge-target resolution for status/finish/sync/pr.
+ * @module flow
+ */
+
+import { getBranchTypeMeta } from "./config.js";
+import { VERSION_REGEX } from "./constants.js";
+import { getMergeBase, isAncestor, resolveSha } from "./git.js";
+import type { BranchType, MergeTarget, ResolvedConfig } from "./types.js";
+
+/**
+ * Classifies a branch name into a workflow type, "main", "dev", or null (unknown).
+ */
+export function classifyBranch(
+  branchName: string,
+  config: ResolvedConfig,
+): BranchType | "main" | "dev" | null {
+  if (branchName === config.main) return "main";
+  if (branchName === config.dev) return "dev";
+  const { prefixes } = config;
+  const order: BranchType[] = ["release", "hotfix", "feature", "bugfix", "chore", "spike"];
+  for (const type of order) {
+    const prefix = prefixes[type];
+    if (prefix && branchName.startsWith(prefix)) {
+      return type;
+    }
+  }
+  return null;
+}
+
+/**
+ * Infers branch type and optional version from branch name using config prefixes.
+ */
+export function parseBranchTypeAndVersion(
+  branchName: string,
+  prefixes: ResolvedConfig["prefixes"],
+): { type: BranchType; version?: string } | null {
+  const order: BranchType[] = ["release", "hotfix", "feature", "bugfix", "chore", "spike"];
+  for (const type of order) {
+    const prefix = prefixes[type];
+    if (prefix && branchName.startsWith(prefix)) {
+      const suffix = branchName.slice(prefix.length);
+      if (type === "release" || type === "hotfix") {
+        const ver = suffix.trim();
+        return VERSION_REGEX.test(ver) ? { type, version: ver } : { type };
+      }
+      return { type };
+    }
+  }
+  return null;
+}
+
+/**
+ * Formats merge target for display using actual branch names.
+ */
+export function formatMergeTarget(mergeTarget: MergeTarget, config: ResolvedConfig): string {
+  if (mergeTarget === "main-then-dev") {
+    return `${config.main}, then ${config.dev}`;
+  }
+  return mergeTarget === "main" ? config.main : config.dev;
+}
+
+/**
+ * Primary compare/merge base branch for a merge target (for ahead/behind and empty-finish checks).
+ */
+export function primaryTargetBranch(mergeTarget: MergeTarget, config: ResolvedConfig): string {
+  if (mergeTarget === "dev") return config.dev;
+  return config.main;
+}
+
+/**
+ * Resolves effective merge target for a workflow branch.
+ * Bugfix branches based on main (merge-base equals main tip, or only reachable from main) use main-then-dev.
+ */
+export async function resolveMergeTarget(
+  repoRoot: string,
+  branchName: string,
+  type: BranchType,
+  config: ResolvedConfig,
+  opts: { dryRun?: boolean; verbose?: boolean } = {},
+): Promise<MergeTarget> {
+  const meta = getBranchTypeMeta(type);
+  if (type !== "bugfix") {
+    return meta.mergeTarget;
+  }
+
+  const mainSha = await resolveSha(repoRoot, config.main, opts);
+  const branchSha = await resolveSha(repoRoot, branchName, opts);
+  if (!mainSha || !branchSha) {
+    return meta.mergeTarget;
+  }
+
+  const mergeBase = await getMergeBase(repoRoot, config.main, branchName, opts);
+  if (mergeBase && mergeBase === mainSha) {
+    return "main-then-dev";
+  }
+
+  // Also treat as from-main when main is ancestor and dev is not the merge-base with branch
+  const mainIsAncestor = await isAncestor(repoRoot, config.main, branchName, opts);
+  const devSha = await resolveSha(repoRoot, config.dev, opts);
+  if (mainIsAncestor && devSha) {
+    const baseWithDev = await getMergeBase(repoRoot, config.dev, branchName, opts);
+    // If branch diverged from main more recently than from dev tip equality check:
+    // when merge-base(main, branch) === main tip, already handled; if branch was created
+    // from main while main had moved from where dev is, merge-base with main is still main's tip at start.
+    if (baseWithDev && mergeBase && baseWithDev !== mergeBase && mergeBase === mainSha) {
+      return "main-then-dev";
+    }
+    // Heuristic: if merge-base with main equals main and differs from merge-base with dev → from main
+    if (mergeBase === mainSha && baseWithDev !== mainSha) {
+      return "main-then-dev";
+    }
+  }
+
+  return meta.mergeTarget;
+}
+
+/**
+ * Default base branch name for a type (and optional fromMain).
+ */
+export function getBaseBranchName(
+  type: BranchType,
+  fromMain: boolean,
+  config: ResolvedConfig,
+): string {
+  if (type === "hotfix") return config.main;
+  if (type === "bugfix" && fromMain) return config.main;
+  const meta = getBranchTypeMeta(type);
+  return meta.base === "main" ? config.main : config.dev;
+}
+
+/**
+ * Normalizes version to vX.Y.Z for tag name.
+ */
+export function normalizeTagVersion(version: string): string {
+  const v = version.trim();
+  return v.startsWith("v") ? v : `v${v}`;
+}
+
+/**
+ * Lists local workflow branches matching configured prefixes.
+ */
+export function filterWorkflowBranches(
+  all: string[],
+  prefixes: ResolvedConfig["prefixes"],
+): string[] {
+  const workflow: string[] = [];
+  for (const b of all) {
+    for (const prefix of Object.values(prefixes)) {
+      if (b.startsWith(prefix)) {
+        workflow.push(b);
+        break;
+      }
+    }
+  }
+  return workflow.sort();
+}