devbrief 0.1.0__tar.gz

devbrief-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.env

devbrief-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

devbrief-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebastien Claro (s3bc40)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

devbrief-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: devbrief
+Version: 0.1.0
+Summary: Generate a human-readable brief for any GitHub repository using Claude AI
+Project-URL: Homepage, https://github.com/s3bc40/devbrief
+Project-URL: Repository, https://github.com/s3bc40/devbrief
+Author-email: "Sebastien Claro (s3bc40)" <s3bc40@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,cli,developer-tools,github
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.12
+Requires-Dist: anthropic>=0.84.0
+Requires-Dist: click>=8.3.1
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: requests>=2.32.5
+Requires-Dist: rich>=14.3.3
+Description-Content-Type: text/markdown
+
+# devbrief
+
+> Generate a human-readable project brief for any GitHub repository using Claude AI.
+
+`devbrief` takes a GitHub URL, pulls the repository metadata, README, and file tree, then asks Claude to produce a structured brief — covering what the project does, its tech stack, how to get started, and its limitations — directly in your terminal.
+
+---
+
+## Installation
+
+### pip
+
+```bash
+pip install devbrief
+```
+
+### uvx (run without installing)
+
+```bash
+uvx devbrief <github-url>
+```
+
+### uv (install globally)
+
+```bash
+uv tool install devbrief
+```
+
+---
+
+## Prerequisites
+
+An [Anthropic API key](https://console.anthropic.com/) is required.
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+Or place it in a `.env` file at your working directory:
+
+```
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+---
+
+## Usage
+
+```bash
+devbrief <github-url> [--output FILE]
+```
+
+### Examples
+
+```bash
+# Print the brief to the terminal
+devbrief https://github.com/anthropics/anthropic-sdk-python
+
+# Save the brief as a markdown file
+devbrief https://github.com/astral-sh/uv --output uv-brief.md
+```
+
+### Options
+
+| Option | Short | Description |
+|---|---|---|
+| `--output FILE` | `-o` | Save the brief as a markdown file |
+| `--help` | | Show usage and exit |
+
+### Output sections
+
+Each generated brief contains:
+
+- **One-line description** — a crisp summary of the project
+- **Problem it solves** — the core need being addressed
+- **Tech stack** — detected languages, frameworks, and tools
+- **Getting started** — steps extracted from the README
+- **Who would find it useful** — the target audience
+- **Limitations / potential improvements** — honest trade-offs
+
+---
+
+## How it works
+
+```
+GitHub URL
+    │
+    ├── /repos/:owner/:repo        → name, description, stars, language, topics
+    ├── /repos/:owner/:repo/readme → decoded README content (first 3000 chars)
+    └── /repos/:owner/:repo/contents → top-level file tree
+            │
+            └── Structured prompt → Claude claude-opus-4-6 → Rich terminal output
+```
+
+---
+
+## Development
+
+Requires [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/s3bc40/devbrief
+cd devbrief
+uv sync
+```
+
+### Run locally
+
+```bash
+uv run devbrief https://github.com/s3bc40/devbrief
+```
+
+### Run tests
+
+```bash
+uv run pytest
+```
+
+Tests cover URL parsing, GitHub API response mapping, edge cases (missing README, empty file tree), and Rich display output. No real API calls are made — all HTTP responses are mocked.
+
+### Project structure
+
+```
+src/devbrief/
+├── main.py       # Click CLI entry point
+├── github.py     # GitHub REST API fetchers
+├── brief.py      # Prompt construction and Claude API call
+└── display.py    # Rich terminal rendering
+tests/
+├── test_github.py
+└── test_display.py
+```
+
+---
+
+## Contributing
+
+1. Fork the repository and create a branch from `main`.
+2. Make focused commits with explicit messages (one concern per commit).
+3. Add or update tests for any changed behaviour.
+4. Open a pull request — describe the problem and your solution.
+
+Please do not open issues to ask for new AI providers or models; the project is intentionally scoped to the Anthropic API.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

devbrief-0.1.0/README.md

@@ -0,0 +1,149 @@
+# devbrief
+
+> Generate a human-readable project brief for any GitHub repository using Claude AI.
+
+`devbrief` takes a GitHub URL, pulls the repository metadata, README, and file tree, then asks Claude to produce a structured brief — covering what the project does, its tech stack, how to get started, and its limitations — directly in your terminal.
+
+---
+
+## Installation
+
+### pip
+
+```bash
+pip install devbrief
+```
+
+### uvx (run without installing)
+
+```bash
+uvx devbrief <github-url>
+```
+
+### uv (install globally)
+
+```bash
+uv tool install devbrief
+```
+
+---
+
+## Prerequisites
+
+An [Anthropic API key](https://console.anthropic.com/) is required.
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+Or place it in a `.env` file at your working directory:
+
+```
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+---
+
+## Usage
+
+```bash
+devbrief <github-url> [--output FILE]
+```
+
+### Examples
+
+```bash
+# Print the brief to the terminal
+devbrief https://github.com/anthropics/anthropic-sdk-python
+
+# Save the brief as a markdown file
+devbrief https://github.com/astral-sh/uv --output uv-brief.md
+```
+
+### Options
+
+| Option | Short | Description |
+|---|---|---|
+| `--output FILE` | `-o` | Save the brief as a markdown file |
+| `--help` | | Show usage and exit |
+
+### Output sections
+
+Each generated brief contains:
+
+- **One-line description** — a crisp summary of the project
+- **Problem it solves** — the core need being addressed
+- **Tech stack** — detected languages, frameworks, and tools
+- **Getting started** — steps extracted from the README
+- **Who would find it useful** — the target audience
+- **Limitations / potential improvements** — honest trade-offs
+
+---
+
+## How it works
+
+```
+GitHub URL
+    │
+    ├── /repos/:owner/:repo        → name, description, stars, language, topics
+    ├── /repos/:owner/:repo/readme → decoded README content (first 3000 chars)
+    └── /repos/:owner/:repo/contents → top-level file tree
+            │
+            └── Structured prompt → Claude claude-opus-4-6 → Rich terminal output
+```
+
+---
+
+## Development
+
+Requires [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/s3bc40/devbrief
+cd devbrief
+uv sync
+```
+
+### Run locally
+
+```bash
+uv run devbrief https://github.com/s3bc40/devbrief
+```
+
+### Run tests
+
+```bash
+uv run pytest
+```
+
+Tests cover URL parsing, GitHub API response mapping, edge cases (missing README, empty file tree), and Rich display output. No real API calls are made — all HTTP responses are mocked.
+
+### Project structure
+
+```
+src/devbrief/
+├── main.py       # Click CLI entry point
+├── github.py     # GitHub REST API fetchers
+├── brief.py      # Prompt construction and Claude API call
+└── display.py    # Rich terminal rendering
+tests/
+├── test_github.py
+└── test_display.py
+```
+
+---
+
+## Contributing
+
+1. Fork the repository and create a branch from `main`.
+2. Make focused commits with explicit messages (one concern per commit).
+3. Add or update tests for any changed behaviour.
+4. Open a pull request — describe the problem and your solution.
+
+Please do not open issues to ask for new AI providers or models; the project is intentionally scoped to the Anthropic API.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

devbrief-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "devbrief"
+version = "0.1.0"
+description = "Generate a human-readable brief for any GitHub repository using Claude AI"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "anthropic>=0.84.0",
+    "click>=8.3.1",
+    "python-dotenv>=1.2.2",
+    "requests>=2.32.5",
+    "rich>=14.3.3",
+]
+license = { text = "MIT" }
+authors = [
+  { name = "Sebastien Claro (s3bc40)", email = "s3bc40@gmail.com" }
+]
+keywords = ["cli", "github", "ai", "developer-tools"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+]
+
+[project.urls]
+Homepage = "https://github.com/s3bc40/devbrief"
+Repository = "https://github.com/s3bc40/devbrief"
+
+[project.scripts]
+devbrief = "devbrief.main:cli"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/devbrief"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-mock>=3.15.1",
+    "twine>=6.2.0",
+]

