contextpruner 0.1.0

package/README.md

@@ -0,0 +1,72 @@
+# contextpruner
+
+Lint your AI-context config files against your repo. `contextpruner lint` checks
+your `AGENTS.md` / `CLAUDE.md` / `GEMINI.md` / Copilot / Cursor rules against the
+files actually in your tree and reports:
+
+- **Missing** — junk the config doesn't ignore yet (with what it's costing you),
+- **Dead** — rules that match nothing,
+- **Drift** — rules in one config but not another,
+- **Conflict** — rules that contradict each other.
+
+It exits non-zero when it finds issues, so it drops straight into CI or a
+pre-commit hook.
+
+## Usage
+
+```sh
+export CONTEXTPRUNER_API_KEY=cp_live_...   # from https://contextpruner.app/account
+npx contextpruner lint
+```
+
+```
+contextpruner lint [--config <path>]... [--fix] [--json]
+```
+
+- `--config <path>` — a config to lint (repeatable). Defaults to auto-detecting
+  the standard files at the repo root.
+- `--fix` — rewrite each config's managed block in place to fix the issues. Your
+  own content outside the block (and the "Exceptions" section) is left alone.
+- `--json` — emit the full report as JSON.
+
+**Exit codes:** `0` clean · `1` issues found · `2` usage/auth error.
+
+## In CI
+
+Fail the build when a config drifts. Save this as
+`.github/workflows/contextpruner-lint.yml` and add your key as the repo secret
+`CONTEXTPRUNER_API_KEY`:
+
+```yaml
+name: ContextPruner Lint
+on: [push, pull_request]
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npx --yes contextpruner lint
+        env:
+          CONTEXTPRUNER_API_KEY: ${{ secrets.CONTEXTPRUNER_API_KEY }}
+```
+
+## Privacy
+
+The pruning engine runs **entirely on your machine** — your file tree never
+leaves it. The only network call is to `/api/license/verify`, which sends just
+your API key to confirm an active subscription.
+
+## Development
+
+The CLI bundles the app's pure engine at build time:
+
+```sh
+npm install   # in packages/cli
+npm run build # → dist/index.js
+```
+
+The published package name is `contextpruner`; the repository's root
+`package.json` is a separate private app that happens to share the name.

package/dist/index.js

