better-commits 1.19.0 → 1.20.0-cli-flags

package/dist/init.js

@@ -1,2 +1,2 @@
 #! /usr/bin/env node
-import{b as r,f as e,u as i}from"./chunk-K2RPF2JY.js";import*as t from"@clack/prompts";import c from"fs";import o from"picocolors";import{parse as l}from"valibot";try{console.clear(),t.intro(`${o.bgCyan(o.black(" better-commits-init "))}`);let s=`${i()}/${e}`,m=l(r,{});c.writeFileSync(s,JSON.stringify(m,null,4)),t.log.success(`${o.green("Successfully created .better-commits.json")}`),t.outro(`Run ${o.bgBlack(o.white("better-commits"))} to start the CLI`)}catch{t.log.error(`${o.red("Could not determine git root folder. better-commits-init must be used in a git repository")}`)}
+import{b as r,h as e,m as i}from"./chunk-OFJCRS3N.js";import*as t from"@clack/prompts";import c from"fs";import o from"picocolors";import{parse as l}from"valibot";try{console.clear(),t.intro(`${o.bgCyan(o.black(" better-commits-init "))}`);let s=`${i()}/${e}`,m=l(r,{});c.writeFileSync(s,JSON.stringify(m,null,4)),t.log.success(`${o.green("Successfully created .better-commits.json")}`),t.outro(`Run ${o.bgBlack(o.white("better-commits"))} to start the CLI`)}catch{t.log.error(`${o.red("Could not determine git root folder. better-commits-init must be used in a git repository")}`)}

package/docs/ai-skills.yaml

@@ -0,0 +1,48 @@
+program: better-commits
+version: 1
+rules:
+  - prefer_non_interactive: true
+  - always_dry_run_first: true
+  - config_precedence: repo_then_home
+  - repo_config_path: .better-commits.json
+  - home_config_path: ~/.better-commits.json
+
+skills:
+  - id: create_commit_non_interactive
+    goal: Create a commit without prompts using CLI flags.
+    command: better-commits --no-interactive [flags]
+    required_flags:
+      - --title
+    optional_flags:
+      - --type
+      - --scope
+      - --body
+      - --ticket
+      - --closes
+      - --trailer
+      - --breaking-title
+      - --breaking-body
+      - --deprecates-title
+      - --deprecates-body
+      - --custom-footer
+    inference:
+      - If --type is missing, infer from branch when possible.
+      - If --ticket is missing, infer from branch when possible.
+    flow:
+      - Run dry-run first.
+      - If valid, rerun without --dry-run.
+    dry_run_example: better-commits --no-interactive --dry-run --title "add parser"
+    commit_example: better-commits --no-interactive --type feat --title "add parser"
+
+  - id: edit_config_interview
+    goal: Create or update .better-commits.json based on user preferences and verify it.
+    flow:
+      - Choose target config: repo .better-commits.json, else ~/.better-commits.json.
+      - If repo config is needed and missing, run better-commits-init in repo root.
+      - Ask focused questions and edit JSON only.
+      - Preserve unknown keys.
+      - Validate with a dry-run commit command.
+    validation_command: better-commits --no-interactive --dry-run --type feat --title "config validation"
+    success_criteria:
+      - command exits successfully
+      - no schema or config validation errors

package/docs/clack.md

