gflows 0.1.9 → 0.1.11

package/README.md

@@ -77,6 +77,11 @@ Available on:
 - [npm: gflows](https://www.npmjs.com/package/gflows)
 - [JSR: @alialnaghmoush/gflows](https://jsr.io/@alialnaghmoush/gflows)
 
+If installed as a local dev dependency, run via your package runner:
+
+- Bun: `bunx gflows ...` (or `bun gflows ...` when available in your Bun setup)
+- npm: `npx gflows ...`
+
 **Global install (optional):**
 
 **npm**

package/package.json

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

package/src/cli.ts

@@ -1,3 +1,5 @@
+#!/usr/bin/env bun
+
 /**
  * CLI entrypoint for gflows. Parses argv, resolves -C/path, dispatches to commands,
  * and ensures exit codes and unhandled rejections are handled.

package/src/commands/bump.ts

@@ -10,6 +10,7 @@ import type { ParsedArgs } from "../types.js";
 import type { BumpDirection, BumpType } from "../types.js";
 import { EXIT_OK, EXIT_USER } from "../constants.js";
 import { InvalidVersionError } from "../errors.js";
+import { hint, success } from "../out.js";
 
 const PACKAGE_JSON = "package.json";
 const JSR_JSON = "jsr.json";
@@ -195,8 +196,8 @@ export async function run(args: ParsedArgs): Promise<void> {
 
   if (dryRun) {
     if (!quiet) {
-      console.error(`Would bump version: ${oldVersion} → ${newVersion}`);
-      console.error(`Would update: ${filesToUpdate.join(", ")}`);
+      success(`Would bump version: ${oldVersion} → ${newVersion}`);
+      success(`Would update: ${filesToUpdate.join(", ")}`);
     }
     process.exit(EXIT_OK);
   }
@@ -205,9 +206,10 @@ export async function run(args: ParsedArgs): Promise<void> {
   const jsrUpdated = syncJsrVersion(cwd, newVersion);
 
   if (!quiet) {
-    console.error(`Bumped version: ${oldVersion} → ${newVersion}`);
+    success(`Bumped version: ${oldVersion} → ${newVersion}`);
     const updated = [PACKAGE_JSON];
     if (jsrUpdated) updated.push(JSR_JSON);
-    console.error(`Updated: ${updated.join(", ")}`);
+    success(`Updated: ${updated.join(", ")}`);
+    hint("Commit the change, then run gflows start release vX.Y.Z to release.");
   }
 }

package/src/commands/delete.ts

@@ -13,6 +13,7 @@ import {
   deleteBranch,
   resolveRepoRoot,
 } from "../git.js";
+import { hint, success } from "../out.js";
 
 const BRANCH_TYPES: BranchType[] = [
   "feature",
@@ -75,9 +76,12 @@ export async function run(args: ParsedArgs): Promise<void> {
         verbose: args.verbose,
       });
       if (!quiet && !dryRun) {
-        console.error(`Deleted branch '${branch}'.`);
+        success(`Deleted branch '${branch}'.`);
       }
     }
+    if (!quiet && !dryRun) {
+      hint("Use gflows list to see remaining workflow branches.");
+    }
     return;
   }
 
@@ -131,7 +135,10 @@ export async function run(args: ParsedArgs): Promise<void> {
       verbose: args.verbose,
     });
     if (!quiet && !dryRun) {
-      console.error(`Deleted branch '${branch}'.`);
+      success(`Deleted branch '${branch}'.`);
     }
   }
+  if (!quiet && !dryRun && chosen.length > 0) {
+    hint("Use gflows list to see remaining workflow branches.");
+  }
 }

package/src/commands/finish.ts

@@ -26,6 +26,7 @@ import {
   tag,
   tagExists,
 } from "../git.js";
+import { hint, success } from "../out.js";
 
 /** Normalizes version to vX.Y.Z for tag name. */
 function normalizeTagVersion(version: string): string {
@@ -206,7 +207,7 @@ export async function run(args: ParsedArgs): Promise<void> {
           tagMessage: args.tagMessage,
         });
         if (!args.quiet && !args.dryRun) {
-          console.error(`gflows: created tag '${tagName}'.`);
+          success(`gflows: created tag '${tagName}'.`);
         }
       }
 
@@ -237,7 +238,7 @@ export async function run(args: ParsedArgs): Promise<void> {
   if (shouldDelete && !opts.dryRun) {
     await deleteBranch(repoRoot, branchToFinish, opts);
     if (!args.quiet) {
-      console.error(`gflows: deleted branch '${branchToFinish}'.`);
+      success(`gflows: deleted branch '${branchToFinish}'.`);
     }
   }
 
@@ -265,11 +266,12 @@ export async function run(args: ParsedArgs): Promise<void> {
       process.exit(2);
     }
     if (!args.quiet && !args.dryRun) {
-      console.error(`gflows: pushed to ${remote}.`);
+      success(`gflows: pushed to ${remote}.`);
     }
   }
 
   if (!args.quiet && !args.dryRun) {
-    console.error(`gflows: finished '${branchToFinish}' into ${meta.mergeTarget}.`);
+    success(`gflows: finished '${branchToFinish}' into ${meta.mergeTarget}.`);
+    hint("Run gflows start <type> <name> to create a new workflow branch.");
   }
 }