@@ -0,0 +1,1066 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+// src/args.ts
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  if (command === void 0 || command === "--help" || command === "-h") {
+    return { command: "help", configs: [], json: false, fix: false };
+  }
+  if (command === "--version" || command === "-v") {
+    return { command: "version", configs: [], json: false, fix: false };
+  }
+  if (command !== "lint") {
+    return {
+      command: "unknown",
+      configs: [],
+      json: false,
+      fix: false,
+      problem: `unknown command "${command}"`
+    };
+  }
+  const configs = [];
+  let json = false;
+  let fix = false;
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === "--json") {
+      json = true;
+    } else if (arg === "--fix") {
+      fix = true;
+    } else if (arg === "--config") {
+      const value = rest[++i];
+      if (value === void 0) {
+        return { command: "lint", configs, json, fix, problem: "--config needs a path" };
+      }
+      configs.push(value);
+    } else if (arg === "--help" || arg === "-h") {
+      return { command: "help", configs: [], json: false, fix: false };
+    } else {
+      return {
+        command: "lint",
+        configs,
+        json,
+        fix,
+        problem: `unknown option "${arg}"`
+      };
+    }
+  }
+  return { command: "lint", configs, json, fix };
+}
+
+// ../../lib/shared/format.ts
+function formatPctReduction(ratio) {
+  return ratio >= 1 ? 100 : Math.min(99, Math.floor(Number((ratio * 100).toPrecision(12))));
+}
+
+// ../../lib/engine/generators/shared.ts
+function formatStatsLine(stats) {
+  const pct = stats.bytesTotal === 0 ? 0 : formatPctReduction(stats.bytesPruned / stats.bytesTotal);
+  return `${stats.filesPruned} of ${stats.filesTotal} files pruned (${pct}% smaller context)`;
+}
+var MANAGED_BLOCK_BEGIN = "<!-- contextpruner:begin -->";
+var MANAGED_BLOCK_END = "<!-- contextpruner:end -->";
+var MANAGED_BLOCK_NOTE = "<!-- generated block \u2014 edits inside are overwritten on regeneration -->";
+function generateMarkdownRules(filename, input) {
+  const lines = [
+    MANAGED_BLOCK_BEGIN,
+    MANAGED_BLOCK_NOTE,
+    "",
+    `# ${filename} \u2014 AI context rules (generated by ContextPruner)`,
+    "",
+    `Generated ${input.generatedAt}. ${formatStatsLine(input.stats)}.`,
+    "",
+    "## Ignore",
+    "",
+    "Do not read, index, or load these paths into context:",
+    ""
+  ];
+  for (const glob of input.excludeGlobs) {
+    lines.push(`- \`${glob}\``);
+  }
+  if (input.summarizeGlobs.length > 0) {
+    lines.push(
+      "",
+      "## Skim",
+      "",
+      "Summarize these instead of reading them in full:",
+      ""
+    );
+    for (const glob of input.summarizeGlobs) {
+      lines.push(`- \`${glob}\``);
+    }
+  }
+  if (input.priorityGlobs.length > 0) {
+    lines.push("", "## Focus", "", "Prioritize these paths when exploring:", "");
+    for (const glob of input.priorityGlobs) {
+      lines.push(`- \`${glob}\``);
+    }
+  }
+  if (input.keepOverridePaths.length > 0 || input.skimOverridePaths.length > 0 || input.pruneOverridePaths.length > 0) {
+    lines.push(
+      "",
+      "## Overrides",
+      "",
+      "The repo owner pinned these verdicts \u2014 they take precedence over every rule above:",
+      ""
+    );
+    for (const path of input.keepOverridePaths) {
+      lines.push(`- Keep (read normally): \`${path}\``);
+    }
+    for (const path of input.skimOverridePaths) {
+      lines.push(`- Skim (summarize only): \`${path}\``);
+    }
+    for (const path of input.pruneOverridePaths) {
+      lines.push(`- Prune (do not read): \`${path}\``);
+    }
+  }
+  lines.push(
+    "",
+    MANAGED_BLOCK_END,
+    "",
+    "## Exceptions (yours \u2014 edit freely)",
+    "",
+    "ContextPruner only sees paths and byte sizes \u2014 you know which",
+    "junk-shaped files actually matter in this repo. Rules you add here",
+    "are yours: when regenerating, replace only the marked block above",
+    "and keep this section.",
+    "",
+    "- _none yet \u2014 add repo-specific overrides here_",
+    ""
+  );
+  return lines.join("\n");
+}
+
+// ../../lib/shared/constants.ts
+var BYTES_PER_TOKEN_RATIO = 0.25;
+var USD_PER_1M_INPUT_TOKENS = 3;
+var PROMPTS_PER_DAY = 50;
+var WORKING_DAYS_PER_MONTH = 20;
+var PROMPTS_PER_MONTH = PROMPTS_PER_DAY * WORKING_DAYS_PER_MONTH;
+var CONTEXT_SLICE_FACTOR = 0.05;
+var DEFAULT_CONTEXT_WINDOW_TOKENS = 1e6;
+var MONTHLY_SAVINGS_CAP_USD = 200;
+var MAX_MANIFEST_FILES = 2e4;
+var OVERSIZED_FILE_BYTES = 1048576;
+
+// ../../lib/engine/rules.ts
+var LOCKFILE_BASENAMES = /* @__PURE__ */ new Set([
+  "package-lock.json",
+  "npm-shrinkwrap.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  "bun.lockb",
+  "bun.lock",
+  "deno.lock",
+  "composer.lock",
+  "Gemfile.lock",
+  "poetry.lock",
+  "uv.lock",
+  "pdm.lock",
+  "Pipfile.lock",
+  "Cargo.lock",
+  "go.sum",
+  "flake.lock",
+  "packages.lock.json",
+  "gradle.lockfile"
+]);
+var PRUNE_DIR_SEGMENT_REASONS = /* @__PURE__ */ new Map([
+  ["node_modules", "dependency-dir"],
+  ["vendor", "vendored-deps"],
+  [".venv", "dependency-dir"],
+  ["venv", "dependency-dir"],
+  ["dist", "build-output"],
+  ["build", "build-output"],
+  ["out", "build-output"],
+  [".next", "build-output"],
+  [".nuxt", "build-output"],
+  [".output", "build-output"],
+  ["target", "build-output"],
+  ["coverage", "test-coverage"],
+  [".nyc_output", "test-coverage"],
+  ["__snapshots__", "test-snapshot"],
+  [".git", "vcs-metadata"],
+  [".idea", "editor-metadata"],
+  [".vscode", "editor-metadata"],
+  ["__pycache__", "cache"],
+  [".pytest_cache", "cache"],
+  [".cache", "cache"],
+  [".turbo", "cache"],
+  ["fixtures", "test-fixture"],
+  ["__fixtures__", "test-fixture"],
+  ["testdata", "test-fixture"]
+]);
+var PRUNE_BASENAME_REASONS = /* @__PURE__ */ new Map([
+  [".DS_Store", "os-metadata"],
+  ["Thumbs.db", "os-metadata"],
+  ["LICENSE", "license"],
+  ["LICENSE.txt", "license"],
+  ["LICENSE.md", "license"],
+  ["NOTICE", "license"]
+]);
+var PRUNE_SUFFIX_REASONS = {
+  ".min.js": "minified",
+  ".min.css": "minified",
+  ".map": "source-map",
+  ".snap": "test-snapshot",
+  ".log": "log-file",
+  ".pyc": "compiled-artifact",
+  ".class": "compiled-artifact",
+  ".o": "compiled-artifact",
+  ".obj": "compiled-artifact"
+};
+var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
+  // images
+  "png",
+  "jpg",
+  "jpeg",
+  "gif",
+  "webp",
+  "avif",
+  "ico",
+  "bmp",
+  "tiff",
+  "svg",
+  // fonts
+  "woff",
+  "woff2",
+  "ttf",
+  "otf",
+  "eot",
+  // audio / video
+  "mp3",
+  "wav",
+  "ogg",
+  "flac",
+  "mp4",
+  "mov",
+  "avi",
+  "mkv",
+  "webm",
+  // archives
+  "zip",
+  "gz",
+  "tgz",
+  "bz2",
+  "xz",
+  "tar",
+  "rar",
+  "7z",
+  "jar",
+  "war",
+  // binaries / data blobs
+  "exe",
+  "dll",
+  "so",
+  "dylib",
+  "a",
+  "wasm",
+  "bin",
+  "dat",
+  "pdf",
+  "psd",
+  "sketch",
+  "fig",
+  "sqlite",
+  "db"
+]);
+var SUMMARIZE_EXTENSIONS = /* @__PURE__ */ new Set([
+  "md",
+  "mdx",
+  "markdown",
+  "rst",
+  "txt",
+  "adoc"
+]);
+
+// ../../lib/engine/classify.ts
+var ENV_EXEMPT_SUFFIXES = [".example", ".sample", ".template"];
+function classify(file) {
+  const { path, sizeInBytes } = file;
+  const segments = path.split("/");
+  const basename = segments[segments.length - 1];
+  const lowerBasename = basename.toLowerCase();
+  const dotIndex = lowerBasename.lastIndexOf(".");
+  const ext = dotIndex > 0 ? lowerBasename.slice(dotIndex + 1) : "";
+  const entry = (verdict, reason, glob) => ({ path, verdict, reason, sizeInBytes, glob });
+  if (basename.startsWith(".env") && !ENV_EXEMPT_SUFFIXES.some((suffix) => lowerBasename.endsWith(suffix))) {
+    return entry("PRUNE", "env-file", "**/.env*");
+  }
+  for (let i = 0; i < segments.length - 1; i++) {
+    const reason = PRUNE_DIR_SEGMENT_REASONS.get(segments[i]);
+    if (reason) {
+      const glob = i === 0 ? `${segments[0]}/**` : `**/${segments[i]}/**`;
+      return entry("PRUNE", reason, glob);
+    }
+  }
+  if (LOCKFILE_BASENAMES.has(basename)) {
+    return entry("PRUNE", "lockfile", segments.length === 1 ? path : `**/${basename}`);
+  }
+  const basenameReason = PRUNE_BASENAME_REASONS.get(basename);
+  if (basenameReason) {
+    return entry("PRUNE", basenameReason, `**/${basename}`);
+  }
+  for (const [suffix, reason] of Object.entries(PRUNE_SUFFIX_REASONS)) {
+    if (lowerBasename.endsWith(suffix) && lowerBasename !== suffix) {
+      return entry("PRUNE", reason, `**/*${suffix}`);
+    }
+  }
+  if (BINARY_EXTENSIONS.has(ext)) {
+    return entry("PRUNE", "binary-asset", `**/*.${ext}`);
+  }
+  if (sizeInBytes > OVERSIZED_FILE_BYTES) {
+    return entry("PRUNE", "oversized", path);
+  }
+  if (SUMMARIZE_EXTENSIONS.has(ext)) {
+    return entry("SUMMARIZE", "docs", `**/*.${ext}`);
+  }
+  return entry("KEEP", "source", null);
+}
+
+// ../../lib/engine/generators/agentsMd.ts
+function generateAgentsMd(input) {
+  return generateMarkdownRules("AGENTS.md", input);
+}
+
+// ../../lib/engine/generators/claudeMd.ts
+function generateClaudeMd(input) {
+  return generateMarkdownRules("CLAUDE.md", input);
+}
+
+// ../../lib/engine/generators/copilotInstructions.ts
+function generateCopilotInstructions(input) {
+  return generateMarkdownRules(".github/copilot-instructions.md", input);
+}
+
+// ../../lib/engine/generators/cursorMdc.ts
+function generateCursorMdc(input) {
+  const frontmatter = [
+    "---",
+    "description: Repo context-pruning rules generated by ContextPruner",
+    "alwaysApply: true",
+    "---",
+    ""
+  ].join("\n");
+  return frontmatter + generateMarkdownRules("Cursor rules", input);
+}
+
+// ../../lib/engine/generators/geminiMd.ts
+function generateGeminiMd(input) {
+  return generateMarkdownRules("GEMINI.md", input);
+}
+
+// ../../lib/engine/savings.ts
+function computeSavings(bytesTotal, bytesKept, options = {}) {
+  const price = options.usdPer1MInputTokens ?? USD_PER_1M_INPUT_TOKENS;
+  const promptsPerMonth = options.promptsPerMonth ?? PROMPTS_PER_MONTH;
+  const sliceFactor = options.contextSliceFactor ?? CONTEXT_SLICE_FACTOR;
+  const cap = options.monthlySpendCapUsd === void 0 ? MONTHLY_SAVINGS_CAP_USD : options.monthlySpendCapUsd;
+  const windowTokens = options.contextWindowTokens ?? DEFAULT_CONTEXT_WINDOW_TOKENS;
+  const bytesPruned = Math.max(0, bytesTotal - bytesKept);
+  const tokensSaved = Math.round(bytesPruned * BYTES_PER_TOKEN_RATIO);
+  const windowClamped = tokensSaved > windowTokens;
+  const tokensWastedPerPrompt = Math.min(tokensSaved, windowTokens) * sliceFactor;
+  const usdPerPrompt = tokensWastedPerPrompt / 1e6 * price;
+  const usdSavedPerMonthUncapped = usdPerPrompt * promptsPerMonth;
+  const capApplied = cap !== null && usdSavedPerMonthUncapped > cap;
+  const usdSavedPerMonth = Math.min(usdSavedPerMonthUncapped, cap ?? Infinity);
+  const pctReduction = bytesTotal === 0 ? 0 : bytesPruned / bytesTotal;
+  return {
+    bytesPruned,
+    tokensSaved,
+    tokensWastedPerPrompt,
+    usdPerPrompt,
+    usdSavedPerMonth,
+    usdSavedPerMonthUncapped,
+    capApplied,
+    windowClamped,
+    pctReduction
+  };
+}
+
+// ../../lib/engine/prune.ts
+var MAX_PRIORITY_GLOBS = 5;
+function prune(files, options = {}) {
+  const overrides = options.verdictOverrides ?? {};
+  const classified = files.map((file) => {
+    const base = classify(file);
+    const pinned = Object.hasOwn(overrides, file.path) ? overrides[file.path] : void 0;
+    if (pinned === void 0 || pinned === base.verdict) {
+      return base;
+    }
+    return {
+      ...base,
+      verdict: pinned,
+      glob: null,
+      overridden: true
+    };
+  });
+  let bytesTotal = 0;
+  let bytesKept = 0;
+  let filesPruned = 0;
+  const excludeGlobs = /* @__PURE__ */ new Set();
+  const summarizeGlobs = /* @__PURE__ */ new Set();
+  const keptBytesByDir = /* @__PURE__ */ new Map();
+  for (const file of classified) {
+    bytesTotal += file.sizeInBytes;
+    if (file.verdict === "PRUNE") {
+      filesPruned++;
+      if (file.glob) excludeGlobs.add(file.glob);
+    } else {
+      bytesKept += file.sizeInBytes;
+      if (file.verdict === "SUMMARIZE") {
+        if (file.glob) summarizeGlobs.add(file.glob);
+      } else if (!file.overridden) {
+        const slash = file.path.indexOf("/");
+        if (slash > 0) {
+          const dir = file.path.slice(0, slash);
+          keptBytesByDir.set(
+            dir,
+            (keptBytesByDir.get(dir) ?? 0) + file.sizeInBytes
+          );
+        }
+      }
+    }
+  }
+  const savings = computeSavings(bytesTotal, bytesKept, options);
+  const pinnedSavings = computeSavings(bytesTotal, bytesKept, {
+    usdPer1MInputTokens: options.usdPer1MInputTokens,
+    monthlySpendCapUsd: options.monthlySpendCapUsd,
+    contextWindowTokens: options.contextWindowTokens
+  });
+  const stats = {
+    filesTotal: classified.length,
+    filesKept: classified.length - filesPruned,
+    filesPruned,
+    bytesTotal,
+    bytesKept,
+    bytesPruned: savings.bytesPruned,
+    tokensSaved: savings.tokensSaved,
+    junkTokensPerPrompt: Math.round(pinnedSavings.tokensWastedPerPrompt),
+    dollarsPerPrompt: Math.round(pinnedSavings.usdPerPrompt * 1e4) / 1e4,
+    dollarsSavedPerMonth: Math.round(pinnedSavings.usdSavedPerMonth * 100) / 100,
+    dollarsSavedPerMonthUncapped: Math.round(pinnedSavings.usdSavedPerMonthUncapped * 100) / 100,
+    savingsCapped: pinnedSavings.capApplied,
+    windowClamped: pinnedSavings.windowClamped
+  };
+  for (const glob of options.extraExcludeGlobs ?? []) excludeGlobs.add(glob);
+  const priorityGlobs = [...keptBytesByDir.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, MAX_PRIORITY_GLOBS).map(([dir]) => `${dir}/**`);
+  const generatorInput = {
+    generatedAt: (options.now ?? /* @__PURE__ */ new Date()).toISOString(),
+    stats,
+    excludeGlobs: [...excludeGlobs].sort(),
+    summarizeGlobs: [...summarizeGlobs].sort(),
+    priorityGlobs,
+    keepOverridePaths: classified.filter((f) => f.overridden && f.verdict === "KEEP").map((f) => f.path).sort(),
+    skimOverridePaths: classified.filter((f) => f.overridden && f.verdict === "SUMMARIZE").map((f) => f.path).sort(),
+    pruneOverridePaths: classified.filter((f) => f.overridden && f.verdict === "PRUNE").map((f) => f.path).sort()
+  };
+  const verdicts = classified.map(
+    ({ path, verdict, reason, sizeInBytes, overridden }) => ({
+      path,
+      verdict,
+      reason,
+      sizeInBytes,
+      ...overridden ? { overridden: true } : {}
+    })
+  );
+  return {
+    version: 2,
+    generatedAt: generatorInput.generatedAt,
+    stats,
+    verdicts,
+    artifacts: {
+      agentsMd: generateAgentsMd(generatorInput),
+      claudeMd: generateClaudeMd(generatorInput),
+      cursorMdc: generateCursorMdc(generatorInput),
+      copilotInstructionsMd: generateCopilotInstructions(generatorInput),
+      geminiMd: generateGeminiMd(generatorInput)
+    }
+  };
+}
+
+// ../../lib/engine/lintFix.ts
+var ARTIFACT_BY_TITLE = {
+  "AGENTS.md": "agentsMd",
+  "CLAUDE.md": "claudeMd",
+  "GEMINI.md": "geminiMd",
+  ".github/copilot-instructions.md": "copilotInstructionsMd",
+  "Cursor rules": "cursorMdc"
+};
+var TITLE_RE = /^# (.+?) — AI context rules/m;
+function detectArtifact(block) {
+  const match = TITLE_RE.exec(block);
+  return match && ARTIFACT_BY_TITLE[match[1]] || "agentsMd";
+}
+function managedBlock(source) {
+  const begin = source.indexOf(MANAGED_BLOCK_BEGIN);
+  if (begin === -1) return null;
+  const endMarker = source.indexOf(
+    MANAGED_BLOCK_END,
+    begin + MANAGED_BLOCK_BEGIN.length
+  );
+  if (endMarker === -1) return null;
+  return source.slice(begin, endMarker + MANAGED_BLOCK_END.length);
+}
+function buildFixedConfig(files, userConfig, now, preserveExcludeGlobs) {
+  const userBlock = managedBlock(userConfig);
+  if (userBlock === null) {
+    return { fixable: false, changed: false, fixed: userConfig };
+  }
+  const artifact = detectArtifact(userBlock);
+  const corrected = prune(files, {
+    ...now ? { now } : {},
+    extraExcludeGlobs: preserveExcludeGlobs
+  }).artifacts[artifact];
+  const canonicalBlock = managedBlock(corrected);
+  if (canonicalBlock === null) {
+    return { fixable: false, changed: false, fixed: userConfig };
+  }
+  const begin = userConfig.indexOf(MANAGED_BLOCK_BEGIN);
+  const end = userConfig.indexOf(MANAGED_BLOCK_END, begin + MANAGED_BLOCK_BEGIN.length) + MANAGED_BLOCK_END.length;
+  const fixed = userConfig.slice(0, begin) + canonicalBlock + userConfig.slice(end);
+  return { fixable: true, changed: fixed !== userConfig, fixed };
+}
+
+// ../../lib/engine/parseConfig.ts
+var GLOB_BULLET = /^- `(.+)`$/;
+var OVERRIDE_BULLET = /^- (Keep|Skim|Prune) \([^)]*\): `(.+)`$/;
+var SECTION_HEADINGS = {
+  "## Ignore": "ignore",
+  "## Skim": "skim",
+  "## Focus": "focus",
+  "## Overrides": "overrides"
+};
+function empty(hasManagedBlock) {
+  return {
+    hasManagedBlock,
+    excludeGlobs: [],
+    summarizeGlobs: [],
+    priorityGlobs: [],
+    overrides: { keep: [], skim: [], prune: [] }
+  };
+}
+function parseConfig(source) {
+  const begin = source.indexOf(MANAGED_BLOCK_BEGIN);
+  if (begin === -1) return empty(false);
+  const end = source.indexOf(MANAGED_BLOCK_END, begin + MANAGED_BLOCK_BEGIN.length);
+  if (end === -1) return empty(false);
+  const config = empty(true);
+  const block = source.slice(begin + MANAGED_BLOCK_BEGIN.length, end);
+  let section = null;
+  for (const raw of block.split("\n")) {
+    const line = raw.trimEnd();
+    const heading = SECTION_HEADINGS[line];
+    if (heading) {
+      section = heading;
+      continue;
+    }
+    if (line.startsWith("## ")) {
+      section = null;
+      continue;
+    }
+    if (section === null) continue;
+    if (section === "overrides") {
+      const match2 = OVERRIDE_BULLET.exec(line);
+      if (!match2) continue;
+      const bucket = match2[1] === "Keep" ? "keep" : match2[1] === "Skim" ? "skim" : "prune";
+      config.overrides[bucket].push(match2[2]);
+      continue;
+    }
+    const match = GLOB_BULLET.exec(line);
+    if (!match) continue;
+    const glob = match[1];
+    if (section === "ignore") config.excludeGlobs.push(glob);
+    else if (section === "skim") config.summarizeGlobs.push(glob);
+    else config.priorityGlobs.push(glob);
+  }
+  return config;
+}
+
+// ../../lib/engine/globMatch.ts
+var ESCAPE = /[.+^${}()|[\]\\]/g;
+function globToRegExp(glob) {
+  let re = "";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        const atSegmentStart = i === 0 || glob[i - 1] === "/";
+        if (glob[i + 2] === "/" && atSegmentStart) {
+          re += "(?:[^/]+/)*";
+          i += 2;
+        } else {
+          re += ".*";
+          i += 1;
+        }
+      } else {
+        re += "[^/]*";
+      }
+    } else if (c === "?") {
+      re += "[^/]";
+    } else {
+      re += c.replace(ESCAPE, "\\$&");
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+function compileGlob(glob) {
+  const re = globToRegExp(glob);
+  return (path) => re.test(path);
+}
+
+// ../../lib/engine/reconcile.ts
+var SEVERITY_RANK = { high: 0, medium: 1, low: 2 };
+function gradeFor(coveragePct) {
+  if (coveragePct >= 95) return "A";
+  if (coveragePct >= 85) return "B";
+  if (coveragePct >= 70) return "C";
+  if (coveragePct >= 50) return "D";
+  return "F";
+}
+function tokensFor(bytes) {
+  return Math.round(bytes * BYTES_PER_TOKEN_RATIO);
+}
+function compileConfig({ name, source }) {
+  const parsed = parseConfig(source);
+  const excludeMatchers = parsed.excludeGlobs.map(compileGlob);
+  const summarizeMatchers = parsed.summarizeGlobs.map(compileGlob);
+  return {
+    ...parsed,
+    name,
+    excludeMatch: (path) => excludeMatchers.some((m) => m(path)),
+    summarizeMatch: (path) => summarizeMatchers.some((m) => m(path)),
+    keepSet: new Set(parsed.overrides.keep),
+    pruneSet: new Set(parsed.overrides.prune),
+    skimSet: new Set(parsed.overrides.skim)
+  };
+}
+function isAddressed(config, path) {
+  return config.keepSet.has(path) || config.pruneSet.has(path) || config.skimSet.has(path) || config.excludeMatch(path) || config.summarizeMatch(path);
+}
+function reconcile(files, configs, options = {}) {
+  const primary = configs[0];
+  const empty2 = {
+    configName: primary?.name ?? "",
+    configRecognized: false,
+    filesTotal: files.length,
+    grade: "\u2014",
+    coveragePct: 0,
+    dollarsLeaking: 0,
+    findings: []
+  };
+  if (!primary) return empty2;
+  const config = compileConfig(primary);
+  if (!config.hasManagedBlock) return empty2;
+  const classified = files.map((file) => ({ ...classify(file) }));
+  const paths = files.map((f) => f.path);
+  const bytesTotal = files.reduce((sum, f) => sum + f.sizeInBytes, 0);
+  const findings = [];
+  const missingBytesByGlob = /* @__PURE__ */ new Map();
+  for (const file of classified) {
+    if (file.verdict === "KEEP") continue;
+    if (isAddressed(config, file.path)) continue;
+    const glob = file.glob ?? file.path;
+    const entry = missingBytesByGlob.get(glob) ?? {
+      verdict: file.verdict,
+      bytes: 0
+    };
+    entry.bytes += file.sizeInBytes;
+    missingBytesByGlob.set(glob, entry);
+  }
+  for (const [glob, { verdict, bytes }] of missingBytesByGlob) {
+    const tokens2 = tokensFor(bytes);
+    const severity = verdict === "SUMMARIZE" ? "low" : tokens2 >= 1e4 ? "high" : "medium";
+    findings.push({
+      kind: "missing",
+      severity,
+      glob,
+      tokens: tokens2,
+      message: verdict === "SUMMARIZE" ? `Docs matching \`${glob}\` aren't marked to skim` : `Junk matching \`${glob}\` isn't ignored`
+    });
+  }
+  const allConfigGlobs = [
+    ...config.excludeGlobs,
+    ...config.summarizeGlobs,
+    ...config.priorityGlobs
+  ];
+  for (const glob of allConfigGlobs) {
+    if (!paths.some(compileGlob(glob))) {
+      findings.push({
+        kind: "dead",
+        severity: "low",
+        glob,
+        message: `Rule \`${glob}\` matches no files`
+      });
+    }
+  }
+  const bucketsByPath = /* @__PURE__ */ new Map();
+  for (const [bucket, list] of [
+    ["Keep", config.overrides.keep],
+    ["Skim", config.overrides.skim],
+    ["Prune", config.overrides.prune]
+  ]) {
+    for (const path of list) {
+      const seen = bucketsByPath.get(path) ?? [];
+      seen.push(bucket);
+      bucketsByPath.set(path, seen);
+    }
+  }
+  for (const [path, buckets] of bucketsByPath) {
+    if (buckets.length > 1) {
+      findings.push({
+        kind: "conflict",
+        severity: "medium",
+        path,
+        message: `\`${path}\` is pinned to conflicting verdicts (${buckets.join(" + ")})`
+      });
+    }
+  }
+  const excludeSet = new Set(config.excludeGlobs);
+  for (const glob of config.priorityGlobs) {
+    if (excludeSet.has(glob)) {
+      findings.push({
+        kind: "conflict",
+        severity: "medium",
+        glob,
+        message: `\`${glob}\` is both a Focus and an Ignore rule`
+      });
+    }
+  }
+  for (let i = 1; i < configs.length; i++) {
+    const other = compileConfig(configs[i]);
+    if (!other.hasManagedBlock) continue;
+    for (const [label, a, b] of [
+      ["Ignore", config.excludeGlobs, other.excludeGlobs],
+      ["Skim", config.summarizeGlobs, other.summarizeGlobs],
+      ["Focus", config.priorityGlobs, other.priorityGlobs]
+    ]) {
+      const bSet = new Set(b);
+      const aSet = new Set(a);
+      for (const glob of a) {
+        if (!bSet.has(glob)) {
+          findings.push({
+            kind: "drift",
+            severity: "medium",
+            glob,
+            message: `${label} \`${glob}\` is in ${config.name} but not ${other.name}`
+          });
+        }
+      }
+      for (const glob of b) {
+        if (!aSet.has(glob)) {
+          findings.push({
+            kind: "drift",
+            severity: "medium",
+            glob,
+            message: `${label} \`${glob}\` is in ${other.name} but not ${config.name}`
+          });
+        }
+      }
+    }
+  }
+  let junkBytes = 0;
+  let prunedBytes = 0;
+  for (const file of classified) {
+    if (file.verdict !== "PRUNE") continue;
+    if (config.keepSet.has(file.path)) continue;
+    junkBytes += file.sizeInBytes;
+    if (config.pruneSet.has(file.path) || config.excludeMatch(file.path)) {
+      prunedBytes += file.sizeInBytes;
+    }
+  }
+  const coveragePct = junkBytes === 0 ? 100 : Math.floor(prunedBytes / junkBytes * 100);
+  const full = computeSavings(bytesTotal, bytesTotal - junkBytes, options).usdSavedPerMonth;
+  const achieved = computeSavings(bytesTotal, bytesTotal - prunedBytes, options).usdSavedPerMonth;
+  const dollarsLeaking = Math.max(0, Math.floor((full - achieved) * 100) / 100);
+  findings.sort(
+    (a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] || a.kind.localeCompare(b.kind) || (a.glob ?? "").localeCompare(b.glob ?? "")
+  );
+  return {
+    configName: config.name,
+    configRecognized: true,
+    filesTotal: files.length,
+    grade: gradeFor(coveragePct),
+    coveragePct,
+    dollarsLeaking,
+    findings
+  };
+}
+
+// src/format.ts
+var KIND = {
+  missing: { symbol: "\u2717", label: "MISSING" },
+  conflict: { symbol: "\u2717", label: "CONFLICT" },
+  dead: { symbol: "\u26A0", label: "DEAD" },
+  drift: { symbol: "~", label: "DRIFT" }
+};
+function tokens(n) {
+  return n >= 1e3 ? `~${Math.round(n / 1e3)}k tokens` : `~${n} tokens`;
+}
+function exitCodeFor(report) {
+  if (!report.configRecognized) return 2;
+  return report.findings.length > 0 ? 1 : 0;
+}
+function formatReport(report) {
+  const lines = ["", `ContextPruner \u2014 ${report.configName}`, ""];
+  if (!report.configRecognized) {
+    lines.push(
+      "  This isn't a ContextPruner-generated config (no managed block).",
+      "  Generate one at https://contextpruner.app.",
+      ""
+    );
+    return lines.join("\n");
+  }
+  if (report.findings.length === 0) {
+    lines.push("  \u2713 No issues \u2014 this config matches the tree.");
+  } else {
+    for (const f of report.findings) {
+      const { symbol, label } = KIND[f.kind];
+      const suffix = f.tokens ? `   (${tokens(f.tokens)})` : "";
+      lines.push(`  ${symbol} ${label.padEnd(9)}${f.message}${suffix}`);
+    }
+  }
+  const dollars = report.dollarsLeaking > 0 ? ` \xB7 ~$${report.dollarsLeaking.toFixed(2)}/mo leaking` : "";
+  lines.push(
+    "",
+    `  Grade ${report.grade} \xB7 ${report.coveragePct}% of junk covered${dollars} \xB7 ${report.filesTotal.toLocaleString("en-US")} files`,
+    ""
+  );
+  return lines.join("\n");
+}
+
+// src/manifest.ts
+function buildManifest(deps) {
+  const paths = deps.listTrackedFiles();
+  const truncated = paths.length > MAX_MANIFEST_FILES;
+  const files = [];
+  for (const path of paths.slice(0, MAX_MANIFEST_FILES)) {
+    let size;
+    try {
+      size = deps.sizeOf(path);
+    } catch {
+      continue;
+    }
+    if (Number.isFinite(size)) files.push({ path, sizeInBytes: size });
+  }
+  return { files, truncated };
+}
+
+// src/verify.ts
+var ACCOUNT = "https://contextpruner.app/account";
+async function verifyKey(opts) {
+  const doFetch = opts.fetchImpl ?? fetch;
+  let res;
+  try {
+    res = await doFetch(`${opts.baseUrl}/api/license/verify`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${opts.key}` }
+    });
+  } catch {
+    return {
+      ok: false,
+      kind: "error",
+      message: "Couldn't reach ContextPruner to verify your key (network error)."
+    };
+  }
+  if (res.status === 200) return { ok: true };
+  if (res.status === 401) {
+    return {
+      ok: false,
+      kind: "invalid_key",
+      message: `Invalid API key. Create or rotate one at ${ACCOUNT}.`
+    };
+  }
+  if (res.status === 402) {
+    return {
+      ok: false,
+      kind: "inactive",
+      message: `Subscription inactive. Manage billing at ${ACCOUNT}.`
+    };
+  }
+  if (res.status === 429) {
+    const retryAfter = res.headers.get("retry-after") ?? await res.json().then((b) => b.retryAfter).catch(() => void 0) ?? 60;
+    return {
+      ok: false,
+      kind: "rate_limited",
+      message: `Rate limited \u2014 retry in ${retryAfter}s.`
+    };
+  }
+  return {
+    ok: false,
+    kind: "error",
+    message: `Key verification failed (HTTP ${res.status}).`
+  };
+}
+
+// src/run.ts
+var DEFAULT_CONFIG_PATHS = [
+  "AGENTS.md",
+  "CLAUDE.md",
+  "GEMINI.md",
+  ".github/copilot-instructions.md",
+  ".cursor/rules/contextpruner.mdc"
+];
+var CREATE_KEY = "Set CONTEXTPRUNER_API_KEY (create one at https://contextpruner.app/account).";
+function dirNameOf(glob) {
+  return glob.match(/^([^*/]+)\/\*\*$/)?.[1] ?? glob.match(/^\*\*\/([^*/]+)\/\*\*$/)?.[1] ?? null;
+}
+function isFalseDead(finding) {
+  if (finding.kind !== "dead" || !finding.glob) return false;
+  const dir = dirNameOf(finding.glob);
+  return dir !== null && PRUNE_DIR_SEGMENT_REASONS.has(dir);
+}
+function hasRuleChange(before, after) {
+  const normalize = (s) => s.replace(/Generated \S+Z\./, "Generated <ts>.");
+  return normalize(before) !== normalize(after);
+}
+async function runLint(deps) {
+  if (!deps.key) {
+    return { text: `No API key. ${CREATE_KEY}`, exitCode: 2, channel: "stderr" };
+  }
+  const verified = await verifyKey({
+    key: deps.key,
+    baseUrl: deps.baseUrl,
+    fetchImpl: deps.fetchImpl
+  });
+  if (!verified.ok)
+    return { text: verified.message, exitCode: 2, channel: "stderr" };
+  const configs = [];
+  for (const path of deps.configPaths) {
+    const source = deps.readConfig(path);
+    if (source !== null) configs.push({ name: path, source });
+  }
+  if (configs.length === 0) {
+    return {
+      text: `No config files found (${deps.configPaths.join(", ")}). Generate one at https://contextpruner.app.`,
+      exitCode: 2,
+      channel: "stderr"
+    };
+  }
+  const { files, truncated } = buildManifest(deps);
+  if (truncated) {
+    return {
+      text: `This repo has more than ${MAX_MANIFEST_FILES.toLocaleString("en-US")} tracked files. Lint needs the whole tree to be accurate \u2014 check out a narrower path.`,
+      exitCode: 2,
+      channel: "stderr"
+    };
+  }
+  if (files.length === 0) {
+    return { text: "No tracked files found.", exitCode: 2, channel: "stderr" };
+  }
+  if (deps.fix) {
+    const fixed = [];
+    const unfixable = [];
+    for (const { name, source } of configs) {
+      const spared = parseConfig(source).excludeGlobs.filter((glob) => {
+        const dir = dirNameOf(glob);
+        return dir !== null && PRUNE_DIR_SEGMENT_REASONS.has(dir);
+      });
+      const result = buildFixedConfig(files, source, void 0, spared);
+      if (!result.fixable) {
+        unfixable.push(name);
+      } else if (hasRuleChange(source, result.fixed)) {
+        deps.writeConfig(name, result.fixed);
+        fixed.push(name);
+      }
+    }
+    if (fixed.length > 0) {
+      return {
+        text: `Fixed ${fixed.join(", ")}. Re-run without --fix to confirm.`,
+        exitCode: 0,
+        channel: "stdout"
+      };
+    }
+    if (unfixable.length === configs.length) {
+      return {
+        text: `Nothing to fix \u2014 ${unfixable.join(", ")} ${unfixable.length === 1 ? "has" : "have"} no ContextPruner managed block.`,
+        exitCode: 2,
+        channel: "stderr"
+      };
+    }
+    const skipped = unfixable.length > 0 ? ` Skipped ${unfixable.join(", ")} (no ContextPruner managed block).` : "";
+    return {
+      text: `Nothing to fix \u2014 your configs already match the tree.${skipped}`,
+      exitCode: 0,
+      channel: "stdout"
+    };
+  }
+  const report = reconcile(files, configs);
+  const kept = report.findings.filter((f) => !isFalseDead(f));
+  const filtered = { ...report, findings: kept };
+  const text = deps.json ? JSON.stringify(filtered, null, 2) : formatReport(filtered);
+  return { text, exitCode: exitCodeFor(filtered), channel: "stdout" };
+}
+
+// src/index.ts
+var VERSION = "0.1.0";
+var HELP = `contextpruner lint \u2014 check your AI-context config against your repo
+
+Usage:
+  contextpruner lint [--config <path>]... [--json]
+
+Options:
+  --config <path>   A config to lint (repeatable). Default: auto-detect
+                    AGENTS.md, CLAUDE.md, GEMINI.md, Copilot, and Cursor rules.
+  --fix             Rewrite each config's managed block in place to fix the
+                    issues. Your own content outside the block is left alone.
+  --json            Emit the full report as JSON.
+  -h, --help        Show this help.
+  -v, --version     Show the version.
+
+Auth:
+  export CONTEXTPRUNER_API_KEY=cp_live_...   (create one at
+  https://contextpruner.app/account). Only your key is sent \u2014 the file tree
+  never leaves your machine.
+
+Exit codes: 0 clean \xB7 1 issues found \xB7 2 usage/auth error.`;
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.command === "help") {
+    console.log(HELP);
+    return 0;
+  }
+  if (args.command === "version") {
+    console.log(VERSION);
+    return 0;
+  }
+  if (args.command !== "lint" || args.problem) {
+    console.error(`contextpruner: ${args.problem ?? "invalid usage"}
+
+${HELP}`);
+    return 2;
+  }
+  const cwd = process.cwd();
+  const { text, exitCode, channel } = await runLint({
+    key: process.env.CONTEXTPRUNER_API_KEY,
+    baseUrl: process.env.CONTEXTPRUNER_API_URL ?? "https://contextpruner.app",
+    configPaths: args.configs.length > 0 ? args.configs : DEFAULT_CONFIG_PATHS,
+    json: args.json,
+    fix: args.fix,
+    listTrackedFiles: () => execFileSync("git", ["ls-files", "-z"], {
+      cwd,
+      maxBuffer: 256 * 1024 * 1024
+    }).toString("utf8").split("\0").filter(Boolean),
+    sizeOf: (path) => statSync(join(cwd, path)).size,
+    readConfig: (path) => existsSync(join(cwd, path)) ? readFileSync(join(cwd, path), "utf8") : null,
+    writeConfig: (path, content) => writeFileSync(join(cwd, path), content, "utf8")
+  });
+  if (channel === "stderr") {
+    console.error(text);
+  } else {
+    console.log(text);
+  }
+  return exitCode;
+}
+main().then((code) => {
+  process.exitCode = code;
+}).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`contextpruner: ${message}`);
+  process.exitCode = 2;
+});

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "contextpruner",
+  "version": "0.1.0",
+  "description": "Lint your AI-context config files (AGENTS.md, CLAUDE.md, GEMINI.md, Cursor rules) against your repo — find missing, dead, drifting, and conflicting rules.",
+  "keywords": [
+    "AGENTS.md",
+    "CLAUDE.md",
+    "cursor rules",
+    "ai",
+    "context",
+    "lint"
+  ],
+  "homepage": "https://contextpruner.app",
+  "type": "module",
+  "bin": {
+    "contextpruner": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "prepublishOnly": "node build.mjs"
+  },
+  "devDependencies": {
+    "esbuild": "^0.24.0"
+  }
+}