jgiox-goodvibes 1.0.0__tar.gz

jgiox_goodvibes-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+dist/
+*.egg-info/

jgiox_goodvibes-1.0.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: jgiox-goodvibes
+Version: 1.0.0
+Summary: One-command bootstrap for vibe coding projects
+License: Apache-2.0
+Keywords: claude,cli,llm,scaffold,starter-kit,vibe-coding
+Requires-Python: >=3.10
+Requires-Dist: rich>=14
+Requires-Dist: typer>=0.15
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
+Requires-Dist: pytest-cov>=7; extra == 'dev'
+Requires-Dist: pytest-mock>=3; extra == 'dev'
+Requires-Dist: pytest>=9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# goodvibes
+
+One-command bootstrap for vibe coding projects.
+
+```
+pip install jgiox-goodvibes
+goodvibes init
+```

jgiox_goodvibes-1.0.0/README.md

@@ -0,0 +1,8 @@
+# goodvibes
+
+One-command bootstrap for vibe coding projects.
+
+```
+pip install jgiox-goodvibes
+goodvibes init
+```

jgiox_goodvibes-1.0.0/hatch_build.py

@@ -0,0 +1,43 @@
+"""Hatchling build hook — copies templates into the wheel when building from sdist."""
+from __future__ import annotations
+
+import pathlib
+import shutil
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class CustomBuildHook(BuildHookInterface):
+    """Resolve and inject the templates directory into the wheel build.
+
+    When building directly from source, ../../templates resolves correctly.
+    When building from an sdist, the templates are at <sdist-root>/templates/.
+    This hook copies whichever location exists into the wheel's goodvibes_cli/templates/.
+    """
+
+    def initialize(self, version: str, build_data: dict) -> None:
+        root = pathlib.Path(self.root)
+
+        # Direct source build: root = packages/pip/, templates at ../../templates
+        templates_source = root / ".." / ".." / "templates"
+        # Sdist build: templates were included at the sdist root level
+        templates_sdist = root / "templates"
+
+        if templates_source.exists():
+            src = templates_source.resolve()
+        elif templates_sdist.exists():
+            src = templates_sdist.resolve()
+        else:
+            return  # no templates to bundle
+
+        dest = root / "src" / "goodvibes_cli" / "templates"
+        if dest.exists():
+            shutil.rmtree(dest)
+        shutil.copytree(src, dest)
+
+        # Clean up after wheel build completes (cleanup hook handles this)
+        self._templates_dest = dest
+
+    def finalize(self, version: str, build_data: dict, artifact_path: str) -> None:
+        if hasattr(self, "_templates_dest") and self._templates_dest.exists():
+            shutil.rmtree(self._templates_dest)