devbrief-0.1.0/src/devbrief/brief.py

@@ -0,0 +1,48 @@
+import os
+import anthropic
+
+
+def build_prompt(repo: dict, readme: str, file_tree: list[str]) -> str:
+    readme_snippet = readme[:3000] if readme else "No README found."
+    tree_str = "\n".join(file_tree) if file_tree else "No file tree available."
+    topics_str = ", ".join(repo["topics"]) if repo["topics"] else "none"
+
+    return f"""You are a senior developer writing a concise project brief for a technical audience.
+
+Repository: {repo['name']}
+Description: {repo['description'] or 'No description provided.'}
+Stars: {repo['stars']}
+Primary language: {repo['language'] or 'unknown'}
+Topics: {topics_str}
+
+Top-level file tree:
+{tree_str}
+
+README (first 3000 chars):
+{readme_snippet}
+
+Write a structured project brief with exactly these sections:
+1. **One-line description** – A single crisp sentence summarizing the project.
+2. **Problem it solves** – 2-3 sentences on the core problem addressed.
+3. **Tech stack** – Bullet list of detected technologies/frameworks.
+4. **Getting started** – 3-5 steps extracted or inferred from the README.
+5. **Who would find it useful** – 2-3 sentences on the target audience.
+6. **Limitations / potential improvements** – 3-5 bullet points.
+
+Be concise. Do not repeat the section headers verbatim — use them as guidance only."""
+
+
+def generate_brief(repo: dict, readme: str, file_tree: list[str]) -> str:
+    api_key = os.environ.get("ANTHROPIC_API_KEY")
+    if not api_key:
+        raise EnvironmentError("ANTHROPIC_API_KEY environment variable is not set.")
+
+    client = anthropic.Anthropic(api_key=api_key)
+    prompt = build_prompt(repo, readme, file_tree)
+
+    message = client.messages.create(
+        model="claude-opus-4-6",
+        max_tokens=1024,
+        messages=[{"role": "user", "content": prompt}],
+    )
+    return message.content[0].text

