gflows 0.1.18 → 1.0.1

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();
+}

package/src/git.ts

@@ -198,16 +198,34 @@ export async function checkout(
 export async function merge(
   cwd: string,
   ref: string,
-  options: GitRunOptions & { noFf?: boolean } = {},
+  options: GitRunOptions & { noFf?: boolean; message?: string; squash?: boolean } = {},
 ): Promise<void> {
-  const { noFf = false, ...opts } = options;
-  const args = noFf ? ["merge", "--no-ff", ref] : ["merge", ref];
+  const { noFf = false, message, squash = false, ...opts } = options;
+  const args = ["merge"];
+  if (squash) args.push("--squash");
+  else if (noFf) args.push("--no-ff");
+  if (message && !squash) args.push("-m", message);
+  args.push(ref);
   const result = await runGit(args, { cwd, ...opts });
 
   if (result.exitCode !== 0) {
-    const hint =
-      "Resolve conflicts in the working tree, then run `git add` and `git merge --continue`, or `git merge --abort` to cancel. Re-run `gflows finish` after resolving if needed.";
-    throw new MergeConflictError(`Merge conflict while merging ${ref}. ${hint}`);
+    throw new MergeConflictError(
+      `Merge conflict while merging ${ref}.`,
+      "Resolve conflicts, then: gflows continue. Or: gflows abort / gflows undo.",
+    );
+  }
+
+  if (squash && !opts.dryRun) {
+    const commitArgs = message
+      ? ["commit", "-m", message]
+      : ["commit", "-m", `Squash merge ${ref}`];
+    const commitResult = await runGit(commitArgs, { cwd, ...opts });
+    if (commitResult.exitCode !== 0) {
+      throw new MergeConflictError(
+        `Squash merge of ${ref} staged but commit failed.`,
+        commitResult.stderr.trim() || "Check git status and commit manually, then gflows continue.",
+      );
+    }
   }
 }
 
@@ -294,14 +312,123 @@ export async function tagExists(
 export async function deleteBranch(
   cwd: string,
   branch: string,
-  options: GitRunOptions = {},
+  options: GitRunOptions & { force?: boolean } = {},
 ): Promise<void> {
-  const result = await runGit(["branch", "-d", branch], { cwd, ...options });
+  const flag = options.force ? "-D" : "-d";
+  const result = await runGit(["branch", flag, branch], { cwd, ...options });
   if (result.exitCode !== 0) {
     throw new BranchNotFoundError(result.stderr.trim() || `Could not delete branch '${branch}'.`);
   }
 }
 
+/**
+ * Deletes a remote branch (git push remote --delete branch).
+ *
+ * @param cwd - Repo root.
+ * @param remote - Remote name.
+ * @param branch - Branch name on remote.
+ * @param options - dryRun, verbose.
+ * @returns Exit code from git push.
+ */
+export async function deleteRemoteBranch(
+  cwd: string,
+  remote: string,
+  branch: string,
+  options: GitRunOptions = {},
+): Promise<number> {
+  const result = await runGit(["push", remote, "--delete", branch], { cwd, ...options });
+  return result.exitCode;
+}
+
+/**
+ * Returns the merge-base SHA of two refs, or null if unavailable.
+ */
+export async function getMergeBase(
+  cwd: string,
+  a: string,
+  b: string,
+  options: GitRunOptions = {},
+): Promise<string | null> {
+  const result = await runGit(["merge-base", a, b], { cwd, ...options });
+  if (result.exitCode !== 0) return null;
+  const sha = result.stdout.trim();
+  return sha.length > 0 ? sha : null;
+}
+
+/**
+ * Returns true if `ancestor` is an ancestor of `commit` (git merge-base --is-ancestor).
+ */
+export async function isAncestor(
+  cwd: string,
+  ancestor: string,
+  commit: string,
+  options: GitRunOptions = {},
+): Promise<boolean> {
+  const result = await runGit(["merge-base", "--is-ancestor", ancestor, commit], {
+    cwd,
+    ...options,
+  });
+  return result.exitCode === 0;
+}
+
+/**
+ * Aborts an in-progress merge if MERGE_HEAD exists.
+ */
+export async function mergeAbort(cwd: string, options: GitRunOptions = {}): Promise<void> {
+  await runGit(["merge", "--abort"], { cwd, ...options });
+}
+
+/**
+ * Aborts an in-progress rebase if one is active.
+ */
+export async function rebaseAbort(cwd: string, options: GitRunOptions = {}): Promise<void> {
+  await runGit(["rebase", "--abort"], { cwd, ...options });
+}
+
+/**
+ * Deletes a local tag.
+ */
+export async function deleteTag(
+  cwd: string,
+  name: string,
+  options: GitRunOptions = {},
+): Promise<void> {
+  await runGit(["tag", "-d", name], { cwd, ...options });
+}
+
+/**
+ * Returns upstream tracking branch (e.g. origin/feature/x) or null.
+ */
+export async function getUpstream(
+  cwd: string,
+  branch: string,
+  options: GitRunOptions = {},
+): Promise<string | null> {
+  const result = await runGit(["rev-parse", "--abbrev-ref", `${branch}@{upstream}`], {
+    cwd,
+    ...options,
+  });
+  if (result.exitCode !== 0) return null;
+  const up = result.stdout.trim();
+  return up.length > 0 ? up : null;
+}
+
+/**
+ * Resolves a ref to a full SHA, or null if missing.
+ */
+export async function resolveSha(
+  cwd: string,
+  ref: string,
+  options: GitRunOptions = {},
+): Promise<string | null> {
+  try {
+    const out = await revParse(cwd, ref, [], options);
+    return out.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Returns true if the working tree is clean (no uncommitted changes).
  *

package/src/index.ts

@@ -28,6 +28,7 @@ export {
   VERSION_REGEX,
 } from "./constants.js";
 export {
+  BranchExistsError,
   BranchNotFoundError,
   CannotDeleteMainOrDevError,
   DetachedHeadError,
@@ -37,9 +38,17 @@ export {
   InvalidBranchNameError,
   InvalidVersionError,
   MergeConflictError,
+  NothingToFinishError,
   NotRepoError,
+  printError,
   RebaseMergeInProgressError,
 } from "./errors.js";
+export {
+  classifyBranch,
+  formatMergeTarget,
+  parseBranchTypeAndVersion,
+  resolveMergeTarget,
+} from "./flow.js";
 export type { GitOptions, GitRunOptions, GitRunResult } from "./git.js";
 export {
   assertNoRebaseOrMerge,
@@ -64,6 +73,9 @@ export {
   tagExists,
   validateBranchName,
 } from "./git.js";
+export { parse } from "./parse.js";
+export type { RecommendAction, Recommendation } from "./recommend.js";
+export { recommend } from "./recommend.js";
 export type {
   BranchPrefixes,
   BranchType,
@@ -77,4 +89,15 @@ export type {
   ParsedArgs,
   ResolvedConfig,
 } from "./types.js";
-export { BRANCH_TYPE_SHORTS } from "./types.js";
+export { ALL_COMMANDS, BRANCH_TYPE_SHORTS } from "./types.js";
+export { paint, renderPanel, section } from "./ui.js";
+export type { VizBranchRow, VizSnapshot } from "./viz.js";
+export {
+  collectVizSnapshot,
+  printViz,
+  renderBranchMap,
+  renderFlowLegend,
+  renderLifecycle,
+  renderVizPanel,
+  renderYouAreHere,
+} from "./viz.js";