commitstash 0.3.0__tar.gz → 0.4.0__tar.gz

{commitstash-0.3.0 → commitstash-0.4.0}/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## v0.4.0 (2026-07-19)
+
+### Features
+
+- **onboarding:** add first-run setup flow
+
+### Chores
+
+- add author metadata to pyproject
+
 ## v0.3.0 (2026-07-18)
 
 ### Features

{commitstash-0.3.0 → commitstash-0.4.0}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.4
 Name: commitstash
-Version: 0.3.0
+Version: 0.4.0
 Summary: AI-powered git commit message generator — reads your staged diff, writes the commit for you
 Project-URL: Homepage, https://github.com/suryaSPS/autocommit
 Project-URL: Issues, https://github.com/suryaSPS/autocommit/issues
+Author-email: Surya Pratap Singh <suryasps20@gmail.com>
 License: MIT
 License-File: LICENSE
 Keywords: ai,cli,commit,developer-tools,git

commitstash-0.4.0/autocommit/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"

{commitstash-0.3.0 → commitstash-0.4.0}/autocommit/cli.py

@@ -6,7 +6,7 @@ from rich.panel import Panel
 from rich.text import Text
 
 from .changelog import build_changelog
-from .config import load_config, save_config
+from .config import CONFIG_PATH, load_config, save_config
 from .explain import explain as _explain
 from .git import (
     get_branch_commits,
@@ -26,6 +26,7 @@ from .git import (
     unstage_all,
 )
 from .llm import generate
+from .onboarding import is_first_run, run_onboarding
 from .pr import write_pr
 from .review import offline_review
 from .review import review as _review
@@ -185,6 +186,17 @@ def cli(ctx, style, emoji, body, provider, no_ai, stage_all_files, yes):
 
     config = load_config()
 
+    # First-run onboarding: only when interactive and the user hasn't already
+    # said what they want. Never in the git hook (--yes) or a non-TTY pipe.
+    if (
+        is_first_run(CONFIG_PATH)
+        and sys.stdin.isatty()
+        and not yes
+        and not provider
+        and not no_ai
+    ):
+        config = run_onboarding(console, config)
+
     # CLI flag overrides
     if style:
         config["style"] = style

commitstash-0.4.0/autocommit/onboarding.py

@@ -0,0 +1,139 @@
+"""First-run onboarding.
+
+Triggers the first time someone runs `autocommit` with no saved config.
+Walks them through picking a provider and getting a key in place.
+
+Security: this flow NEVER writes an API key to disk. A key entered here is
+used for the current process only (set in os.environ); to persist it we
+print the exact shell command for the user to add themselves. This mirrors
+the guarantee load_config/save_config already make.
+"""
+
+import os
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+
+from .config import save_config
+
+# provider -> (env var name, sample key prefix)
+PROVIDER_ENV = {
+    "anthropic": ("ANTHROPIC_API_KEY", "sk-ant-..."),
+    "openai": ("OPENAI_API_KEY", "sk-..."),
+}
+
+PROVIDER_CHOICES = ["anthropic", "openai", "ollama", "local"]
+
+PROVIDER_BLURB = {
+    "anthropic": "Anthropic Claude — best quality (needs an API key)",
+    "openai": "OpenAI GPT — needs an API key",
+    "ollama": "Ollama — a local model on your machine, free, no key",
+    "local": "Offline heuristic — no AI, no key, works anywhere",
+}
+
+
+def is_first_run(config_path) -> bool:
+    """True when no config file exists yet."""
+    return not config_path.exists()
+
+
+def _shell_rc_hint(env_name: str) -> str:
+    shell = os.environ.get("SHELL", "")
+    if shell.endswith("zsh"):
+        return "~/.zshrc"
+    if shell.endswith("bash"):
+        return "~/.bashrc"
+    return "your shell profile"
+
+
+def _setup_key(console: Console, provider: str) -> bool:
+    """Ensure a usable key for provider. Returns True if AI is ready this run."""
+    env_name, sample = PROVIDER_ENV[provider]
+
+    if os.getenv(env_name):
+        console.print(f"[green]✓ {env_name} is already set in your environment.[/green]")
+        return True
+
+    console.print(f"\n[bold]{provider.title()} needs an API key[/bold] ([dim]{env_name}[/dim]).")
+    key = click.prompt(
+        f"  Paste your key ({sample}), or press Enter to skip for now",
+        hide_input=True,
+        default="",
+        show_default=False,
+    ).strip()
+
+    if not key:
+        console.print("[yellow]Skipped.[/yellow] You can set it later:")
+        console.print(f"  [dim]export {env_name}={sample}[/dim]")
+        return False
+
+    # Session-only: used by this process, never persisted by us.
+    os.environ[env_name] = key
+    rc = _shell_rc_hint(env_name)
+    console.print("[green]✓ Key accepted for this session.[/green]  [dim](not written to disk)[/dim]")
+    console.print(f"[dim]To keep it for next time, add this line to {rc}:[/dim]")
+    console.print(f"  [dim]export {env_name}=<the key you just entered>[/dim]")
+    return True
+
+
+def _setup_ollama(console: Console, config: dict) -> None:
+    model = click.prompt("  Ollama model", default=config.get("ollama_model", "llama3.2"))
+    config["ollama_model"] = model
+    console.print("[dim]Make sure Ollama is running before you commit:[/dim]")
+    console.print("  [dim]ollama serve[/dim]")
+    console.print(f"  [dim]ollama pull {model}[/dim]")
+
+
+def run_onboarding(console: Console, config: dict) -> dict:
+    """Interactive first-run setup. Returns the config to use for this run.
+
+    Persists non-secret preferences (creating the config file, so this won't
+    trigger again). If the chosen AI provider has no key available, falls back
+    to offline mode for THIS run only so the first commit still succeeds — the
+    chosen provider is still saved for next time.
+    """
+    console.print(
+        Panel(
+            "Welcome to [bold]autocommit[/bold] 👋\n\n"
+            "Let's set up how your commit messages get generated.\n"
+            "[dim]Takes about 20 seconds. Change anything later with "
+            "[bold]autocommit configure[/bold].[/dim]",
+            title="[bold]First-time setup[/bold]",
+            border_style="cyan",
+        )
+    )
+
+    console.print("\n[bold]Providers[/bold]")
+    for name in PROVIDER_CHOICES:
+        console.print(f"  [cyan]{name}[/cyan] — {PROVIDER_BLURB[name]}")
+    console.print()
+
+    provider = click.prompt(
+        "Which provider?",
+        type=click.Choice(PROVIDER_CHOICES),
+        default="anthropic",
+    )
+    config["provider"] = provider
+
+    ready = True
+    if provider in PROVIDER_ENV:
+        ready = _setup_key(console, provider)
+    elif provider == "ollama":
+        _setup_ollama(console, config)
+    else:  # local
+        console.print("[green]✓ Offline mode — no key needed.[/green]")
+
+    path = save_config(config)
+    console.print(f"\n[green]✓ Setup saved to {path}[/green]")
+
+    run_config = dict(config)
+    if provider in PROVIDER_ENV and not ready:
+        console.print(
+            "\n[yellow]No key yet — using offline mode for this commit.[/yellow] "
+            f"[dim]Next time, with {PROVIDER_ENV[provider][0]} set, it'll use {provider}.[/dim]"
+        )
+        run_config["provider"] = "local"
+
+    console.print()
+    return run_config

{commitstash-0.3.0 → commitstash-0.4.0}/pyproject.toml

@@ -4,11 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "commitstash"
-version = "0.3.0"
+version = "0.4.0"
 description = "AI-powered git commit message generator — reads your staged diff, writes the commit for you"
 readme = "README.md"
 requires-python = ">=3.9"
 license = { text = "MIT" }
+authors = [{ name = "Surya Pratap Singh", email = "suryasps20@gmail.com" }]
 keywords = ["git", "ai", "commit", "cli", "developer-tools"]
 classifiers = [
     "Development Status :: 4 - Beta",

commitstash-0.4.0/tests/test_onboarding.py

@@ -0,0 +1,53 @@
+from rich.console import Console
+
+from autocommit import onboarding
+
+
+def test_is_first_run(tmp_path):
+    cfg = tmp_path / "config.json"
+    assert onboarding.is_first_run(cfg) is True
+    cfg.write_text("{}")
+    assert onboarding.is_first_run(cfg) is False
+
+
+def _patch_config_path(monkeypatch, tmp_path):
+    """Point save_config at a temp file so tests never touch the real ~/.autocommit."""
+    monkeypatch.setattr("autocommit.config.CONFIG_PATH", tmp_path / "config.json")
+
+
+def test_onboarding_local_provider(monkeypatch, tmp_path):
+    _patch_config_path(monkeypatch, tmp_path)
+    monkeypatch.setattr("click.prompt", lambda *a, **k: "local")
+
+    run_config = onboarding.run_onboarding(Console(), {})
+    assert run_config["provider"] == "local"
+    assert (tmp_path / "config.json").exists()
+
+
+def test_onboarding_key_used_for_session_not_persisted(monkeypatch, tmp_path):
+    _patch_config_path(monkeypatch, tmp_path)
+    monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
+    answers = iter(["anthropic", "sk-ant-secret"])
+    monkeypatch.setattr("click.prompt", lambda *a, **k: next(answers))
+
+    run_config = onboarding.run_onboarding(Console(), {})
+
+    assert run_config["provider"] == "anthropic"  # real choice kept
+    assert onboarding.os.environ["ANTHROPIC_API_KEY"] == "sk-ant-secret"  # session only
+    saved = (tmp_path / "config.json").read_text()
+    assert "sk-ant-secret" not in saved  # never written to disk
+
+
+def test_onboarding_no_key_falls_back_to_local_this_run(monkeypatch, tmp_path):
+    _patch_config_path(monkeypatch, tmp_path)
+    monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
+    answers = iter(["anthropic", ""])  # choose anthropic, skip the key
+    monkeypatch.setattr("click.prompt", lambda *a, **k: next(answers))
+
+    run_config = onboarding.run_onboarding(Console(), {})
+
+    assert run_config["provider"] == "local"  # this run falls back
+    import json
+
+    saved = json.loads((tmp_path / "config.json").read_text())
+    assert saved["provider"] == "anthropic"  # but the choice is remembered

commitstash-0.3.0/autocommit/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.3.0"