gflows 0.1.1

package/src/commands/status.ts

@@ -0,0 +1,137 @@
+/**
+ * Status command: show current branch flow info.
+ * Classifies branch (feature/bugfix/chore/release/hotfix/spike or unknown),
+ * shows base and merge target(s), and optionally ahead/behind vs base.
+ * No write operations.
+ * @module commands/status
+ */
+
+import type { BranchType, ParsedArgs } from "../types.js";
+import type { ResolvedConfig } from "../types.js";
+import {
+  getBranchTypeMeta,
+  resolveConfig,
+} from "../config.js";
+import { NotRepoError } from "../errors.js";
+import {
+  getAheadBehind,
+  getCurrentBranch,
+  resolveRepoRoot,
+} from "../git.js";
+
+const BRANCH_TYPES: BranchType[] = [
+  "feature",
+  "bugfix",
+  "chore",
+  "release",
+  "hotfix",
+  "spike",
+];
+
+/**
+ * Classifies a branch name into a workflow type, "main", "dev", or null (unknown).
+ * Uses resolved config for main/dev names and prefixes.
+ */
+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;
+  for (const type of BRANCH_TYPES) {
+    const prefix = prefixes[type];
+    if (prefix && branchName.startsWith(prefix)) {
+      return type;
+    }
+  }
+  return null;
+}
+
+/**
+ * Formats merge target for display (actual branch names).
+ */
+function formatMergeTarget(
+  mergeTarget: "main" | "dev" | "main-then-dev",
+  config: ResolvedConfig
+): string {
+  if (mergeTarget === "main-then-dev") {
+    return `${config.main}, then ${config.dev}`;
+  }
+  return mergeTarget === "main" ? config.main : config.dev;
+}
+
+/**
+ * Runs the status command.
+ * Shows current branch, classification, base, merge target(s), and ahead/behind vs base.
+ * Output goes to stdout for scripts. On detached HEAD or non-repo, reports clearly and exits.
+ */
+export async function run(args: ParsedArgs): Promise<void> {
+  const { cwd, 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 });
+  const current = await getCurrentBranch(root, {
+    dryRun: !!dryRun,
+    verbose: !!verbose,
+  });
+
+  if (current === null) {
+    if (!quiet) {
+      console.log("HEAD is detached.");
+    }
+    return;
+  }
+
+  const classification = classifyBranch(current, config);
+
+  if (!quiet) {
+    console.log(`Branch: ${current}`);
+  }
+
+  if (classification === "main") {
+    if (!quiet) {
+      console.log("Type: long-lived (main)");
+    }
+    return;
+  }
+
+  if (classification === "dev") {
+    if (!quiet) {
+      console.log("Type: long-lived (dev)");
+    }
+    return;
+  }
+
+  if (classification === null) {
+    if (!quiet) {
+      console.log("Type: unknown");
+    }
+    return;
+  }
+
+  const meta = getBranchTypeMeta(classification);
+  const baseBranch = meta.base === "main" ? config.main : config.dev;
+  const mergeTargetDisplay = formatMergeTarget(meta.mergeTarget, config);
+
+  if (!quiet) {
+    console.log(`Type: ${classification}`);
+    console.log(`Base: ${baseBranch}`);
+    console.log(`Merge target(s): ${mergeTargetDisplay}`);
+  }
+
+  const { ahead, behind } = await getAheadBehind(
+    root,
+    baseBranch,
+    current,
+    { dryRun: !!dryRun, verbose: !!verbose }
+  );
+
+  if (!quiet) {
+    console.log(`Ahead/behind: ${ahead} ahead, ${behind} behind`);
+  }
+}

package/src/commands/switch.ts

