gflows 0.1.18 → 1.0.0

package/src/commands/schema.ts

@@ -0,0 +1,98 @@
+/**
+ * Print a machine-readable catalog of gflows commands, flags, types, and exit codes.
+ * @module commands/schema
+ */
+
+import type { ParsedArgs } from "../types.js";
+import { ALL_COMMANDS, BRANCH_TYPE_SHORTS } from "../types.js";
+
+/**
+ * Emits JSON schema for agents and tooling.
+ */
+export async function run(_args: ParsedArgs): Promise<void> {
+  const schema = {
+    name: "gflows",
+    version: "1.0.0",
+    description: "Git branching workflow CLI (main + dev + typed short-lived branches)",
+    exitCodes: {
+      "0": "success",
+      "1": "usage/validation",
+      "2": "git/system",
+    },
+    branchTypes: Object.entries(BRANCH_TYPE_SHORTS).map(([type, short]) => ({
+      type,
+      short,
+    })),
+    commands: ALL_COMMANDS.map((command) => ({
+      command,
+      ...commandMeta(command),
+    })),
+    flags: {
+      common: [
+        "-C/--path",
+        "-p/--push",
+        "-P/--no-push",
+        "-y/--yes",
+        "-d/--dry-run",
+        "-v/--verbose",
+        "-q/--quiet",
+        "--force",
+        "--json",
+        "--main",
+        "--dev",
+        "-R/--remote",
+      ],
+      finish: [
+        "-B/--branch",
+        "-D/--delete",
+        "-N/--no-delete",
+        "--no-ff",
+        "--squash",
+        "--preview",
+        "--bump",
+        "-s/--sign",
+        "-T/--no-tag",
+        "-M/--tag-message",
+        "-m/--message",
+      ],
+      start: ["-o/--from", "--force", "-p/--push"],
+      sync: ["--rebase", "--force"],
+      list: ["-r/--include-remote", "--json"],
+      status: ["--json"],
+    },
+    agentNotes: [
+      "Always pass explicit flags in non-TTY (never assume interactive hub).",
+      "Prefer -y to accept finish plan (delete defaults on); pass -P or -p for push.",
+      "On conflict: gflows continue | gflows abort | gflows undo.",
+      "Use gflows schema and AGENTS.md as source of truth.",
+    ],
+  };
+  console.log(JSON.stringify(schema, null, 2));
+}
+
+function commandMeta(command: string): { summary: string; interactiveOk: boolean } {
+  const map: Record<string, { summary: string; interactiveOk: boolean }> = {
+    init: { summary: "Ensure main; create dev", interactiveOk: true },
+    start: { summary: "Create workflow branch", interactiveOk: true },
+    finish: { summary: "Merge and close workflow branch", interactiveOk: true },
+    switch: { summary: "Switch workflow branch", interactiveOk: true },
+    delete: { summary: "Delete local workflow branches", interactiveOk: true },
+    list: { summary: "List workflow branches", interactiveOk: false },
+    bump: { summary: "Bump package version", interactiveOk: true },
+    sync: { summary: "Update branch from base", interactiveOk: true },
+    pr: { summary: "Open PR/MR via gh/glab", interactiveOk: true },
+    viz: { summary: "Visual branch map and flow diagram", interactiveOk: true },
+    doctor: { summary: "Repo health checks", interactiveOk: false },
+    config: { summary: "Get/set .gflows.json", interactiveOk: true },
+    schema: { summary: "Machine-readable command catalog", interactiveOk: false },
+    continue: { summary: "Resume suspended operation", interactiveOk: false },
+    undo: { summary: "Undo last completed operation", interactiveOk: false },
+    abort: { summary: "Abort suspended operation", interactiveOk: false },
+    completion: { summary: "Shell completion script", interactiveOk: false },
+    status: { summary: "Current branch flow info", interactiveOk: false },
+    help: { summary: "Usage", interactiveOk: false },
+    version: { summary: "CLI version", interactiveOk: false },
+    mcp: { summary: "Start MCP server for agents", interactiveOk: false },
+  };
+  return map[command] ?? { summary: command, interactiveOk: false };
+}

package/src/commands/start.ts

@@ -6,7 +6,13 @@
 
 import { getPrefixForType, resolveConfig } from "../config.js";
 import { EXIT_USER, VERSION_REGEX } from "../constants.js";