package/src/commands/help.ts

@@ -50,6 +50,11 @@ Finish: --no-ff         Always create merge commit; -D/--delete, -N/--no-delete;
 List:   -r, --include-remote   Include remote-tracking branches
 
 Exit codes: 0 success, 1 usage/validation, 2 Git or system error.
+
+Hints:
+  • gflows init then gflows start feature <name> — set up and create first branch
+  • gflows finish <type> — merge current workflow branch (use -B <name> to specify branch)
+  • gflows list -r — include remote branches; gflows status — show current branch flow
 `;
   console.log(out.trim());
 }

package/src/commands/init.ts

@@ -13,6 +13,7 @@ import {
   revParse,
   runGit,
 } from "../git.js";
+import { banner, hint, success } from "../out.js";
 import type { ParsedArgs } from "../types.js";
 
 /**
@@ -35,6 +36,18 @@ export async function run(args: ParsedArgs): Promise<void> {
     { verbose: args.verbose }
   );
 
+  if (!args.quiet) {
+    banner("gflows init", [
+      "Setting up main + dev workflow",
+      "",
+      `  main   ${config.main}`,
+      `  dev    ${config.dev}`,
+      `  remote ${config.remote}`,
+      "",
+      "→ Dev from main. Use --push to push.",
+    ]);
+  }
+
   const opts = {
     dryRun: args.dryRun,
     verbose: args.verbose,
@@ -59,7 +72,7 @@ export async function run(args: ParsedArgs): Promise<void> {
   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}'.`);
+      success(`gflows: created branch '${config.dev}' from '${config.main}'.`);
     }
   }
 
@@ -72,7 +85,7 @@ export async function run(args: ParsedArgs): Promise<void> {
       );
     }
     if (!args.quiet && !args.dryRun) {
-      console.error(`gflows: pushed '${config.dev}' to '${config.remote}'.`);
+      success(`gflows: pushed '${config.dev}' to '${config.remote}'.`);
     }
   }
 
@@ -84,7 +97,11 @@ export async function run(args: ParsedArgs): Promise<void> {
       ...(args.remote !== undefined && { remote: args.remote }),
     });
     if (!args.quiet) {
-      console.error("gflows: updated .gflows.json with provided options.");
+      success("gflows: updated .gflows.json with provided options.");
     }
   }
+
+  if (!args.quiet) {
+    hint("Run gflows start feature <name> to create a workflow branch.");
+  }
 }

package/src/commands/list.ts

@@ -11,6 +11,7 @@ import type { ResolvedConfig } from "../types.js";
 import { resolveConfig } from "../config.js";
 import { NotRepoError } from "../errors.js";
 import { branchList, fetch, resolveRepoRoot } from "../git.js";
+import { hint } from "../out.js";
 
 const BRANCH_TYPES: BranchType[] = [
   "feature",
@@ -89,5 +90,8 @@ export async function run(args: ParsedArgs): Promise<void> {
 
   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) {
+    hint("Use gflows switch <branch> to switch to a branch.");
   }
 }

package/src/commands/start.ts

@@ -8,6 +8,7 @@ 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 { hint, success } from "../out.js";
 import {
   assertNoRebaseOrMerge,
   assertNotDetached,
@@ -122,7 +123,7 @@ export async function run(args: ParsedArgs): Promise<void> {
   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}'.`);
+    success(`gflows: created and checked out branch '${fullBranchName}' from '${base}'.`);
   }
 
   const doPush = args.push && !args.noPush;
@@ -135,7 +136,11 @@ export async function run(args: ParsedArgs): Promise<void> {
       );
     }
     if (!args.quiet && !args.dryRun) {
-      console.error(`gflows: pushed '${fullBranchName}' to '${remote}'.`);
+      success(`gflows: pushed '${fullBranchName}' to '${remote}'.`);
     }
   }
+
+  if (!args.quiet && !args.dryRun) {
+    hint(`When done, run gflows finish ${type} to merge into the target branch.`);
+  }
 }

