gflows 0.1.10 → 0.1.12

package/README.md

@@ -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,30 @@ 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 +214,18 @@ 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 +248,18 @@ 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 +284,25 @@ 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 +318,13 @@ 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 +340,13 @@ 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 +364,15 @@ 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 +394,14 @@ 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 +416,13 @@ 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 +476,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.10",
+  "version": "0.1.12",
   "description": "A lightweight CLI for consistent Git branching workflows (main + dev, feature/bugfix/chore/release/hotfix).",
   "license": "MIT",
   "type": "module",

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,11 @@ 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: 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

@@ -13,6 +13,7 @@ import {
   deleteBranch,
   resolveRepoRoot,
 } from "../git.js";
+import { hint, success } from "../out.js";
 
 const BRANCH_TYPES: BranchType[] = [
   "feature",
@@ -75,9 +76,13 @@ 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: suggest listing remaining branches
+      hint("Use gflows list to see remaining workflow branches.");
+    }
     return;
   }
 
@@ -131,7 +136,11 @@ 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: suggest listing remaining branches
+    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,14 +238,25 @@ 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}'.`);
     }
   }
 
-  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];
@@ -265,11 +277,14 @@ 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}.`);
+    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)
@@ -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,12 @@ 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: suggest next step — create first workflow branch
+    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,10 @@ export async function run(args: ParsedArgs): Promise<void> {
 
   if (!quiet && sorted.length === 0) {
     console.error("No workflow branches found.");
+    // Hint: suggest creating first workflow branch
+    hint("Run gflows start <type> <name> to create a workflow branch.");
+  } else 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

@@ -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,12 @@ 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: 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

@@ -18,6 +18,7 @@ import {
   getCurrentBranch,
   resolveRepoRoot,
 } from "../git.js";
+import { hint } from "../out.js";
 
 const BRANCH_TYPES: BranchType[] = [
   "feature",
@@ -137,5 +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

@@ -13,6 +13,7 @@ import {
   checkout,
   resolveRepoRoot,
 } from "../git.js";
+import { hint, success } from "../out.js";
 
 const BRANCH_TYPES: BranchType[] = [
   "feature",
@@ -63,7 +64,9 @@ 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: suggest listing branches
+      hint("Use gflows list to see all workflow branches.");
     }
     return;
   }
@@ -101,6 +104,8 @@ 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: suggest listing branches
+    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("");
+}