devbrief-0.1.0/src/devbrief/display.py

@@ -0,0 +1,30 @@
+from rich.console import Console
+from rich.panel import Panel
+from rich.markdown import Markdown
+from rich.rule import Rule
+from rich import print as rprint
+
+console = Console()
+
+
+def show_fetching(url: str) -> None:
+    console.print(f"\n[bold cyan]Fetching data for:[/bold cyan] {url}")
+
+
+def show_generating() -> None:
+    console.print("[bold yellow]Generating brief with Claude...[/bold yellow]\n")
+
+
+def show_brief(repo_name: str, brief_text: str, elapsed: float) -> None:
+    console.print(Rule(f"[bold green] DevBrief: {repo_name} [/bold green]"))
+    console.print(Panel(Markdown(brief_text), border_style="green", padding=(1, 2)))
+    console.print(Rule(style="green"))
+    console.print(f"[dim]Brief generated in {elapsed:.1f}s[/dim]\n")
+
+
+def show_saved(path: str) -> None:
+    console.print(f"[dim]Saved to[/dim] [bold]{path}[/bold]\n")
+
+
+def show_error(message: str) -> None:
+    rprint(f"\n[bold red]Error:[/bold red] {message}\n")

devbrief-0.1.0/src/devbrief/github.py

@@ -0,0 +1,48 @@
+import requests
+
+
+def parse_repo_url(url: str) -> tuple[str, str]:
+    """Extract owner and repo name from a GitHub URL."""
+    parts = url.rstrip("/").split("/")
+    if len(parts) < 2:
+        raise ValueError(f"Invalid GitHub URL: {url}")
+    return parts[-2], parts[-1]
+
+
+def fetch_repo_data(owner: str, repo: str) -> dict:
+    """Fetch repository metadata from GitHub API."""
+    url = f"https://api.github.com/repos/{owner}/{repo}"
+    response = requests.get(url, timeout=10)
+    response.raise_for_status()
+    data = response.json()
+    return {
+        "name": data.get("name", ""),
+        "description": data.get("description", ""),
+        "stars": data.get("stargazers_count", 0),
+        "language": data.get("language", ""),
+        "topics": data.get("topics", []),
+        "homepage": data.get("homepage", ""),
+    }
+
+
+def fetch_readme(owner: str, repo: str) -> str:
+    """Fetch README content from GitHub API (decoded from base64)."""
+    url = f"https://api.github.com/repos/{owner}/{repo}/readme"
+    response = requests.get(url, timeout=10)
+    if response.status_code == 404:
+        return ""
+    response.raise_for_status()
+    import base64
+    content = response.json().get("content", "")
+    return base64.b64decode(content).decode("utf-8", errors="replace")
+
+
+def fetch_file_tree(owner: str, repo: str) -> list[str]:
+    """Fetch top-level file/directory names from GitHub API."""
+    url = f"https://api.github.com/repos/{owner}/{repo}/contents"
+    response = requests.get(url, timeout=10)
+    if response.status_code == 404:
+        return []
+    response.raise_for_status()
+    items = response.json()
+    return [item["name"] for item in items if isinstance(item, dict)]