-import { BranchNotFoundError, DirtyWorkingTreeError, InvalidVersionError } from "../errors.js";
+import {
+  BranchExistsError,
+  BranchNotFoundError,
+  DirtyWorkingTreeError,
+  InvalidVersionError,
+} from "../errors.js";
+import { getBaseBranchName } from "../flow.js";
 import {
   assertNoRebaseOrMerge,
   assertNotDetached,
@@ -19,35 +25,30 @@ import {
   runGit,
   validateBranchName,
 } from "../git.js";
+import { promptStartArgs } from "../interactive.js";
 import { hint, success } from "../out.js";
-import type { BranchType, ParsedArgs } from "../types.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;
-}
+import type { ParsedArgs } from "../types.js";
 
 /**
  * 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 === "") {
+  let type = args.type;
+  let name = args.name?.trim();
+
+  if ((!type || !name) && process.stdin.isTTY) {
+    const prompted = await promptStartArgs();
+    type = type ?? prompted.type;
+    name = name || prompted.name;
+  }
+
+  if (!type || name === undefined || 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,
@@ -60,11 +61,9 @@ export async function run(args: ParsedArgs): Promise<void> {
     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) {
@@ -72,7 +71,6 @@ export async function run(args: ParsedArgs): Promise<void> {
     }
   }
 
-  // Validate name: version for release/hotfix, branch name for others
   if (type === "release" || type === "hotfix") {
     if (!VERSION_REGEX.test(name)) {
       throw new InvalidVersionError(
@@ -83,15 +81,18 @@ export async function run(args: ParsedArgs): Promise<void> {
     validateBranchName(name);
   }
 
-  const base = getBaseBranch(type, args.fromMain, config.main, config.dev);
+  const fromMain =
+    args.fromMain ||
+    (typeof args.from === "string" && (args.from === config.main || args.from === "main"));
+
+  const base =
+    typeof args.from === "string" && args.from !== "main" && args.from !== config.main
+      ? args.from
+      : getBaseBranchName(type, fromMain, config);
 
-  // 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 {
@@ -99,7 +100,6 @@ export async function run(args: ParsedArgs): Promise<void> {
       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.`,
@@ -112,8 +112,9 @@ export async function run(args: ParsedArgs): Promise<void> {
 
   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.`,
+    throw new BranchExistsError(
+      `Branch '${fullBranchName}' already exists.`,
+      `Use a different name, or: gflows switch ${fullBranchName}`,
     );
   }
 
@@ -138,7 +139,8 @@ export async function run(args: ParsedArgs): Promise<void> {
   }
 
   if (!args.quiet && !args.dryRun) {
-    // Hint: suggest next step — merge branch when done
-    hint(`When done, run gflows finish ${type} to merge into the target branch.`);
+    hint(
+      `Commit your work, then gflows sync or gflows finish ${type}. Interactive: just run gflows`,
+    );
   }
 }

package/src/commands/status.ts

@@ -1,59 +1,26 @@
 /**
- * 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.
+ * Status command: show current branch flow info and recovery hints.
  * @module commands/status
  */
 
-import { getBranchTypeMeta, resolveConfig } from "../config.js";
+import { resolveConfig } from "../config.js";
 import { NotRepoError } from "../errors.js";
+import {
+  classifyBranch,
+  formatMergeTarget,
+  getBaseBranchName,
+  resolveMergeTarget,
+} from "../flow.js";
 import { getAheadBehind, getCurrentBranch, resolveRepoRoot } from "../git.js";
 import { hint } from "../out.js";