@@ -0,0 +1,143 @@
+# Clack Usage
+
+`better-commits` uses [`@clack/prompts`](https://github.com/natemoo-re/clack) as its sole interactive UI layer. All terminal prompts, logging, and banners go through clack — there is no `readline`, `inquirer`, or other prompt library in use.
+
+## Packages
+
+| Package          | Version  | Role                                                   |
+| ---------------- | -------- | ------------------------------------------------------ |
+| `@clack/prompts` | `^0.7.0` | Directly imported in all source files                  |
+| `@clack/core`    | `^0.3.1` | Peer dependency of `@clack/prompts`, used transitively |
+
+All files import clack with the alias:
+
+```ts
+import * as p from "@clack/prompts";
+```
+
+## Files That Use Clack
+
+- `src/index.ts` — main `better-commits` CLI flow
+- `src/branch.ts` — `better-branch` CLI flow
+- `src/utils.ts` — config loading and setup
+- `src/git.ts` — git operation feedback
+- `src/init.ts` — config initialization
+
+## API Reference
+
+### `p.intro(message)`
+
+Renders a styled banner at the start of each CLI entrypoint.
+
+```ts
+// src/utils.ts
+p.intro(color.bgCyan(color.black(cli_name)));
+
+// src/init.ts
+p.intro(color.bgCyan(color.black(" better-commits-init ")));
+```
+
+### `p.outro(message)`
+
+Renders a closing message at the end of a CLI flow. Only used in `src/init.ts` after writing the config file.
+
+```ts
+p.outro("Run better-commits to start the CLI");
+```
+
+### `p.note(message, title)`
+
+Prints a multi-line boxed panel. Used in `src/index.ts` to display a formatted commit preview before confirmation.
+
+```ts
+p.note(commit_string, "Commit Preview");
+```
+
+### `p.select(options)`
+
+Single-selection list prompt. Used for:
+
+| Location        | Prompt                                    |
+| --------------- | ----------------------------------------- |
+| `src/index.ts`  | "Select a commit type"                    |
+| `src/index.ts`  | "Select a commit scope"                   |
+| `src/branch.ts` | "Checkout a branch or create a worktree?" |
+| `src/branch.ts` | "Select a branch type"                    |
+
+### `p.multiselect(options)`
+
+Multi-selection checkbox prompt. Used for:
+
+| Location       | Prompt                                                                           |
+| -------------- | -------------------------------------------------------------------------------- |
+| `src/index.ts` | "would you like to add them now?" — lists unstaged files                         |
+| `src/index.ts` | "Select optional footers" — closes, trailer, breaking-change, deprecated, custom |
+
+The footers prompt uses `required: false` to make it skippable.
+
+### `p.text(options)`
+
+Free-text input with optional `validate` and `initialValue`. Used across 15+ prompts, including:
+
+| Location        | Prompt                                                             |
+| --------------- | ------------------------------------------------------------------ |
+| `src/index.ts`  | "Write a custom scope"                                             |
+| `src/index.ts`  | "Add ticket / issue" (pre-filled from branch name inference)       |
+| `src/index.ts`  | "Write a brief title describing the commit" (validates `max_size`) |
+| `src/index.ts`  | "Write a detailed description of the changes"                      |
+| `src/index.ts`  | "Breaking changes: Write a short title / summary"                  |
+| `src/index.ts`  | "Breaking Changes: Write a description & migration instructions"   |
+| `src/index.ts`  | "Deprecated: Write a short title / summary"                        |
+| `src/index.ts`  | "Deprecated: Write a description"                                  |
+| `src/index.ts`  | "Write a custom footer"                                            |
+| `src/branch.ts` | "Type your git username"                                           |
+| `src/branch.ts` | "Type ticket / issue number"                                       |
+| `src/branch.ts` | "Type version number"                                              |
+| `src/branch.ts` | "Type a short description" (enforces `max_length`)                 |
+
+### `p.confirm(options)`
+
+Yes/No confirmation prompt. Used once in `src/index.ts`:
+
+```ts
+const confirmed = await p.confirm({ message: "Confirm Commit?" });
+```
+
+Only shown when `config.confirm_commit` is `true`. The boolean result controls whether the git commit executes.
+
+### `p.isCancel(value)`
+
+Checks if the user cancelled a prompt (via `Ctrl+C`). Called immediately after **every** prompt throughout the codebase. On cancel, `process.exit(0)` is called for a graceful exit.
+
+- Called **19 times** in `src/index.ts`
+- Called **7 times** in `src/branch.ts`
+
+Pattern used throughout:
+
+```ts
+const value = await p.text({ message: "..." });
+if (p.isCancel(value)) process.exit(0);
+```
+
+### `p.log.*`
+
+Structured log functions used in place of `console.log` across all files.
+
+| Method               | Color   | Usage                                                                         |
+| -------------------- | ------- | ----------------------------------------------------------------------------- |
+| `p.log.step(msg)`    | neutral | Info messages: "Found global config", "Checking Git Status"                   |
+| `p.log.success(msg)` | green   | "Commit Complete", "Successfully created .better-commits.json"                |
+| `p.log.error(msg)`   | red     | Failed git commands, invalid config, failed staging                           |
+| `p.log.warn(msg)`    | yellow  | Missing git root, cache failures, invalid config paths                        |
+| `p.log.warning(msg)` | yellow  | Alias for `warn`; used once in `src/branch.ts` for duplicate branch detection |
+| `p.log.info(msg)`    | blue    | "Committing changes...", "Exiting without commit", branch creation success    |
+
+## CLI Interaction Flow
+
+Every CLI command follows this structure:
+
+1. `p.intro()` — welcome banner
+2. Series of `p.select` / `p.multiselect` / `p.text` / `p.confirm` prompts, each immediately guarded by `p.isCancel()`
+3. `p.log.*` — structured feedback at each meaningful step (config loading, git operations, errors)
+4. `p.note()` — optional formatted commit preview before final confirmation (`src/index.ts` only)
+5. `p.outro()` — closing message (`src/init.ts` only; main flows end with `p.log.success`)

package/docs/valibot.md

@@ -0,0 +1,228 @@
+# Valibot Usage
+
+`better-commits` uses [`valibot`](https://valibot.dev) (`^0.30.0`) for all runtime schema validation, type inference, and config parsing. Valibot defines the shape of every configuration object, commit state, and branch state in the application.
+
+## Files
+
+| File                    | Role                                                               |
+| ----------------------- | ------------------------------------------------------------------ |
+| `src/valibot-consts.ts` | Shared picklist schemas and constant arrays                        |
+| `src/valibot-state.ts`  | Core schema definitions for `Config`, `CommitState`, `BranchState` |
+| `src/utils.ts`          | Config loading, `parse`, and `ValiError` handling                  |
+| `src/index.ts`          | Parses `CommitState`; uses `Output<>` types                        |
+| `src/branch.ts`         | Parses `BranchState`; uses `Output<>` types                        |
+| `src/init.ts`           | Calls `parse(Config, {})` to generate a default config file        |
+
+## Schema Overview
+
+### `src/valibot-consts.ts` — Picklist Constants
+
+Defines shared enum-like schemas used across the codebase:
+
+```ts
+export const V_BRANCH_ACTIONS = v.picklist(["branch", "worktree"]);
+export const V_FOOTER_OPTIONS = v.picklist([
+  "closes",
+  "trailer",
+  "breaking-change",
+  "deprecated",
+  "custom",
+]);
+export const V_BRANCH_FIELDS = v.picklist([
+  "user",
+  "version",
+  "type",
+  "ticket",
+  "description",
+]);
+export const V_BRANCH_CONFIG_FIELDS = v.picklist([
+  "branch_user",
+  "branch_version",
+  "branch_type",
+  "branch_ticket",
+  "branch_description",
+]);
+```
+
+Constant arrays are typed using `v.Output<>` to derive element types directly from the schemas:
+
+```ts
+export const FOOTER_OPTION_VALUES: v.Output<typeof V_FOOTER_OPTIONS>[] = [...];
+export const BRANCH_ORDER_DEFAULTS: v.Output<typeof V_BRANCH_FIELDS>[] = [...];
+```
+
+---
+
+### `src/valibot-state.ts` — Core Schemas
+
+#### `Config`
+
+The main application config schema. Validates `.better-commits.json`. Parsing an empty object `{}` produces a fully-defaulted config.
+
+Key fields and their validators:
+
+| Field                    | Schema                                                        | Default    |
+| ------------------------ | ------------------------------------------------------------- | ---------- |
+| `check_status`           | `v.optional(v.boolean(), true)`                               | `true`     |
+| `cache_last_value`       | `v.optional(v.boolean(), true)`                               | `true`     |
+| `confirm_with_editor`    | `v.optional(v.boolean(), false)`                              | `false`    |
+| `confirm_commit`         | `v.optional(v.boolean(), true)`                               | `true`     |
+| `print_commit_output`    | `v.optional(v.boolean(), true)`                               | `true`     |
+| `enable_worktrees`       | `v.optional(v.boolean(), true)`                               | `true`     |
+| `branch_pre_commands`    | `v.optional(v.array(v.string()), [])`                         | `[]`       |
+| `branch_post_commands`   | `v.optional(v.array(v.string()), [])`                         | `[]`       |
+| `worktree_pre_commands`  | `v.optional(v.array(v.string()), [])`                         | `[]`       |
+| `worktree_post_commands` | `v.optional(v.array(v.string()), [])`                         | `[]`       |
+| `branch_action_default`  | `v.optional(V_BRANCH_ACTIONS, "branch")`                      | `"branch"` |
+| `branch_order`           | `v.optional(v.array(V_BRANCH_FIELDS), BRANCH_ORDER_DEFAULTS)` | all fields |
+
+**Notable nested validators:**
+
+- `commit_type.options[].emoji` — `v.string([v.emoji()])` validates the value is a real emoji character
+- `commit_type.max_items` / `commit_scope.max_items` — `v.number([v.minValue(1)])` enforces minimum of 1
+- `check_ticket.prepend_hashtag` — `v.picklist(["Never", "Always", "Prompt"])`
+- `check_ticket.surround` — `v.picklist(["", "()", "[]", "{}"])`
+- `check_ticket.title_position` — `v.picklist(["start", "end", "before-colon", "beginning"])`
+- `branch_*.separator` — `v.picklist(["/", "-", "_"])` (branch_description also allows `""`)
+
+**Cross-field validation with `v.custom`:**
+
+Both `commit_type` and `commit_scope` use `v.custom` to ensure `initial_value` exists within their `options` array:
+
+```ts
+v.custom(
+  (val) =>
+    !val.initial_value ||
+    val.options.some((o) => o.value === val.initial_value),
+  (val) =>
+    `Type: initial_value "${val.input.initial_value}" must exist in options`,
+);
+```
+
+**Post-parse transformation with `v.transform`:**
+
+- `commit_type` — when `append_emoji_to_label` is `true`, prepends emoji to each option's label
+- `commit_scope` — when `custom_scope` is `true`, injects `{ label: "custom", value: "custom", hint: "..." }` into options if not already present
+
+---
+
+#### `CommitState`
+
+Models the mutable in-memory state of an in-progress commit. All fields are `v.optional(v.string(), "")`.
+
+| Field              | Purpose                     |
+| ------------------ | --------------------------- |
+| `type`             | Commit type (e.g. `"feat"`) |
+| `scope`            | Commit scope (e.g. `"app"`) |
+| `title`            | Short commit title          |
+| `body`             | Long commit body            |
+| `closes`           | "Closes: " footer token     |
+| `ticket`           | Issue/ticket number         |
+| `breaking_title`   | Breaking change summary     |
+| `breaking_body`    | Breaking change description |
+| `deprecates`       | Deprecation marker          |
+| `deprecates_title` | Deprecation summary         |
+| `deprecates_body`  | Deprecation description     |
+| `custom_footer`    | Custom footer text          |
+| `trailer`          | Git trailer string          |
+
+---
+
+#### `BranchState`
+
+Models the mutable in-memory state for the `better-branch` CLI flow. All fields are `v.optional(v.string(), "")`.
+
+| Field         | Purpose                             |
+| ------------- | ----------------------------------- |
+| `user`        | Git username portion of branch name |
+| `type`        | Branch type (mirrors commit type)   |
+| `ticket`      | Ticket/issue number                 |
+| `description` | Short branch description            |
+| `version`     | Version number                      |
+
+---
+
+## Runtime Usage
+
+### Parsing with defaults
+
+All three state objects are initialized by parsing an empty object, which triggers all `v.optional` defaults:
+
+```ts
+// src/index.ts
+const commit_state = parse(CommitState, {});
+
+// src/branch.ts
+const branch_state = parse(BranchState, {});
+
+// src/init.ts
+const default_config = parse(Config, {});
+```
+
+### Config validation in `src/utils.ts`
+
+`validate_config` wraps `parse(Config, config)` to produce human-friendly errors:
+
+```ts
+function validate_config(config: unknown) {
+  try {
+    return parse(Config, config);
+  } catch (err) {
+    if (err instanceof ValiError) {
+      const path = err.issues[0].path?.map((p) => p.key).join(".");
+      p.log.error(`Invalid config at: ${path}`);
+      process.exit(1);
+    }
+  }
+}
+```
+
+### TypeScript types via `Output<>`
+
+`Output<typeof Schema>` is used throughout as the TypeScript type for parsed objects, avoiding manual interface duplication:
+
+```ts
+// Function signatures
+function build_commit_string(
+  state: Output<typeof CommitState>,
+  config: Output<typeof Config>
+): string { ... }
+
+// Variable types
+const checkout_type: Output<typeof V_BRANCH_ACTIONS> = ...;
+```
+
+---
+
+## Valibot API Summary
+
+| API                           | Purpose                                                                |
+| ----------------------------- | ---------------------------------------------------------------------- |
+| `v.object({...})`             | Defines all three top-level schemas and all nested sub-objects         |
+| `v.optional(schema, default)` | Makes fields optional with a fallback default                          |
+| `v.boolean()`                 | Validates boolean config flags                                         |
+| `v.string()`                  | Validates string fields                                                |
+| `v.number([...])`             | Validates number fields with optional pipe validators                  |
+| `v.array(schema)`             | Validates array fields                                                 |
+| `v.picklist([...])`           | Validates enum-like string fields                                      |
+| `v.minValue(1)`               | Pipe validator: enforces a minimum numeric value                       |
+| `v.emoji()`                   | Pipe validator: ensures a string is a valid emoji character            |
+| `v.custom(fn, msgFn)`         | Cross-field validation with a custom predicate                         |
+| `v.transform(schema, fn)`     | Post-parse transformation of validated data                            |
+| `parse(schema, data)`         | Parses and validates data, applying all defaults and transforms        |
+| `Output<typeof Schema>`       | TypeScript utility to extract the inferred output type                 |
+| `ValiError`                   | Error class caught to produce human-readable validation error messages |
+
+---
+
+## Known Quirk
+
+`src/branch.ts` contains a bare no-op reference to `CommitState` at the bottom of the file:
+
+```ts
+// TODO: No idea what's happening here
+// If you don't use CommitState, (even in unreachable code), parse fails on Config
+CommitState;
+```
+
+This is a workaround for a bundler/tree-shaking issue: without this reference, `parse(Config, ...)` fails at runtime. The root cause is likely that `CommitState` imports something from `valibot-state.ts` that is needed for `Config` to work correctly at runtime, but the bundler eliminates it as dead code without this reference.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "better-commits",
   "private": false,
-  "version": "1.19.0",
+  "version": "1.20.0-cli-flags",
   "description": "A CLI for creating better commits following the conventional commits specification",
   "author": "Erik Verduin (https://github.com/everduin94)",
   "type": "module",
@@ -26,18 +26,20 @@
     "url": "https://github.com/Everduin94/better-commits"
   },
   "dependencies": {
-    "@clack/core": "^0.3.1",
-    "@clack/prompts": "^0.7.0",
+    "@bomb.sh/args": "^0.3.1",
+    "@clack/core": "^1.2.0",
+    "@clack/prompts": "^1.2.0",
     "configstore": "^5.0.1",
     "picocolors": "^1.0.0",
-    "valibot": "^0.30.0"
+    "valibot": "^1.3.1"
   },
   "scripts": {
-    "start": "jiti ./src/index.ts",
-    "branch": "jiti ./src/branch.ts",
-    "init": "jiti ./src/init.ts",
+    "start": "tsx ./src/index.ts",
+    "branch": "tsx ./src/branch.ts",
+    "init": "tsx ./src/init.ts",
     "build": "tsup",
-    "commit": "jiti ./src/index.ts"
+    "commit": "tsx ./src/index.ts",
+    "test": "vitest run"
   },
   "devDependencies": {
     "@semantic-release/git": "^10.0.1",
@@ -49,7 +51,8 @@
     "semantic-release": "^25.0.2",
     "tsup": "^8.0.2",
     "tsx": "^3.12.3",
-    "typescript": "^5.4.5"
+    "typescript": "^5.4.5",
+    "vitest": "^3.2.4"
   },
   "release": {
     "branches": [

package/readme.md

@@ -49,10 +49,14 @@ better-commits # Create a new commit
 better-branch # Create a new branch
 ```
 
-`better-commits` will prompt a series of questions. These prompts will build a commit message, which you can preview, before confirming the commit.
+`better-commits` will prompt a series of questions. These prompts will build a commit message, which you can preview, before confirming the commit. - To better understand these prompts and their intention, read [Conventional Commits Summary](https://www.conventionalcommits.org/en/v1.0.0-beta.4/#summary)
+
 Some of the values in these prompts will be inferred by your branch name and auto populated. You can adjust this in your `.better-commits.json` configuration file.
 
-To better understand these prompts and their intention, read [Conventional Commits Summary](https://www.conventionalcommits.org/en/v1.0.0-beta.4/#summary)
+For documentation on passing commit values to `better-commits` via the CLI, see [CLI Flags](#cli-flags).
+
+> [!TIP]
+> The --no-interactive flag, allows automated workflows or AI agents like OpenCode and Claude Code, to use better-commits to generate consistent commit messages using less tokens.
 
 ## ⚙️ Configuration
 
@@ -438,6 +442,18 @@ You can add this badge to your repository to display that you're using a better-
 | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `[![better commits is enabled](https://img.shields.io/badge/better--commits-enabled?style=for-the-badge&logo=git&color=a6e3a1&logoColor=D9E0EE&labelColor=302D41)](https://github.com/Everduin94/better-commits)` | [![better commits is enabled](https://img.shields.io/badge/better--commits-enabled?style=for-the-badge&logo=git&color=a6e3a1&logoColor=D9E0EE&labelColor=302D41)](https://github.com/Everduin94/better-commits) |
 
+### CLI Flags
+
+Use CLI flags to pass commit values directly instead of answering prompts.
+
+- Use `--no-interactive` to skip prompts, confirmation, and editor flows. This is the recommended mode for OpenCode, Claude Code, and other coding agents.
+- Use `--dry-run` to validate the generated `git commit` command without creating a commit.
+- Supported commit field flags: `--type`, `--scope`, `--title`, `--body`, `--ticket`, `--closes`, `--deprecates`, `--breaking-title`, `--breaking-body`, `--deprecates-title`, `--deprecates-body`, `--custom-footer`, `--trailer`.
+
+```sh
+better-commits --no-interactive --dry-run --type feat --scope cli --title "add parser"
+```
+
 ### Git Arguments
 
 You can pass arguments to `git` through `better-commits` like so:

package/src/args.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest";
+import { parse_runtime_flags } from "./args";
+
+describe("parse_runtime_flags", () => {
+  it("uses interactive mode by default", () => {
+    const parsed = parse_runtime_flags([]);
+
+    expect(parsed.no_interactive).toBe(false);
+    expect(parsed.dry_run).toBe(false);
+    expect(parsed.git_args).toBe("");
+    expect(parsed.commit_state).toEqual({});
+  });
+
+  it("parses --no-interactive and --dry-run", () => {
+    const parsed = parse_runtime_flags(["--no-interactive", "--dry-run"]);
+
+    expect(parsed.no_interactive).toBe(true);
+    expect(parsed.dry_run).toBe(true);
+  });
+
+  it("parses --version and -v", () => {
+    const long_flag = parse_runtime_flags(["--version"]);
+    const short_flag = parse_runtime_flags(["-v"]);
+
+    expect(long_flag.version).toBe(true);
+    expect(short_flag.version).toBe(true);
+  });
+
+  it("maps commit flags into commit_state keys", () => {
+    const parsed = parse_runtime_flags([
+      "--type",
+      "feat",
+      "--title",
+      "ship feature",
+      "--breaking-title",
+      "api changed",
+      "--custom-footer",
+      "Reviewed-by: Jane",
+    ]);
+
+    expect(parsed.commit_state).toEqual({
+      type: "feat",
+      title: "ship feature",
+      breaking_title: "api changed",
+      custom_footer: "Reviewed-by: Jane",
+    });
+  });
+
+  it("builds git args from --git-dir and --work-tree", () => {
+    const parsed = parse_runtime_flags([
+      "--git-dir",
+      "/tmp/repo/.git",
+      "--work-tree",
+      "/tmp/repo",
+    ]);
+
+    expect(parsed.git_args).toBe(
+      "--git-dir=/tmp/repo/.git --work-tree=/tmp/repo",
+    );
+  });
+
+  it("builds git args when only one git location flag is provided", () => {
+    const with_git_dir = parse_runtime_flags(["--git-dir", "/tmp/repo/.git"]);
+    const with_work_tree = parse_runtime_flags(["--work-tree", "/tmp/repo"]);
+
+    expect(with_git_dir.git_args).toBe("--git-dir=/tmp/repo/.git");
+    expect(with_work_tree.git_args).toBe("--work-tree=/tmp/repo");
+  });
+
+  it("maps dashed commit flags to snake_case commit_state keys", () => {
+    const parsed = parse_runtime_flags([
+      "--breaking-body",
+      "major impact",
+      "--deprecates-title",
+      "legacy endpoint",
+      "--deprecates-body",
+      "use v2 endpoint",
+      "--custom-footer",
+      "Reviewed-by: Alex",
+      "--breaking-title",
+      "v1 removed",
+    ]);
+
+    expect(parsed.commit_state).toEqual({
+      breaking_body: "major impact",
+      deprecates_title: "legacy endpoint",
+      deprecates_body: "use v2 endpoint",
+      custom_footer: "Reviewed-by: Alex",
+      breaking_title: "v1 removed",
+    });
+  });
+
+  it("honors interactive flag semantics", () => {
+    const default_flags = parse_runtime_flags([]);
+    const explicit_interactive = parse_runtime_flags(["--interactive"]);
+    const no_interactive = parse_runtime_flags(["--no-interactive"]);
+
+    expect(default_flags.no_interactive).toBe(false);
+    expect(explicit_interactive.no_interactive).toBe(false);
+    expect(no_interactive.no_interactive).toBe(true);
+  });
+});