agentpack-cli 0.2.2__tar.gz → 0.3.1__tar.gz

{agentpack_cli-0.2.2 → agentpack_cli-0.3.1}/.gitignore

@@ -12,6 +12,8 @@ env/
 
 # agentpack:start
 # AgentPack generated context/cache (safe to ignore)
+.agentpack/*
+!.agentpack/config.toml
 .agentpack/cache/
 .agentpack/snapshots/
 .agentpack/context*
@@ -23,9 +25,11 @@ env/
 .agentpack/session.json
 .agentpack/task.md
 .agentpack/benchmark_results.jsonl
+.agentignore
 .agent/skills/agentpack/
+.vscode/tasks.json
+GEMINI.md
 # agentpack:end
-
 .pytest_cache/
 .mypy_cache/
 .ruff_cache/

{agentpack_cli-0.2.2 → agentpack_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpack-cli
-Version: 0.2.2
+Version: 0.3.1
 Summary: Task-aware context packing for AI coding agents — Claude, Cursor, Windsurf, Codex, and Antigravity
 License: MIT
 License-File: LICENSE
@@ -44,7 +44,7 @@ Description-Content-Type: text/markdown
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml/badge.svg)](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml)
 
-> **Status: alpha (v0.2.1).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Not yet validated across a wide range of repos. API may change before 1.0.
+> **Status: alpha (v0.3.1).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Public benchmark proof exists for the current suite, but broader repo coverage is still growing. API may change before 1.0.
 >
 > **Platform note:** macOS and Linux are fully supported. Windows support is not yet implemented (git hooks use POSIX shell; the Claude Code session hooks use `python3`/`rm -f`). Contributions welcome.
 
@@ -80,11 +80,30 @@ AgentPack is useful when a repo is too large to paste, but a blank agent session
 ## Install
 
 ```bash
-pip install agentpack-cli
+pipx install agentpack-cli
 agentpack --version
 ```
 
-Requires Python 3.10+. The PyPI package is `agentpack-cli`; the command is `agentpack`.
+Requires Python 3.10+. The PyPI package is `agentpack-cli`; the command is `agentpack`. Use `pipx` for normal installs because many macOS/Linux Python distributions block global `pip install` with PEP 668's `externally-managed-environment` error. If you prefer `pip`, install inside a virtual environment.
+
+Install `pipx` with your OS package manager first if needed:
+
+```bash
+# macOS
+brew install pipx
+
+# Ubuntu/Debian
+sudo apt install pipx
+
+# Fedora
+sudo dnf install pipx
+
+# Arch
+sudo pacman -S python-pipx
+
+# Then ensure pipx apps are on PATH
+pipx ensurepath
+```
 
 JavaScript-heavy teams can install the npm wrapper:
 
@@ -93,7 +112,7 @@ npm install -g @vishal2612200/agentpack
 agentpack --version
 ```
 
-The npm package is a Node launcher around the Python implementation. It installs the matching `agentpack-cli` package into a per-version virtual environment on first run.
+The npm package is a Node launcher around the Python implementation. It requires Node.js 18+ and Python 3.10+, then installs the matching core `agentpack-cli` package into a per-version virtual environment on first run. The Python package remains the source of truth; npm is the convenience install path for JavaScript-heavy teams. Use the PyPI extras below when you need optional `watch` or `mcp` dependencies.
 
 ## Quickstart
 
@@ -454,7 +473,7 @@ jobs:
         with:
           python-version: "3.12"
 
-      - run: pip install agentpack-cli
+      - run: python -m pip install agentpack-cli
 
       - name: Generate context pack
         run: |
@@ -767,7 +786,7 @@ Uses `watchdog` if installed, falls back to polling. Context is refreshed whenev
 
 Install watchdog for better performance:
 ```bash
-pip install "agentpack-cli[watch]"
+pipx inject agentpack-cli watchdog
 ```
 
 ---
@@ -789,7 +808,7 @@ Requires an initialized project (`agentpack init`). Refreshes context, prints th
 Run AgentPack as an MCP server — exposes context packing as tools that Claude Code (and any MCP-compatible agent) can call directly.
 
 ```bash
-pip install "agentpack-cli[mcp]"
+pipx inject agentpack-cli "agentpack-cli[mcp]"
 agentpack mcp
 ```
 
@@ -1451,7 +1470,7 @@ src/agentpack/
 
 ## Roadmap
 
-Next release target: **0.3.0 = public proof + npm publish hardening**.
+Post-0.3 release focus: broader real-repo proof, npm publish reliability, and continued ranking precision.
 
 - Expand the public real-repo suite beyond the current curated Pallets smoke set.
 - Keep recall gains measured with `--prove-targets`; target 60%+ recall, 50%+ token precision, and task packs under 25k tokens.
@@ -1464,9 +1483,9 @@ Next release target: **0.3.0 = public proof + npm publish hardening**.
 ## Optional dependencies
 
 ```bash
-pip install "agentpack-cli[watch]"    # watchdog — faster file watching for agentpack watch
-pip install "agentpack-cli[mcp]"      # mcp — expose agentpack as MCP server tools
-pip install "agentpack-cli[all]"      # watch + mcp
+pipx inject agentpack-cli watchdog              # faster file watching for agentpack watch
+pipx inject agentpack-cli "agentpack-cli[mcp]"  # expose agentpack as MCP server tools
+pipx inject agentpack-cli "agentpack-cli[all]"  # watch + mcp
 ```
 
 ---
@@ -1495,7 +1514,7 @@ agentpack benchmark --sample-fixtures --misses
 agentpack doctor
 ```
 
-For npm publish, configure GitHub secret `NPM_TOKEN`. `agentpack doctor` warns locally when neither `NPM_TOKEN` nor `NODE_AUTH_TOKEN` is present, and the npm publish workflow fails early with a clear error if the secret is missing.
+For npm publish, configure GitHub secret `NPM_TOKEN`. The token must publish to the npm scope in `npm/package.json` (`@vishal2612200` today): use a token from that npm user, or create an npm org with that scope and grant the token owner publish access. If `npm publish` reaches the registry and then fails with `E404 Not Found - PUT ... @scope/package`, the token is authenticated but does not own or have write access to that scope. `agentpack doctor` warns locally when neither `NPM_TOKEN` nor `NODE_AUTH_TOKEN` is present, and the npm publish workflow fails early when the secret or scope access is wrong.
 
 Good contribution areas:
 

{agentpack_cli-0.2.2 → agentpack_cli-0.3.1}/README.md

@@ -5,7 +5,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml/badge.svg)](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml)
 
-> **Status: alpha (v0.2.1).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Not yet validated across a wide range of repos. API may change before 1.0.
+> **Status: alpha (v0.3.1).** Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Public benchmark proof exists for the current suite, but broader repo coverage is still growing. API may change before 1.0.
 >
 > **Platform note:** macOS and Linux are fully supported. Windows support is not yet implemented (git hooks use POSIX shell; the Claude Code session hooks use `python3`/`rm -f`). Contributions welcome.
 
@@ -41,11 +41,30 @@ AgentPack is useful when a repo is too large to paste, but a blank agent session
 ## Install
 
 ```bash
-pip install agentpack-cli
+pipx install agentpack-cli
 agentpack --version
 ```
 
-Requires Python 3.10+. The PyPI package is `agentpack-cli`; the command is `agentpack`.
+Requires Python 3.10+. The PyPI package is `agentpack-cli`; the command is `agentpack`. Use `pipx` for normal installs because many macOS/Linux Python distributions block global `pip install` with PEP 668's `externally-managed-environment` error. If you prefer `pip`, install inside a virtual environment.
+
+Install `pipx` with your OS package manager first if needed:
+
+```bash
+# macOS
+brew install pipx
+
+# Ubuntu/Debian
+sudo apt install pipx
+
+# Fedora
+sudo dnf install pipx
+
+# Arch
+sudo pacman -S python-pipx
+
+# Then ensure pipx apps are on PATH
+pipx ensurepath
+```
 
 JavaScript-heavy teams can install the npm wrapper:
 
@@ -54,7 +73,7 @@ npm install -g @vishal2612200/agentpack
 agentpack --version
 ```
 
-The npm package is a Node launcher around the Python implementation. It installs the matching `agentpack-cli` package into a per-version virtual environment on first run.
+The npm package is a Node launcher around the Python implementation. It requires Node.js 18+ and Python 3.10+, then installs the matching core `agentpack-cli` package into a per-version virtual environment on first run. The Python package remains the source of truth; npm is the convenience install path for JavaScript-heavy teams. Use the PyPI extras below when you need optional `watch` or `mcp` dependencies.
 
 ## Quickstart
 
@@ -415,7 +434,7 @@ jobs:
         with:
           python-version: "3.12"
 
-      - run: pip install agentpack-cli
+      - run: python -m pip install agentpack-cli
 
       - name: Generate context pack
         run: |
@@ -728,7 +747,7 @@ Uses `watchdog` if installed, falls back to polling. Context is refreshed whenev
 
 Install watchdog for better performance:
 ```bash
-pip install "agentpack-cli[watch]"
+pipx inject agentpack-cli watchdog
 ```
 
 ---
@@ -750,7 +769,7 @@ Requires an initialized project (`agentpack init`). Refreshes context, prints th
 Run AgentPack as an MCP server — exposes context packing as tools that Claude Code (and any MCP-compatible agent) can call directly.
 
 ```bash
-pip install "agentpack-cli[mcp]"
+pipx inject agentpack-cli "agentpack-cli[mcp]"
 agentpack mcp
 ```
 
@@ -1412,7 +1431,7 @@ src/agentpack/
 
 ## Roadmap
 
-Next release target: **0.3.0 = public proof + npm publish hardening**.
+Post-0.3 release focus: broader real-repo proof, npm publish reliability, and continued ranking precision.
 
 - Expand the public real-repo suite beyond the current curated Pallets smoke set.
 - Keep recall gains measured with `--prove-targets`; target 60%+ recall, 50%+ token precision, and task packs under 25k tokens.
@@ -1425,9 +1444,9 @@ Next release target: **0.3.0 = public proof + npm publish hardening**.
 ## Optional dependencies
 
 ```bash
-pip install "agentpack-cli[watch]"    # watchdog — faster file watching for agentpack watch
-pip install "agentpack-cli[mcp]"      # mcp — expose agentpack as MCP server tools
-pip install "agentpack-cli[all]"      # watch + mcp
+pipx inject agentpack-cli watchdog              # faster file watching for agentpack watch
+pipx inject agentpack-cli "agentpack-cli[mcp]"  # expose agentpack as MCP server tools
+pipx inject agentpack-cli "agentpack-cli[all]"  # watch + mcp
 ```
 
 ---
@@ -1456,7 +1475,7 @@ agentpack benchmark --sample-fixtures --misses
 agentpack doctor
 ```
 
-For npm publish, configure GitHub secret `NPM_TOKEN`. `agentpack doctor` warns locally when neither `NPM_TOKEN` nor `NODE_AUTH_TOKEN` is present, and the npm publish workflow fails early with a clear error if the secret is missing.
+For npm publish, configure GitHub secret `NPM_TOKEN`. The token must publish to the npm scope in `npm/package.json` (`@vishal2612200` today): use a token from that npm user, or create an npm org with that scope and grant the token owner publish access. If `npm publish` reaches the registry and then fails with `E404 Not Found - PUT ... @scope/package`, the token is authenticated but does not own or have write access to that scope. `agentpack doctor` warns locally when neither `NPM_TOKEN` nor `NODE_AUTH_TOKEN` is present, and the npm publish workflow fails early when the secret or scope access is wrong.
 
 Good contribution areas:
 

{agentpack_cli-0.2.2 → agentpack_cli-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentpack-cli"
-version = "0.2.2"
+version = "0.3.1"
 description = "Task-aware context packing for AI coding agents — Claude, Cursor, Windsurf, Codex, and Antigravity"
 readme = "README.md"
 requires-python = ">=3.10"

{agentpack_cli-0.2.2 → agentpack_cli-0.3.1}/src/agentpack/__init__.py

@@ -1,3 +1,3 @@
 """AgentPack — task-aware context packing for AI coding agents."""
 
-__version__ = "0.2.2"
+__version__ = "0.3.1"

{agentpack_cli-0.2.2 → agentpack_cli-0.3.1}/src/agentpack/analysis/ranking.py

@@ -160,6 +160,12 @@ _VARIANTS: dict[str, str] = {
     "middleware": "middleware",
     "request": "req",
     "response": "res",
+    "verification": "verify",
+    "verified": "verify",
+    "verifying": "verify",
+    "payments": "payment",
+    "webhooks": "webhook",
+    "variables": "variable",
     "session": "session",
     "sessions": "session",
     "error": "error",
@@ -226,6 +232,7 @@ _FILENAME_CORROBORATION_PREFIXES = (
     "staged",
     "symbol keyword match",
     "content keyword match",
+    "matched ",
     "direct dependency",
     "reverse dependency",
     "has related tests",
@@ -404,6 +411,82 @@ def _symbol_matches_keywords(symbols: list[str], keywords: set[str] | dict[str,
     return best_weight
 
 
+def _summary_values(summary: object, field: str) -> list[str]:
+    if summary is None:
+        return []
+    if isinstance(summary, dict):
+        value = summary.get(field)
+    else:
+        value = getattr(summary, field, None)
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, list):
+        result: list[str] = []
+        for item in value:
+            if isinstance(item, str):
+                result.append(item)
+            elif isinstance(item, dict) and "name" in item:
+                result.append(str(item["name"]))
+            elif hasattr(item, "name"):
+                result.append(str(item.name))
+            else:
+                result.append(str(item))
+        return result
+    return [str(value)]
+
+
+def _best_summary_match(
+    values: list[str],
+    keywords: set[str] | dict[str, float],
+    *,
+    presence_terms: set[str] | None = None,
+) -> tuple[str, float] | None:
+    if not values:
+        return None
+    best_value = ""
+    best_weight = 0.0
+    for value in values:
+        weight = _match_weight(value, keywords)
+        if weight > best_weight:
+            best_value = value
+            best_weight = weight
+    if best_weight > 0:
+        return best_value, best_weight
+    if presence_terms and (set(_keyword_token_weights(keywords)) & presence_terms):
+        return values[0], 0.6
+    return None
+
+
+def _short_reason_value(value: str, max_len: int = 80) -> str:
+    clean = " ".join(value.split())
+    if len(clean) <= max_len:
+        return clean
+    return clean[: max_len - 1].rstrip() + "..."
+
+
+_GENERIC_SUMMARY_VALUES = {
+    "HTTP API route handler",
+    "React UI component",
+    "React page component",
+    "React page: page",
+    "entrypoint",
+    "configuration",
+    "api",
+    "frontend",
+    "data",
+}
+
+
+def _summary_boost_weight(field: str, value: str, amount: float) -> float:
+    if field in {"role", "domain"} and value in _GENERIC_SUMMARY_VALUES:
+        return min(amount, 16.0)
+    if field == "ranking_keywords" and value in {"handler", "http", "route", "api", "component", "page"}:
+        return min(amount, 10.0)
+    return amount
+
+
 def _has_role(path: str, roles: set[str]) -> bool:
     return bool(_path_tokens(path) & roles)
 
@@ -463,17 +546,38 @@ def score_files(
 
         node = dep_graph.get(fi.path)
         sym_names: list[str] = []
-        if summaries and fi.path in summaries:
-            raw_syms = summaries[fi.path].get("symbols", [])
-            sym_names = [
-                (s["name"] if isinstance(s, dict) else s.name)
-                for s in raw_syms
-            ]
+        summary_data = summaries.get(fi.path) if summaries and fi.path in summaries else None
+        if summary_data:
+            sym_names = _summary_values(summary_data, "symbols")
         symbol_weight = _symbol_matches_keywords(sym_names, keywords)
         if symbol_weight > 0:
             score += w.symbol_keyword * symbol_weight
             reasons.append("symbol keyword match")
 
+        if summary_data:
+            summary_boosts = [
+                ("entrypoints", "matched entrypoint", 72.0, None),
+                ("external_systems", "matched external system", 64.0, None),
+                ("role", "matched role keyword", 56.0, None),
+                ("domain", "matched domain", 50.0, None),
+                ("ranking_keywords", "matched ranking keyword", 44.0, None),
+                ("defines", "matched define", 42.0, None),
+                ("reads_env", "matched env read", 52.0, {"env", "environment", "variable", "config", "settings"}),
+                ("side_effects", "matched side effect", 46.0, {"side", "effect", "effects", "io", "debug"}),
+                ("calls", "matched call", 26.0, None),
+            ]
+            for field, label, amount, presence_terms in summary_boosts:
+                match = _best_summary_match(
+                    _summary_values(summary_data, field),
+                    keywords,
+                    presence_terms=presence_terms,
+                )
+                if not match:
+                    continue
+                value, match_weight = match
+                score += _summary_boost_weight(field, value, amount) * match_weight
+                reasons.append(f"{label}: {_short_reason_value(value)}")
+
         content_hits = 0
         if fi.content is not None:
             hits, hit_weight = _content_matches_keywords(fi.content, keywords)

{agentpack_cli-0.2.2 → agentpack_cli-0.3.1}/src/agentpack/analysis/repo_map.py

@@ -44,7 +44,7 @@ def build_repo_map(
         top_members = sorted(members, key=lambda member: file_scores.get(member.path, 0.0), reverse=True)[:4]
         for member in top_members:
             summary = summaries.get(member.path) or {}
-            label = summary.get("role") or _short_summary(summary.get("summary", ""))
+            label = _member_label(summary)
             deps = dep_graph.get(member.path)
             rel = ""
             if deps.imports or deps.imported_by:
@@ -71,7 +71,12 @@ def _group_role(members: list[FileInfo], summaries: dict[str, Any]) -> str:
     roles: dict[str, int] = {}
     for member in members:
         summary = summaries.get(member.path) or {}
+        domain = summary.get("domain")
         role = summary.get("role") or _short_summary(summary.get("summary", ""))
+        if domain and role:
+            role = f"{domain} / {role}"
+        elif domain:
+            role = domain
         if role:
             roles[role] = roles.get(role, 0) + 1
     if not roles:
@@ -90,5 +95,19 @@ def _short_summary(summary: str) -> str:
     return ""
 
 
+def _member_label(summary: dict[str, Any]) -> str:
+    domain = summary.get("domain")
+    role = summary.get("role") or _short_summary(summary.get("summary", ""))
+    parts = []
+    if role:
+        parts.append(role)
+    elif domain:
+        parts.append(domain)
+    entrypoints = summary.get("entrypoints") or []
+    if entrypoints:
+        parts.append(str(entrypoints[0]))
+    return "; ".join(parts)
+
+
 def _fits(lines: list[str], candidate: str, budget_tokens: int) -> bool:
     return estimate_tokens("\n".join([*lines, candidate])) <= budget_tokens