@@ -0,0 +1,102 @@
+/**
+ * Switch command: switch to a workflow branch (picker when TTY and no name, else branch name).
+ * @module commands/switch
+ */
+
+import type { BranchType } from "../types.js";
+import type { ParsedArgs } from "../types.js";
+import { resolveConfig } from "../config.js";
+import { EXIT_OK, EXIT_USER } from "../constants.js";
+import { NotRepoError } from "../errors.js";
+import {
+  branchList,
+  checkout,
+  resolveRepoRoot,
+} from "../git.js";
+
+const BRANCH_TYPES: BranchType[] = [
+  "feature",
+  "bugfix",
+  "chore",
+  "release",
+  "hotfix",
+  "spike",
+];
+
+/**
+ * Returns local branch names that match any workflow prefix (feature/, bugfix/, etc.).
+ */
+function getWorkflowBranches(
+  allBranches: string[],
+  prefixes: Record<BranchType, string>
+): string[] {
+  const prefixed = BRANCH_TYPES.map((t) => prefixes[t]).filter(Boolean);
+  return allBranches.filter((b) =>
+    prefixed.some((p) => p && b.startsWith(p))
+  );
+}
+
+/**
+ * Run the switch command.
+ * With a branch name (positional or -B): checkout that branch.
+ * With no name and TTY: show a select picker of workflow branches; if none, exit 0 with message.
+ * With no name and not TTY: exit 1 with message to provide a branch name.
+ */
+export async function run(args: ParsedArgs): Promise<void> {
+  const { cwd, name, branch, dryRun, quiet } = args;
+
+  const root = await resolveRepoRoot(cwd).catch((err) => {
+    if (err instanceof NotRepoError) throw err;
+    throw err;
+  });
+  const config = resolveConfig(root);
+
+  const branchName = (branch?.trim() || name?.trim() || "").trim() || undefined;
+
+  if (branchName) {
+    await checkout(root, branchName, {
+      dryRun,
+      verbose: args.verbose,
+    });
+    if (!quiet && !dryRun) {
+      console.error(`Switched to branch '${branchName}'.`);
+    }
+    return;
+  }
+
+  const isTTY = typeof process.stdin.isTTY === "boolean" && process.stdin.isTTY;
+  if (!isTTY) {
+    console.error(
+      "gflows switch: no branch name given and stdin is not a TTY. Pass a branch name (e.g. gflows switch feature/my-branch) or run from an interactive terminal."
+    );
+    process.exit(EXIT_USER);
+  }
+
+  const allLocal = await branchList(root, { dryRun, verbose: args.verbose });
+  const workflowBranches = getWorkflowBranches(allLocal, config.prefixes);
+
+  if (workflowBranches.length === 0) {
+    if (!quiet) {
+      console.error("No workflow branches found. Create one with 'gflows start <type> <name>'.");
+    }
+    process.exit(EXIT_OK);
+  }
+
+  const { select } = await import("@inquirer/prompts");
+  const chosen = await select({
+    message: "Switch to branch",
+    choices: workflowBranches.map((b) => ({ name: b, value: b })),
+  });
+
+  if (typeof chosen !== "string") {
+    process.exit(EXIT_USER);
+  }
+
+  await checkout(root, chosen, {
+    dryRun,
+    verbose: args.verbose,
+  });
+  if (!quiet && !dryRun) {
+    console.error(`Switched to branch '${chosen}'.`);
+  }
+}

package/src/commands/version.ts

