gflows 0.1.1

package/src/commands/finish.ts

@@ -0,0 +1,275 @@
+/**
+ * Finish command: merge workflow branch into target(s), optional tag, delete branch, and push.
+ * Resolves branch (current, -B <name>, or picker when -B with no value and TTY).
+ * Uses normal merge with optional --no-ff; on conflict exits with clear message. Release/hotfix: merge to main then dev, create tag.
+ * @module commands/finish
+ */
+
+import type { BranchType, ParsedArgs } from "../types.js";
+import { EXIT_USER, VERSION_REGEX } from "../constants.js";
+import {
+  getBranchTypeMeta,
+  getPrefixForType,
+  resolveConfig,
+} from "../config.js";
+import { BranchNotFoundError } from "../errors.js";
+import {
+  assertNoRebaseOrMerge,
+  assertNotDetached,
+  branchList,
+  checkout,
+  deleteBranch,
+  getCurrentBranch,
+  merge,
+  push,
+  resolveRepoRoot,
+  tag,
+  tagExists,
+} from "../git.js";
+
+/** Normalizes version to vX.Y.Z for tag name. */
+function normalizeTagVersion(version: string): string {
+  const v = version.trim();
+  return v.startsWith("v") ? v : `v${v}`;
+}
+
+/**
+ * Returns workflow branches (local) that match any configured prefix.
+ */
+async function getWorkflowBranches(
+  cwd: string,
+  prefixes: Record<BranchType, string>
+): Promise<string[]> {
+  const all = await branchList(cwd, { dryRun: false, verbose: false });
+  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();
+}
+
+/**
+ * Infers branch type and optional version from branch name using config prefixes.
+ */
+function parseBranchTypeAndVersion(
+  branchName: string,
+  prefixes: Record<BranchType, string>
+): { type: BranchType; version?: string } | null {
+  for (const type of [
+    "release",
+    "hotfix",
+    "feature",
+    "bugfix",
+    "chore",
+    "spike",
+  ] as BranchType[]) {
+    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;
+}
+
+/**
+ * Runs the finish command: resolve branch, run pre-checks, merge to target(s), optional tag/delete/push.
+ * Pre-checks: repo, not detached HEAD, no rebase/merge, branch is not main/dev; for release/hotfix tag must not exist.
+ *
+ * @param args - Parsed CLI args (cwd, type, branch, push, noPush, remote, dryRun, verbose, quiet, yes, noFf, deleteAfterFinish, noDeleteAfterFinish, signTag, noTag, tagMessage).
+ */
+export async function run(args: ParsedArgs): Promise<void> {
+  const repoRoot = await resolveRepoRoot(args.cwd);
+  const config = resolveConfig(
+    repoRoot,
+    { remote: args.remote },
+    { verbose: args.verbose }
+  );
+
+  const opts: { dryRun: boolean; verbose: boolean } = {
+    dryRun: args.dryRun,
+    verbose: args.verbose,
+  };
+
+  const isTTY = Boolean(process.stdin.isTTY);
+
+  // Resolve branch to finish (and guard main/dev early so we can error before picker)
+  let branchToFinish: string;
+  const explicitBranch =
+    typeof args.branch === "string" && args.branch.trim() !== ""
+      ? args.branch.trim()
+      : undefined;
+
+  if (explicitBranch) {
+    branchToFinish = explicitBranch;
+  } else if (isTTY) {
+    const workflow = await getWorkflowBranches(repoRoot, config.prefixes);
+    if (workflow.length === 0) {
+      console.error("gflows finish: no workflow branches found.");
+      process.exit(EXIT_USER);
+    }
+    const { select } = await import("@inquirer/prompts");
+    branchToFinish = await select({
+      message: "Branch to finish",
+      choices: workflow.map((b) => ({ name: b, value: b })),
+    });
+  } else {
+    const current = await getCurrentBranch(repoRoot, opts);
+    if (!current) {
+      console.error(
+        "gflows finish: HEAD is detached. Checkout a branch or specify one with -B <name>."
+      );
+      process.exit(EXIT_USER);
+    }
+    branchToFinish = current;
+  }
+
+  // Refuse finish on main or dev
+  if (branchToFinish === config.main || branchToFinish === config.dev) {
+    console.error(
+      `gflows finish: cannot finish the long-lived branch '${branchToFinish}'. Finish a workflow branch (feature, bugfix, etc.) instead.`
+    );
+    process.exit(2);
+  }
+
+  // Infer type from branch name (or use args.type if provided and consistent)
+  const parsed = parseBranchTypeAndVersion(branchToFinish, config.prefixes);
+  const type: BranchType | undefined = args.type ?? parsed?.type ?? undefined;
+  if (!type) {
+    console.error(
+      `gflows finish: cannot determine branch type for '${branchToFinish}'. Specify type (e.g. gflows finish feature) or use a branch name with a known prefix.`
+    );
+    process.exit(EXIT_USER);
+  }
+  if (parsed && parsed.type !== type) {
+    console.error(
+      `gflows finish: branch '${branchToFinish}' matches type '${parsed.type}', but '${type}' was specified.`
+    );
+    process.exit(EXIT_USER);
+  }
+
+  const meta = getBranchTypeMeta(type);
+  const version = parsed?.version;
+
+  // Pre-checks: not detached, no rebase/merge
+  await assertNotDetached(repoRoot);
+  assertNoRebaseOrMerge(repoRoot);
+
+  // For release/hotfix: tag must not already exist
+  if (meta.tagOnFinish && version) {
+    const tagName = normalizeTagVersion(version);
+    const exists = await tagExists(repoRoot, tagName, opts);
+    if (exists) {
+      console.error(`gflows finish: tag '${tagName}' already exists.`);
+      process.exit(2);
+    }
+  } else if (meta.tagOnFinish && !version) {
+    console.error(
+      `gflows finish: release/hotfix branch '${branchToFinish}' has no valid version segment. Use format release/vX.Y.Z or hotfix/vX.Y.Z.`
+    );
+    process.exit(EXIT_USER);
+  }
+
+  // Ensure the branch we're finishing exists (e.g. if -B was used)
+  const branches = await branchList(repoRoot, { ...opts, dryRun: false });
+  if (!branches.includes(branchToFinish)) {
+    throw new BranchNotFoundError(
+      `Branch '${branchToFinish}' not found. Specify an existing local branch with -B <name>.`
+    );
+  }
+
+  const noFf = args.noFf;
+
+  try {
+    if (meta.mergeTarget === "dev") {
+      await checkout(repoRoot, config.dev, opts);
+      await merge(repoRoot, branchToFinish, { ...opts, noFf });
+    } else {
+      // main-then-dev: merge into main first, then merge main into dev
+      await checkout(repoRoot, config.main, opts);
+      await merge(repoRoot, branchToFinish, { ...opts, noFf });
+
+      if (meta.tagOnFinish && version && !args.noTag) {
+        const tagName = normalizeTagVersion(version);
+        await tag(repoRoot, tagName, {
+          ...opts,
+          sign: args.signTag,
+          tagMessage: args.tagMessage,
+        });
+        if (!args.quiet && !args.dryRun) {
+          console.error(`gflows: created tag '${tagName}'.`);
+        }
+      }
+
+      await checkout(repoRoot, config.dev, opts);
+      await merge(repoRoot, config.main, { ...opts, noFf });
+    }
+  } catch (err) {
+    throw err;
+  }
+
+  // Optional: delete the finished branch
+  let shouldDelete = args.deleteAfterFinish;
+  if (!args.deleteAfterFinish && !args.noDeleteAfterFinish) {
+    if (args.yes) {
+      shouldDelete = false;
+    } else if (isTTY) {
+      const { confirm } = await import("@inquirer/prompts");
+      shouldDelete = await confirm({
+        message: "Delete branch after finish?",
+        default: false,
+      });
+    }
+  }
+  if (args.noDeleteAfterFinish) {
+    shouldDelete = false;
+  }
+
+  if (shouldDelete && !opts.dryRun) {
+    await deleteBranch(repoRoot, branchToFinish, opts);
+    if (!args.quiet) {
+      console.error(`gflows: deleted branch '${branchToFinish}'.`);
+    }
+  }
+
+  const doPush = args.push && !args.noPush;
+  const didCreateTag = !!(
+    meta.mergeTarget === "main-then-dev" && meta.tagOnFinish && version && !args.noTag
+  );
+  if (doPush) {
+    const remote = args.remote ?? config.remote;
+    const refsToPush: string[] = [config.dev];
+    if (meta.mergeTarget === "main-then-dev") {
+      refsToPush.push(config.main);
+    }
+    const pushCode = await push(
+      repoRoot,
+      remote,
+      refsToPush,
+      didCreateTag,
+      opts
+    );
+    if (pushCode !== 0) {
+      console.error(
+        "gflows: merge and tag succeeded locally, but push failed. Retry with `git push` or `gflows finish ... --push`."
+      );
+      process.exit(2);
+    }
+    if (!args.quiet && !args.dryRun) {
+      console.error(`gflows: pushed to ${remote}.`);
+    }
+  }
+
+  if (!args.quiet && !args.dryRun) {
+    console.error(`gflows: finished '${branchToFinish}' into ${meta.mergeTarget}.`);
+  }
+}

package/src/commands/help.ts

@@ -0,0 +1,53 @@
+/**
+ * Help command: print quick reference from the spec and list commands/flags.
+ * @module commands/help
+ */
+
+import type { ParsedArgs } from "../types.js";
+
+/**
+ * Runs the help command: prints usage, commands, types, flags, and exit codes to stdout.
+ * @param _args - Parsed CLI args (unused; kept for command signature consistency).
+ */
+export async function run(_args: ParsedArgs): Promise<void> {
+  const out = `
+gflows — Modern Git branching workflow CLI
+
+Usage: gflows <command> [type] [name] [flags]
+
+Commands:
+  init, -I       Ensure main, create dev
+  start, -S      Create workflow branch
+  finish, -F     Merge and close branch
+  switch, -W     Switch branch (picker or name)
+  delete, -L     Delete local branch(es)
+  list, -l       List branches by type
+  bump           Bump or rollback package version
+  completion     Print shell completion script
+  status, -t     Show current branch flow info
+  help, -h       Show this usage
+  version, -V    Show version
+
+Types: feature (-f), bugfix (-b), chore (-c), release (-r), hotfix (-x), spike (-e)
+
+Common flags:
+  -p, --push           Push after init/start/finish
+  -P, --no-push        Do not push
+  -R, --remote <name>  Remote name for push
+  -o, --from <branch>  Base branch override (e.g. -o main for bugfix)
+  -B, --branch <name>  Branch name (finish: branch to finish)
+  -y, --yes            Skip confirmations
+  -d, --dry-run        Log actions only, no writes
+  -v, --verbose        Verbose output
+  -q, --quiet          Minimal output
+  -C, --path <dir>     Run as if in <dir>
+
+Start:  --force         Allow dirty working tree
+Finish: --no-ff         Always create merge commit; -D/--delete, -N/--no-delete;
+        -s/--sign, -T/--no-tag, -M/--tag-message, -m/--message
+List:   -r, --include-remote   Include remote-tracking branches
+
+Exit codes: 0 success, 1 usage/validation, 2 Git or system error.
+`;
+  console.log(out.trim());
+}

package/src/commands/init.ts

@@ -0,0 +1,70 @@
+/**
+ * Init command: ensure main exists, create dev from main, optional push and dry-run.
+ * @module commands/init
+ */
+
+import { resolveConfig } from "../config.js";
+import { BranchNotFoundError, NotRepoError } from "../errors.js";
+import {
+  branchList,
+  push,
+  resolveRepoRoot,
+  revParse,
+  runGit,
+} from "../git.js";
+import type { ParsedArgs } from "../types.js";
+
+/**
+ * Runs the init command: ensure main exists, create dev from main if missing, optional push.
+ * Pre-check: cwd (or -C) must be a git repo; main branch must exist (exit 2 otherwise).
+ * Skips creating dev if it already exists. Supports --dry-run and --push.
+ *
+ * @param args - Parsed CLI args (cwd, dryRun, push, noPush, remote, verbose, quiet).
+ */
+export async function run(args: ParsedArgs): Promise<void> {
+  const repoRoot = await resolveRepoRoot(args.cwd);
+  const config = resolveConfig(repoRoot, {
+    remote: args.remote,
+  }, { verbose: args.verbose });
+
+  const opts = {
+    dryRun: args.dryRun,
+    verbose: args.verbose,
+  };
+
+  // Ensure main branch exists
+  try {
+    await revParse(repoRoot, config.main, [], { dryRun: false, verbose: opts.verbose });
+  } catch (err) {
+    if (err instanceof NotRepoError) throw err;
+    if (err instanceof BranchNotFoundError) {
+      throw new BranchNotFoundError(
+        `Main branch '${config.main}' does not exist. Create an initial commit and the main branch first.`
+      );
+    }
+    throw err;
+  }
+
+  const branches = await branchList(repoRoot, { ...opts, dryRun: false });
+  const devExists = branches.includes(config.dev);
+
+  if (!devExists) {
+    await runGit(["branch", config.dev, config.main], { cwd: repoRoot, ...opts });
+    if (!args.quiet && !args.dryRun) {
+      console.error(`gflows: created branch '${config.dev}' from '${config.main}'.`);
+    }
+  }
+
+  const doPush = args.push && !args.noPush;
+  if (doPush) {
+    const pushCode = await push(repoRoot, config.remote, [config.dev], false, opts);
+    if (pushCode !== 0) {
+      throw new Error(
+        `Push failed. Local branch '${config.dev}' was created. Retry with \`git push ${config.remote} ${config.dev}\` or \`gflows init --push\`.`
+      );
+    }
+    if (!args.quiet && !args.dryRun) {
+      console.error(`gflows: pushed '${config.dev}' to '${config.remote}'.`);
+    }
+  }
+}

package/src/commands/list.ts

@@ -0,0 +1,89 @@
+/**
+ * List command: list workflow branches using resolved config prefixes;
+ * optional type filter and -r/--include-remote for remote-tracking branches.
+ * Script-friendly: one branch per line to stdout.
+ * @module commands/list
+ */
+
+import type { BranchType } from "../types.js";
+import type { ParsedArgs } from "../types.js";
+import type { ResolvedConfig } from "../types.js";
+import { resolveConfig } from "../config.js";
+import { NotRepoError } from "../errors.js";
+import { branchList, fetch, resolveRepoRoot } from "../git.js";
+
+const BRANCH_TYPES: BranchType[] = [
+  "feature",
+  "bugfix",
+  "chore",
+  "release",
+  "hotfix",
+  "spike",
+];
+
+/**
+ * Returns branch names that match any workflow prefix. If typeFilter is set,
+ * only branches with that type's prefix are included. Excludes main and dev.
+ */
+function filterWorkflowBranches(
+  allBranches: string[],
+  config: ResolvedConfig,
+  typeFilter: BranchType | undefined
+): string[] {
+  const { main, dev, prefixes } = config;
+  const prefixesToMatch =
+    typeFilter !== undefined
+      ? [prefixes[typeFilter]]
+      : BRANCH_TYPES.map((t) => prefixes[t]);
+
+  return allBranches.filter((b) => {
+    if (b === main || b === dev) return false;
+    return prefixesToMatch.some((p) => p && b.startsWith(p));
+  });
+}
+
+/**
+ * Runs the list command.
+ * Lists workflow branches (matching config prefixes), optionally filtered by type
+ * and optionally including remote-tracking branches (-r/--include-remote).
+ * When includeRemote is true, fetches from the configured remote first so refs are up to date.
+ * Output: one branch per line to stdout (script-friendly).
+ */
+export async function run(args: ParsedArgs): Promise<void> {
+  const { cwd, type: typeFilter, includeRemote, dryRun, verbose, quiet } = args;
+
+  const root = await resolveRepoRoot(cwd).catch((err: unknown) => {
+    if (err instanceof NotRepoError) throw err;
+    throw err;
+  });
+
+  const config = resolveConfig(root, undefined, { verbose: !!verbose });
+
+  if (includeRemote && !dryRun) {
+    await fetch(root, config.remote, {
+      verbose: !!verbose,
+    });
+  }
+
+  const allBranches = await branchList(root, {
+    includeRemote: includeRemote ?? false,
+    dryRun: !!dryRun,
+    verbose: !!verbose,
+  });
+
+  const workflowBranches = filterWorkflowBranches(
+    allBranches,
+    config,
+    typeFilter
+  );
+
+  const sorted = [...workflowBranches].sort();
+
+  for (const b of sorted) {
+    console.log(b);
+  }
+
+  if (!quiet && sorted.length === 0) {
+    console.error("No workflow branches found.");
+  }
+}

package/src/commands/start.ts

@@ -0,0 +1,141 @@
+/**
+ * Start command: create a workflow branch from the appropriate base.
+ * Ensures clean tree (or --force), base exists (local or after fetch), creates type/name branch, optional push.
+ * @module commands/start
+ */
+
+import type { BranchType, ParsedArgs } from "../types.js";
+import { EXIT_USER, VERSION_REGEX } from "../constants.js";
+import { getPrefixForType, resolveConfig } from "../config.js";
+import { BranchNotFoundError, DirtyWorkingTreeError, InvalidVersionError } from "../errors.js";
+import {
+  assertNoRebaseOrMerge,
+  assertNotDetached,
+  branchList,
+  fetch,
+  isClean,
+  push,
+  resolveRepoRoot,
+  revParse,
+  runGit,
+  validateBranchName,
+} from "../git.js";
+
+/**
+ * Returns the base branch name for the given type and fromMain flag (main vs dev).
+ */
+function getBaseBranch(
+  type: BranchType,
+  fromMain: boolean,
+  main: string,
+  dev: string
+): string {
+  if (type === "hotfix") return main;
+  if (type === "bugfix" && fromMain) return main;
+  return dev;
+}
+
+/**
+ * Runs the start command: validate pre-conditions, ensure base exists, create branch, optional push.
+ * Pre-checks: repo is git, not detached HEAD, no rebase/merge in progress, working tree clean (or --force), base exists.
+ * Requires type and name (exit 1 if missing). For release/hotfix, name must match vX.Y.Z or X.Y.Z.
+ *
+ * @param args - Parsed CLI args (cwd, type, name, push, noPush, remote, dryRun, verbose, quiet, force, fromMain).
+ */
+export async function run(args: ParsedArgs): Promise<void> {
+  if (!args.type || args.name === undefined || args.name === "") {
+    console.error("gflows start: requires type and name (e.g. gflows start feature my-feat). Use 'gflows help' for usage.");
+    process.exit(EXIT_USER);
+  }
+
+  const type = args.type;
+  const name = args.name.trim();
+  const repoRoot = await resolveRepoRoot(args.cwd);
+  const config = resolveConfig(
+    repoRoot,
+    { remote: args.remote },
+    { verbose: args.verbose }
+  );
+
+  const opts = {
+    dryRun: args.dryRun,
+    verbose: args.verbose,
+  };
+
+  // Pre-checks: not detached HEAD, no rebase/merge in progress
+  await assertNotDetached(repoRoot);
+  assertNoRebaseOrMerge(repoRoot);
+
+  // Working tree clean or --force
+  if (!args.force) {
+    const clean = await isClean(repoRoot, { dryRun: false, verbose: opts.verbose });
+    if (!clean) {
+      throw new DirtyWorkingTreeError();
+    }
+  }
+
+  // Validate name: version for release/hotfix, branch name for others
+  if (type === "release" || type === "hotfix") {
+    if (!VERSION_REGEX.test(name)) {
+      throw new InvalidVersionError(
+        `Invalid version '${name}'. Use format vX.Y.Z or X.Y.Z (e.g. v1.2.0).`
+      );
+    }
+  } else {
+    validateBranchName(name);
+  }
+
+  const base = getBaseBranch(type, args.fromMain, config.main, config.dev);
+
+  // Ensure base exists (local or create from remote after fetch)
+  let baseExists = false;
+  try {
+    await revParse(repoRoot, base, [], { dryRun: false, verbose: opts.verbose });
+    baseExists = true;
+  } catch {
+    // Fetch and try remote ref
+    await fetch(repoRoot, config.remote, opts);
+    const remoteRef = `${config.remote}/${base}`;
+    try {
+      await revParse(repoRoot, remoteRef, [], { dryRun: false, verbose: opts.verbose });
+      if (!opts.dryRun) {
+        await runGit(["branch", base, remoteRef], { cwd: repoRoot, ...opts, dryRun: false });
+      }
+      baseExists = true;
+    } catch {
+      throw new BranchNotFoundError(
+        `Base branch '${base}' not found locally or on ${config.remote}. Create it or push it first.`
+      );
+    }
+  }
+
+  const prefix = getPrefixForType(config, type);
+  const fullBranchName = `${prefix}${name}`;
+
+  const branches = await branchList(repoRoot, { ...opts, dryRun: false });
+  if (branches.includes(fullBranchName)) {
+    throw new BranchNotFoundError(
+      `Branch '${fullBranchName}' already exists. Use a different name or switch to it.`
+    );
+  }
+
+  await runGit(["checkout", "-b", fullBranchName, base], { cwd: repoRoot, ...opts });
+
+  if (!args.quiet && !args.dryRun) {
+    console.error(`gflows: created and checked out branch '${fullBranchName}' from '${base}'.`);
+  }
+
+  const doPush = args.push && !args.noPush;
+  if (doPush) {
+    const remote = args.remote ?? config.remote;
+    const pushCode = await push(repoRoot, remote, [fullBranchName], false, opts);
+    if (pushCode !== 0) {
+      throw new Error(
+        `Push failed. Local branch '${fullBranchName}' was created. Retry with \`git push ${remote} ${fullBranchName}\` or \`gflows start ... --push\`.`
+      );
+    }
+    if (!args.quiet && !args.dryRun) {
+      console.error(`gflows: pushed '${fullBranchName}' to '${remote}'.`);
+    }
+  }
+}