devbrief 0.1.0__py3-none-any.whl

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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+devbrief/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+devbrief/brief.py,sha256=Uj05Q8sC3bsOFvMoJwyy68vQDhGCBc9wkbFsnYrv-mA,1812
+devbrief/display.py,sha256=e7inuUA8v-EBgnUsyQ5GMWxlowMPGb7H9TDLwGcgb5I,947
+devbrief/github.py,sha256=H-05q1K_XMlBbIvpNzFOCsqHnoQljEtmfJ7XPxxrCYg,1705
+devbrief/main.py,sha256=Xbzu3k1QUkZn0itTXJ99dKUFqwNPSz-XeqPkkYMcReE,1551
+devbrief-0.1.0.dist-info/METADATA,sha256=dcs-gEA6nKug-oS8I9hQFc-6tCVMGMgGME-IRid-AnY,3991
+devbrief-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+devbrief-0.1.0.dist-info/entry_points.txt,sha256=kU7SIO5C2UJVzm_pxUgbqFZjf2sO5EsSigaaeyfiTdQ,47
+devbrief-0.1.0.dist-info/licenses/LICENSE,sha256=M0Es4-j3Vq11f-N220IAcsGJrvRm3EMv3-e52DNg22c,1081
+devbrief-0.1.0.dist-info/RECORD,,

devbrief-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

devbrief-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+devbrief = devbrief.main:cli

devbrief-0.1.0.dist-info/licenses/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.