git-cai-cli 0.14.1__tar.gz → 0.14.2__tar.gz

{git_cai_cli-0.14.1 → git_cai_cli-0.14.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-cai-cli
-Version: 0.14.1
+Version: 0.14.2
 Summary: Use LLM to create git commit messages
 Author-email: Thorsten Foltz <thorsten.foltz@live.com>
 License-Expression: MIT
@@ -274,7 +274,7 @@ In addition to `git cai`, the following options are available:
 - `-C`, `--conventional` – use Conventional Commits format (`type(scope): description`)
 - `-c`, `--crazy` – Trust the LLM and commit without checking
 - `-d`, `--debug` – enable debug logging
-- `-e`, `--temperature` `TEMPERATURE` – override the active provider's sampling temperature for this invocation (provider-scoped, like `-m`)
+- `-E`, `--temperature` `TEMPERATURE` – override the active provider's sampling temperature for this invocation (provider scoped, like `-m`)
 - `-F`, `--full-files` – attach the full contents of affected files alongside the diff (uses `full_files_prompt.md`)
 - `-f`, `--files` `PATH` – limit the diff (and full-file content, if enabled) to PATH; repeat for multiple files
 - `-g`, `--generate-config` – generate the default `cai_config.yml` in the current directory
@@ -297,9 +297,9 @@ In addition to `git cai`, the following options are available:
 - `--base` `BRANCH` – explicit base branch for `--PR` (overrides auto-detection: `origin/HEAD` → `main` → `master`)
 - `-S`, `--set` – set a config value (`key=value`) in repo config (requires existing repo config)
 - `-s`, `--squash` `[N|HASH]` – squash commits on the current branch and summarize them. Without argument: squash all since branch checkout. With a number: squash the last N commits. With a commit hash: squash up to and including that commit
-- `--style` `STYLE` – override the commit message style for this invocation (e.g. `funny`, `neutral`, `none`); validated against the supported styles
-- `--language` `CODE` – override the commit message language for this invocation (e.g. `de`, `fr`, `none`); validated against supported codes
-- `--emoji` / `--no-emoji` – override emoji usage for this invocation (use `--no-emoji` to disable when config enables it)
+- `-y`, `--style` `STYLE` – override the commit message style for this invocation (e.g. `funny`, `neutral`, `none`); validated against the supported styles
+- `-L`, `--language` `CODE` – override the commit message language for this invocation (e.g. `de`, `fr`, `none`); validated against supported codes
+- `-e`, `--emoji` / `--no-emoji` – override emoji usage for this invocation (use `--no-emoji` to disable when config enables it)
 - `-T`, `--timeout` `SECONDS` – HTTP timeout for this invocation (overrides config)
 - `-t`, `--time` – measure and log commit message generation time
 - `-u`, `--update` – check for updates

{git_cai_cli-0.14.1 → git_cai_cli-0.14.2}/README.md

@@ -244,7 +244,7 @@ In addition to `git cai`, the following options are available:
 - `-C`, `--conventional` – use Conventional Commits format (`type(scope): description`)
 - `-c`, `--crazy` – Trust the LLM and commit without checking
 - `-d`, `--debug` – enable debug logging
-- `-e`, `--temperature` `TEMPERATURE` – override the active provider's sampling temperature for this invocation (provider-scoped, like `-m`)
+- `-E`, `--temperature` `TEMPERATURE` – override the active provider's sampling temperature for this invocation (provider scoped, like `-m`)
 - `-F`, `--full-files` – attach the full contents of affected files alongside the diff (uses `full_files_prompt.md`)
 - `-f`, `--files` `PATH` – limit the diff (and full-file content, if enabled) to PATH; repeat for multiple files
 - `-g`, `--generate-config` – generate the default `cai_config.yml` in the current directory
@@ -267,9 +267,9 @@ In addition to `git cai`, the following options are available:
 - `--base` `BRANCH` – explicit base branch for `--PR` (overrides auto-detection: `origin/HEAD` → `main` → `master`)
 - `-S`, `--set` – set a config value (`key=value`) in repo config (requires existing repo config)
 - `-s`, `--squash` `[N|HASH]` – squash commits on the current branch and summarize them. Without argument: squash all since branch checkout. With a number: squash the last N commits. With a commit hash: squash up to and including that commit
-- `--style` `STYLE` – override the commit message style for this invocation (e.g. `funny`, `neutral`, `none`); validated against the supported styles
-- `--language` `CODE` – override the commit message language for this invocation (e.g. `de`, `fr`, `none`); validated against supported codes
-- `--emoji` / `--no-emoji` – override emoji usage for this invocation (use `--no-emoji` to disable when config enables it)
+- `-y`, `--style` `STYLE` – override the commit message style for this invocation (e.g. `funny`, `neutral`, `none`); validated against the supported styles
+- `-L`, `--language` `CODE` – override the commit message language for this invocation (e.g. `de`, `fr`, `none`); validated against supported codes
+- `-e`, `--emoji` / `--no-emoji` – override emoji usage for this invocation (use `--no-emoji` to disable when config enables it)
 - `-T`, `--timeout` `SECONDS` – HTTP timeout for this invocation (overrides config)
 - `-t`, `--time` – measure and log commit message generation time
 - `-u`, `--update` – check for updates

{git_cai_cli-0.14.1 → git_cai_cli-0.14.2}/docs/man/git-cai.1

@@ -2,12 +2,12 @@
 .\"     Title: git-cai
 .\"    Author: Thorsten Foltz
 .\" Generator: Asciidoctor 2.0.26
-.\"      Date: 2026-06-04
+.\"      Date: 2026-06-14
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "GIT\-CAI" "1" "2026-06-04" "\ \&" "\ \&"
+.TH "GIT\-CAI" "1" "2026-06-14" "\ \&" "\ \&"
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .ss \n[.ss] 0

git_cai_cli-0.14.2/docs/superpowers/specs/2026-06-14-custom-styles-design.md

@@ -0,0 +1,203 @@
+# Custom styles + richer built-in style guidance — Design
+
+**Date:** 2026-06-14
+**Branch:** `fix/style-option`
+**Status:** Approved
+
+## Goal
+
+Extend the commit-message `style` option in two ways:
+
+- **A — User-defined custom styles:** let users define their own styles in
+  `cai_config.yml` via a `custom_styles` map, so individuals and teams can add
+  tones beyond the shipped set without code changes.
+- **C — Richer built-in style guidance:** replace the single generic style
+  instruction with a per-style prompt fragment, so each style (built-in or
+  custom) contributes real tone guidance to the prompt.
+- **E — Single registry (cleanup):** consolidate the built-in style data, which
+  today is split between the allowlist in `validate.py` and the
+  descriptions/examples in `options.py::styles()`, into one source of truth.
+- **F — Override flag ergonomics:** give the invocation-override options short
+  flags and make them visible in `git cai -h`. Today `--style`, `--language`,
+  `--emoji`, and `--temperature` are long-only **and** absent from the
+  hand-maintained help text (`cli/helptext.py`).
+
+## Background (current behaviour)
+
+- `_validate_style()` (`core/validate.py`) checks a hardcoded allowlist:
+  `professional, neutral, friendly, funny, excited, sarcastic, apologetic,
+  academic`, plus `none` (disables the style instruction).
+- `_style_instruction()` (`core/llm.py`) emits one generic line for every
+  style: *"Write the commit message in the following tone style: {style}.
+  Apply this tone to both the headline and the bullet points."*
+- `options.py::styles()` holds per-style `description` and `example` used by
+  `git cai -l style`, hand-synced with the allowlist.
+
+## Decisions
+
+1. **Custom style entry shape (Option 3 — hybrid):** `instruction` is required;
+   `description` and `example` are optional.
+2. **Built-in names are protected (Option 2):** a `custom_styles` key that
+   collides with a built-in name or with `none` is a config validation error.
+3. **Prompt assembly (Option 3):** the style's `instruction` leads, followed by
+   a fixed suffix: `"{instruction} Apply this tone to both the headline and the
+   bullet points."`
+4. **Listing (Option 1 — merged + marker):** `git cai -l style` shows built-in
+   and custom styles in one list; custom entries are tagged `name (custom)`.
+5. **Override short flags (F):** the invocation-override options get short flags
+   and are added to the help text — `-y/--style`, `-e/--emoji`, `-L/--language`,
+   `-E/--temperature`. `--temperature` previously used `-e`; it moves to `-E` so
+   `--emoji` can take the mnemonic `-e`. `-L` and `-E` each differ from an
+   existing flag (`-l/--list`, `-e`) only by case, which Typer/Click handle.
+
+## Components
+
+### 1. `core/styles.py` (new — single registry)
+
+Dependency-free module (same rationale as `prompts_fallback.py`: importable by
+`config`, `validate`, `llm`, `options` without creating import cycles). Single
+source of truth for built-in styles, each carrying all three fields:
+
+```python
+BUILTIN_STYLES: dict[str, dict[str, str]] = {
+    "professional": {
+        "instruction": "Write in a clear, concise, and formal tone.",
+        "description": "Clear, concise, and formal. Default style.",
+        "example": "...",
+    },
+    # neutral, friendly, funny, excited, sarcastic, apologetic, academic
+}
+
+RESERVED_STYLE_NAMES = set(BUILTIN_STYLES) | {"none"}
+```
+
+Replaces the allowlist in `validate.py` and the inline descriptions/examples in
+`options.py::styles()`.
+
+### 2. Config — `custom_styles` key
+
+- New top-level key in `DEFAULT_CONFIG`, default `{}`; documented in
+  `cai_config.yml`.
+- Repo config remains authoritative (per `CLAUDE.md`), so a repo can ship a
+  house style set.
+- Entry shape: `instruction` required; `description`, `example` optional.
+
+Example:
+
+```yaml
+custom_styles:
+  sardonic:
+    instruction: "Use dry, ironic understatement; keep the subject imperative."
+    description: "Dry, ironic tone."   # optional
+    example: "Heroically fixed the bug we wrote yesterday."  # optional
+```
+
+### 3. Validation (`core/validate.py`)
+
+- **`_validate_custom_styles(custom_styles)`** (new): for each entry —
+  - key is a non-empty string and **not** in `RESERVED_STYLE_NAMES`
+    (collision → `ValueError`);
+  - value has a non-empty `instruction`;
+  - `description` / `example`, if present, are strings.
+  Called during config load; fails fast with a message naming the offending key
+  and the problem.
+- **`_validate_style(style, custom_names)`**: signature gains the set of
+  configured custom style names. Accepts built-ins, `none`, or any custom name;
+  otherwise raises with the merged allowed list. Call sites in `config.py`
+  (default load and `--style` override) already have `custom_styles` available
+  and pass the names through.
+
+### 4. Prompt assembly (`core/llm.py::_style_instruction`)
+
+Look up the active style in `BUILTIN_STYLES` merged with config `custom_styles`,
+then:
+
+```python
+return f"{entry['instruction']} Apply this tone to both the headline and the bullet points."
+```
+
+`none` / `None` → `""` (unchanged). The old generic hardcoded line is removed;
+every style now contributes its own flavor plus the fixed suffix.
+
+### 5. Listing (`core/options.py::styles`)
+
+Build the returned dict from `BUILTIN_STYLES` + config `custom_styles`. Custom
+entries are tagged `name (custom)`. When `description` is absent, fall back to
+the `instruction` text; when `example` is absent, omit the example line.
+
+### 6. CLI short flags + help visibility (`cli/cli.py`, `cli/helptext.py`)
+
+- Update the override `typer.Option` definitions in `cli.py`:
+  - `--style` → add `"-y"`
+  - `--emoji` → add `"-e"`
+  - `--language` → add `"-L"`
+  - `--temperature` → change its existing `"-e"` to `"-E"` (freeing `-e` for
+    emoji)
+- Add the four flags to the hand-maintained `HELP_TEXT` in `helptext.py`, in
+  the alphabetical position used by the existing list, e.g.:
+
+  ```text
+  -E, --temperature FLOAT  Override the active provider's sampling temperature for this invocation
+  -e, --emoji              Toggle emoji prefixes (use --no-emoji to disable)
+  -L, --language CODE      Override the commit message language (e.g. de, fr, none)
+  -y, --style NAME         Override the commit message style (e.g. funny, neutral, none)
+  ```
+
+  The `-l, --list` line already documents `style` as a list type and stays as
+  is.
+
+## Data flow
+
+```text
+cai_config.yml (custom_styles)
+        │
+        ▼
+config load ──► _validate_custom_styles()         (structure + collisions)
+        │
+        ├──► _validate_style(style, custom_names)  (default + --style override)
+        │
+        ▼
+config["style"], config["custom_styles"]
+        │
+        ├──► llm._style_instruction()  → "{instruction} <suffix>"  (BUILTIN_STYLES ∪ custom)
+        │
+        └──► options.styles()          → merged list with (custom) markers
+```
+
+## Error handling
+
+An invalid `custom_styles` block fails fast at config load with a clear message
+(which key, what is wrong), consistent with how `_validate_style` already
+reports invalid styles. An unknown `--style` value raises with the merged
+allowed list (built-ins + `none` + configured custom names).
+
+## Testing
+
+All mocked — no real API/HTTP calls (CI has no creds; tokens cost money):
+
+- `_validate_custom_styles`: happy path; missing/empty `instruction`;
+  collision with a built-in name; collision with `none`; non-string optional
+  fields.
+- `_validate_style`: accepts a configured custom name; rejects an unknown name
+  with the merged allowed list in the message.
+- `_style_instruction`: builds `"{instruction} <suffix>"` for a built-in, for a
+  custom style, and returns `""` for `none` / `None`.
+- `options.styles()`: merges built-ins + custom; applies `(custom)` marker;
+  falls back `description → instruction`; omits `example` when absent.
+- CLI short flags: invoking with `-y`, `-e`, `-L`, `-E` is parsed equivalently
+  to the long form (via Typer's `CliRunner`, no network), and `git cai -h`
+  output contains all four override flags.
+
+## Documentation
+
+Update **`docs/git-cai.txt` only** (per standing preference — do not touch
+`docs/man/git-cai.1`, `README.md`, or `CLAUDE.md` unless asked): document the
+`custom_styles` key and entry shape, and the new `-y/-e/-L/-E` override short
+flags.
+
+## Out of scope (YAGNI)
+
+- Overriding/retuning built-in styles via config (built-ins are protected).
+- Free-form passthrough of arbitrary style strings (rejected in favor of an
+  explicit custom registry).
+- `random`/surprise style selection.

{git_cai_cli-0.14.1 → git_cai_cli-0.14.2}/src/git_cai_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.14.1'
-__version_tuple__ = version_tuple = (0, 14, 1)
+__version__ = version = '0.14.2'
+__version_tuple__ = version_tuple = (0, 14, 2)
 
-__commit_id__ = commit_id = 'gbd1b6f7b7'
+__commit_id__ = commit_id = 'gf575cff14'

{git_cai_cli-0.14.1 → git_cai_cli-0.14.2}/src/git_cai_cli/cli/cli.py

@@ -181,22 +181,25 @@ def callback(  # pylint: disable=too-many-arguments,too-many-positional-argument
     ),
     temperature: float = typer.Option(
         None,
-        "-e",
+        "-E",
         "--temperature",
         help="Override the active provider's sampling temperature for this invocation.",
     ),
     style: str = typer.Option(
         None,
+        "-y",
         "--style",
         help="Override the commit message style for this invocation (e.g. funny, neutral, none).",
     ),
     language: str = typer.Option(
         None,
+        "-L",
         "--language",
         help="Override the commit message language code for this invocation (e.g. de, fr, none).",
     ),
     emoji: bool | None = typer.Option(
         None,
+        "-e",
         "--emoji/--no-emoji",
         help="Override emoji usage for this invocation. Use --no-emoji to disable when config enables it.",
     ),

{git_cai_cli-0.14.1 → git_cai_cli-0.14.2}/src/git_cai_cli/cli/helptext.py

@@ -21,6 +21,8 @@ Flags:
   -C, --conventional       Use Conventional Commits format (type(scope): description)
   -c, --crazy              Commit immediately without opening editor (trust LLM output)
   -d, --debug              Enable debug logging
+  -E, --temperature FLOAT  Override the active provider's sampling temperature for this invocation
+  -e, --emoji              Toggle emoji prefixes (use --no-emoji to disable)
   -F, --full-files         Send the full contents of affected files alongside the diff
   -f, --files PATH         Limit the diff (and full files) to PATH; repeat the flag for multiple files
   -g, --generate-config    Generate default cai_config.yml in the current directory
@@ -28,6 +30,7 @@ Flags:
   -h, --help               Show this help message or opens manual
   -I, --init               Interactive setup wizard (writes home config and tokens.yml)
   -i, --install-completion Install shell completion for git-cai
+  -L, --language CODE      Override the commit message language (e.g. de, fr, none)
   -l, --list [TYPE]        List information. TYPE: config, editor, language,
                            model, path, provider, style
   -m, --model NAME         Override model for this invocation (requires --provider)
@@ -48,6 +51,7 @@ Flags:
   -u, --update             Check for updates
   -v, --version            Show installed version
   -x, --context TEXT       Provide extra context for the LLM (e.g. ticket number, reason)
+  -y, --style NAME         Override the commit message style (e.g. funny, neutral, none)
   -z, --stats              Show local-only usage analytics (commits, tokens, latency)
       --since YYYY-MM-DD   Filter --stats to events on or after this date
       --json               Render --stats output as JSON instead of text

{git_cai_cli-0.14.1 → git_cai_cli-0.14.2}/src/git_cai_cli/core/prompts_fallback.py

@@ -7,7 +7,7 @@ Both modules can safely import from here without creating import cycles.
 
 HARDCODED_COMMIT_PROMPT = (
     "You are an expert software engineer assistant.\n"
-    "Your task is to generate a concise, professional git commit message\n"
+    "Your task is to generate a concise git commit message\n"
     "from the provided git diff.\n"
     "\n"
     "Follow the seven rules of a great git commit message:\n"
@@ -44,7 +44,7 @@ HARDCODED_COMMIT_PROMPT = (
 
 HARDCODED_FULL_FILES_PROMPT = (
     "You are an expert software engineer assistant.\n"
-    "Your task is to generate a concise, professional git commit message\n"
+    "Your task is to generate a concise git commit message\n"
     "from the provided git diff AND the full contents of the affected files.\n"
     "\n"
     "The input is structured as follows:\n"

{git_cai_cli-0.14.1 → git_cai_cli-0.14.2}/src/git_cai_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-cai-cli
-Version: 0.14.1
+Version: 0.14.2
 Summary: Use LLM to create git commit messages
 Author-email: Thorsten Foltz <thorsten.foltz@live.com>
 License-Expression: MIT
@@ -274,7 +274,7 @@ In addition to `git cai`, the following options are available:
 - `-C`, `--conventional` – use Conventional Commits format (`type(scope): description`)
 - `-c`, `--crazy` – Trust the LLM and commit without checking
 - `-d`, `--debug` – enable debug logging
-- `-e`, `--temperature` `TEMPERATURE` – override the active provider's sampling temperature for this invocation (provider-scoped, like `-m`)
+- `-E`, `--temperature` `TEMPERATURE` – override the active provider's sampling temperature for this invocation (provider scoped, like `-m`)
 - `-F`, `--full-files` – attach the full contents of affected files alongside the diff (uses `full_files_prompt.md`)
 - `-f`, `--files` `PATH` – limit the diff (and full-file content, if enabled) to PATH; repeat for multiple files
 - `-g`, `--generate-config` – generate the default `cai_config.yml` in the current directory
@@ -297,9 +297,9 @@ In addition to `git cai`, the following options are available:
 - `--base` `BRANCH` – explicit base branch for `--PR` (overrides auto-detection: `origin/HEAD` → `main` → `master`)
 - `-S`, `--set` – set a config value (`key=value`) in repo config (requires existing repo config)
 - `-s`, `--squash` `[N|HASH]` – squash commits on the current branch and summarize them. Without argument: squash all since branch checkout. With a number: squash the last N commits. With a commit hash: squash up to and including that commit
-- `--style` `STYLE` – override the commit message style for this invocation (e.g. `funny`, `neutral`, `none`); validated against the supported styles
-- `--language` `CODE` – override the commit message language for this invocation (e.g. `de`, `fr`, `none`); validated against supported codes
-- `--emoji` / `--no-emoji` – override emoji usage for this invocation (use `--no-emoji` to disable when config enables it)
+- `-y`, `--style` `STYLE` – override the commit message style for this invocation (e.g. `funny`, `neutral`, `none`); validated against the supported styles
+- `-L`, `--language` `CODE` – override the commit message language for this invocation (e.g. `de`, `fr`, `none`); validated against supported codes
+- `-e`, `--emoji` / `--no-emoji` – override emoji usage for this invocation (use `--no-emoji` to disable when config enables it)
 - `-T`, `--timeout` `SECONDS` – HTTP timeout for this invocation (overrides config)
 - `-t`, `--time` – measure and log commit message generation time
 - `-u`, `--update` – check for updates

{git_cai_cli-0.14.1 → git_cai_cli-0.14.2}/src/git_cai_cli.egg-info/SOURCES.txt

@@ -34,6 +34,7 @@ uv.lock
 .linters/pyrightconfig.json
 docs/git-cai.txt
 docs/man/git-cai.1
+docs/superpowers/specs/2026-06-14-custom-styles-design.md
 src/git_cai_cli/__init__.py
 src/git_cai_cli/_version.py
 src/git_cai_cli/main.py

{git_cai_cli-0.14.1 → git_cai_cli-0.14.2}/tests/unit/test_prompt_loading.py

@@ -2,6 +2,7 @@
 Unit tests for prompt loading, custom prompt files, and 'none' config values.
 """
 
+from pathlib import Path
 from unittest.mock import patch
 
 import pytest
@@ -218,6 +219,30 @@ class TestLoadPromptFileHardcoded:
 
         assert result == HARDCODED_SQUASH_PROMPT
 
+    def test_hardcoded_commit_prompt_is_tone_neutral(self):
+        """
+        The hardcoded base prompts must not bake in a tone word, so the style
+        instruction is the single source of tone (and an override wins cleanly).
+        """
+        assert "professional" not in HARDCODED_COMMIT_PROMPT
+        assert "professional" not in HARDCODED_FULL_FILES_PROMPT
+
+    def test_style_override_is_authoritative_in_fallback(self, base_config):
+        """
+        With the hardcoded fallback (no config files) and style overridden to
+        'funny', the built prompt carries only the chosen style — not the old
+        hardcoded 'professional' tone.
+        """
+        base_config["style"] = "funny"
+        gen = CommitMessageGenerator("tok", base_config, "openai")
+
+        empty_dir = Path("/nonexistent-cai-config-dir")
+        with patch("git_cai_cli.core.llm.CONFIG_DIR", empty_dir):
+            prompt = gen._build_commit_prompt()
+
+        assert "funny" in prompt
+        assert "professional" not in prompt
+
 
 # ---------------------------------------------------------------------------
 # load_prompt_file: logging