goodvibes-cli 1.6.1__py3-none-any.whl

goodvibes_cli/__init__.py

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

goodvibes_cli/__main__.py

@@ -0,0 +1,15 @@
+import sys
+
+if sys.version_info < (3, 10):
+    print(
+        f"goodvibes requires Python 3.10 or higher. "
+        f"You have Python {sys.version_info.major}.{sys.version_info.minor}.",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+import typer  # noqa: E402 — version guard must run before any import
+from goodvibes_cli.main import app  # noqa: E402
+
+if __name__ == "__main__":
+    app()

goodvibes_cli/commands/doctor_cmd.py

@@ -0,0 +1,110 @@
+"""goodvibes doctor command — checks that goodvibes setup is complete."""
+from __future__ import annotations
+
+import importlib.metadata
+import pathlib
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+# ponytail: not imported from sentinel_merge — define locally to avoid coupling
+SENTINEL_START = "<!-- goodvibes:start -->"
+SENTINEL_END = "<!-- goodvibes:end -->"
+
+console = Console()
+
+
+def _installed_version() -> str:
+    try:
+        return importlib.metadata.version("goodvibes-cli")
+    except importlib.metadata.PackageNotFoundError:
+        return "unknown"
+
+
+@dataclass
+class CheckResult:
+    label: str
+    passed: bool
+    remedy: str = field(default="")
+
+
+def _check_headroom() -> CheckResult:
+    present = shutil.which("headroom") is not None
+    return CheckResult(
+        label="headroom on PATH",
+        passed=present,
+        remedy="" if present else 'Run: uv tool install "headroom-ai[all]"  (or re-run goodvibes init)',
+    )
+
+
+def _check_git_config(key: str) -> CheckResult:
+    try:
+        result = subprocess.run(
+            ["git", "config", key],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        passed = bool(result.stdout.strip())
+        return CheckResult(
+            label=f"git {key}",
+            passed=passed,
+            remedy="" if passed else f'Run: git config --global {key} "Your Value"',
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return CheckResult(
+            label=f"git {key}",
+            passed=False,
+            remedy=f'Run: git config --global {key} "Your Value"',
+        )
+
+
+def _check_claude_md(cwd: pathlib.Path) -> CheckResult:
+    present = (cwd / "CLAUDE.md").exists()
+    return CheckResult(
+        label="CLAUDE.md present",
+        passed=present,
+        remedy="" if present else "Run: goodvibes init",
+    )
+
+
+def _check_sentinel(cwd: pathlib.Path) -> CheckResult:
+    path = cwd / "CLAUDE.md"
+    if not path.exists():
+        return CheckResult(label="goodvibes sentinel block", passed=False, remedy="Run: goodvibes init")
+    content = path.read_text(encoding="utf-8")
+    ok = SENTINEL_START in content and SENTINEL_END in content
+    return CheckResult(
+        label="goodvibes sentinel block",
+        passed=ok,
+        remedy="" if ok else "Run: goodvibes init (will merge sentinel block)",
+    )
+
+
+def doctor_cmd() -> None:
+    """Check that goodvibes setup is complete."""
+    cwd = pathlib.Path.cwd()
+
+    results = [
+        _check_headroom(),
+        _check_git_config("user.name"),
+        _check_git_config("user.email"),
+        _check_claude_md(cwd),
+        _check_sentinel(cwd),
+    ]
+
+    version = _installed_version()
+    lines = [f"goodvibes v{version}"] + [f"{'✓' if r.passed else '✗'} {r.label}" for r in results]
+    console.print(Panel("\n".join(lines), title="goodvibes doctor"))
+
+    failures = [r for r in results if not r.passed]
+    if failures:
+        remediation = "\n".join(r.remedy for r in failures if r.remedy)
+        console.print(Panel(remediation, title="How to fix"))
+        raise typer.Exit(1)
+
+    console.rule("[green]All checks passed.[/green]")

goodvibes_cli/commands/init_cmd.py

@@ -0,0 +1,102 @@
+"""goodvibes init command — port of init.ts."""
+import pathlib
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from goodvibes_cli.steps.configure_mcp import configure_mcp
+from goodvibes_cli.steps.copy_templates import copy_templates, list_template_files, resolve_templates_dir
+from goodvibes_cli.steps.install_headroom import install_headroom
+from goodvibes_cli.utils.detect_project_type import detect_project_type
+
+console = Console()
+
+_NEXT_STEPS = (
+    "1. Open this project in your AI coding tool\n"
+    "2. Claude Code users: /plugin marketplace add DietrichGebert/ponytail\n"
+    "   Other IDEs (Cursor, Windsurf, Kiro, Antigravity, etc.): rules already active\n"
+    "3. Start coding — CLAUDE.md rules are already active"
+)
+
+
+def init_cmd(
+    dry_run: Annotated[bool, typer.Option("--dry-run", help="Preview files without writing")] = False,
+    minimal: Annotated[bool, typer.Option("--minimal", help="Skip headroom install and CI workflows")] = False,
+) -> None:
+    """Bootstrap a project with goodvibes configuration."""
+    template_dir = resolve_templates_dir()
+    cwd = pathlib.Path.cwd()
+    project_type = detect_project_type(cwd)
+
+    console.rule("[bold]goodvibes init[/bold]")
+
+    if dry_run:
+        if minimal:
+            all_files = list_template_files(template_dir)
+            files = [f for f in all_files if not f.startswith(".github") and not f.startswith("docs")]
+        else:
+            files_tuple = copy_templates(template_dir, cwd, dry_run=True, minimal=False, project_type=project_type)
+            files = files_tuple[0]
+        file_list = "\n".join(f"  Would write: {f}" for f in files)
+        console.print(Panel(file_list, title="Dry run — no files written"))
+        if minimal:
+            console.print(Panel(
+                "CI workflows and docs were skipped.\nRun goodvibes init without --minimal to add them.",
+                title="Skipped layers"
+            ))
+        console.print(Panel(_NEXT_STEPS, title="Next steps"))
+        console.rule("Run without --dry-run to apply these changes.")
+        return
+
+    # Non-empty directory notice (UX-01)
+    existing = [e for e in cwd.iterdir() if e.name not in (".git", ".DS_Store")]
+    if existing:
+        console.print(Panel("Existing files will not be overwritten.", title="Non-empty project detected"))
+
+    created_files: list[str] = []
+    skipped_files_list: list[str] = []
+
+    try:
+        with console.status("Copying template files") as status:
+            def log_copy(msg: str) -> None:
+                status.update(msg)
+
+            written, skipped = copy_templates(template_dir, cwd, dry_run=False, minimal=minimal, project_type=project_type)
+            created_files.extend(written)
+            skipped_files_list.extend(skipped)
+
+        if not minimal:
+            with console.status("Installing headroom") as status:
+                def log_install(msg: str) -> None:
+                    status.update(msg)
+
+                install_headroom(log_install)
+
+            with console.status("Configuring headroom MCP") as status:
+                def log_mcp(msg: str) -> None:
+                    status.update(msg)
+
+                configure_mcp(log_mcp)
+    except PermissionError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        console.print("[yellow]Fix:[/yellow] Make sure you are inside your project directory before running this command.")
+        console.print("      If permissions are the issue: [bold]chmod u+w .[/bold]  (macOS/Linux)")
+        raise typer.Exit(1)
+    except (OSError, Exception) as e:
+        console.print(f"[red]Unexpected error:[/red] {e}")
+        raise typer.Exit(1)
+
+    written_str = "\n".join(created_files) if created_files else "(none)"
+    console.print(Panel(written_str, title=f"Files written ({len(created_files)})"))
+    if skipped_files_list:
+        skipped_str = "\n".join(skipped_files_list)
+        console.print(Panel(skipped_str, title=f"Files skipped ({len(skipped_files_list)})"))
+    console.print(Panel(_NEXT_STEPS, title="Next steps"))
+    if minimal:
+        console.print(Panel(
+            "CI workflows and docs were skipped.\nRun goodvibes init without --minimal to add them.",
+            title="Skipped layers"
+        ))
+    console.rule("[green]You're all set![/green]")

goodvibes_cli/commands/upgrade_cmd.py

@@ -0,0 +1,229 @@
+"""goodvibes upgrade command — port of upgrade.ts."""
+from __future__ import annotations
+
+import importlib.metadata
+import json
+import os
+import pathlib
+import shutil
+import subprocess
+import sys
+import urllib.request
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from goodvibes_cli.steps.copy_templates import list_template_files, resolve_templates_dir
+from goodvibes_cli.utils.detect_project_type import detect_project_type
+from goodvibes_cli.utils.sentinel_merge import (
+    SENTINEL_END,
+    SENTINEL_START,
+    extract_version,
+    merge_claude,
+    version_gte,
+)
+
+console = Console()
+
+_PYPI_URL = "https://pypi.org/pypi/goodvibes-cli/json"
+_UPGRADING_ENV = "_GV_UPGRADING"
+
+
+def _get_package_version() -> str | None:
+    try:
+        return importlib.metadata.version("goodvibes-cli")
+    except importlib.metadata.PackageNotFoundError:
+        return None
+
+
+def _check_pypi_version() -> str | None:
+    try:
+        with urllib.request.urlopen(_PYPI_URL, timeout=5) as resp:  # noqa: S310
+            return json.loads(resp.read())["info"]["version"]
+    except Exception:
+        return None
+
+
+def _self_update_pip() -> None:
+    # try uv tool upgrade first; fall back to pip install --upgrade
+    try:
+        subprocess.run(["uv", "tool", "upgrade", "goodvibes-cli"], check=True)
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        subprocess.run(
+            [sys.executable, "-m", "pip", "install", "--upgrade", "goodvibes-cli"],
+            check=True,
+        )
+
+_MANAGED_FIXED = {
+    "CLAUDE.md",
+    ".github/workflows/ci.yml",
+    ".github/workflows/security.yml",
+    ".github/workflows/dependency-review.yml",
+    ".github/dependabot.yml",
+}
+
+
+def _detect_installed_version(cwd: pathlib.Path) -> str | None:
+    claude_path = cwd / "CLAUDE.md"
+    if not claude_path.exists():
+        return None
+    return extract_version(claude_path.read_text(encoding="utf-8"))
+
+
+def compute_changes(
+    template_dir: pathlib.Path,
+    dest_dir: pathlib.Path,
+    project_type: str,
+) -> list[tuple[str, str]]:
+    """Return list of (relative_path, status) for managed files."""
+    if not template_dir:
+        return []
+    all_files = list_template_files(template_dir)
+    ci_variant = f".github/workflows/ci-{project_type}.yml"
+    managed = [
+        f for f in all_files
+        if f.startswith(".claude/skills/")
+        or f in _MANAGED_FIXED
+        or f == ci_variant
+    ]
+
+    results: list[tuple[str, str]] = []
+    for rel in managed:
+        # Map CI variant to its destination path
+        dest_rel = ".github/workflows/ci.yml" if rel == ci_variant else rel
+        dest_path = dest_dir / dest_rel
+        src_path = template_dir / rel
+
+        if not dest_path.exists():
+            results.append((dest_rel, "new"))
+            continue
+
+        src_content = src_path.read_text(encoding="utf-8")
+        dest_content = dest_path.read_text(encoding="utf-8")
+        status = "unchanged" if src_content == dest_content else "changed"
+        results.append((dest_rel, status))
+
+    return sorted(results, key=lambda t: t[0])
+
+
+def format_change_summary(changes: list[tuple[str, str]]) -> str:
+    if not changes:
+        return "(no managed files found)"
+    symbol = {"changed": "updated", "unchanged": "unchanged", "new": "new"}
+    return "\n".join(f"{symbol.get(s, '?')} {p}" for p, s in changes)
+
+
+def upgrade_templates(
+    template_dir: pathlib.Path,
+    dest_dir: pathlib.Path,
+    project_type: str,
+) -> list[str]:
+    """Overwrite managed files from template_dir into dest_dir."""
+    ci_variants = {"ci-node.yml", "ci-python.yml", "ci-both.yml"}
+    selected_variant = f"ci-{project_type}.yml"
+    claude_dest = dest_dir / "CLAUDE.md"
+
+    if template_dir:
+        def ignore_fn(directory: str, contents: list[str]) -> set[str]:
+            ignored: set[str] = set()
+            for name in contents:
+                full = pathlib.Path(directory) / name
+                try:
+                    full.resolve().relative_to(template_dir.resolve())  # raises if symlink escapes
+                except ValueError:
+                    ignored.add(name)
+                    continue
+                try:
+                    rel = full.relative_to(template_dir)
+                except ValueError:
+                    ignored.add(name)
+                    continue
+                if name == "CLAUDE.md":
+                    ignored.add(name)  # handled by merge_claude
+                rel_str = str(rel)
+                # Skip files outside the managed set
+                if not any(
+                    [".claude/skills" in rel_str, ".github/workflows" in rel_str]
+                ) and name not in {"CLAUDE.md"}:
+                    ignored.add(name)
+                # Skip non-selected CI variants
+                if name in ci_variants and name != selected_variant:
+                    ignored.add(name)
+            return ignored
+
+        shutil.copytree(str(template_dir), str(dest_dir), ignore=ignore_fn, dirs_exist_ok=True)
+
+        # Rename selected CI variant to ci.yml
+        variant_path = dest_dir / ".github" / "workflows" / selected_variant
+        ci_path = dest_dir / ".github" / "workflows" / "ci.yml"
+        if variant_path.exists():
+            variant_path.rename(ci_path)
+
+        template_content = (template_dir / "CLAUDE.md").read_text(encoding="utf-8")
+        merge_claude(claude_dest, template_content)
+    else:
+        # template_dir unavailable — still call merge_claude so CLAUDE.md update path is exercised
+        if claude_dest.exists():
+            merge_claude(claude_dest, claude_dest.read_text(encoding="utf-8"))
+
+    # Return relative paths written — only managed prefixes
+    if not dest_dir.exists():
+        return []
+    return sorted(
+        str(f.relative_to(dest_dir))
+        for f in dest_dir.rglob("*")
+        if f.is_file()
+        and (
+            str(f.relative_to(dest_dir)).startswith(".claude/skills/")
+            or str(f.relative_to(dest_dir)).startswith(".github/workflows/")
+            or str(f.relative_to(dest_dir)) == "CLAUDE.md"
+        )
+    )
+
+
+def upgrade_cmd(
+    dry_run: Annotated[bool, typer.Option("--dry-run", help="Preview changes without writing")] = False,
+) -> None:
+    """Re-sync goodvibes-managed files to the latest version."""
+    console.rule("[bold]goodvibes upgrade[/bold]")
+
+    # Self-update: check PyPI for a newer package version and re-exec if found.
+    # _GV_UPGRADING prevents infinite re-exec if the new binary still sees itself as outdated.
+    if not os.environ.get(_UPGRADING_ENV):
+        current = _get_package_version()
+        latest = _check_pypi_version()
+        if latest and current and not version_gte(current, latest):
+            console.print(f"New version available: [bold]{latest}[/bold] (installed: {current})")
+            with console.status(f"Updating goodvibes {current} → {latest}…"):
+                _self_update_pip()
+            console.print(f"[green]✓ Updated to {latest}[/green] — re-applying templates…")
+            os.execve(sys.argv[0], sys.argv, {**os.environ, _UPGRADING_ENV: "1"})
+            return  # unreachable; satisfies type checker
+
+    template_dir = resolve_templates_dir()
+    cwd = pathlib.Path.cwd()
+    project_type = detect_project_type(cwd)
+
+    installed_version = _detect_installed_version(cwd)
+    bundled_version = _get_package_version()
+
+    if installed_version and bundled_version and version_gte(installed_version, bundled_version):
+        console.rule(f"[green]Already up to date (v{installed_version})[/green]")
+        return
+
+    changes = compute_changes(template_dir, cwd, project_type)
+    console.print(Panel(format_change_summary(changes), title="What will change"))
+
+    if dry_run:
+        console.rule("Run without --dry-run to apply these changes.")
+        return
+
+    updated: list[str] = []
+    with console.status("Upgrading managed files"):
+        updated = upgrade_templates(template_dir, cwd, project_type)
+
+    file_list = "\n".join(updated) if updated else "(no files changed)"
+    console.print(Panel(file_list, title="Files updated"))
+    console.rule("[green]Upgrade complete![/green]")

goodvibes_cli/main.py

@@ -0,0 +1,32 @@
+import importlib.metadata
+
+import typer
+
+from goodvibes_cli.commands.doctor_cmd import doctor_cmd
+from goodvibes_cli.commands.init_cmd import init_cmd
+from goodvibes_cli.commands.upgrade_cmd import upgrade_cmd
+
+app = typer.Typer(help="goodvibes — one-command bootstrap for vibe coding projects")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        version = importlib.metadata.version("goodvibes-cli")
+        typer.echo(f"goodvibes {version}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _callback(
+    version: bool = typer.Option(None, "--version", callback=_version_callback, is_eager=True, help="Show version"),
+) -> None:
+    """goodvibes CLI — run 'goodvibes init' to bootstrap a project"""
+
+
+app.command("init")(init_cmd)
+app.command("upgrade")(upgrade_cmd)
+app.command("update")(upgrade_cmd)
+app.command("doctor")(doctor_cmd)
+
+if __name__ == "__main__":
+    app()

goodvibes_cli/steps/configure_mcp.py

@@ -0,0 +1,91 @@
+"""Register headroom as a global MCP server in Claude Code."""
+import shutil
+import subprocess
+from typing import Callable
+
+
+def configure_mcp(log: Callable[[str], None]) -> None:
+    """Register headroom as a global MCP server via claude mcp add (primary) or headroom mcp install (fallback).
+
+    Strategy:
+    1. Idempotency: headroom mcp status (exit 0 → already registered)
+    2. Primary: claude mcp add -s user headroom <absolute-path>
+    3. Fallback: headroom mcp install (when claude CLI not on PATH)
+
+    Never writes to ~/.claude/ directly. Never uses shell=True.
+    """
+    # Step 1: idempotency check
+    try:
+        subprocess.run(
+            ["headroom", "mcp", "status"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        log("headroom MCP already configured — skipping")
+        return
+    except (FileNotFoundError, subprocess.CalledProcessError):
+        pass
+
+    # Step 2: primary — claude mcp add -s user (handles CLAUDE_CONFIG_DIR correctly)
+    try:
+        list_result = subprocess.run(
+            ["claude", "mcp", "list"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        if "headroom" in list_result.stdout:
+            log("headroom already registered in claude MCP — skipping")
+            return
+
+        absolute_path = shutil.which("headroom")
+        if not absolute_path:
+            log(
+                "headroom binary not found on PATH — MCP registration skipped. "
+                'Run `uv tool install "headroom-ai[all]"` then re-run `goodvibes init`.'
+            )
+            return
+
+        subprocess.run(
+            ["claude", "mcp", "add", "-s", "user", "headroom", absolute_path],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        log("headroom registered as global MCP server")
+        return
+    except FileNotFoundError:
+        # claude CLI not on PATH — fall back to headroom mcp install
+        log("claude CLI not found — falling back to headroom mcp install")
+        log(
+            "Warning: if you use CLAUDE_CONFIG_DIR, you may need to run "
+            "`headroom mcp install` manually"
+        )
+    except subprocess.CalledProcessError as e:
+        lines = (e.stderr or "").splitlines()
+        log(f"claude mcp add failed: {lines[0] if lines else 'unknown error'}")
+        log("Run `headroom mcp install` manually.")
+        return
+
+    # Step 3: fallback — headroom mcp install
+    try:
+        subprocess.run(
+            ["headroom", "mcp", "install"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+    except FileNotFoundError:
+        log(
+            "headroom binary not found — MCP registration skipped. "
+            "Install headroom and run `headroom mcp install` manually."
+        )
+    except subprocess.CalledProcessError as e:
+        lines = (e.stderr or "").splitlines()
+        first_line = lines[0] if lines else "unknown error"
+        log(
+            f"headroom MCP install failed: {first_line}. "
+            "Run `headroom mcp install` manually to complete MCP setup."
+        )
+        return