gflows 0.1.17 → 1.0.0

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";

package/src/interactive.ts

@@ -0,0 +1,209 @@
+/**
+ * Interactive hub entry — prefers Ink TUI, falls back to Clack menu.
+ * @module interactive
+ */
+
+import { resolveConfig } from "./config.js";
+import { dispatch } from "./dispatch.js";
+import { classifyBranch, formatMergeTarget, getBaseBranchName } from "./flow.js";
+import { getAheadBehind, getCurrentBranch, resolveRepoRoot } from "./git.js";
+import { hint } from "./out.js";
+import { confirmPrompt, inputPrompt, selectPrompt } from "./prompts.js";
+import { type RecommendAction, recommend } from "./recommend.js";
+import { readActiveRun } from "./run-state.js";
+import type { BranchType } from "./types.js";
+import { ansi, paint, rule } from "./ui.js";
+import { printViz, type VizSnapshot } from "./viz.js";
+
+const BRANCH_TYPES: BranchType[] = ["feature", "bugfix", "chore", "release", "hotfix", "spike"];
+
+export { dispatch } from "./dispatch.js";
+
+/**
+ * Runs the interactive hub until the user quits.
+ * Uses the Ink fullscreen TUI when stdin/stdout are TTYs; otherwise Clack menu.
+ */
+export async function runHub(cwd: string): Promise<void> {
+  const { runTuiHub } = await import("./tui/hub.js");
+  const usedTui = await runTuiHub(cwd);
+  if (!usedTui) {
+    await runLegacyHub(cwd);
+  }
+}
+
+/**
+ * Legacy Clack select hub (when Ink/TUI cannot run).
+ */
+async function runLegacyHub(cwd: string): Promise<void> {
+  for (;;) {
+    let snap: VizSnapshot | null = null;
+    try {
+      snap = await printViz(cwd);
+    } catch {
+      await printContextFallback(cwd);
+    }
+
+    const rec = snap ? recommend(snap) : null;
+    const options = buildLegacyOptions(rec?.action ?? null, snap);
+    const action = await selectPrompt({
+      message: rec ? `Recommended · ${rec.label}` : "What do you want to do?",
+      options,
+      initialValue: options[0]?.value,
+    });
+
+    if (action === "quit") {
+      console.log(paint(ansi.dim, "Bye."));
+      break;
+    }
+
+    try {
+      await runHubAction(cwd, action);
+    } catch (err) {
+      console.error("gflows:", err instanceof Error ? err.message : String(err));
+    }
+
+    console.log("");
+    console.log(rule(56));
+    const again = await confirmPrompt({ message: "Back to menu?", initialValue: true });
+    if (!again) break;
+  }
+}
+
+function buildLegacyOptions(
+  recommended: RecommendAction | null,
+  snap: VizSnapshot | null,
+): Array<{ value: string; label: string; hint?: string }> {
+  const items: Array<{ value: string; label: string; hint?: string }> = [];
+  if (snap?.needsInit) {
+    items.push({ value: "init", label: "Initialize repo", hint: "gflows init" });
+  }
+  items.push(
+    { value: "start", label: "Start new work" },
+    { value: "sync", label: "Sync this branch with base" },
+    { value: "pr", label: "Open a pull request" },
+    { value: "finish", label: "Finish / merge this branch" },
+    { value: "switch", label: "Switch branch" },
+    { value: "list", label: "List branches" },
+    { value: "viz", label: "Refresh map" },
+    { value: "doctor", label: "Doctor (check setup)" },
+    { value: "config", label: "Config" },
+    { value: "bump", label: "Bump version" },
+    { value: "continue", label: "Continue suspended operation" },
+    { value: "help", label: "Help" },
+    { value: "quit", label: "Quit" },
+  );
+
+  const prefer = recommended && recommended !== "commit" ? recommended : null;
+  if (prefer) {
+    const idx = items.findIndex((a) => a.value === prefer);
+    if (idx >= 0) {
+      const [item] = items.splice(idx, 1);
+      if (item) {
+        items.unshift({ ...item, label: `★ ${item.label}` });
+      }
+    }
+  }
+  return items;
+}
+
+async function runHubAction(cwd: string, action: string): Promise<void> {
+  if (action === "viz") {
+    await printViz(cwd);
+    return;
+  }
+  if (action === "start") {
+    await promptStart(cwd);
+    return;
+  }
+  if (action === "finish") {
+    const push = await confirmPrompt({ message: "Push after finish?", initialValue: false });
+    await dispatch(cwd, ["finish", "-y", push ? "-p" : "-P"]);
+    return;
+  }
+  if (action === "sync") {
+    const rebase = await confirmPrompt({
+      message: "Rebase onto base (instead of merge)?",
+      initialValue: false,
+    });
+    await dispatch(cwd, ["sync", ...(rebase ? ["--rebase"] : []), "--force"]);
+    return;
+  }
+  await dispatch(cwd, [action]);
+}
+
+/** Fallback text context when viz cannot run (e.g. not a repo). */
+async function printContextFallback(cwd: string): Promise<void> {
+  try {
+    const root = await resolveRepoRoot(cwd);
+    const config = resolveConfig(root, {}, {});
+    const current = await getCurrentBranch(root, {});
+    const active = readActiveRun(root);
+    console.log("");
+    console.log(paint(ansi.cyan + ansi.bold, "╭─ gflows ──────────────────────────────╮"));
+    if (active) {
+      console.log(`│ Suspended: ${active.command} — use Continue, or gflows abort`);
+    }
+    if (!current) {
+      console.log("│ HEAD: detached");
+      console.log(paint(ansi.dim, "╰────────────────────────────────────────╯"));
+      return;
+    }
+    const kind = classifyBranch(current, config);
+    console.log(`│ Branch: ${current}`);
+    if (kind === "main" || kind === "dev") {
+      console.log(`│ Type: long-lived (${kind})`);
+      console.log(paint(ansi.dim, "╰────────────────────────────────────────╯"));
+      hint("Start new work from the menu, or switch to a workflow branch.");
+      return;
+    }
+    if (kind === null) {
+      console.log("│ Type: unknown");
+      console.log(paint(ansi.dim, "╰────────────────────────────────────────╯"));
+      return;
+    }
+    const base = getBaseBranchName(kind, false, config);
+    const { ahead, behind } = await getAheadBehind(root, base, current, {});
+    const meta = formatMergeTarget(
+      kind === "release" || kind === "hotfix" ? "main-then-dev" : "dev",
+      config,
+    );
+    console.log(`│ Type: ${kind}  ·  base: ${base}  ·  +${ahead}/-${behind}`);
+    console.log(`│ Merge: ${meta}`);
+    console.log(paint(ansi.dim, "╰────────────────────────────────────────╯"));
+  } catch {
+    console.log("");
+    console.log(paint(ansi.yellow, "╭─ gflows ──────────────────────────────╮"));
+    console.log("│ Not a git repo here");
+    console.log(paint(ansi.dim, "│ → cd into a repo, or git init + gflows init"));
+    console.log(paint(ansi.dim, "╰────────────────────────────────────────╯"));
+    console.log("");
+  }
+}
+
+async function promptStart(cwd: string): Promise<void> {
+  const { type, name } = await promptStartArgs();
+  const push = await confirmPrompt({ message: "Push after create?", initialValue: false });
+  const argv = ["start", type, name, push ? "-p" : "-P"];
+  if (type === "bugfix") {
+    const fromMain = await confirmPrompt({
+      message: "Base from main (production fix)?",
+      initialValue: false,
+    });
+    if (fromMain) argv.push("-o", "main");
+  }
+  await dispatch(cwd, argv);
+}
+
+/**
+ * Prompts for start type/name when missing (TTY).
+ */
+export async function promptStartArgs(): Promise<{ type: BranchType; name: string }> {
+  const type = await selectPrompt({
+    message: "Branch type",
+    options: BRANCH_TYPES.map((t) => ({ value: t, label: t })),
+  });
+  const name = await inputPrompt({
+    message: type === "release" || type === "hotfix" ? "Version (vX.Y.Z)" : "Branch name",
+  });
+  return { type, name };
+}

