repo-context-center 0.1.2 → 0.1.3

package/README.md

@@ -22,6 +22,12 @@ This project adds a generic Repository Context Center to answer those questions
 
 ## Quick Start
 
+Inside a target repository:
+
+```sh
+npx repo-context-center init
+```
+
 From a clone of this project:
 
 ```sh
@@ -35,6 +41,7 @@ Then, inside a target repository:
 ```sh
 repo-context-center init
 repo-context-center validate
+repo-context-center suggest "fix auth bug"
 ```
 
 Preview installation without writing files:
@@ -43,6 +50,12 @@ Preview installation without writing files:
 repo-context-center init --dry-run
 ```
 
+Install a PR validation workflow:
+
+```sh
+repo-context-center init --github-action
+```
+
 Overwrite existing context templates:
 
 ```sh
@@ -70,13 +83,20 @@ repo-context-center init --force
 
 It also creates `.repo-context-center/config.json`.
 
+With `--github-action`, it also creates:
+
+- `.github/workflows/repo-context-check.yml`
+
 ## Commands
 
 ```sh
 repo-context-center --help
-repo-context-center init [--dry-run] [--force]
+repo-context-center init [--dry-run] [--force] [--github-action]
 repo-context-center validate [--strict]
 repo-context-center archive [--keep <number>] [--dry-run]
