@vishal2612200/agentpack 0.3.0 → 0.3.4

package/README.md

@@ -1,10 +1,32 @@
 # AgentPack
 
-Task-aware context packing for AI coding agents.
+[![npm version](https://img.shields.io/npm/v/@vishal2612200/agentpack.svg)](https://www.npmjs.com/package/@vishal2612200/agentpack)
+[![npm downloads](https://img.shields.io/npm/dm/@vishal2612200/agentpack.svg)](https://www.npmjs.com/package/@vishal2612200/agentpack)
+[![PyPI core](https://img.shields.io/pypi/v/agentpack-cli.svg)](https://pypi.org/project/agentpack-cli/)
+[![CI](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml/badge.svg)](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml)
 
-AgentPack scans a repository locally, ranks the files that matter for the current task, and writes a compact markdown context pack for tools such as Claude Code, Cursor, Windsurf, Codex, Antigravity, CI jobs, and generic LLM workflows.
+> **Status: alpha (v0.3.4).** 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, Linux, and Windows are supported. Windows support targets PowerShell plus Git for Windows.
 
-Use it when the repo is too large to paste, but a blank agent session keeps wasting time rediscovering routes, services, tests, configs, and recent changes.
+**Local context engine for AI coding agents.**
+
+AgentPack analyzes your repo locally, finds the relevant files for a task, and packages compact task-focused context packs for Claude Code, Codex, Cursor, Windsurf, Antigravity, MCP tools and workflows, CI jobs, and other agent workflows.
+
+Use it when the repo is too large to paste and you want faster, more consistent context around the files, routes, services, tests, configs, and recent changes that actually matter.
+
+This npm package is a launcher and wrapper for the Python CLI [`agentpack-cli`](https://pypi.org/project/agentpack-cli/), giving JavaScript-heavy teams a familiar install path while keeping the Python implementation as the source of truth.
+
+AgentPack is a context preparation tool, not a coding agent. It stays local, deterministic, and explainable: no hosted LLM calls, no embeddings, and no vector database for scan, summarize, rank, pack, stats, or benchmark.
+
+## Features
+
+- **Task-focused packing**: ranks files from git changes, task terms, symbols, imports, related tests, configs, churn, repo history, and deterministic offline summaries.
+- **Budget-aware compression**: emits `full`, `diff`, `symbols`, `skeleton`, or `summary` views instead of all-or-nothing file dumps.
+- **Local code intelligence**: extracts roles, domains, entrypoints, definitions, dependencies, env reads, side effects, and external systems using static analysis.
+- **Agent integrations**: installs Claude Code, Cursor, Windsurf, Codex, Antigravity, VS Code tasks, git hooks, and MCP configuration.
+- **Freshness and deltas**: records task source, git state, snapshot hashes, selected-file deltas, and stale-context warnings.
+- **Measurable quality**: benchmark expected-file recall, token efficiency, misses, and public smoke suites.
 
 ## What this npm package is
 
@@ -30,9 +52,7 @@ Requirements:
 
 - Node.js 18+
 - Python 3.10+
-- macOS or Linux
-
-Windows is not supported directly yet. Use WSL, or install `agentpack-cli` inside a Linux environment.
+- macOS, Linux, or Windows with PowerShell plus Git for Windows
 
 ## First project
 
@@ -61,6 +81,45 @@ For a guided setup:
 agentpack quickstart --task "fix auth token expiry"
 ```
 
+## Project scope
+
+AgentPack is:
+
+- A local context engine for building task-focused packs for AI coding agents.
+- A CLI, MCP server, hook runner, and integration layer.
+- A summary cache, import graph, ranking engine, semantic repo map, and token-budget selector.
+- An eval harness for measuring whether selected files match files you actually changed.
+
+AgentPack is not:
+
+- A coding agent.
+- A hosted service.
+- A semantic code search engine.
+- A replacement for normal source inspection on critical changes.
+- Proven across a large public benchmark suite yet.
+
+## Quality bar
+
+AgentPack is best treated as a ranked starting map. It should reduce repeated orientation work, but the agent and reviewer still own correctness.
+
+| Signal | What good looks like |
+|---|---|
+| Token reduction | 90-99% smaller than raw repo text on large repos |
+| Pack size | Usually 8k-25k tokens for a specific task |
+| Pack time | Seconds on a warm cache; first summarize pass is slower |
+| Recall | Expected files appear near the top; validate with `agentpack benchmark --misses` |
+| Precision | Good enough to reduce exploration; summaries and repo maps may still include noise |
+| Freshness | Stale packs are clearly marked by task, git, and snapshot checks |
+
+Use real repo evals instead of trusting compression numbers:
+
+```bash
+agentpack benchmark --init
+# add historical tasks and files actually changed
+agentpack benchmark --compare --misses --public-table
+agentpack benchmark --public-repos --prove-targets --misses --public-table
+```
+
 ## Daily workflow
 
 ```bash
@@ -81,19 +140,23 @@ agentpack repair --agent all
 
 ## Optional watch and MCP workflows
 
-The `watch` and `mcp` commands use optional Python dependencies. If you need those workflows today, install the Python package with extras:
+The `watch` and `mcp` commands use optional Python dependencies. If you need those workflows today, add the Python extras to a `pipx` install or use a virtual environment. Avoid global `pip3 install` on system-managed Python: many macOS/Linux distributions block it with PEP 668's `externally-managed-environment`.
 
 ```bash
-python -m pip install "agentpack-cli[all]"
-agentpack watch
-agentpack mcp
+pipx install agentpack-cli
+pipx inject agentpack-cli "agentpack-cli[all]"
+PIPX_AGENTPACK="$(pipx environment --value PIPX_BIN_DIR)/agentpack"
+"$PIPX_AGENTPACK" watch
+"$PIPX_AGENTPACK" mcp
 ```
 
-The npm wrapper still works well for the core setup, pack, status, doctor, explain, repair, and benchmark commands.
+Install `pipx` with your OS package manager first if needed: `brew install pipx`, `sudo apt install pipx`, `sudo dnf install pipx`, or `sudo pacman -S python-pipx`; then run `pipx ensurepath`.
+
+Use the explicit `pipx` binary path above for `watch` and `mcp` so those commands do not resolve back to the npm wrapper on PATH. The npm wrapper still works well for the core setup, pack, status, doctor, explain, repair, and benchmark commands.
 
 ## Python selection
 
-By default, the wrapper tries `python3` and then `python`. To force a specific interpreter:
+By default, the wrapper tries the Windows `py -3` launcher on `win32`, then `python3`, then `python`. To force a specific interpreter:
 
 ```bash
 AGENTPACK_PYTHON=/opt/homebrew/bin/python3 agentpack --version
@@ -125,18 +188,27 @@ To force a clean reinstall of the Python CLI for this npm package version, remov
 
 `agentpack npm wrapper: Python >=3.10 is required.`
 
-Install Python 3.10+ or set `AGENTPACK_PYTHON=/path/to/python3`.
+Install Python 3.10+ or set `AGENTPACK_PYTHON=/path/to/python3` (or `python.exe` on Windows).
 
 `failed to install agentpack-cli==<version>`
 
-Check that `python -m pip` can reach PyPI. Corporate networks may need standard pip index or proxy configuration.
+Check that Python can reach PyPI. Corporate networks may need standard package index or proxy configuration. Avoid global `pip3 install` on system-managed Python; many macOS/Linux distributions block it with PEP 668's `externally-managed-environment`. Use `pipx` or a virtual environment for direct Python installs.
+
+Optional Python `watch` and `mcp` extras can be added to a `pipx` install:
+
+```bash
+pipx install agentpack-cli
+pipx inject agentpack-cli "agentpack-cli[all]"
+```
+
+Install `pipx` with your OS package manager first if needed: `brew install pipx`, `sudo apt install pipx`, `sudo dnf install pipx`, or `sudo pacman -S python-pipx`; then run `pipx ensurepath`.
 
 `agentpack: command not found`
 
 Make sure your global npm bin directory is on `PATH`:
 
 ```bash
-npm bin -g
+printf '%s/bin\n' "$(npm prefix -g)"
 ```
 
 ## Security and privacy

package/bin/agentpack.js

@@ -6,7 +6,7 @@ const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
 
-const PACKAGE_VERSION = "0.3.0";
+const PACKAGE_VERSION = "0.3.4";
 const PYPI_PACKAGE = `agentpack-cli==${PACKAGE_VERSION}`;
 
 function compareVersions(left, right) {
@@ -35,7 +35,8 @@ function fail(message, code = 1) {
 }
 
 function pythonVersion(python) {
-  const result = run(python, [
+  const result = run(python.command, [
+    ...python.args,
     "-c",
     "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')",
   ]);
@@ -47,15 +48,16 @@ function pythonVersion(python) {
 
 function findPython() {
   const candidates = [
-    process.env.AGENTPACK_PYTHON,
-    "python3",
-    "python",
+    process.env.AGENTPACK_PYTHON ? { command: process.env.AGENTPACK_PYTHON, args: [] } : null,
+    process.platform === "win32" ? { command: "py", args: ["-3"] } : null,
+    { command: "python3", args: [] },
+    { command: "python", args: [] },
   ].filter(Boolean);
 
   for (const candidate of candidates) {
     const version = pythonVersion(candidate);
     if (version && compareVersions(version, "3.10") >= 0) {
-      return { command: candidate, version };
+      return { ...candidate, version };
     }
   }
   return null;
@@ -65,7 +67,9 @@ function cacheRoot() {
   if (process.env.AGENTPACK_NPM_CACHE_DIR) {
     return process.env.AGENTPACK_NPM_CACHE_DIR;
   }
-  const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache");
+  const base = process.platform === "win32"
+    ? (process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local"))
+    : (process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache"));
   return path.join(base, "agentpack-npm", PACKAGE_VERSION);
 }
 
@@ -80,12 +84,6 @@ function venvPaths(root) {
   };
 }
 
-function ensureSupportedPlatform() {
-  if (process.platform === "win32") {
-    fail("Windows is not supported yet. Please use macOS/Linux or install agentpack-cli directly in WSL.");
-  }
-}
-
 function installOrUpdateVenv(systemPython, paths) {
   const marker = fs.existsSync(paths.marker) ? fs.readFileSync(paths.marker, "utf8").trim() : "";
   if (marker === PACKAGE_VERSION && fs.existsSync(paths.agentpack)) {
@@ -94,7 +92,7 @@ function installOrUpdateVenv(systemPython, paths) {
 
   fs.mkdirSync(path.dirname(paths.marker), { recursive: true });
 
-  let result = run(systemPython, ["-m", "venv", paths.venv], { stdio: "inherit" });
+  let result = run(systemPython.command, [...systemPython.args, "-m", "venv", paths.venv], { stdio: "inherit" });
   if (result.status !== 0) {
     fail(`failed to create Python virtual environment at ${paths.venv}`);
   }
@@ -126,11 +124,9 @@ function main(argv = process.argv.slice(2)) {
     return;
   }
 
-  ensureSupportedPlatform();
-
   const python = findPython();
   if (!python) {
-    fail("Python >=3.10 is required. Install Python, or set AGENTPACK_PYTHON=/path/to/python.");
+    fail("Python >=3.10 is required. Install Python, set AGENTPACK_PYTHON=/path/to/python, or use the Windows py launcher.");
   }
 
   installOrUpdateVenv(python.command, paths);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vishal2612200/agentpack",
-  "version": "0.3.0",
-  "description": "Task-aware context packing for AI coding agents. npm wrapper for the Python AgentPack CLI.",
+  "version": "0.3.4",
+  "description": "npm launcher for the Python AgentPack CLI, a local context engine for AI coding agents that ranks relevant files and builds task-focused context packs.",
   "license": "MIT",
   "homepage": "https://github.com/vishal2612200/agentpack#readme",
   "repository": {
@@ -28,15 +28,25 @@
     "node": ">=18"
   },
   "keywords": [
-    "ai",
-    "cli",
-    "claude",
+    "ai-coding-agents",
+    "developer-tools",
+    "repo-analysis",
+    "context-engine",
+    "context-packing",
+    "prompt-context",
+    "mcp",
+    "ci",
+    "claude-code",
     "codex",
-    "context",
     "cursor",
+    "windsurf",
     "antigravity",
+    "ai",
     "llm",
+    "context",
     "packing",
-    "windsurf"
+    "claude",
+    "npm",
+    "cli"
   ]
 }