gflows 0.1.11 → 0.1.13

package/README.md

@@ -1,4 +1,4 @@
-# gflows
+# gFlows
 
 A lightweight CLI for consistent Git branching workflows: long-lived **main** (production) and **dev** (integration), plus short-lived workflow branches with clear merge targets. Built for [Bun](https://bun.sh) and TypeScript; **scriptable** and **safe by default**—no history rewriting, predictable exit codes, and optional interactive pickers only when running in a TTY.
 
@@ -171,7 +171,7 @@ gflows finish hotfix --push               # merge to main, then dev; tag v1.3.1;
 | `delete`     | `-L`  | Delete local workflow branch(es). Never main/dev.                         |
 | `list`       | `-l`  | List workflow branches; optional type filter and remote.                  |
 | `bump`       | —     | Bump or rollback package version (patch/minor/major).                     |
-| `completion` | —     | Print shell completion script (bash | zsh | fish).                        |
+| `completion` | —     | Print shell completion script (bash/zsh/fish).                            |
 | `status`     | `-t`  | Show current branch, type, base, merge target(s), ahead/behind.           |
 | `help`       | `-h`  | Show usage and quick reference.                                           |
 | `version`    | `-V`  | Show version.                                                             |
@@ -179,13 +179,32 @@ gflows finish hotfix --push               # merge to main, then dev; tag v1.3.1;
 
 **Branch types (for start/finish/list):** `feature` (`-f`), `bugfix` (`-b`), `chore` (`-c`), `release` (`-r`), `hotfix` (`-x`), `spike` (`-e`).
 
+**Common flags** (used by multiple commands):
+
+
+| Flag              | Short | Description                           |
+| ----------------- | ----- | ------------------------------------- |
+| `--path <dir>`    | `-C`  | Run as if in `<dir>`.                 |
+| `--dry-run`       | `-d`  | Log intended actions only; no writes. |
+| `--verbose`       | `-v`  | Verbose output.                       |
+| `--quiet`         | `-q`  | Minimal output.                       |
+| `--push`          | `-p`  | Push after init/start/finish.         |
+| `--no-push`       | `-P`  | Do not push.                          |
+| `--main <name>`   | —     | Main branch override.                 |
+| `--dev <name>`    | —     | Dev branch override.                  |
+| `--remote <name>` | `-R`  | Remote for push.                      |
+| `--from <branch>` | `-o`  | Base branch override (start).         |
+| `--branch <name>` | `-B`  | Branch name (finish).                 |
+| `--yes`           | `-y`  | Skip confirmations.                   |
+
+
 ---
 
 ### init
 
 Ensures the **main** branch exists (exits with error if not). Creates **dev** from main if it does not exist; does nothing if dev already exists. Does not rewrite or force-push.
 
-You can set and persist config with `**--main`**, `**--dev**`, and `**-R`/`--remote**`. Any of these flags cause init to write or update `.gflows.json` with the given values (after a successful init; skipped with `--dry-run`).
+You can set and persist config with `**--main`**, `**--dev`**, and `**-R`/`--remote**`. Any of these flags cause init to write or update `.gflows.json` with the given values (after a successful init; skipped with `--dry-run`).
 
 **Examples:**
 
@@ -197,7 +216,20 @@ gflows init -C ../other-repo    # run in another directory
 gflows init --dry-run           # log intended actions only
 ```
 
-**Flags:** `--push`, `--main <name>`, `--dev <name>`, `-R`/`--remote <name>` (main/dev/remote are persisted to `.gflows.json` when provided), `-C`/`--path <dir>`, `--dry-run`, `-v`/`--verbose`, `-q`/`--quiet`.
+**Flags:**
+
+
+| Flag              | Short | Description                                                   |
+| ----------------- | ----- | ------------------------------------------------------------- |
+| `--push`          | `-p`  | Push dev to remote after creating.                            |
+| `--main <name>`   | —     | Main branch name (persisted to `.gflows.json` when provided). |
+| `--dev <name>`    | —     | Dev branch name (persisted to `.gflows.json` when provided).  |
+| `--remote <name>` | `-R`  | Remote name (persisted to `.gflows.json` when provided).      |
+| `--path <dir>`    | `-C`  | Run as if in `<dir>`.                                         |
+| `--dry-run`       | `-d`  | Log intended actions only; no writes.                         |
+| `--verbose`       | `-v`  | Verbose output.                                               |
+| `--quiet`         | `-q`  | Minimal output.                                               |
+
 
 ---
 
@@ -220,7 +252,20 @@ gflows start feature api-v2 --push               # create branch and push to rem
 gflows start chore deps-update -C ./backend      # run in subdirectory
 ```
 
-**Flags:** `--force` (allow dirty working tree), `--push`, `-o`/`--from <branch>` (base override, e.g. `-o main` for bugfix), `-R`/`--remote`, `-C`/`--path`, `--dry-run`, `-v`, `-q`.
+**Flags:**
+
+
+| Flag              | Short | Description                                       |
+| ----------------- | ----- | ------------------------------------------------- |
+| `--force`         | —     | Allow dirty working tree.                         |
+| `--push`          | `-p`  | Push new branch to remote after creating.         |
+| `--from <branch>` | `-o`  | Base branch override (e.g. `-o main` for bugfix). |
+| `--remote <name>` | `-R`  | Remote for push.                                  |
+| `--path <dir>`    | `-C`  | Run as if in `<dir>`.                             |
+| `--dry-run`       | `-d`  | Log intended actions only; no writes.             |
+| `--verbose`       | `-v`  | Verbose output.                                   |
+| `--quiet`         | `-q`  | Minimal output.                                   |
+
 
 ---
 
@@ -245,7 +290,27 @@ gflows finish -y                           # skip "Delete branch after finish?"
 
 **Branch resolution:** If you omit the branch name, gflows uses the current branch. With `-B` and no value in a TTY, it shows a picker of workflow branches. Without a TTY, you must pass the branch name explicitly.
 
-**Flags:** `-B`/`--branch <name>`, `--no-ff`, `-D`/`--delete` (delete branch after finish), `-N`/`--no-delete`, `--push`, `-s`/`--sign`, `-T`/`--no-tag`, `-M`/`--tag-message`, `-m`/`--message`, `-y`/`--yes`, `-C`, `--dry-run`, `-v`, `-q`.
+**Flags:**
+
+
+| Flag                  | Short | Description                                                                          |
+| --------------------- | ----- | ------------------------------------------------------------------------------------ |
+| `--branch <name>`     | `-B`  | Branch to finish (current branch if omitted; picker in TTY when `-B` with no value). |
+| `--no-ff`             | —     | Always create a merge commit.                                                        |
+| `--delete`            | `-D`  | Delete branch after finish.                                                          |
+| `--no-delete`         | `-N`  | Do not delete branch after finish.                                                   |
+| `--push`              | `-p`  | Push after merge (finish prompts "Do you want to push?" when neither `-p` nor `-P`). |
+| `--no-push`           | `-P`  | Do not push.                                                                         |
+| `--sign`              | `-s`  | Sign the tag (release/hotfix; GPG).                                                  |
+| `--no-tag`            | `-T`  | Do not create tag (release/hotfix).                                                  |
+| `--tag-message <msg>` | `-M`  | Tag message.                                                                         |
+| `--message <msg>`     | `-m`  | Merge message.                                                                       |
+| `--yes`               | `-y`  | Skip confirmations (e.g. "Delete branch after finish?").                             |
+| `--path <dir>`        | `-C`  | Run as if in `<dir>`.                                                                |
+| `--dry-run`           | `-d`  | Log intended actions only; no writes.                                                |
+| `--verbose`           | `-v`  | Verbose output.                                                                      |
+| `--quiet`             | `-q`  | Minimal output.                                                                      |
+
 
 ---
 
@@ -261,7 +326,15 @@ gflows switch feature/auth-refactor
 gflows -W feature/auth-refactor    # same with short command
 ```
 
-**Flags:** `-C`/`--path`, `-v`, `-q`.
+**Flags:**
+
+
+| Flag           | Short | Description           |
+| -------------- | ----- | --------------------- |
+| `--path <dir>` | `-C`  | Run as if in `<dir>`. |
+| `--verbose`    | `-v`  | Verbose output.       |
+| `--quiet`      | `-q`  | Minimal output.       |
+
 
 ---
 
@@ -277,7 +350,15 @@ gflows delete feature/old-spike
 gflows delete feature/one feature/two    # delete multiple
 ```
 
-**Flags:** `-C`/`--path`, `-v`, `-q`.
+**Flags:**
+
+
+| Flag           | Short | Description           |
+| -------------- | ----- | --------------------- |
+| `--path <dir>` | `-C`  | Run as if in `<dir>`. |
+| `--verbose`    | `-v`  | Verbose output.       |
+| `--quiet`      | `-q`  | Minimal output.       |
+
 
 ---
 
@@ -295,7 +376,17 @@ gflows list -r feature                   # remote + local feature branches
 gflows list --include-remote
 ```
 
-**Flags:** `-r`/`--include-remote`, `-C`/`--path`, `--dry-run`, `-v`, `-q`.
+**Flags:**
+
+
+| Flag               | Short | Description                                             |
+| ------------------ | ----- | ------------------------------------------------------- |
+| `--include-remote` | `-r`  | Include remote-tracking branches (may run `git fetch`). |
+| `--path <dir>`     | `-C`  | Run as if in `<dir>`.                                   |
+| `--dry-run`        | `-d`  | Log intended actions only.                              |
+| `--verbose`        | `-v`  | Verbose output.                                         |
+| `--quiet`          | `-q`  | Minimal output.                                         |
+
 
 ---
 
@@ -317,7 +408,16 @@ gflows bump                              # interactive (direction + type) when T
 gflows bump --dry-run                    # print old → new, no file writes
 ```
 
-**Flags:** `--dry-run`, `-C`/`--path`, `-v`, `-q`.
+**Flags:**
+
+
+| Flag           | Short | Description                                   |
+| -------------- | ----- | --------------------------------------------- |
+| `--dry-run`    | `-d`  | Print old → new version only; no file writes. |
+| `--path <dir>` | `-C`  | Run as if in `<dir>`.                         |
+| `--verbose`    | `-v`  | Verbose output.                               |
+| `--quiet`      | `-q`  | Minimal output.                               |
+
 
 ---
 
@@ -332,7 +432,15 @@ gflows status
 gflows -t
 ```
 
-**Flags:** `-C`/`--path`, `-v`, `-q`.
+**Flags:**
+
+
+| Flag           | Short | Description           |
+| -------------- | ----- | --------------------- |
+| `--path <dir>` | `-C`  | Run as if in `<dir>`. |
+| `--verbose`    | `-v`  | Verbose output.       |
+| `--quiet`      | `-q`  | Minimal output.       |
+
 
 ---
 
@@ -386,7 +494,7 @@ Configuration is **optional**. Override branch names, remote, and branch **prefi
 **Resolution order** (later overrides earlier):
 
 1. Built-in defaults (`main`, `dev`, `origin`, and default prefixes).
-2. Repo config file: `**.gflows.json`** in repo root, or `**gflows**` key in `**package.json**`.
+2. Repo config file: `**.gflows.json`** in repo root, or `**gflows`** key in `**package.json`**.
 3. CLI (e.g. `--main`, `--dev`, `-R`/`--remote`).
 
 Only include keys you want to override; the rest stay default. Invalid or malformed config is ignored (with an optional warning when using `-v`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gflows",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "A lightweight CLI for consistent Git branching workflows (main + dev, feature/bugfix/chore/release/hotfix).",
   "license": "MIT",
   "type": "module",

package/src/cli.ts

@@ -123,6 +123,45 @@ function resolveCwd(pathFlag: string | undefined): string {
   return absolute;
 }
 
+/**
+ * Returns the command name closest to `input` by edit distance, or undefined if no close match.
+ * Used for "did you mean?" when the user mistypes a command.
+ */
+function closestCommand(input: string): Command | undefined {
+  if (!input || input.length < 2) return undefined;
+  const target = input.toLowerCase();
+  let best: Command | undefined;
+  let bestDistance = 3; // only suggest if within 2 edits
+  for (const cmd of COMMANDS) {
+    const d = editDistance(target, cmd);
+    if (d < bestDistance) {
+      bestDistance = d;
+      best = cmd as Command;
+    }
+  }
+  return best;
+}
+
+/** Levenshtein edit distance between two strings. */
+function editDistance(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  const dp: number[][] = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) dp[i]![0] = i;
+  for (let j = 0; j <= n; j++) dp[0]![j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i]![j] = Math.min(
+        dp[i - 1]![j]! + 1,
+        dp[i]![j - 1]! + 1,
+        dp[i - 1]![j - 1]! + cost
+      );
+    }
+  }
+  return dp[m]![n]!;
+}
+
 /** Resolve command from positionals and short flags. Short wins if both present. */
 function resolveCommand(
   positionals: string[],
@@ -240,7 +279,13 @@ export function parse(argv: string[] = Bun.argv.slice(2)): ParsedArgs {
 
   const command = resolveCommand(positionals, v);
   if (!command) {
-    console.error("gflows: missing command. Use 'gflows help' for usage.");
+    const first = positionals[0];
+    const suggestion = typeof first === "string" ? closestCommand(first) : undefined;
+    if (suggestion) {
+      console.error(`gflows: unknown command '${first}'. Did you mean '${suggestion}'?`);
+    } else {
+      console.error("gflows: missing command. Use 'gflows help' for usage.");
+    }
     process.exit(EXIT_USER);
   }
 

package/src/commands/bump.ts

@@ -111,7 +111,7 @@ function readPackageVersion(dir: string): { raw: string; semver: Semver } {
   const version = data.version;
   if (typeof version !== "string" || version.trim() === "") {
     throw new InvalidVersionError(
-      "package.json has no valid 'version' field."
+      "package.json has no valid 'version' field. Add a \"version\" field (e.g. \"0.0.0\") to package.json."
     );
   }
   const semver = parseVersion(version);
@@ -210,6 +210,7 @@ export async function run(args: ParsedArgs): Promise<void> {
     const updated = [PACKAGE_JSON];
     if (jsrUpdated) updated.push(JSR_JSON);
     success(`Updated: ${updated.join(", ")}`);
+    // Hint: suggest next step — commit and start release branch
     hint("Commit the change, then run gflows start release vX.Y.Z to release.");
   }
 }

package/src/commands/delete.ts

@@ -80,6 +80,7 @@ export async function run(args: ParsedArgs): Promise<void> {
       }
     }
     if (!quiet && !dryRun) {
+      // Hint: suggest listing remaining branches
       hint("Use gflows list to see remaining workflow branches.");
     }
     return;
@@ -139,6 +140,7 @@ export async function run(args: ParsedArgs): Promise<void> {
     }
   }
   if (!quiet && !dryRun && chosen.length > 0) {
+    // Hint: suggest listing remaining branches
     hint("Use gflows list to see remaining workflow branches.");
   }
 }

package/src/commands/finish.ts

@@ -242,10 +242,21 @@ export async function run(args: ParsedArgs): Promise<void> {
     }
   }
 
-  const doPush = args.push && !args.noPush;
-  const didCreateTag = !!(
+  const createdTagName =
     meta.mergeTarget === "main-then-dev" && meta.tagOnFinish && version && !args.noTag
-  );
+      ? normalizeTagVersion(version)
+      : undefined;
+  const didCreateTag = Boolean(createdTagName);
+
+  let doPush = args.push && !args.noPush;
+  if (!args.push && !args.noPush && isTTY) {
+    const { confirm } = await import("@inquirer/prompts");
+    doPush = await confirm({
+      message: "Do you want to push?",
+      default: true,
+    });
+  }
+
   if (doPush) {
     const remote = args.remote ?? config.remote;
     const refsToPush: string[] = [config.dev];
@@ -271,7 +282,9 @@ export async function run(args: ParsedArgs): Promise<void> {
   }
 
   if (!args.quiet && !args.dryRun) {
-    success(`gflows: finished '${branchToFinish}' into ${meta.mergeTarget}.`);
+    const tagSuffix = createdTagName ? ` (tag ${createdTagName})` : "";
+    success(`gflows: finished '${branchToFinish}' into ${meta.mergeTarget}${tagSuffix}.`);
+    // Hint: suggest next step — create a new workflow branch
     hint("Run gflows start <type> <name> to create a new workflow branch.");
   }
 }

package/src/commands/help.ts

@@ -32,7 +32,7 @@ Types: feature (-f), bugfix (-b), chore (-c), release (-r), hotfix (-x), spike (
 
 Common flags:
   -p, --push           Push after init/start/finish
-  -P, --no-push        Do not push
+  -P, --no-push        Do not push (finish: prompts "Do you want to push?" when neither -p nor -P)
   --main <name>        Main branch (init: persist to .gflows.json)
   --dev <name>         Dev branch (init: persist to .gflows.json)
   -R, --remote <name>  Remote for push (init: persist to .gflows.json)

package/src/commands/init.ts

@@ -102,6 +102,7 @@ export async function run(args: ParsedArgs): Promise<void> {
   }
 
   if (!args.quiet) {
+    // Hint: suggest next step — create first workflow branch
     hint("Run gflows start feature <name> to create a workflow branch.");
   }
 }

package/src/commands/list.ts

@@ -82,16 +82,18 @@ export async function run(args: ParsedArgs): Promise<void> {
     typeFilter
   );
 
-  const sorted = [...workflowBranches].sort();
+  // Show main and dev first (when present), then workflow branches
+  const mainAndDev = [config.main, config.dev].filter((b) =>
+    allBranches.includes(b)
+  );
+  const sorted = [...mainAndDev, ...[...workflowBranches].sort()];
 
   for (const b of sorted) {
     console.log(b);
   }
 
-  if (!quiet && sorted.length === 0) {
-    console.error("No workflow branches found.");
-    hint("Run gflows start <type> <name> to create a workflow branch.");
-  } else if (!quiet && sorted.length > 0) {
+  if (!quiet && sorted.length > 0) {
+    // Hint: suggest switching to a listed branch
     hint("Use gflows switch <branch> to switch to a branch.");
   }
 }

package/src/commands/start.ts

@@ -141,6 +141,7 @@ 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.`);
   }
 }