jgiox_goodvibes-1.0.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "jgiox-goodvibes"
+version = "1.0.0"
+description = "One-command bootstrap for vibe coding projects"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+keywords = ["scaffold", "vibe-coding", "claude", "llm", "starter-kit", "cli"]
+dependencies = ["typer>=0.15", "rich>=14"]
+
+[project.scripts]
+goodvibes = "goodvibes_cli.main:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/goodvibes_cli"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/goodvibes_cli/**", "tests/**", "hatch_build.py"]
+# ponytail: include templates in sdist so hook can find them when building from sdist
+force-include = {"../../templates" = "templates"}
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9",
+    "pytest-mock>=3",
+    "pytest-asyncio>=0.25",
+    "pytest-cov>=7",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-x -q"

jgiox_goodvibes-1.0.0/src/goodvibes_cli/__init__.py

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

jgiox_goodvibes-1.0.0/src/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()

jgiox_goodvibes-1.0.0/src/goodvibes_cli/commands/init_cmd.py

@@ -0,0 +1,65 @@
+"""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
+
+console = Console()
+
+_NEXT_STEPS = (
+    "1. Open this project in Claude Code\n"
+    "2. In Claude Code CLI: /plugin marketplace add DietrichGebert/ponytail\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()
+
+    console.rule("[bold]goodvibes init[/bold]")
+
+    if dry_run:
+        files = list_template_files(template_dir)
+        file_list = "\n".join(f"  Would write: {f}" for f in files)
+        console.print(Panel(file_list, title="Dry run — no files written"))
+        console.print(Panel(_NEXT_STEPS, title="Next steps"))
+        console.rule("Run without --dry-run to apply these changes.")
+        return
+
+    created_files: list[str] = []
+
+    with console.status("Copying template files") as status:
+        def log_copy(msg: str) -> None:
+            status.update(msg)
+
+        files = copy_templates(template_dir, cwd, dry_run=False, minimal=minimal)
+        created_files.extend(files)
+
+    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)
+
+    file_list_str = "\n".join(created_files) if created_files else "(none)"
+    console.print(Panel(file_list_str, title="Files created"))
+    console.print(Panel(_NEXT_STEPS, title="Next steps"))
+    console.rule("[green]You're all set![/green]")

jgiox_goodvibes-1.0.0/src/goodvibes_cli/main.py

@@ -0,0 +1,26 @@
+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.commands.init_cmd import init_cmd  # noqa: E402
+
+app = typer.Typer(help="goodvibes — one-command bootstrap for vibe coding projects")
+
+
+@app.callback()
+def _callback() -> None:
+    """goodvibes CLI — run 'goodvibes init' to bootstrap a project"""
+
+
+app.command("init")(init_cmd)
+
+if __name__ == "__main__":
+    app()

jgiox_goodvibes-1.0.0/src/goodvibes_cli/steps/configure_mcp.py

@@ -0,0 +1,80 @@
+"""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"
+        )
+
+    # 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:
+        raise  # unexpected failure in fallback — re-raise so caller can surface it

jgiox_goodvibes-1.0.0/src/goodvibes_cli/steps/copy_templates.py

@@ -0,0 +1,75 @@
+"""File copy orchestrator — port of copy-templates.ts. Uses shutil + importlib.resources."""
+from __future__ import annotations
+
+import importlib.resources
+import pathlib
+import shutil
+
+from goodvibes_cli.utils.sentinel_merge import merge_claude
+
+
+def resolve_templates_dir() -> pathlib.Path:
+    """Return the bundled templates directory from the installed wheel."""
+    ref = importlib.resources.files("goodvibes_cli").joinpath("templates")
+    # Wrap with Path(str(...)) for str/PathLike compatibility (RESEARCH.md Pitfall 2)
+    path = pathlib.Path(str(ref))
+    if not path.exists():
+        raise FileNotFoundError("goodvibes template files not found in installed package")
+    return path
+
+
+def list_template_files(template_dir: pathlib.Path) -> list[str]:
+    """Return sorted list of relative file paths under template_dir."""
+    return sorted(
+        str(f.relative_to(template_dir))
+        for f in template_dir.rglob("*")
+        if f.is_file()
+    )
+
+
+def copy_templates(
+    template_dir: pathlib.Path,
+    dest_dir: pathlib.Path,
+    dry_run: bool = False,
+    minimal: bool = False,
+) -> list[str]:
+    """Copy template files to dest_dir, handling CLAUDE.md via sentinel merge.
+
+    Returns the list of template file paths (relative to template_dir).
+    When dry_run=True, returns the list without writing any files.
+    """
+    if dry_run:
+        return list_template_files(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:
+                rel = full.relative_to(template_dir)
+            except ValueError:
+                # path not relative to template_dir — path traversal
+                ignored.add(name)
+                continue
+            if name == "CLAUDE.md":
+                ignored.add(name)  # sentinel merge handles it separately
+            if ".." in pathlib.Path(str(rel)).parts:
+                ignored.add(name)  # path traversal guard (T-03-02-01)
+            if minimal and ".github" in rel.parts and "workflows" in rel.parts:
+                ignored.add(name)
+            # No-clobber: skip if destination already exists (T-03-02-03)
+            dest_candidate = dest_dir / rel
+            if dest_candidate.exists():
+                ignored.add(name)
+        return ignored
+
+    shutil.copytree(str(template_dir), str(dest_dir), ignore=ignore_fn, dirs_exist_ok=True)
+
+    # Handle CLAUDE.md via sentinel merge
+    claude_src = template_dir / "CLAUDE.md"
+    if claude_src.exists():
+        claude_dest = dest_dir / "CLAUDE.md"
+        template_content = claude_src.read_text(encoding="utf-8")
+        merge_claude(claude_dest, template_content)
+
+    return list_template_files(template_dir)

jgiox_goodvibes-1.0.0/src/goodvibes_cli/steps/install_headroom.py

@@ -0,0 +1,52 @@
+"""Install headroom-ai via uv → pipx → pip fallback chain."""
+import subprocess
+from typing import Callable
+
+from goodvibes_cli.utils.detect_python import detect_python
+
+
+def install_headroom(log: Callable[[str], None]) -> None:
+    """Install headroom-ai[all] using the first available installer.
+
+    Order: uv tool install → pipx install → pip install --user.
+
+    Never raises. Never uses shell=True. Soft-fails on CalledProcessError.
+    """
+    python_cmd = detect_python()
+    if python_cmd is None:
+        log(
+            "Python 3.10+ not found — skipping headroom install. "
+            "Install Python 3.10+ and run `goodvibes init` again."
+        )
+        return
+
+    # HDR-03: ONNX warning BEFORE any subprocess call — shows even if installer is slow
+    log(
+        "Note: headroom will download its compression model on first use"
+        " — this may take 1–3 minutes on a slow connection."
+    )
+
+    installers: list[list[str]] = [
+        ["uv", "tool", "install", "headroom-ai[all]"],
+        ["pipx", "install", "headroom-ai[all]"],
+        [python_cmd, "-m", "pip", "install", "--user", "headroom-ai[all]"],
+    ]
+
+    for cmd_list in installers:
+        try:
+            subprocess.run(cmd_list, capture_output=True, text=True, check=True)
+            return
+        except FileNotFoundError:
+            continue
+        except subprocess.CalledProcessError as e:
+            lines = (e.stderr or "").splitlines()
+            first_line = lines[0] if lines else "unknown error"
+            log(f"headroom install failed: {first_line}")
+            log('You can install headroom manually later: uv tool install "headroom-ai[all]"')
+            return
+
+    # All three installers were FileNotFoundError
+    log(
+        "No package installer found (uv, pipx, pip). "
+        "Install Python 3.10+ with uv or pipx and run `goodvibes init` again."
+    )

jgiox_goodvibes-1.0.0/src/goodvibes_cli/templates/.claude/skills/cavecrew/README.md

@@ -0,0 +1,41 @@
+# cavecrew
+
+Decision guide. When to delegate to caveman subagents instead of doing the work inline.
+
+## What it does
+
+Tells the main thread when to spawn a caveman-style subagent versus the vanilla equivalent. The win: subagent tool-results inject back into main context verbatim, and caveman output is roughly 1/3 the size of vanilla prose. Across 20 delegations in one session, that is the difference between context exhaustion and finishing the task.
+
+Three subagents:
+
+| Subagent | Job | Use when |
+|----------|-----|----------|
+| `cavecrew-investigator` | Locate code (read-only) | "Where is X defined / what calls Y / list uses of Z" |
+| `cavecrew-builder` | Surgical edit, 1-2 files | Scope is obvious, ≤2 files. Refuses 3+ file scope. |
+| `cavecrew-reviewer` | Diff/file review | One-line findings with severity emoji |
+
+Use vanilla `Explore` or `Code Reviewer` when you want prose, architecture commentary, or rationale. Use main thread directly for one-line answers and 3+ file refactors.
+
+This skill is a decision guide, not a slash command. It activates when the conversation mentions delegation.
+
+## How to invoke
+
+Triggers on phrases like "delegate to subagent", "use cavecrew", "spawn investigator", "save context", "compressed agent output".
+
+## Example chaining
+
+Locate → fix → verify (most common):
+
+1. `cavecrew-investigator` returns site list (`path:line — symbol — note`)
+2. Main thread picks 1-2 sites, hands paths to `cavecrew-builder`
+3. `cavecrew-reviewer` audits the resulting diff
+
+Parallel scout: spawn 2-3 `cavecrew-investigator` calls in one message with different angles (defs, callers, tests). Aggregate in main.
+
+## See also
+
+- [`SKILL.md`](./SKILL.md) — full decision matrix and output contracts
+- [`agents/cavecrew-investigator.md`](../../agents/cavecrew-investigator.md)
+- [`agents/cavecrew-builder.md`](../../agents/cavecrew-builder.md)
+- [`agents/cavecrew-reviewer.md`](../../agents/cavecrew-reviewer.md)
+- [Caveman README](../../README.md) — repo overview

jgiox_goodvibes-1.0.0/src/goodvibes_cli/templates/.claude/skills/cavecrew/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: cavecrew
+description: >
+  Decision guide for delegating to caveman-style subagents. Tells the main
+  thread WHEN to spawn `cavecrew-investigator` (locate code), `cavecrew-builder`
+  (1-2 file edit), or `cavecrew-reviewer` (diff review) instead of doing the
+  work inline or using vanilla `Explore`. Subagent output is caveman-compressed
+  so the tool-result injected back into main context is ~60% smaller — main
+  context lasts longer across long sessions.
+  Trigger: "delegate to subagent", "use cavecrew", "spawn investigator/builder/reviewer",
+  "save context", "compressed agent output".
+---
+
+Cavecrew = three subagent presets that emit caveman output. Same job as Anthropic defaults (`Explore`, edit-style agents, reviewer); difference is the tool-result they return is compressed, so main context shrinks per delegation.
+
+## When to use cavecrew vs alternatives
+
+| Task | Use |
+|---|---|
+| "Where is X defined / what calls Y / list uses of Z" | `cavecrew-investigator` |
+| Same but you also want suggestions/architecture commentary | `Explore` (vanilla) |
+| Surgical edit, ≤2 files, scope obvious | `cavecrew-builder` |
+| New feature / 3+ files / cross-cutting refactor | Main thread or `feature-dev:code-architect` |
+| Review diff, branch, or file for bugs | `cavecrew-reviewer` |
+| Deep code review with rationale + alternatives | `Code Reviewer` (vanilla) |
+| One-line answer you already know | Main thread, no subagent |
+
+Rule of thumb: **if you'd want the subagent's output in 1/3 the tokens, pick cavecrew. If you'd want prose, pick vanilla.**
+
+## Why this exists (the real win)
+
+Subagent tool results get injected into main context verbatim. A vanilla `Explore` that returns 2k tokens of prose costs 2k tokens of main-context budget every time. The same finding from `cavecrew-investigator` returns ~700 tokens. Across 20 delegations in one session that's the difference between context exhaustion and finishing the task.
+
+## Output contracts
+
+What main thread can rely on per agent:
+
+**`cavecrew-investigator`**
+```
+<Header>:
+- path:line — `symbol` — short note
+totals: <counts>.
+```
+Or `No match.` Always file-path-first, line-number-attached, backticked symbols. Safe to grep with `path:\d+`.
+
+**`cavecrew-builder`**
+```
+<path:line-range> — <change ≤10 words>.
+verified: <re-read OK | mismatch @ path:line>.
+```
+Or one of: `too-big.` / `needs-confirm.` / `ambiguous.` / `regressed.` (terminal first token).
+
+**`cavecrew-reviewer`**
+```
+path:line: <emoji> <severity>: <problem>. <fix>.
+totals: N🔴 N🟡 N🔵 N❓
+```
+Or `No issues.` Findings sorted file → line ascending.
+
+## Chaining patterns
+
+**Locate → fix → verify** (most common):
+1. `cavecrew-investigator` returns site list.
+2. Main thread picks 1-2 sites, hands paths to `cavecrew-builder`.
+3. `cavecrew-reviewer` audits the diff.
+
+**Parallel scout** (when investigation is broad):
+Spawn 2-3 `cavecrew-investigator` calls in one message (different angles: defs vs callers vs tests). Aggregate in main thread.
+
+**Single-shot edit** (when site is already known):
+Skip investigator. Hand exact path:line to `cavecrew-builder` directly.
+
+## What NOT to do
+
+- Don't use `cavecrew-builder` when you don't already know the file. Spawn investigator first or main thread will eat tokens passing context.
+- Don't chain `cavecrew-investigator → cavecrew-builder` for a 5-file refactor. Builder will return `too-big.` and you'll have wasted a turn.
+- Don't ask `cavecrew-reviewer` for "general feedback" — it returns findings only, no architecture opinions. Use `Code Reviewer` for that.
+- Don't expect prose. Cavecrew output is structured, sometimes terse to the point of cryptic. If a human will read it directly, paraphrase.
+
+## Auto-clarity (inherited)
+
+Subagents drop caveman → normal English for security warnings, irreversible-action confirmations, and any output where fragment ambiguity could be misread. Resume caveman after.

jgiox_goodvibes-1.0.0/src/goodvibes_cli/templates/.claude/skills/caveman/README.md

@@ -0,0 +1,48 @@
+# caveman
+
+Talk like smart caveman. Same brain, fewer tokens.
+
+## What it does
+
+Compress every model response to caveman-style prose. Drops articles, filler, pleasantries, and hedging. Keeps every technical detail, code block, error string, and symbol exact. Cuts ~65-75% of output tokens with full accuracy preserved. Mode persists for the whole session until changed or stopped.
+
+Six intensity levels:
+
+| Level | What change |
+|-------|-------------|
+| `lite` | Drop filler/hedging. Sentences stay full. Professional but tight. |
+| `full` | Default. Drop articles, fragments OK, short synonyms. |
+| `ultra` | Bare fragments. Abbreviations (DB, auth, fn). Arrows for causality. |
+| `wenyan-lite` | Classical Chinese register, light compression. |
+| `wenyan-full` | Maximum 文言文. 80-90% character reduction. |
+| `wenyan-ultra` | Extreme classical compression. |
+
+Auto-clarity rule: caveman drops to normal prose for security warnings, irreversible-action confirmations, multi-step sequences where fragment ambiguity risks misread, and when user repeats a question. Resumes after the clear part.
+
+## How to invoke
+
+```
+/caveman              # full mode (default)
+/caveman lite         # lighter compression
+/caveman ultra        # extreme compression
+/caveman wenyan       # classical Chinese
+stop caveman          # back to normal prose
+```
+
+## Example output
+
+Question: "Why does my React component re-render?"
+
+Normal prose:
+> Your component re-renders because you create a new object reference each render. Wrapping it in `useMemo` will fix the issue.
+
+Caveman (full):
+> New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`.
+
+Caveman (ultra):
+> Inline obj prop → new ref → re-render. `useMemo`.
+
+## See also
+
+- [`SKILL.md`](./SKILL.md) — full LLM-facing instructions
+- [Caveman README](../../README.md) — repo overview, install, benchmarks