+repo-context-center estimate [--mode compact|investigation|detailed] [--compare-naive] [--json]
+repo-context-center scan [--json]
+repo-context-center suggest "<task>" [--json]
 ```
 
 - `init`: install the generic context templates.
@@ -84,6 +104,29 @@ repo-context-center archive [--keep <number>] [--dry-run]
   Missing `.repo-context-center/config.json` is a warning by default and a
   failure with `--strict`.
 - `archive`: archive older entries from long-running context files; defaults to keeping 50 entries.
+- `estimate`: estimate context token overhead and compare it with a naive repo scan.
+- `scan`: inspect only the repository layout and suggest lightweight entries for context maps.
+- `suggest`: recommend low-token context files, likely modules, likely tests, mode, and risk level for a task.
+
+See [docs/github-action.md](docs/github-action.md) for PR validation setup.
+
+Example:
+
+```sh
+repo-context-center suggest "fix payment consent bug" --json
+```
+
+Estimate context overhead:
+
+```sh
+repo-context-center estimate --compare-naive
+repo-context-center estimate --mode investigation --task "fix auth bug" --json
+```
+
+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.
 
 ## Recommended AI Agent Workflow
 
@@ -91,9 +134,10 @@ Ask the agent to:
 
 1. Read `AGENTS.md`.
 2. Follow `docs/ai-context/TASK_ROUTING.md`.
-3. Read only the context files relevant to the task.
-4. Check `DO_NOT_READ.md` before broad search.
-5. Update `LESSONS_LEARNED.md` and `CHANGE_LOG.md` when durable context changes.
+3. Check `docs/ai-context/TOKEN_BUDGET.md` and `docs/ai-context/DO_NOT_READ.md`.
+4. Read only the on-demand context files relevant to the task.
+5. Verify source code before changing behavior.
+6. Update context files only when durable repo knowledge changes.
 
 See [docs/agent-usage.md](docs/agent-usage.md).
 
@@ -126,17 +170,20 @@ More examples are in [docs/examples.md](docs/examples.md).
 - [Agent usage](docs/agent-usage.md)
 - [Token strategy](docs/token-strategy.md)
 - [Examples](docs/examples.md)
+- [GitHub Action](docs/github-action.md)
 
 ## Supported Project Types
 
 The generic templates are language-agnostic. They can be installed in JavaScript, TypeScript, Python, Go, Rust, Ruby, Java, monorepos, docs repos, and mixed stacks.
 
-Project-specific templates and repo scanning are not implemented yet.
+Project-specific templates are not implemented yet. The current scanner is intentionally lightweight and does not read full source files.
 
 ## Roadmap
 
 - Generic template installation and validation.
 - Context file archiving.
+- Lightweight repo layout scanning.
+- Task-specific context suggestions.
 - Project-specific template packs.
 - Optional repository scanning to prefill maps.
 - Safer update workflows for existing context centers.

package/dist/cli/commands/estimate.d.ts

@@ -0,0 +1,2 @@
+import type { CliIO } from "../index";
+export declare function estimateCommand(io: CliIO, args?: string[]): Promise<number>;

package/dist/cli/commands/estimate.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateCommand = estimateCommand;
+const tokenEstimator_1 = require("../../core/tokenEstimator");
+function parseEstimateOptions(args) {
+    let json = false;
+    let mode = "compact";
+    let task;
+    let compareNaive = false;
+    let maxFiles = 500;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--json") {
+            json = true;
+        }
+        else if (arg === "--compare-naive") {
+            compareNaive = true;
+        }
+        else if (arg === "--mode") {
+            const value = args[index + 1];
+            if (value !== "compact" && value !== "investigation" && value !== "detailed") {
+                return undefined;
+            }
+            mode = value;
+            index += 1;
+        }
+        else if (arg === "--task") {
+            const value = args[index + 1];
+            if (!value) {
+                return undefined;
+            }
+            task = value;
+            index += 1;
+        }
+        else if (arg === "--max-files") {
+            const value = Number.parseInt(args[index + 1] ?? "", 10);
+            if (!Number.isInteger(value) || value < 1) {
+                return undefined;
+            }
+            maxFiles = value;
+            index += 1;
+        }
+        else {
+            return undefined;
+        }
+    }
+    return { json, mode, task, compareNaive, maxFiles };
+}
+function formatNumber(value) {
+    return value === undefined ? "not run" : value.toLocaleString("en-US");
+}
+function formatReport(report) {
+    const lines = [
+        "repo-context-center token estimate",
+        "",
+        "Method:",
+        `- Approximation: ${report.method}`,
+        "",
+        "Mode:",
+        `- ${report.mode}`,
+        "",
+        "Context cost:",
+        `- Startup context: ${formatNumber(report.startupTokens)} tokens`,
+        `- On-demand context available: ${formatNumber(report.onDemandTokens)} tokens`,
+        `- History/archive excluded: ${formatNumber(report.historyTokens)} tokens`,
+        `- Included for mode: ${formatNumber(report.includedContextTokens)} tokens`
+    ];
+    if (report.naiveScanTokens !== undefined) {
+        lines.push("", "Naive comparison:", `- Estimated naive scan: ${formatNumber(report.naiveScanTokens)} tokens`, `- Estimated compact startup: ${formatNumber(report.startupTokens)} tokens`, `- Estimated saving: ${formatNumber(report.estimatedSavedTokens)} tokens`, `- Estimated saving: ${formatNumber(report.estimatedSavingPercent)}%`);
+        if (report.naiveScanCapped) {
+            lines.push(`- Naive scan capped at ${report.maxFiles} files`);
+        }
+    }
+    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("", "Warnings:", ...report.warnings.map((warning) => `- ${warning}`));
+    return `${lines.join("\n")}\n`;
+}
+async function estimateCommand(io, args = []) {
+    const options = parseEstimateOptions(args);
+    if (!options) {
+        io.stderr('Usage: repo-context-center estimate [--json] [--mode compact|investigation|detailed] [--task "<task>"] [--compare-naive] [--max-files <number>]\n');
+        return 1;
+    }
+    const report = await (0, tokenEstimator_1.estimateTokenCost)({
+        cwd: io.cwd,
+        mode: options.mode,
+        task: options.task,
+        compareNaive: options.compareNaive,
+        maxFiles: options.maxFiles
+    });
+    if (options.json) {
+        io.stdout(`${JSON.stringify(report, null, 2)}\n`);
+        return 0;
+    }
+    io.stdout(formatReport(report));
+    return 0;
+}

package/dist/cli/commands/init.js

@@ -6,7 +6,8 @@ const templateInstaller_1 = require("../../core/templateInstaller");
 function parseInitOptions(args) {
     return {
         force: args.includes("--force"),
-        dryRun: args.includes("--dry-run")
+        dryRun: args.includes("--dry-run"),
+        githubAction: args.includes("--github-action")
     };
 }
 function formatInstallMessage(result, dryRun) {
@@ -24,7 +25,8 @@ function formatInstallMessage(result, dryRun) {
 }
 async function initCommand(io, args = []) {
     const options = parseInitOptions(args);
-    const unknownFlag = args.find((arg) => arg.startsWith("--") && arg !== "--force" && arg !== "--dry-run");
+    const knownFlags = new Set(["--force", "--dry-run", "--github-action"]);
+    const unknownFlag = args.find((arg) => arg.startsWith("--") && !knownFlags.has(arg));
     if (unknownFlag) {
         io.stderr(`Unknown init option: ${unknownFlag}\n`);
         return 1;
@@ -32,7 +34,8 @@ async function initCommand(io, args = []) {
     const results = await (0, templateInstaller_1.installGenericTemplates)({
         cwd: io.cwd,
         force: options.force,
-        dryRun: options.dryRun
+        dryRun: options.dryRun,
+        githubAction: options.githubAction
     });
     for (const result of results) {
         io.stdout(formatInstallMessage(result, options.dryRun));

package/dist/cli/commands/scan.d.ts

@@ -0,0 +1,2 @@
+import type { CliIO } from "../index";
+export declare function scanCommand(io: CliIO, args?: string[]): Promise<number>;

package/dist/cli/commands/scan.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanCommand = scanCommand;
+const scanner_1 = require("../../core/scanner");
+function parseScanOptions(args) {
+    const unknownFlag = args.find((arg) => arg !== "--json");
+    if (unknownFlag) {
+        return undefined;
+    }
+    return {
+        json: args.includes("--json")
+    };
+}
+function formatList(values) {
+    return values.length > 0 ? values.join(", ") : "none";
+}
+function formatScanReport(report) {
+    const lines = [
+        "repo-context-center scan report",
+        "",
+        `Source folders: ${formatList(report.detected.sourceFolders)}`,
+        `Test folders: ${formatList(report.detected.testFolders)}`,
+        `Generated folders: ${formatList(report.detected.generatedFolders)}`,
+        ""
+    ];
+    if (report.detected.modules.length > 0) {
+        lines.push("Detected modules:");
+        for (const module of report.detected.modules) {
+            lines.push(`  - ${module.path}`);
+        }
+    }
+    else {
+        lines.push("Detected modules: none");
+    }
+    lines.push("");
+    for (const [file, suggestions] of Object.entries(report.suggestions)) {
+        lines.push(file);
+        lines.push(...suggestions.map((line) => (line ? `  ${line}` : "")));
+        lines.push("");
+    }
+    return `${lines.join("\n").trimEnd()}\n`;
+}
+async function scanCommand(io, args = []) {
+    const options = parseScanOptions(args);
+    if (!options) {
+        io.stderr("Unknown scan option. Supported options: --json\n");
+        return 1;
+    }
+    const report = await (0, scanner_1.scanRepository)(io.cwd);
+    if (options.json) {
+        io.stdout(`${JSON.stringify(report, null, 2)}\n`);
+        return 0;
+    }
+    io.stdout(formatScanReport(report));
+    return 0;
+}

package/dist/cli/commands/suggest.d.ts

@@ -0,0 +1,2 @@
+import type { CliIO } from "../index";
+export declare function suggestCommand(io: CliIO, args?: string[]): Promise<number>;

package/dist/cli/commands/suggest.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.suggestCommand = suggestCommand;
+const suggester_1 = require("../../core/suggester");
+function parseSuggestOptions(args) {
+    const json = args.includes("--json");
+    const symbols = args.includes("--symbols");
+    const taskParts = args.filter((arg) => arg !== "--json" && arg !== "--symbols");
+    if (taskParts.some((arg) => arg.startsWith("--"))) {
+        return undefined;
+    }
+    const task = taskParts.join(" ").trim();
+    if (!task) {
+        return undefined;
+    }
+    return { json, symbols, task };
+}
+function formatList(values) {
+    return values.length > 0 ? values.map((value) => `  - ${value}`).join("\n") : "  - none";
+}
+function formatSymbols(suggestion) {
+    if (suggestion.relevantSymbols.length === 0) {
+        return "  - none";
+    }
+    return suggestion.relevantSymbols
+        .map((entry) => [
+        `  - ${entry.file}`,
+        ...entry.symbols.map((symbol) => `    - ${symbol}`)
+    ].join("\n"))
+        .join("\n");
+}
+function formatSuggestion(suggestion, includeSymbols) {
+    const lines = [
+        "repo-context-center suggestion",
+        "",
+        `Task: ${suggestion.task}`,
+        `Mode: ${suggestion.mode}`,
+        `Risk: ${suggestion.riskLevel}`,
+        "",
+        "Context files:",
+        formatList(suggestion.contextFiles),
+        "",
+        "Likely source files:",
+        formatList(suggestion.likelySourceFiles),
+    ];
+    if (includeSymbols) {
+        lines.push("", "Relevant symbols:", formatSymbols(suggestion));
+    }
+    lines.push("", "Likely tests:", formatList(suggestion.likelyTests), "", "Reasons:", formatList(suggestion.reasons));
+    return `${lines.join("\n")}\n`;
+}
+async function suggestCommand(io, args = []) {
+    const options = parseSuggestOptions(args);
+    if (!options) {
+        io.stderr('Usage: repo-context-center suggest "<task>" [--json] [--symbols]\n');
+        return 1;
+    }
+    const suggestion = await (0, suggester_1.suggestContext)(io.cwd, options.task);
+    if (options.json) {
+        io.stdout(`${JSON.stringify(suggestion, null, 2)}\n`);
+        return 0;
+    }
+    io.stdout(formatSuggestion(suggestion, options.symbols));
+    return 0;
+}

package/dist/cli/index.js

@@ -4,12 +4,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getHelpText = getHelpText;
 exports.run = run;
 const archive_1 = require("./commands/archive");
+const estimate_1 = require("./commands/estimate");
 const init_1 = require("./commands/init");
+const scan_1 = require("./commands/scan");
+const suggest_1 = require("./commands/suggest");
 const validate_1 = require("./commands/validate");
 const commands = {
     init: init_1.initCommand,
     validate: validate_1.validateCommand,
-    archive: archive_1.archiveCommand
+    archive: archive_1.archiveCommand,
+    estimate: estimate_1.estimateCommand,
+    scan: scan_1.scanCommand,
+    suggest: suggest_1.suggestCommand
 };
 const helpText = `repo-context-center
 
