repo-context-center 0.1.3 → 0.1.4

package/README.md

@@ -4,6 +4,13 @@ A context layer for AI coding agents.
 
 `repo-context-center` installs a small set of repository instructions and context maps into a target repo so AI coding tools can find the right context faster and avoid rereading noisy files.
 
+Measure estimated context token savings before using the repo.
+
+```sh
+repo-context-center estimate --compare-naive
+repo-context-center estimate --task "fix Cypress test" --mode compact
+```
+
 It is not an AI agent. It is not a code analyzer. It does not understand your project automatically yet. It gives agents a durable place to store routing notes, module maps, risk notes, token guidance, and lessons learned.
 
 It is designed to work with Codex, Claude Code, Cursor, Copilot-style agents, and other tools that read repository instructions.
@@ -120,13 +127,15 @@ Estimate context overhead:
 
 ```sh
 repo-context-center estimate --compare-naive
-repo-context-center estimate --mode investigation --task "fix auth bug" --json
+repo-context-center estimate --task "fix Cypress test" --mode compact
 ```
 
 Token estimates use `ceil(characters / 4)`. They are rough planning numbers,
 not exact tokenizer output and not model billing estimates. The command is meant
 to help evaluate whether the context center is reducing broad repo reads enough
-to justify its own startup cost.
+to justify its own startup cost. In an empty repo, startup context can be zero
+until templates are installed; after `repo-context-center init`, default context
+files should produce a realistic non-zero startup estimate.
 
 ## Recommended AI Agent Workflow
 

package/dist/cli/commands/estimate.js

@@ -72,7 +72,7 @@ function formatReport(report) {
         }
     }
     if (report.taskEstimate) {
-        lines.push("", "Task recommendation:", `- Task: ${report.taskEstimate.task}`, `- Recommended context: ${formatNumber(report.taskEstimate.recommendedContextTokens)} tokens`, `- Likely source: ${formatNumber(report.taskEstimate.likelySourceTokens)} tokens`, `- Likely tests: ${formatNumber(report.taskEstimate.likelyTestTokens)} tokens`);
+        lines.push("", "Task recommendation:", `- Task: ${report.taskEstimate.task}`, `- Recommended context: ${formatNumber(report.taskEstimate.recommendedContextTokens)} tokens`, `- Likely source: ${formatNumber(report.taskEstimate.likelySourceTokens)} tokens`, `- Likely tests: ${formatNumber(report.taskEstimate.likelyTestTokens)} tokens`, `- Likely context docs: ${formatNumber(report.taskEstimate.likelyContextTokens)} tokens`);
     }
     lines.push("", "Warnings:", ...report.warnings.map((warning) => `- ${warning}`));
     return `${lines.join("\n")}\n`;

package/dist/core/tokenEstimator.d.ts