package/src/commands/status.ts

@@ -138,6 +138,7 @@ 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}.`);
   }
 }

package/src/commands/switch.ts

@@ -65,6 +65,7 @@ export async function run(args: ParsedArgs): Promise<void> {
     });
     if (!quiet && !dryRun) {
       success(`Switched to branch '${branchName}'.`);
+      // Hint: suggest listing branches
       hint("Use gflows list to see all workflow branches.");
     }
     return;
@@ -80,10 +81,15 @@ export async function run(args: ParsedArgs): Promise<void> {
 
   const allLocal = await branchList(root, { dryRun, verbose: args.verbose });
   const workflowBranches = getWorkflowBranches(allLocal, config.prefixes);
+  // Include main and dev so we always show whatever branches exist
+  const mainAndDev = [config.main, config.dev].filter((b) =>
+    allLocal.includes(b)
+  );
+  const choices = [...mainAndDev, ...workflowBranches];
 
-  if (workflowBranches.length === 0) {
+  if (choices.length === 0) {
     if (!quiet) {
-      console.error("No workflow branches found. Create one with 'gflows start <type> <name>'.");
+      console.error("No branches found.");
     }
     process.exit(EXIT_OK);
   }
@@ -91,7 +97,7 @@ export async function run(args: ParsedArgs): Promise<void> {
   const { select } = await import("@inquirer/prompts");
   const chosen = await select({
     message: "Switch to branch",
-    choices: workflowBranches.map((b) => ({ name: b, value: b })),
+    choices: choices.map((b) => ({ name: b, value: b })),
   });
 
   if (typeof chosen !== "string") {
@@ -104,6 +110,7 @@ export async function run(args: ParsedArgs): Promise<void> {
   });
   if (!quiet && !dryRun) {
     success(`Switched to branch '${chosen}'.`);
+    // Hint: suggest listing branches
     hint("Use gflows list to see all workflow branches.");
   }
 }