codebase-brief 0.1.1__tar.gz → 0.1.2__tar.gz

{codebase_brief-0.1.1 → codebase_brief-0.1.2}/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.2
+
+- Add `brief --demo`, which generates a real example brief from temporary sample files without reading or modifying the user's project.
+- Clarify how to try the demo and install the CLI when pipx is not already available.
+- Show the menu's actual `0` exit key correctly in the README.
+
 ## 0.1.1
 
 - Clarify the product's best-fit use case as browser-based coding chats that cannot inspect a local working tree.

{codebase_brief-0.1.1 → codebase_brief-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebase-brief
-Version: 0.1.1
+Version: 0.1.2
 Summary: Local-first CLI that builds task-focused context briefs from code repositories
 Author: Mohamed Maggy
 License-Expression: MIT
@@ -53,7 +53,7 @@ The first image is a terminal-style rendering of the app's actual numbered menu.
 
 You need Python 3.10 or newer. Git is optional, but required for recent-history and base-diff details.
 
-The current PyPI release is `0.1.1` and includes the reviewed-file feedback summary and importer-aware `--base` selection. Install it with `pipx`:
+The current PyPI release is `0.1.2` and includes the review-feedback summary, importer-aware `--base` selection, and a sample demo. Install it with `pipx`:
 
 ```powershell
 pipx install codebase-brief
@@ -62,6 +62,10 @@ brief "C:\work\my-app" --task "Trace the login flow" --copy
 
 The brief is copied to your clipboard for pasting into your assistant. Replace the example path and task with yours. To use the numbered menu, run `brief` with no arguments.
 
+Want to see a real example before choosing your project? Run `brief --demo`. It uses a tiny temporary example project and does not read or change your files.
+
+If you do not have `pipx` installed, skip the command above and use the virtual-environment steps below instead; they work with the project's minimum Python version. To install `pipx` first, follow its [official installation guide](https://pipx.pypa.io/latest/how-to/install-pipx.html). The current pipx installer requires Python 3.11 or newer, while Codebase Brief itself supports Python 3.10 and newer.
+
 Or use a virtual environment:
 
 ```powershell
@@ -79,10 +83,10 @@ If the `brief` command is not available, use `python -m context_inject` while th
 
 When the menu opens, it uses the folder you launched it from as the starting project. Type a number and press Enter:
 
-1. **Build a context brief** — describe the coding task, optionally enter a Git base ref, then accept or change the approximate size limit.
-2. **Choose a different project** — point the tool at another local repository or source folder.
-3. **Help and examples** — see the workflow and an example command.
-0. **Exit** — close the menu.
+- **1 — Build a context brief:** Describe the coding task, optionally enter a Git base ref, then accept or change the approximate size limit.
+- **2 — Choose a different project:** Point the tool at another local repository or source folder.
+- **3 — Help and examples:** See the workflow and an example command.
+- **0 — Exit:** Close the menu.
 
 In plain terms, Codebase Brief makes a small guide to a project so an AI coding assistant can get oriented before helping with a task. It does not write or fix code. It reads project information locally and prepares a guide for you to review and share.
 

{codebase_brief-0.1.1 → codebase_brief-0.1.2}/README.md

@@ -28,7 +28,7 @@ The first image is a terminal-style rendering of the app's actual numbered menu.
 
 You need Python 3.10 or newer. Git is optional, but required for recent-history and base-diff details.
 
-The current PyPI release is `0.1.1` and includes the reviewed-file feedback summary and importer-aware `--base` selection. Install it with `pipx`:
+The current PyPI release is `0.1.2` and includes the review-feedback summary, importer-aware `--base` selection, and a sample demo. Install it with `pipx`:
 
 ```powershell
 pipx install codebase-brief
@@ -37,6 +37,10 @@ brief "C:\work\my-app" --task "Trace the login flow" --copy
 
 The brief is copied to your clipboard for pasting into your assistant. Replace the example path and task with yours. To use the numbered menu, run `brief` with no arguments.
 
+Want to see a real example before choosing your project? Run `brief --demo`. It uses a tiny temporary example project and does not read or change your files.
+
+If you do not have `pipx` installed, skip the command above and use the virtual-environment steps below instead; they work with the project's minimum Python version. To install `pipx` first, follow its [official installation guide](https://pipx.pypa.io/latest/how-to/install-pipx.html). The current pipx installer requires Python 3.11 or newer, while Codebase Brief itself supports Python 3.10 and newer.
+
 Or use a virtual environment:
 
 ```powershell
@@ -54,10 +58,10 @@ If the `brief` command is not available, use `python -m context_inject` while th
 
 When the menu opens, it uses the folder you launched it from as the starting project. Type a number and press Enter:
 
-1. **Build a context brief** — describe the coding task, optionally enter a Git base ref, then accept or change the approximate size limit.
-2. **Choose a different project** — point the tool at another local repository or source folder.
-3. **Help and examples** — see the workflow and an example command.
-0. **Exit** — close the menu.
+- **1 — Build a context brief:** Describe the coding task, optionally enter a Git base ref, then accept or change the approximate size limit.
+- **2 — Choose a different project:** Point the tool at another local repository or source folder.
+- **3 — Help and examples:** See the workflow and an example command.
+- **0 — Exit:** Close the menu.
 
 In plain terms, Codebase Brief makes a small guide to a project so an AI coding assistant can get oriented before helping with a task. It does not write or fix code. It reads project information locally and prepares a guide for you to review and share.
 

{codebase_brief-0.1.1 → codebase_brief-0.1.2}/codebase_brief.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebase-brief
-Version: 0.1.1
+Version: 0.1.2
 Summary: Local-first CLI that builds task-focused context briefs from code repositories
 Author: Mohamed Maggy
 License-Expression: MIT
@@ -53,7 +53,7 @@ The first image is a terminal-style rendering of the app's actual numbered menu.
 
 You need Python 3.10 or newer. Git is optional, but required for recent-history and base-diff details.
 
-The current PyPI release is `0.1.1` and includes the reviewed-file feedback summary and importer-aware `--base` selection. Install it with `pipx`:
+The current PyPI release is `0.1.2` and includes the review-feedback summary, importer-aware `--base` selection, and a sample demo. Install it with `pipx`:
 
 ```powershell
 pipx install codebase-brief
@@ -62,6 +62,10 @@ brief "C:\work\my-app" --task "Trace the login flow" --copy
 
 The brief is copied to your clipboard for pasting into your assistant. Replace the example path and task with yours. To use the numbered menu, run `brief` with no arguments.
 
+Want to see a real example before choosing your project? Run `brief --demo`. It uses a tiny temporary example project and does not read or change your files.
+
+If you do not have `pipx` installed, skip the command above and use the virtual-environment steps below instead; they work with the project's minimum Python version. To install `pipx` first, follow its [official installation guide](https://pipx.pypa.io/latest/how-to/install-pipx.html). The current pipx installer requires Python 3.11 or newer, while Codebase Brief itself supports Python 3.10 and newer.
+
 Or use a virtual environment:
 
 ```powershell
@@ -79,10 +83,10 @@ If the `brief` command is not available, use `python -m context_inject` while th
 
 When the menu opens, it uses the folder you launched it from as the starting project. Type a number and press Enter:
 
-1. **Build a context brief** — describe the coding task, optionally enter a Git base ref, then accept or change the approximate size limit.
-2. **Choose a different project** — point the tool at another local repository or source folder.
-3. **Help and examples** — see the workflow and an example command.
-0. **Exit** — close the menu.
+- **1 — Build a context brief:** Describe the coding task, optionally enter a Git base ref, then accept or change the approximate size limit.
+- **2 — Choose a different project:** Point the tool at another local repository or source folder.
+- **3 — Help and examples:** See the workflow and an example command.
+- **0 — Exit:** Close the menu.
 
 In plain terms, Codebase Brief makes a small guide to a project so an AI coding assistant can get oriented before helping with a task. It does not write or fix code. It reads project information locally and prepares a guide for you to review and share.
 

{codebase_brief-0.1.1 → codebase_brief-0.1.2}/context_inject/cli.py

@@ -11,6 +11,7 @@ import re
 import shutil
 import subprocess
 import sys
+import tempfile
 from pathlib import Path
 
 CHARS_PER_TOKEN = 4  # rough estimate; real token counts vary by model and text
@@ -23,7 +24,7 @@ MAX_KEY_FILES = 12
 MAX_SELECTION_CHOICES = 30
 MAX_DISCOVERED_FILES = 20_000
 IMPORT_SUFFIXES = {".py", ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".mts", ".cts"}
-VERSION = "0.1.1"
+VERSION = "0.1.2"
 MANIFESTS = (
     "package.json", "pyproject.toml", "requirements.txt", "Cargo.toml",
     "go.mod", "Gemfile", "composer.json", "pom.xml",
@@ -943,6 +944,46 @@ def terminal_supports_color() -> bool:
         return False
 
 
+DEMO_TASK = "Trace how a sign-in request is checked"
+DEMO_FILES = {
+    "README.md": (
+        "# Sample Shop\n\n"
+        "A tiny example storefront. Its sign-in route checks a password through a small auth helper.\n"
+    ),
+    "pyproject.toml": (
+        "[project]\nname = 'sample-shop'\nversion = '0.1.0'\n"
+        "requires-python = '>=3.10'\ndependencies = []\n"
+    ),
+    "src/sample_shop/auth.py": (
+        "def check_password(saved_password: str, supplied_password: str) -> bool:\n"
+        "    return saved_password == supplied_password\n"
+    ),
+    "src/sample_shop/routes.py": (
+        "from .auth import check_password\n\n"
+        "def sign_in(saved_password: str, supplied_password: str) -> str:\n"
+        "    if check_password(saved_password, supplied_password):\n"
+        "        return 'Welcome back'\n"
+        "    return 'Password did not match'\n"
+    ),
+    "tests/test_auth.py": (
+        "from sample_shop.auth import check_password\n\n"
+        "def test_matching_password_is_accepted():\n"
+        "    assert check_password('correct horse', 'correct horse')\n"
+    ),
+}
+
+
+def generate_demo_brief() -> str:
+    """Generate a real sample brief without reading or changing the user's project."""
+    with tempfile.TemporaryDirectory(prefix="codebase-brief-demo-") as temporary:
+        root = Path(temporary)
+        for relative, content in DEMO_FILES.items():
+            path = root / relative
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(content, encoding="utf-8")
+        return gather(root, DEMO_TASK, budget_tokens=1_200)
+
+
 def interactive() -> int:
     """Run the guided, numbered terminal interface."""
     repo = Path.cwd().resolve()
@@ -1036,6 +1077,7 @@ def interactive() -> int:
             print("\nA base ref only helps when your current Git commit differs from that ref. Matching covers static imports, literal dynamic imports, and simple TS/JS aliases; runtime-built names may be missed.")
             print(f"The default guide size is about {DEFAULT_BUDGET_TOKENS:,} tokens ({CHARS_PER_TOKEN} characters per token, roughly).")
             print("Save creates a Markdown file; copy puts the guide on your clipboard only when you choose it.")
+            print("Run 'brief --demo' to see a sample brief without using your project.")
             print('\nExample: codebase-brief "C:\\work\\my-app" --task "Find login handling" --base main --budget 2400 --copy')
             input("\nPress Enter to return to the menu...")
             continue
@@ -1135,7 +1177,14 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--output", help="Write Markdown to this path (default: stdout)")
     parser.add_argument("--copy", action="store_true", help="Copy the generated Markdown to your system clipboard")
     parser.add_argument("-i", "--interactive", action="store_true", help="Open the numbered interactive menu")
+    parser.add_argument("--demo", action="store_true", help="Print a real sample brief without reading your project")
     args = parser.parse_args(argv)
+    if args.demo:
+        if args.interactive or args.repo_path or args.task or args.base or args.output or args.copy or args.budget != DEFAULT_BUDGET_TOKENS:
+            parser.error("--demo cannot be combined with repo_path, --task, --base, --budget, --output, --copy, or --interactive")
+        print("Preview from a built-in sample project. Your project folder was not read or changed.\n")
+        sys.stdout.write(generate_demo_brief())
+        return 0
     if args.interactive:
         if args.repo_path or args.task or args.base or args.output or args.copy or args.budget != DEFAULT_BUDGET_TOKENS:
             parser.error("--interactive cannot be combined with repo_path, --task, --base, --budget, --output, or --copy")

{codebase_brief-0.1.1 → codebase_brief-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codebase-brief"
-version = "0.1.1"
+version = "0.1.2"
 description = "Local-first CLI that builds task-focused context briefs from code repositories"
 readme = "README.md"
 license = "MIT"

{codebase_brief-0.1.1 → codebase_brief-0.1.2}/tests/test_cli.py

@@ -222,6 +222,26 @@ class ContextInjectTests(unittest.TestCase):
         self.assertIn("First use:", stdout.getvalue())
         self.assertIn("--budget", stdout.getvalue())
         self.assertIn("--copy", stdout.getvalue())
+        self.assertIn("--demo", stdout.getvalue())
+
+    def test_demo_generates_real_brief_without_reading_or_changing_current_folder(self):
+        output = io.StringIO()
+        before = set(self.root.rglob("*"))
+        with patch("pathlib.Path.cwd", return_value=self.root), contextlib.redirect_stdout(output):
+            self.assertEqual(main(["--demo"]), 0)
+        brief = output.getvalue()
+        self.assertIn("Trace how a sign-in request is checked", brief)
+        self.assertIn("src/sample_shop/auth.py", brief)
+        self.assertIn("src/sample_shop/routes.py", brief)
+        self.assertIn("check_password", brief)
+        self.assertEqual(set(self.root.rglob("*")), before)
+
+    def test_demo_rejects_combined_project_arguments(self):
+        stderr = io.StringIO()
+        with contextlib.redirect_stderr(stderr), self.assertRaises(SystemExit) as error:
+            main([str(self.root), "--demo"])
+        self.assertEqual(error.exception.code, 2)
+        self.assertIn("--demo cannot be combined", stderr.getvalue())
 
     def test_cli_copy_generates_a_brief_and_calls_clipboard(self):
         self.put("README.md", "# Clipboard fixture")
@@ -466,7 +486,7 @@ class ContextInjectTests(unittest.TestCase):
         plain = __import__("re").sub(r"\x1b\[[0-9;]*m", "", output.getvalue())
         self.assertIn("CODEBASE", plain)
         self.assertIn("BRIEF", plain)
-        self.assertIn("v0.1.1", plain)
+        self.assertIn("v0.1.2", plain)
         self.assertIn("Meet Briefy - your repo guide", plain)
         self.assertIn("WHAT THIS DOES", plain)
         self.assertIn("Makes a short guide to your project for an AI coding assistant", plain)