-import type { BranchType, ParsedArgs, ResolvedConfig } from "../types.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;
-}
+import { readActiveRun } from "../run-state.js";
+import type { ParsedArgs } from "../types.js";
 
 /**
  * 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 { cwd, dryRun, verbose, quiet, json } = args;
 
   const root = await resolveRepoRoot(cwd).catch((err: unknown) => {
     if (err instanceof NotRepoError) throw err;
@@ -70,22 +37,62 @@ export async function run(args: ParsedArgs): Promise<void> {
     verbose: !!verbose,
   });
 
+  const active = readActiveRun(root);
+
+  if (json) {
+    const payload: Record<string, unknown> = {
+      branch: current,
+      suspended: active
+        ? { command: active.command, status: active.status, nextStep: active.nextStep }
+        : null,
+    };
+    if (current) {
+      const classification = classifyBranch(current, config);
+      payload.type = classification;
+      if (classification && classification !== "main" && classification !== "dev") {
+        const mergeTarget = await resolveMergeTarget(root, current, classification, config, {
+          dryRun: !!dryRun,
+          verbose: !!verbose,
+        });
+        const base = getBaseBranchName(classification, false, config);
+        const ab = await getAheadBehind(root, base, current, {
+          dryRun: !!dryRun,
+          verbose: !!verbose,
+        });
+        payload.base = base;
+        payload.mergeTarget = mergeTarget;
+        payload.mergeTargetDisplay = formatMergeTarget(mergeTarget, config);
+        payload.ahead = ab.ahead;
+        payload.behind = ab.behind;
+      }
+    }
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  if (active && !quiet) {
+    console.log(`Suspended: ${active.command} (${active.status})`);
+    hint("Run gflows continue after resolving conflicts, or gflows abort / undo.");
+  }
+
   if (current === null) {
     if (!quiet) {
       console.log("HEAD is detached.");
+      hint("Try: git checkout dev");
     }
     return;
   }
 
-  const classification = classifyBranch(current, config);
-
   if (!quiet) {
     console.log(`Branch: ${current}`);
   }
 
+  const classification = classifyBranch(current, config);
+
   if (classification === "main") {
     if (!quiet) {
       console.log("Type: long-lived (main)");
+      hint("Run gflows start feature <name> or gflows start hotfix vX.Y.Z");
     }
     return;
   }
@@ -93,6 +100,7 @@ export async function run(args: ParsedArgs): Promise<void> {
   if (classification === "dev") {
     if (!quiet) {
       console.log("Type: long-lived (dev)");
+      hint("Run gflows start feature <name> to begin work.");
     }
     return;
   }
@@ -100,13 +108,21 @@ export async function run(args: ParsedArgs): Promise<void> {
   if (classification === null) {
     if (!quiet) {
       console.log("Type: unknown");
+      hint("Use a typed prefix (feature/, bugfix/, …) or gflows start …");
     }
     return;
   }
 
-  const meta = getBranchTypeMeta(classification);
-  const baseBranch = meta.base === "main" ? config.main : config.dev;
-  const mergeTargetDisplay = formatMergeTarget(meta.mergeTarget, config);
+  const mergeTarget = await resolveMergeTarget(root, current, classification, config, {
+    dryRun: !!dryRun,
+    verbose: !!verbose,
+  });
+  const baseBranch = getBaseBranchName(
+    classification,
+    mergeTarget === "main-then-dev" && classification === "bugfix",
+    config,
+  );
+  const mergeTargetDisplay = formatMergeTarget(mergeTarget, config);
 
   if (!quiet) {
     console.log(`Type: ${classification}`);
@@ -121,7 +137,10 @@ export async function run(args: ParsedArgs): Promise<void> {
 
   if (!quiet) {
     console.log(`Ahead/behind: ${ahead} ahead, ${behind} behind`);
-    // Hint: suggest next step — finish current branch
-    hint(`Run gflows finish ${classification} to merge into ${mergeTargetDisplay}.`);
+    if (ahead === 0) {
+      hint("No commits to finish yet — commit changes first.");
+    } else {
+      hint(`Run gflows finish ${classification} to merge into ${mergeTargetDisplay}.`);
+    }
   }
 }

package/src/commands/switch.ts

@@ -92,19 +92,14 @@ export async function run(args: ParsedArgs): Promise<void> {
       dryRun,
       verbose: args.verbose,
     });
-    const { select } = await import("@inquirer/prompts");
-    const chosen = await select({
+    const { selectPrompt } = await import("../prompts.js");
+    targetBranch = await selectPrompt({
       message: "Switch to branch",
-      choices: choices.map((b) => ({
-        name: currentBranchForPicker && b === currentBranchForPicker ? `${b} (current)` : b,
+      options: choices.map((b) => ({
+        label: currentBranchForPicker && b === currentBranchForPicker ? `${b} (current)` : b,
         value: b,
       })),
     });
-
-    if (typeof chosen !== "string") {
-      process.exit(EXIT_USER);
-    }
-    targetBranch = chosen;
   }
 
   const gitOpts = { dryRun, verbose: args.verbose };
@@ -115,21 +110,21 @@ export async function run(args: ParsedArgs): Promise<void> {
   if (args.switchMode !== undefined) {
     whenUncommitted = args.switchMode;
   } else if (!treeClean && isTTY) {
-    const { select: selectPrompt } = await import("@inquirer/prompts");
-    whenUncommitted = await selectPrompt({
+    const { selectPrompt } = await import("../prompts.js");
+    whenUncommitted = await selectPrompt<"move" | "restore" | "clean" | "destroy" | "cancel">({
       message: "Working tree has uncommitted changes. What do you want to do?",
-      choices: [
-        { name: "Move — Move current changes to the target branch", value: "move" as const },
+      options: [
+        { label: "Move — Move current changes to the target branch", value: "move" },
         {
-          name: "Restore — Save changes for this branch; restore target's saved state (if any)",
-          value: "restore" as const,
+          label: "Restore — Save changes for this branch; restore target's saved state (if any)",
+          value: "restore",
         },
-        { name: "Clean — Discard changes and switch clean at HEAD", value: "clean" as const },
+        { label: "Clean — Discard changes and switch clean at HEAD", value: "clean" },
         {
-          name: "Destroy — Delete current branch and switch to the target branch",
-          value: "destroy" as const,
+          label: "Destroy — Delete current branch and switch to the target branch",
+          value: "destroy",
         },
-        { name: "Cancel — Abort switching", value: "cancel" as const },
+        { label: "Cancel — Abort switching", value: "cancel" },
       ],
     });
   } else if (!treeClean) {

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