package/src/commands/status.ts

@@ -18,6 +18,7 @@ import {
   getCurrentBranch,
   resolveRepoRoot,
 } from "../git.js";
+import { hint } from "../out.js";
 
 const BRANCH_TYPES: BranchType[] = [
   "feature",
@@ -137,5 +138,6 @@ export async function run(args: ParsedArgs): Promise<void> {
 
   if (!quiet) {
     console.log(`Ahead/behind: ${ahead} ahead, ${behind} behind`);
+    hint(`Run gflows finish ${classification} to merge into ${mergeTargetDisplay}.`);
   }
 }

package/src/commands/switch.ts

@@ -13,6 +13,7 @@ import {
   checkout,
   resolveRepoRoot,
 } from "../git.js";
+import { hint, success } from "../out.js";
 
 const BRANCH_TYPES: BranchType[] = [
   "feature",
@@ -63,7 +64,8 @@ export async function run(args: ParsedArgs): Promise<void> {
       verbose: args.verbose,
     });
     if (!quiet && !dryRun) {
-      console.error(`Switched to branch '${branchName}'.`);
+      success(`Switched to branch '${branchName}'.`);
+      hint("Use gflows list to see all workflow branches.");
     }
     return;
   }
@@ -101,6 +103,7 @@ export async function run(args: ParsedArgs): Promise<void> {
     verbose: args.verbose,
   });
   if (!quiet && !dryRun) {
-    console.error(`Switched to branch '${chosen}'.`);
+    success(`Switched to branch '${chosen}'.`);
+    hint("Use gflows list to see all workflow branches.");
   }
 }

package/src/out.ts

@@ -0,0 +1,81 @@
+/**
+ * Stdout helpers for success/info messages so they are not sent to stderr (which many terminals show in red).
+ * @module out
+ */
+
+const GREEN = "\x1b[32m";
+const CYAN = "\x1b[36m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+const SUCCESS_ICON = "✓";
+
+/**
+ * Whether stdout is a TTY and can safely use ANSI color codes.
+ */
+function isColorCapable(): boolean {
+  return typeof process.stdout.isTTY === "boolean" && process.stdout.isTTY;
+}
+
+/**
+ * Prints a success message to stdout with a green checkmark icon.
+ * Uses stdout so terminals do not render it as error (red). Disables color when not a TTY (e.g. CI).
+ *
+ * @param message - One-line success message to print (no trailing newline added).
+ */
+export function success(message: string): void {
+  const icon = SUCCESS_ICON;
+  const line = isColorCapable() ? `${GREEN}${icon}${RESET} ${message}` : `${icon} ${message}`;
+  console.log(line);
+}
+
+/**
+ * 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.
+ *
+ * @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 BANNER_INNER_WIDTH = 42;
+
+/** Box-drawing characters for table-style banner. */
+const BOX = {
+  TL: "╔",
+  TR: "╗",
+  BL: "╚",
+  BR: "╝",
+  H: "═",
+  V: "║",
+} as const;
+
+/**
+ * Prints a table-style banner to stdout (e.g. for init). Uses cyan/bold when TTY.
+ * Skips color when not a TTY (e.g. CI). Supports multiple detail lines.
+ *
+ * @param title - Main banner line (e.g. "gflows init").
+ * @param lines - Optional lines below the title (subtitle, key-value rows, blank "" for spacing).
+ */
+export function banner(title: string, lines?: string[]): void {
+  const color = isColorCapable();
+  const c = (s: string) => (color ? `${CYAN}${s}${RESET}` : s);
+  const inner = BANNER_INNER_WIDTH - 4;
+  const top = `  ${c(BOX.TL)}${c(BOX.H.repeat(BANNER_INNER_WIDTH))}${c(BOX.TR)}`;
+  const bottom = `  ${c(BOX.BL)}${c(BOX.H.repeat(BANNER_INNER_WIDTH))}${c(BOX.BR)}`;
+  const row = (text: string) =>
+    "  " + c(BOX.V) + "  " + text + " ".repeat(Math.max(0, inner - text.length)) + "  " + c(BOX.V);
+  const titleDisplay = color ? `${CYAN}${BOLD}${title}${RESET}` : title;
+  console.log("");
+  console.log(top);
+  console.log("  " + c(BOX.V) + "  " + titleDisplay + " ".repeat(Math.max(0, inner - title.length)) + "  " + c(BOX.V));
+  if (lines?.length) {
+    for (const line of lines) {
+      console.log(line === "" ? row("") : row(line));
+    }
+  }
+  console.log(bottom);
+  console.log("");
+}