devbrief-0.1.0/src/devbrief/main.py

@@ -0,0 +1,49 @@
+import time
+import click
+from dotenv import load_dotenv
+
+from devbrief.github import parse_repo_url, fetch_repo_data, fetch_readme, fetch_file_tree
+from devbrief.brief import generate_brief
+from devbrief.display import show_fetching, show_generating, show_brief, show_error, show_saved
+
+load_dotenv()
+
+
+@click.command()
+@click.argument("github_url")
+@click.option("--output", "-o", default=None, metavar="FILE", help="Save the brief to a markdown file.")
+def cli(github_url: str, output: str | None) -> None:
+    """Generate a human-readable brief for a GitHub repository."""
+    try:
+        show_fetching(github_url)
+        owner, repo_name = parse_repo_url(github_url)
+
+        repo = fetch_repo_data(owner, repo_name)
+        readme = fetch_readme(owner, repo_name)
+        file_tree = fetch_file_tree(owner, repo_name)
+
+        show_generating()
+        start = time.monotonic()
+        brief = generate_brief(repo, readme, file_tree)
+        elapsed = time.monotonic() - start
+        show_brief(repo["name"], brief, elapsed)
+
+        if output:
+            md = f"# {repo['name']}\n\n> {github_url}\n\n{brief}\n"
+            with open(output, "w", encoding="utf-8") as f:
+                f.write(md)
+            show_saved(output)
+
+    except ValueError as e:
+        show_error(str(e))
+        raise SystemExit(1)
+    except EnvironmentError as e:
+        show_error(str(e))
+        raise SystemExit(1)
+    except Exception as e:
+        show_error(f"Unexpected error: {e}")
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    cli()

devbrief-0.1.0/tests/test_display.py

@@ -0,0 +1,94 @@
+import pytest
+from io import StringIO
+from rich.console import Console
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _capture(fn, *args, **kwargs) -> str:
+    """Run a display function with a plain-text Rich console and capture output."""
+    buf = StringIO()
+    console = Console(file=buf, highlight=False, markup=True, no_color=True)
+
+    import devbrief.display as display_module
+    original = display_module.console
+    display_module.console = console
+    try:
+        fn(*args, **kwargs)
+    finally:
+        display_module.console = original
+
+    return buf.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# show_fetching
+# ---------------------------------------------------------------------------
+
+class TestShowFetching:
+    def test_contains_url(self):
+        from devbrief.display import show_fetching
+        out = _capture(show_fetching, "https://github.com/owner/repo")
+        assert "https://github.com/owner/repo" in out
+
+
+# ---------------------------------------------------------------------------
+# show_generating
+# ---------------------------------------------------------------------------
+
+class TestShowGenerating:
+    def test_contains_generating_text(self):
+        from devbrief.display import show_generating
+        out = _capture(show_generating)
+        assert "Generating" in out
+
+
+# ---------------------------------------------------------------------------
+# show_brief
+# ---------------------------------------------------------------------------
+
+class TestShowBrief:
+    def test_contains_repo_name(self):
+        from devbrief.display import show_brief
+        out = _capture(show_brief, "my-repo", "Some brief text.", 2.5)
+        assert "my-repo" in out
+
+    def test_contains_brief_text(self):
+        from devbrief.display import show_brief
+        out = _capture(show_brief, "repo", "**Problem:** it crashes.", 1.0)
+        assert "Problem" in out
+
+    def test_displays_elapsed_time(self):
+        from devbrief.display import show_brief
+        out = _capture(show_brief, "repo", "brief", 3.7)
+        assert "3.7s" in out
+
+    def test_elapsed_time_format(self):
+        from devbrief.display import show_brief
+        out = _capture(show_brief, "repo", "brief", 10.0)
+        assert "10.0s" in out
+
+
+# ---------------------------------------------------------------------------
+# show_saved
+# ---------------------------------------------------------------------------
+
+class TestShowSaved:
+    def test_contains_file_path(self):
+        from devbrief.display import show_saved
+        out = _capture(show_saved, "output/brief.md")
+        assert "output/brief.md" in out
+
+
+# ---------------------------------------------------------------------------
+# show_error
+# ---------------------------------------------------------------------------
+
+class TestShowError:
+    def test_contains_error_message(self, capsys):
+        from devbrief.display import show_error
+        show_error("something went wrong")
+        captured = capsys.readouterr()
+        assert "something went wrong" in captured.out