@@ -18,11 +24,17 @@ Usage:
 
 Commands:
   init      Install generic context templates and config
-            Options: --dry-run, --force
+            Options: --dry-run, --force, --github-action
   validate  Validate required context files and warnings
             Options: --strict
   archive   Archive older CHANGE_LOG and LESSONS_LEARNED entries
             Options: --keep <number>, --dry-run
+  estimate  Estimate context token costs and rough savings
+            Options: --json, --mode <mode>, --task <text>, --compare-naive, --max-files <number>
+  scan      Suggest lightweight context entries from repo layout
+            Options: --json
+  suggest   Recommend context files for a task
+            Usage: suggest "<task>" [--json] [--symbols]
 
 Options:
   -h, --help  Show this help

package/dist/core/contextFiles.d.ts

@@ -1,4 +1,9 @@
 export declare const requiredContextFiles: readonly ["AGENTS.md", "docs/ai-context/COMMUNICATION_MODE.md", "docs/ai-context/TASK_ROUTING.md", "docs/ai-context/MODULE_INDEX.md", "docs/ai-context/PROJECT_MAP.md", "docs/ai-context/RISK_REGISTER.md", "docs/ai-context/DEPENDENCY_MAP.md", "docs/ai-context/SYMBOL_MAP.md", "docs/ai-context/TOKEN_BUDGET.md", "docs/ai-context/DO_NOT_READ.md", "docs/ai-context/HOTSPOTS.md", "docs/ai-context/LESSONS_LEARNED.md", "docs/ai-context/CHANGE_LOG.md"];
 export type RequiredContextFile = (typeof requiredContextFiles)[number];
 export declare const contextArchiveDir = "docs/ai-context/archive";