@@ -9,9 +9,11 @@ export interface TaskTokenEstimate {
     recommendedContextTokens: number;
     likelySourceTokens: number;
     likelyTestTokens: number;
+    likelyContextTokens: number;
     recommendedContextFiles: FileTokenEstimate[];
     likelySourceFiles: FileTokenEstimate[];
     likelyTests: FileTokenEstimate[];
+    likelyContextFiles: FileTokenEstimate[];
 }
 export interface TokenEstimateOptions {
     cwd: string;

package/dist/core/tokenEstimator.js

@@ -176,6 +176,111 @@ async function estimateRecommendedFiles(cwd, files, maxFiles) {
     const limitedFiles = uniqueSorted(files).slice(0, maxFiles);
     return Promise.all(limitedFiles.map((file) => estimateBySize(cwd, file)));
 }
+function isContextPath(filePath) {
+    const normalized = filePath.replace(/\\/g, "/").replace(/^\.\//, "");
+    return normalized === "AGENTS.md"
+        || normalized.startsWith("docs/ai-context/")
+        || normalized.startsWith(".project-brain/");
+}
+function isTestPath(filePath) {
+    const normalized = filePath.replace(/\\/g, "/");
+    const parts = normalized.split("/");
+    return normalized.startsWith("tests/")
+        || normalized.startsWith("cypress/")
+        || parts.some((part) => part.toLowerCase().includes("tests"))
+        || /\.(spec|test)\.[^.]+$/i.test(normalized);
+}
+function classifyRecommendedPath(filePath) {
+    if (isContextPath(filePath)) {
+        return "context";
+    }
+    if (isTestPath(filePath)) {
+        return "test";
+    }
+    return "source";
+}
+async function collectRecommendedFiles(cwd, filePath, excludedPaths, files, maxFiles) {
+    if (files.length >= maxFiles) {
+        return;
+    }
+    const normalizedPath = filePath.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/$/, "");
+    let fileStat;
+    try {
+        fileStat = await (0, promises_1.stat)(node_path_1.default.join(cwd, normalizedPath));
+    }
+    catch {
+        return;
+    }
+    if (fileStat.isFile()) {
+        if (isSourceOrDocFile(normalizedPath)) {
+            files.push(normalizedPath);
+        }
+        return;
+    }
+    if (!fileStat.isDirectory()) {
+        return;
+    }
+    let entries;
+    try {
+        entries = await (0, promises_1.readdir)(node_path_1.default.join(cwd, normalizedPath), { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+        if (files.length >= maxFiles) {
+            return;
+        }
+        const relativePath = `${normalizedPath}/${entry.name}`;
+        if (entry.name === ".git" || isExcluded(relativePath, excludedPaths)) {
+            continue;
+        }
+        if (entry.isDirectory()) {
+            await collectRecommendedFiles(cwd, relativePath, excludedPaths, files, maxFiles);
+        }
+        else if (entry.isFile() && isSourceOrDocFile(relativePath)) {
+            files.push(relativePath);
+        }
+    }
+}
+async function resolveRecommendedFiles(cwd, paths, maxFiles) {
+    const excludedPaths = await readExcludedPaths(cwd);
+    const files = [];
+    for (const filePath of uniqueSorted(paths)) {
+        if (files.length >= maxFiles) {
+            break;
+        }
+        await collectRecommendedFiles(cwd, filePath, excludedPaths, files, maxFiles);
+    }
+    return uniqueSorted(files).slice(0, maxFiles);
+}
+async function estimateTaskRecommendation(cwd, task, maxFiles) {
+    const suggestion = await (0, suggester_1.suggestContext)(cwd, task);
+    const recommendedPaths = [
+        ...suggestion.contextFiles,
+        ...suggestion.likelySourceFiles,
+        ...suggestion.likelyTests
+    ];
+    const resolvedFiles = await resolveRecommendedFiles(cwd, recommendedPaths, maxFiles);
+    const sourcePaths = resolvedFiles.filter((file) => classifyRecommendedPath(file) === "source");
+    const testPaths = resolvedFiles.filter((file) => classifyRecommendedPath(file) === "test");
+    const contextPaths = resolvedFiles.filter((file) => classifyRecommendedPath(file) === "context");
+    const recommendedContextFiles = await estimateRecommendedFiles(cwd, contextPaths, maxFiles);
+    const likelySourceFiles = await estimateRecommendedFiles(cwd, sourcePaths, maxFiles);
+    const likelyTests = await estimateRecommendedFiles(cwd, testPaths, maxFiles);
+    return {
+        task,
+        recommendedContextTokens: sumTokens(recommendedContextFiles),
+        likelySourceTokens: sumTokens(likelySourceFiles),
+        likelyTestTokens: sumTokens(likelyTests),
+        likelyContextTokens: sumTokens(recommendedContextFiles),
+        recommendedContextFiles,
+        likelySourceFiles,
+        likelyTests,
+        likelyContextFiles: recommendedContextFiles
+    };
+}
 function modeFiles(mode, startupFiles, onDemandFiles, historyFiles) {
     if (mode === "compact") {
         return startupFiles;
@@ -267,19 +372,7 @@ async function estimateTokenCost(options) {
     }
     if (options.task) {
         try {
-            const suggestion = await (0, suggester_1.suggestContext)(options.cwd, options.task);
-            const recommendedContextFiles = await Promise.all(suggestion.contextFiles.map((file) => estimateTextFile(options.cwd, file)));
-            const likelySourceFiles = await estimateRecommendedFiles(options.cwd, suggestion.likelySourceFiles, options.maxFiles);
-            const likelyTests = await estimateRecommendedFiles(options.cwd, suggestion.likelyTests, options.maxFiles);
-            report.taskEstimate = {
-                task: options.task,
-                recommendedContextTokens: sumTokens(recommendedContextFiles),
-                likelySourceTokens: sumTokens(likelySourceFiles),
-                likelyTestTokens: sumTokens(likelyTests),
-                recommendedContextFiles,
-                likelySourceFiles,
-                likelyTests
-            };
+            report.taskEstimate = await estimateTaskRecommendation(options.cwd, options.task, options.maxFiles);
         }
         catch {
             warnings.push("Task-specific suggestion failed; estimate excludes task recommendations.");

package/dist/templates/generic/AGENTS.md

@@ -1,30 +1,49 @@
 # AGENTS.md
 
-Repository Context Center startup guide for AI coding agents.
-
-Start here:
-- Read `docs/ai-context/COMMUNICATION_MODE.md`.
-- Read `docs/ai-context/TASK_ROUTING.md`.
-- Read `docs/ai-context/TOKEN_BUDGET.md`.
-- Read `docs/ai-context/DO_NOT_READ.md`.
-- Use `TASK_ROUTING.md` before scanning the repo.
-
-Context loading:
-- Default to Compact Mode.
-- Use Investigation Mode for security, auth, production, migration, release, or high-risk bug tasks.
-- Use Detailed Mode only when explicitly requested.
-- Load these only on demand: `MODULE_INDEX.md`, `PROJECT_MAP.md`, `DEPENDENCY_MAP.md`, `RISK_REGISTER.md`, `HOTSPOTS.md`, `SYMBOL_MAP.md`, `LESSONS_LEARNED.md`.
-
-Do not read by default:
-- `docs/ai-context/archive/*`.
-- Generated folders listed in `docs/ai-context/DO_NOT_READ.md`.
-- `.repo-context-center/config.json` unless debugging repo-context-center installation.
-
-Work rules:
-- Verify source code before changing behavior.
-- Treat context files as guidance, not source of truth.
-- Trust source code when context and code disagree.
-- Keep changes focused.
-- Run the smallest useful verification.
-- Avoid unnecessary repository-wide scans.
-- Update context files only when the task creates durable repo knowledge.
+Repo Context Center startup.
+
+## Startup
+
+Read:
+1. `docs/ai-context/COMMUNICATION_MODE.md`
+2. `docs/ai-context/TASK_ROUTING.md`
+3. `docs/ai-context/TOKEN_BUDGET.md`
+4. `docs/ai-context/DO_NOT_READ.md`
+
+Use `TASK_ROUTING.md` before opening repo files.
+
+## Modes
+
+Default: Compact
+
+Investigation:
+- security/auth
+- production/release
+- migrations
+- high-risk bugs
+
+Detailed: explicit request only.
+
+On demand:
+- `MODULE_INDEX.md`
+- `PROJECT_MAP.md`
+- `DEPENDENCY_MAP.md`
+- `RISK_REGISTER.md`
+- `HOTSPOTS.md`
+- `SYMBOL_MAP.md`
+- `LESSONS_LEARNED.md`
+
+## Skip
+
+- `docs/ai-context/archive/*`
+- paths in `DO_NOT_READ.md`
+- `.repo-context-center/config.json` unless debugging install
+
+## Rules
+
+- Code is source of truth.
+- Context guides navigation.
+- Verify before behavior changes.
+- Keep changes small.
+- Run smallest useful check.
+- Update context only for durable repo knowledge.

package/dist/templates/generic/docs/ai-context/CHANGE_LOG.md

@@ -1,15 +1,12 @@
 # Change Log
 
-Record context-center changes, not every code change.
-
-Format:
+Record context edits only.
 
 | Date | Change | Reason |
 | --- | --- | --- |
-| YYYY-MM-DD | File or section updated | Why context changed |
+| YYYY-MM-DD | file/section | why |
 
-Use when:
-- A template is installed.
-- A context map is corrected.
-- Routing guidance changes.
-- A stale note is removed.
+Record:
+- install/update/remove context files
+- routing/map corrections
+- stale context removed

package/dist/templates/generic/docs/ai-context/COMMUNICATION_MODE.md

@@ -1,14 +1,10 @@
 # Communication Mode
 
-Purpose: align the agent's working style with the current task.
-
-Default mode:
+Use:
 - Read first, then act.
-- Share assumptions when context is incomplete.
-- Ask only when a wrong assumption would be costly.
-- Keep updates concise and tied to observable progress.
-
-When editing:
-- Name the files being changed.
+- State risky assumptions.
+- Ask only when guessing is costly.
+- Keep updates short.
+- Name changed files.
 - Preserve user changes.
-- Report tests run and failures clearly.
+- Report checks run.

package/dist/templates/generic/docs/ai-context/DEPENDENCY_MAP.md

@@ -1,16 +1,12 @@
 # Dependency Map
 
-Record important internal and external dependencies.
-
-Format:
+Record dependencies that change blast radius.
 
 | From | Depends On | Why It Matters |
 | --- | --- | --- |
-| `module` | `module/package` | Runtime, API, build, or test impact |
-
-Use this to avoid surprise blast radius.
+| `module` | `module/package` | impact |
 
-Update when:
-- A shared dependency changes.
-- A module boundary shifts.
-- A new external package is added.
+Update:
+- shared dependency changes
+- module boundary shifts
+- package added/removed

package/dist/templates/generic/docs/ai-context/DO_NOT_READ.md

@@ -1,8 +1,6 @@
 # Do Not Read
 
-Skip these unless the task explicitly requires them.
-
-Common examples:
+Skip:
 - `node_modules/`
 - `dist/`
 - `build/`
@@ -15,4 +13,4 @@ Common examples:
 - Vendored code
 - Minified bundles
 
-When an excluded file is required, explain why and read the smallest useful section.
+If required, explain why and read the smallest slice.

package/dist/templates/generic/docs/ai-context/HOTSPOTS.md

@@ -1,18 +1,13 @@
 # Hotspots
 
-Track files or flows that often cause bugs.
-
-Format:
+Record fragile files/flows.
 
 | Hotspot | Why | Safer Move |
 | --- | --- | --- |
-| `path/or/flow` | Failure pattern | Test, review, or constraint |
-
-Use for:
-- Complex state.
-- Concurrency.
-- Auth or permissions.
-- Serialization.
-- Boundary adapters.
+| `path/or/flow` | failure pattern | check |
 
-Remove entries when they stop being true.
+Use:
+- state/concurrency
+- auth/permissions
+- serialization
+- boundary adapters

package/dist/templates/generic/docs/ai-context/LESSONS_LEARNED.md

@@ -1,19 +1,12 @@
 # Lessons Learned
 
-Capture durable facts discovered during work.
-
-Format:
+Record durable repo facts only.
 
 | Date | Lesson | Source |
 | --- | --- | --- |
-| YYYY-MM-DD | Short factual note | PR, issue, test, or file |
-
-Good entries:
-- Save future investigation.
-- Explain non-obvious constraints.
-- Point to evidence.
+| YYYY-MM-DD | fact | PR/issue/test/file |
 
-Avoid:
-- Opinions without proof.
-- Temporary task notes.
-- Long narratives.
+Skip:
+- opinions
+- temporary task notes
+- long narratives

package/dist/templates/generic/docs/ai-context/MODULE_INDEX.md

@@ -1,16 +1,12 @@
 # Module Index
 
-List important modules and their responsibilities.
-
-Format:
+Record stable module boundaries.
 
 | Path | Owns | Read When |
 | --- | --- | --- |
-| `src/...` | Main behavior or boundary | Task touches this area |
-
-Keep entries short. Prefer stable boundaries over file-by-file detail.
+| `src/...` | boundary | task touches area |
 
-Update when:
-- A module is added, removed, or renamed.
-- Ownership changes.
-- A task repeatedly requires the same context.
+Update:
+- module added/renamed/removed
+- ownership changes
+- repeated task needs same context

package/dist/templates/generic/docs/ai-context/PROJECT_MAP.md

@@ -1,17 +1,15 @@
 # Project Map
 
-Describe the repository at a glance.
-
 Fill in:
-- Primary language/runtime:
+- Runtime:
 - Package manager:
-- Build command:
-- Test command:
-- Main entrypoints:
-- Generated or vendored paths:
-- Important conventions:
+- Build:
+- Test:
+- Entrypoints:
+- Generated/vendored:
+- Conventions:
 
-Agent notes:
-- Keep this file factual.
-- Link to files instead of restating long docs.
-- Update when commands or entrypoints change.
+Rules:
+- factual only
+- link, do not restate
+- update commands/entrypoints promptly

package/dist/templates/generic/docs/ai-context/RISK_REGISTER.md

@@ -1,18 +1,14 @@
 # Risk Register
 
-Track areas where changes need extra care.
-
-Format:
+Record high-care areas.
 
 | Area | Risk | Check |
 | --- | --- | --- |
-| `path/or/system` | What can break | Test or review needed |
+| `path/or/system` | what breaks | check |
 
 Include:
-- Security-sensitive code.
-- Data migrations.
-- Public APIs.
-- Cross-cutting utilities.
-- Flaky or expensive tests.
-
-Keep risks current and specific.
+- security
+- migrations
+- public APIs
+- shared utilities
+- flaky/expensive tests

package/dist/templates/generic/docs/ai-context/SYMBOL_MAP.md

@@ -1,26 +1,15 @@
 # Symbol Map
 
-Track high-value names agents should find quickly.
-
-Format:
+Record high-value symbols only.
 
 ## src/example/module.ts
 
-Important symbols:
+Symbols:
 - exportedFunction
 - ExportedClass
 - PublicType
 
-Common tests:
+Tests:
 - tests/example/module.test.ts
 
-Risk:
-low
-
-Include:
-- Public APIs.
-- Main classes/functions.
-- Config objects.
-- Cross-module types.
-
-Do not list every symbol. Keep this navigational.
+Risk: low

package/dist/templates/generic/docs/ai-context/TASK_ROUTING.md

@@ -1,18 +1,9 @@
 # Task Routing
 
-Use this map to choose the smallest useful context set.
+Read:
+- Bug: `PROJECT_MAP.md`, `MODULE_INDEX.md`, `HOTSPOTS.md`, related tests.
+- Feature: `PROJECT_MAP.md`, `MODULE_INDEX.md`, `DEPENDENCY_MAP.md`, examples.
+- Refactor: `DEPENDENCY_MAP.md`, `SYMBOL_MAP.md`, callers.
+- Docs/config: `PROJECT_MAP.md`, target files.
 
-Bug fix:
-- Read `PROJECT_MAP.md`, `MODULE_INDEX.md`, `HOTSPOTS.md`, and related tests.
-
-Feature:
-- Read `PROJECT_MAP.md`, `MODULE_INDEX.md`, `DEPENDENCY_MAP.md`, and nearby examples.
-
-Refactor:
-- Read `DEPENDENCY_MAP.md`, `SYMBOL_MAP.md`, and affected callers.
-
-Docs/config:
-- Read `PROJECT_MAP.md` and the target files.
-
-Before broad search:
-- Check `DO_NOT_READ.md`.
+Before broad search: check `DO_NOT_READ.md`.

package/dist/templates/generic/docs/ai-context/TOKEN_BUDGET.md

@@ -1,16 +1,12 @@
 # Token Budget
 
-Use context deliberately.
-
 Compact Mode:
-- Read routing, the target file, and the nearest test only.
-- Use when the task is narrow or low risk.
+- routing + target file + nearest test
 
 Investigation Mode:
-- Add maps, related callers, and failure evidence.
-- Use when behavior, ownership, or blast radius is unclear.
+- add maps, callers, failure evidence
 
-Default read order:
+Read:
 1. `AGENTS.md`
 2. `TASK_ROUTING.md`
 3. Relevant map files
@@ -18,12 +14,12 @@ Default read order:
 
 Estimate overhead:
 - Run `repo-context-center estimate`.
-- Use `--compare-naive` to compare startup context with a broad repo pass.
-- Treat results as approximate, not billing data.
+- `--compare-naive` compares startup vs broad pass.
+- Approximate, not billing data.
 
-Avoid:
-- Generated output.
-- Lockfiles unless dependency state matters.
-- Large snapshots or fixtures unless failing behavior depends on them.
+Skip:
+- generated output
+- lockfiles unless dependency state matters
+- large snapshots unless failure depends on them
 
-Escalate context only when the first pass leaves a concrete unknown.
+Escalate only for concrete unknowns.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repo-context-center",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "A ContextOps toolkit for AI coding agents.",
   "keywords": [
     "ai",