package/src/out.ts

@@ -30,14 +30,21 @@ export function success(message: string): void {
 }
 
 /**
- * Prints a hint line to stdout (dim when TTY). Use after success messages to suggest next steps.
- * Skips color when not a TTY (e.g. CI). Omit when --quiet to keep output minimal.
+ * Whether stderr is a TTY and can safely use ANSI color codes for hints.
+ */
+function isStderrColorCapable(): boolean {
+  return typeof process.stderr.isTTY === "boolean" && process.stderr.isTTY;
+}
+
+/**
+ * Prints a hint line to stderr (dim when TTY). Keeps stdout clean for scripting (`list`, pipes).
+ * Omit when --quiet to keep output minimal.
  *
  * @param message - One-line hint (e.g. "Run gflows start feature <name> to create a branch").
  */
 export function hint(message: string): void {
-  const line = isColorCapable() ? `${DIM}Hint: ${message}${RESET}` : `Hint: ${message}`;
-  console.log(line);
+  const line = isStderrColorCapable() ? `${DIM}Hint: ${message}${RESET}` : `Hint: ${message}`;
+  console.error(line);
 }
 
 const BANNER_INNER_WIDTH = 42;

package/src/package-scripts.ts

@@ -0,0 +1,73 @@
+/**
+ * Helpers for optional package.json script aliases (e.g. "g": "gflows").
+ * @module package-scripts
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const PACKAGE_JSON = "package.json";
+const SCRIPT_VALUE = "gflows";
+
+/** Result of attempting to add a script alias. */
+export type ScriptAliasResult =
+  | { status: "added"; name: string }
+  | { status: "unchanged"; name: string }
+  | { status: "conflict"; name: string; existing: string }
+  | { status: "no-package" }
+  | { status: "invalid"; name: string };
+
+/**
+ * Validates a package.json script name (npm/bun safe subset).
+ */
+export function isValidScriptAliasName(name: string): boolean {
+  return /^[a-z][a-z0-9:_-]*$/i.test(name) && name.length <= 64;
+}
+
+/**
+ * Ensures `scripts[name] = "gflows"` in the nearest package.json under repoRoot.
+ * Does not overwrite a different existing script value.
+ */
+export function ensureGflowsScriptAlias(
+  repoRoot: string,
+  name: string,
+  options?: { dryRun?: boolean },
+): ScriptAliasResult {
+  if (!isValidScriptAliasName(name)) {
+    return { status: "invalid", name };
+  }
+
+  const pkgPath = join(repoRoot, PACKAGE_JSON);
+  if (!existsSync(pkgPath)) {
+    return { status: "no-package" };
+  }
+
+  let pkg: Record<string, unknown>;
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as Record<string, unknown>;
+  } catch {
+    return { status: "no-package" };
+  }
+
+  const scripts =
+    pkg.scripts && typeof pkg.scripts === "object" && !Array.isArray(pkg.scripts)
+      ? { ...(pkg.scripts as Record<string, unknown>) }
+      : {};
+
+  const existing = scripts[name];
+  if (typeof existing === "string") {
+    if (existing === SCRIPT_VALUE || existing.trim() === SCRIPT_VALUE) {
+      return { status: "unchanged", name };
+    }
+    return { status: "conflict", name, existing };
+  }
+
+  if (options?.dryRun) {
+    return { status: "added", name };
+  }
+
+  scripts[name] = SCRIPT_VALUE;
+  pkg.scripts = scripts;
+  writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf-8");
+  return { status: "added", name };
+}