@@ -0,0 +1,27 @@
+/**
+ * Version command: print version from the CLI's package.json.
+ * @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));
+
+/**
+ * Runs the version command: reads version from package.json (repo root when
+ * developing, package root when installed) and prints it 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");
+  }
+}

package/src/config.ts

@@ -0,0 +1,229 @@
+/**
+ * Config resolution for gflows: defaults → repo config file → env → CLI overrides.
+ * Exposes resolved main, dev, remote, and branch type prefixes for use by commands.
+ * @module config
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type {
+  BranchPrefixes,
+  BranchType,
+  BranchTypeMeta,
+  GflowsConfigFile,
+  ResolvedConfig,
+} from "./types.js";
+import {
+  DEFAULT_DEV,
+  DEFAULT_MAIN,
+  DEFAULT_PREFIXES,
+  DEFAULT_REMOTE,
+} from "./constants.js";
+
+const CONFIG_FILE = ".gflows.json";
+const PACKAGE_JSON = "package.json";
+const GFLOWS_KEY = "gflows";
+
+const ENV_MAIN = "GFLOWS_MAIN";
+const ENV_DEV = "GFLOWS_DEV";
+const ENV_REMOTE = "GFLOWS_REMOTE";
+
+/** CLI overrides for main, dev, and remote (e.g. from -R/--remote or future flags). */
+export interface ConfigCliOverrides {
+  main?: string;
+  dev?: string;
+  remote?: string;
+}
+
+/** Result of reading config file: config if valid, plus whether parsing failed (for verbose warning). */
+export interface ReadConfigResult {
+  config: GflowsConfigFile | null;
+  /** True when a config file or package.json "gflows" key was present but invalid. */
+  invalid: boolean;
+}
+
+/** Options for config resolution. */
+export interface ResolveConfigOptions {
+  /** If true, warn to stderr when config file is invalid. */
+  verbose?: boolean;
+}
+
+/**
+ * Reads and parses repo config from a directory: .gflows.json or package.json "gflows" key.
+ * Returns config when valid; invalid JSON or wrong types yield null with invalid: true for warning.
+ */
+export function readConfigFile(dir: string): ReadConfigResult {
+  const gflowsPath = join(dir, CONFIG_FILE);
+  if (existsSync(gflowsPath)) {
+    try {
+      const raw = readFileSync(gflowsPath, "utf-8");
+      const data = JSON.parse(raw) as unknown;
+      const config = normalizeConfigFile(data);
+      return { config, invalid: config === null };
+    } catch {
+      return { config: null, invalid: true };
+    }
+  }
+
+  const pkgPath = join(dir, PACKAGE_JSON);
+  if (existsSync(pkgPath)) {
+    try {
+      const raw = readFileSync(pkgPath, "utf-8");
+      const pkg = JSON.parse(raw) as Record<string, unknown>;
+      const data = pkg[GFLOWS_KEY];
+      if (data === undefined || data === null) {
+        return { config: null, invalid: false };
+      }
+      const config = normalizeConfigFile(data);
+      return { config, invalid: config === null };
+    } catch {
+      return { config: null, invalid: true };
+    }
+  }
+
+  return { config: null, invalid: false };
+}
+
+/**
+ * Normalizes and validates parsed config data. Returns a valid partial config or null if invalid.
+ */
+function normalizeConfigFile(data: unknown): GflowsConfigFile | null {
+  if (data === null || typeof data !== "object" || Array.isArray(data)) {
+    return null;
+  }
+  const obj = data as Record<string, unknown>;
+  const out: GflowsConfigFile = {};
+
+  if (typeof obj.main === "string" && obj.main.trim() !== "") {
+    out.main = obj.main.trim();
+  }
+  if (typeof obj.dev === "string" && obj.dev.trim() !== "") {
+    out.dev = obj.dev.trim();
+  }
+  if (typeof obj.remote === "string" && obj.remote.trim() !== "") {
+    out.remote = obj.remote.trim();
+  }
+  if (obj.prefixes !== undefined && obj.prefixes !== null && typeof obj.prefixes === "object" && !Array.isArray(obj.prefixes)) {
+    const prefs = obj.prefixes as Record<string, unknown>;
+    const prefixes: BranchPrefixes = {};
+    const keys: (keyof BranchPrefixes)[] = ["feature", "bugfix", "chore", "release", "hotfix", "spike"];
+    for (const k of keys) {
+      const v = prefs[k];
+      if (typeof v === "string" && v.trim() !== "") {
+        prefixes[k] = v.trim();
+      }
+    }
+    if (Object.keys(prefixes).length > 0) {
+      out.prefixes = prefixes;
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Returns config overrides from environment (GFLOWS_MAIN, GFLOWS_DEV, GFLOWS_REMOTE).
+ */
+export function getEnvConfigOverrides(): ConfigCliOverrides {
+  const overrides: ConfigCliOverrides = {};
+  const main = process.env[ENV_MAIN];
+  if (typeof main === "string" && main.trim() !== "") {
+    overrides.main = main.trim();
+  }
+  const dev = process.env[ENV_DEV];
+  if (typeof dev === "string" && dev.trim() !== "") {
+    overrides.dev = dev.trim();
+  }
+  const remote = process.env[ENV_REMOTE];
+  if (typeof remote === "string" && remote.trim() !== "") {
+    overrides.remote = remote.trim();
+  }
+  return overrides;
+}
+
+/**
+ * Merges prefix overrides into a full Required<BranchPrefixes> (defaults + overrides).
+ */
+function mergePrefixes(overrides?: BranchPrefixes): Required<BranchPrefixes> {
+  const result: Required<BranchPrefixes> = { ...DEFAULT_PREFIXES };
+  if (!overrides) return result;
+  const keys: (keyof BranchPrefixes)[] = ["feature", "bugfix", "chore", "release", "hotfix", "spike"];
+  for (const k of keys) {
+    if (typeof overrides[k] === "string" && overrides[k]!.trim() !== "") {
+      result[k] = overrides[k]!.trim();
+    }
+  }
+  return result;
+}
+
+/**
+ * Resolves full config for the given directory: defaults → file → env → CLI.
+ * Uses dir as the repo root for locating .gflows.json and package.json.
+ *
+ * @param dir - Directory to read config from (e.g. cwd or resolved -C path).
+ * @param cliOverrides - Optional overrides from CLI (e.g. --remote).
+ * @param options - Optional { verbose } to warn when config file is missing or invalid.
+ * @returns Resolved config with main, dev, remote, and full prefixes.
+ */
+export function resolveConfig(
+  dir: string,
+  cliOverrides?: ConfigCliOverrides,
+  options?: ResolveConfigOptions
+): ResolvedConfig {
+  const verbose = options?.verbose === true;
+
+  let main = DEFAULT_MAIN;
+  let dev = DEFAULT_DEV;
+  let remote = DEFAULT_REMOTE;
+  let prefixes = mergePrefixes(undefined);
+
+  const readResult = readConfigFile(dir);
+  if (readResult.invalid && verbose) {
+    console.error("gflows: invalid or empty config file; using defaults.");
+  }
+  const file = readResult.config;
+  if (file) {
+    if (file.main !== undefined) main = file.main;
+    if (file.dev !== undefined) dev = file.dev;
+    if (file.remote !== undefined) remote = file.remote;
+    if (file.prefixes !== undefined) prefixes = mergePrefixes(file.prefixes);
+  }
+
+  const envOverrides = getEnvConfigOverrides();
+  if (envOverrides.main !== undefined) main = envOverrides.main;
+  if (envOverrides.dev !== undefined) dev = envOverrides.dev;
+  if (envOverrides.remote !== undefined) remote = envOverrides.remote;
+
+  if (cliOverrides?.main !== undefined) main = cliOverrides.main;
+  if (cliOverrides?.dev !== undefined) dev = cliOverrides.dev;
+  if (cliOverrides?.remote !== undefined) remote = cliOverrides.remote;
+
+  return { main, dev, remote, prefixes };
+}
+
+/**
+ * Returns the branch name prefix for a given branch type from resolved config.
+ */
+export function getPrefixForType(
+  config: ResolvedConfig,
+  type: BranchType
+): string {
+  return config.prefixes[type] ?? DEFAULT_PREFIXES[type];
+}
+
+/** Metadata per branch type: base, merge target, and whether to tag on finish. */
+const BRANCH_TYPE_META: Record<BranchType, BranchTypeMeta> = {
+  feature: { base: "dev", mergeTarget: "dev", tagOnFinish: false },
+  bugfix: { base: "dev", mergeTarget: "dev", tagOnFinish: false },
+  chore: { base: "dev", mergeTarget: "dev", tagOnFinish: false },
+  release: { base: "dev", mergeTarget: "main-then-dev", tagOnFinish: true },
+  hotfix: { base: "main", mergeTarget: "main-then-dev", tagOnFinish: true },
+  spike: { base: "dev", mergeTarget: "dev", tagOnFinish: false },
+};
+
+/**
+ * Returns metadata for a branch type (base, merge target, tag on finish).
+ */
+export function getBranchTypeMeta(type: BranchType): BranchTypeMeta {
+  return BRANCH_TYPE_META[type];
+}

package/src/constants.ts

@@ -0,0 +1,38 @@
+/**
+ * Exit codes and default branch names/prefixes for gflows.
+ * @module constants
+ */
+
+/** Exit code: success. */
+export const EXIT_OK = 0;
+
+/** Exit code: usage/validation error (missing args, invalid type, invalid branch name/version). */
+export const EXIT_USER = 1;
+
+/** Exit code: Git or system error (not a repo, branch missing, merge failed, tag exists, etc.). */
+export const EXIT_GIT = 2;
+
+/** Default long-lived main branch name. */
+export const DEFAULT_MAIN = "main";
+
+/** Default long-lived development branch name. */
+export const DEFAULT_DEV = "dev";
+
+/** Default remote name. */
+export const DEFAULT_REMOTE = "origin";
+
+/** Default branch prefix per type (trailing slash for consistency). */
+export const DEFAULT_PREFIXES = {
+  feature: "feature/",
+  bugfix: "bugfix/",
+  chore: "chore/",
+  release: "release/",
+  hotfix: "hotfix/",
+  spike: "spike/",
+} as const;
+
+/** Semver version pattern: optional leading 'v', then X.Y.Z. */
+export const VERSION_REGEX = /^v?\d+\.\d+\.\d+$/;
+
+/** Characters invalid in Git ref names (branch names). */
+export const INVALID_BRANCH_CHARS = /\.\.|[\s~^?:*\[\]\\]/;

package/src/errors.ts

@@ -0,0 +1,96 @@
+/**
+ * Typed errors for gflows CLI. Each maps to an exit code:
+ * - Validation/usage (InvalidVersionError, InvalidBranchNameError) → EXIT_USER (1)
+ * - Git/repo/state (others) → EXIT_GIT (2)
+ * @module errors
+ */
+
+import { EXIT_GIT, EXIT_USER } from "./constants.js";
+
+/** Base error for gflows with a stable exit code. */
+export class GflowsError extends Error {
+  /** Exit code to use when this error is thrown (1 = user, 2 = git). */
+  readonly exitCode: number;
+
+  constructor(message: string, exitCode: number) {
+    super(message);
+    this.name = this.constructor.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.exitCode = exitCode;
+  }
+}
+
+/** 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);
+  }
+}
+
+/** Thrown when a required branch does not exist (local or after fetch). */
+export class BranchNotFoundError extends GflowsError {
+  constructor(message: string) {
+    super(message, EXIT_GIT);
+  }
+}
+
+/** Thrown when start is run with uncommitted changes and without --force. */
+export class DirtyWorkingTreeError extends GflowsError {
+  constructor(message = "Working tree has uncommitted changes. Commit or stash them, or use --force.") {
+    super(message, EXIT_GIT);
+  }
+}
+
+/** 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);
+  }
+}
+
+/** 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."
+  ) {
+    super(message, EXIT_GIT);
+  }
+}
+
+/** Thrown when merge fails due to conflicts; user must resolve manually. */
+export class MergeConflictError extends GflowsError {
+  constructor(message: string) {
+    super(message, EXIT_GIT);
+  }
+}
+
+/** Thrown when release/hotfix version does not match expected format (vX.Y.Z or X.Y.Z). */
+export class InvalidVersionError extends GflowsError {
+  constructor(message: string) {
+    super(message, EXIT_USER);
+  }
+}
+
+/** Thrown when branch name is empty, whitespace, or contains invalid ref characters. */
+export class InvalidBranchNameError extends GflowsError {
+  constructor(message: string) {
+    super(message, EXIT_USER);
+  }
+}
+
+/** Thrown when delete is attempted on the configured main or dev branch. */
+export class CannotDeleteMainOrDevError extends GflowsError {
+  constructor(message = "Cannot delete the long-lived branch main or dev.") {
+    super(message, EXIT_GIT);
+  }
+}
+
+/**
+ * Returns the exit code for an error: use error.exitCode if it's a GflowsError, else EXIT_GIT.
+ */
+export function exitCodeForError(error: unknown): number {
+  if (error instanceof GflowsError) {
+    return error.exitCode;
+  }
+  return EXIT_GIT;
+}