+export declare const agentsFile = "AGENTS.md";
+export declare const tokenBudgetFile = "docs/ai-context/TOKEN_BUDGET.md";
+export declare const doNotReadFile = "docs/ai-context/DO_NOT_READ.md";
+export declare const requiredTokenBudgetModes: readonly ["Compact Mode", "Investigation Mode"];
+export declare const generatedFolderExclusions: readonly ["node_modules", "dist", "build", "coverage", "archive"];
 export declare const contextSizeLimits: Partial<Record<RequiredContextFile, number>>;

package/dist/core/contextFiles.js

@@ -1,9 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.contextSizeLimits = exports.contextArchiveDir = exports.requiredContextFiles = void 0;
+exports.contextSizeLimits = exports.generatedFolderExclusions = exports.requiredTokenBudgetModes = exports.doNotReadFile = exports.tokenBudgetFile = exports.agentsFile = exports.contextArchiveDir = exports.requiredContextFiles = void 0;
 const generic_1 = require("../templates/generic");
 exports.requiredContextFiles = generic_1.genericTemplateFiles;
 exports.contextArchiveDir = "docs/ai-context/archive";
+exports.agentsFile = "AGENTS.md";
+exports.tokenBudgetFile = "docs/ai-context/TOKEN_BUDGET.md";
+exports.doNotReadFile = "docs/ai-context/DO_NOT_READ.md";
+exports.requiredTokenBudgetModes = ["Compact Mode", "Investigation Mode"];
+exports.generatedFolderExclusions = [
+    "node_modules",
+    "dist",
+    "build",
+    "coverage",
+    "archive"
+];
 exports.contextSizeLimits = {
     "docs/ai-context/CHANGE_LOG.md": 32 * 1024,
     "docs/ai-context/TASK_ROUTING.md": 16 * 1024

package/dist/core/contextReader.d.ts

@@ -0,0 +1,7 @@
+export declare const suggestContextFiles: readonly ["docs/ai-context/TASK_ROUTING.md", "docs/ai-context/MODULE_INDEX.md", "docs/ai-context/DEPENDENCY_MAP.md", "docs/ai-context/SYMBOL_MAP.md", "docs/ai-context/RISK_REGISTER.md", "docs/ai-context/HOTSPOTS.md"];
+export type SuggestContextFile = (typeof suggestContextFiles)[number];
+export interface ContextDocument {
+    path: SuggestContextFile;
+    content: string;
+}
+export declare function readSuggestContext(cwd: string): Promise<ContextDocument[]>;

package/dist/core/contextReader.js

@@ -0,0 +1,30 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.suggestContextFiles = void 0;
+exports.readSuggestContext = readSuggestContext;
+const node_path_1 = __importDefault(require("node:path"));
+const fileSystem_1 = require("./fileSystem");
+exports.suggestContextFiles = [
+    "docs/ai-context/TASK_ROUTING.md",
+    "docs/ai-context/MODULE_INDEX.md",
+    "docs/ai-context/DEPENDENCY_MAP.md",
+    "docs/ai-context/SYMBOL_MAP.md",
+    "docs/ai-context/RISK_REGISTER.md",
+    "docs/ai-context/HOTSPOTS.md"
+];
+async function readSuggestContext(cwd) {
+    const documents = [];
+    for (const file of exports.suggestContextFiles) {
+        const fullPath = node_path_1.default.join(cwd, file);
+        if (await (0, fileSystem_1.pathExists)(fullPath)) {
+            documents.push({
+                path: file,
+                content: await (0, fileSystem_1.readTextFile)(fullPath)
+            });
+        }
+    }
+    return documents;
+}

package/dist/core/fileSystem.d.ts

@@ -2,4 +2,7 @@ export declare function pathExists(filePath: string): Promise<boolean>;
 export declare function ensureDir(dirPath: string): Promise<void>;
 export declare function writeJsonFile(filePath: string, value: unknown): Promise<void>;
 export declare function writeTextFile(filePath: string, content: string): Promise<void>;
+export declare function readTextFile(filePath: string): Promise<string>;
 export declare function readJsonFile<T>(filePath: string): Promise<T>;
+export declare function listDirectoryNames(dirPath: string): Promise<string[]>;
+export declare function listFilesRecursive(dirPath: string, rootPath?: string): Promise<string[]>;

package/dist/core/fileSystem.js

@@ -7,7 +7,10 @@ exports.pathExists = pathExists;
 exports.ensureDir = ensureDir;
 exports.writeJsonFile = writeJsonFile;
 exports.writeTextFile = writeTextFile;
+exports.readTextFile = readTextFile;
 exports.readJsonFile = readJsonFile;
+exports.listDirectoryNames = listDirectoryNames;
+exports.listFilesRecursive = listFilesRecursive;
 const promises_1 = require("node:fs/promises");
 const node_path_1 = __importDefault(require("node:path"));
 async function pathExists(filePath) {
@@ -30,6 +33,40 @@ async function writeTextFile(filePath, content) {
     await ensureDir(node_path_1.default.dirname(filePath));
     await (0, promises_1.writeFile)(filePath, content, "utf8");
 }
+async function readTextFile(filePath) {
+    return (0, promises_1.readFile)(filePath, "utf8");
+}
 async function readJsonFile(filePath) {
     return JSON.parse(await (0, promises_1.readFile)(filePath, "utf8"));
 }
+async function listDirectoryNames(dirPath) {
+    try {
+        const entries = await (0, promises_1.readdir)(dirPath, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort((left, right) => left.localeCompare(right));
+    }
+    catch {
+        return [];
+    }
+}
+async function listFilesRecursive(dirPath, rootPath = dirPath) {
+    try {
+        const entries = await (0, promises_1.readdir)(dirPath, { withFileTypes: true });
+        const files = [];
+        for (const entry of entries) {
+            const fullPath = node_path_1.default.join(dirPath, entry.name);
+            if (entry.isDirectory()) {
+                files.push(...await listFilesRecursive(fullPath, rootPath));
+            }
+            else if (entry.isFile()) {
+                files.push(node_path_1.default.relative(rootPath, fullPath).split(node_path_1.default.sep).join("/"));
+            }
+        }
+        return files.sort((left, right) => left.localeCompare(right));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/core/scanner.d.ts

@@ -0,0 +1,34 @@
+export interface ScannedModule {
+    name: string;
+    path: string;
+    sourceRoot: string;
+}
+export type ScannedSymbolKind = "function" | "class" | "interface" | "type" | "const" | "export";
+export interface ScannedSymbol {
+    name: string;
+    kind: ScannedSymbolKind;
+    path: string;
+}
+export interface ScannedSourceFile {
+    path: string;
+    symbols: ScannedSymbol[];
+    tests: string[];
+}
+export interface ScanReport {
+    root: string;
+    detected: {
+        sourceFolders: string[];
+        testFolders: string[];
+        generatedFolders: string[];
+        modules: ScannedModule[];
+        sourceFiles: ScannedSourceFile[];
+    };
+    suggestions: {
+        "MODULE_INDEX.md": string[];
+        "DO_NOT_READ.md": string[];
+        "TASK_ROUTING.md": string[];
+        "SYMBOL_MAP.md": string[];
+    };
+}
+export declare function extractExportedSymbols(sourcePath: string, content: string): ScannedSymbol[];
+export declare function scanRepository(cwd: string): Promise<ScanReport>;