repoctx 0.1.0

package/README.md

@@ -0,0 +1,202 @@
+# repoctx
+
+LLMs are probabilistic reasoners.
+Repositories are deterministic systems.
+
+Deterministic context should be extracted outside the LLM.
+
+repoctx precomputes repository context — diffs, summaries, symbol cards —
+so the assistant reasons instead of explores.
+
+Fast. Local. Minimal.
+No server. No DB. No embeddings. No magic.
+
+## The problem
+
+Every new session, your agent reads the same files again to understand the
+codebase. In large repos this means dozens of tool calls before writing a
+single line. The context is thrown away when the session closes.
+
+## How it works
+
+- You (or your agent) run `repoctx save <file> "<summary>"` after working on a file
+- repoctx stores the summary, exported symbols, keywords, and a content hash in `.repoctx/`
+- Next session: `repoctx get --keyword auth` returns all indexed modules tagged with that keyword — **0 file reads**
+- If a file changed since the last save, repoctx flags it as stale
+
+The index survives session resets. Context is never lost.
+
+## Install
+
+```bash
+# From npm (recommended)
+npm install -g repoctx
+
+# From source
+git clone https://github.com/Ezequiiel98/repoctx.git
+cd repoctx
+npm install
+npm run build
+npm install -g .
+```
+
+## Quick start
+
+```bash
+cd your-repo
+repoctx init                        # creates .repoctx/, adds to .gitignore
+repoctx onboarding >> CLAUDE.md     # tells Claude how to use repoctx
+```
+
+That's it. From now on Claude can save context as it works and retrieve it at the start of each session.
+
+## Token savings
+
+Measured on a real Node.js service (checkout API, 341 source files):
+
+| Scenario | Chars read | Tokens (~) | File reads |
+|---|---|---|---|
+| Without repoctx | 3,731 | ~933 | 4 |
+| repoctx (layer not indexed yet) | 3,396 | ~849 | 2 |
+| repoctx (layer fully indexed) | **1,139** | **~285** | **0** |
+
+Tokens estimated using ~4 chars per token heuristic.
+
+First session costs the same — you're reading the files anyway to work on them.
+From the second session onwards, you pay ~285 tokens instead of ~933 for the
+same context. The savings compound across sessions and teammates.
+
+## Commands
+
+### `repoctx save <file> "<summary>" [options]`
+
+Save context for a file. Run this when a file's public contract changes.
+
+```bash
+repoctx save src/users/dal.js "MongoDB DAL for users. CRUD operations." \
+  --symbols "createUser,getUser,deleteUser" \
+  --keywords "dal,users,mongodb" \
+  --deps "userSchema,sessionSchema" \
+  --footguns "deleteUser is soft-delete only" \
+  --delta "Added deleteUser (soft delete)"
+```
+
+| Option | Description |
+|---|---|
+| `--symbols` | Comma-separated exported functions/classes |
+| `--keywords` | Tags for filtering with `get --keyword`. **Always include these.** |
+| `--deps` | Dependencies this module relies on |
+| `--footguns` | Things that break if touched wrong |
+| `--delta` | What changed in this save |
+| `--meta` | Virtual entry — no real file (for patterns, glossary, folder maps) |
+
+### `repoctx save-symbol <name> "<purpose>" --file <path> [options]`
+
+Save a Symbol Card for a specific function or class.
+
+```bash
+repoctx save-symbol deleteUser "Hard delete a user from MongoDB" \
+  --file src/users/dal.js \
+  --kind function \
+  --signature "({ userSchema }) => async ({ id }) => Promise<DeleteResult>" \
+  --related "softDeleteUser:soft-delete variant" \
+  --keywords "dal,users,delete"
+```
+
+### `repoctx get [path] [--keyword k1,k2] [--symbol name]`
+
+Print saved context. **Prefer `--keyword` over bare `repoctx get`** — it uses
+a keyword index (O(1)) and returns only what's relevant.
+
+```bash
+repoctx get --keyword auth            # modules tagged with "auth"
+repoctx get --keyword dal,users       # OR logic across keywords
+repoctx get src/users/                # everything indexed under a path
+repoctx get --symbol deleteUser       # look up a specific function
+```
+
+### `repoctx stale`
+
+List all files whose content changed since the last `save`.
+
+```bash
+repoctx stale
+# ⚠ src/users/dal.js  (file content changed)
+#   → repoctx save src/users/dal.js "<summary>" --delta "what changed"
+```
+
+### `repoctx checkpoint` / `repoctx diff [--top N]`
+
+Save the current git HEAD as a baseline, then show what changed since then —
+formatted for Claude to understand without reading full diffs.
+
+```bash
+repoctx checkpoint
+# ... work for a few days ...
+repoctx diff --top 5
+```
+
+### `repoctx init`
+
+Initialize repoctx in the current repo. Creates `.repoctx/` and adds it to
+`.gitignore`.
+
+### `repoctx onboarding`
+
+Print agent instructions ready to paste into `CLAUDE.md` or `AGENTS.md`.
+
+```bash
+repoctx onboarding >> CLAUDE.md
+```
+
+## When to save
+
+**Do save** when the public contract changed:
+- Exported functions, classes, or constants
+- Route handlers or API surface
+- DAL/service patterns (factory signatures, argument shapes)
+- Business logic behavior (soft-delete vs hard-delete, idempotency, etc.)
+- A file is moved, renamed, or becomes a new entrypoint
+
+**Don't save** for:
+- Literals, logs, comments, or formatting changes
+- Internal refactors with no public interface change
+- Test-only changes
+
+## Meta entries (patterns, glossary, folder map)
+
+For knowledge not tied to a single file:
+
+```bash
+# Codebase conventions
+repoctx save .meta/patterns \
+  "DAL pattern: ({ schema }) => async (args) => ... Exports at bottom: fn: fn(models)." \
+  --keywords "pattern,convention,dal" --meta
+
+# Domain glossary
+repoctx save .meta/glossary \
+  "user = registered account. session = active login token." \
+  --keywords "glossary,domain" --meta
+
+# Folder ownership
+repoctx save .meta/structure \
+  "src/users = user domain. src/auth = authentication. src/api = route handlers." \
+  --keywords "structure,folders" --meta
+```
+
+## Sharing context with your team
+
+`.repoctx/` is added to `.gitignore` by default (`repoctx init`). Context is
+local per developer.
+
+If you want to share context across the team, remove `.repoctx` from
+`.gitignore` and commit it. Anyone who clones the repo gets the full index
+immediately — no re-indexing needed.
+
+## Maintenance
+
+Built for my workflow; support is best-effort. PRs welcome.
+
+## License
+
+MIT

package/dist/cache.d.ts

@@ -0,0 +1,61 @@
+export type ExportEntry = {
+    name: string;
+    kind: "function" | "class" | "constant" | "type" | "other";
+};
+export type RepoctxFileCache = {
+    path: string;
+    hash: string;
+    publicSurfaceHash?: string | undefined;
+    summary: string;
+    symbols: string[];
+    exports?: ExportEntry[] | undefined;
+    keywords?: string[] | undefined;
+    dependencies?: string[] | undefined;
+    footguns?: string | undefined;
+    delta?: string | undefined;
+    repoHeadAtSave?: string | undefined;
+    updatedAt: string;
+};
+export type RepoctxIndex = {
+    version: 1;
+    metaVersion?: number | undefined;
+    files: Record<string, {
+        hash: string;
+        ref: string;
+    }>;
+    keywordIndex: Record<string, string[]>;
+};
+export type SymbolRelation = {
+    symbol: string;
+    relation: string;
+};
+export type SymbolCard = {
+    symbol: string;
+    kind: "function" | "class" | "constant" | "type" | "other";
+    file: string;
+    signature?: string | undefined;
+    purpose: string;
+    related?: SymbolRelation[] | undefined;
+    keywords?: string[] | undefined;
+    updatedAt: string;
+};
+export type SymbolsIndex = {
+    version: 1;
+    symbols: Record<string, string>;
+};
+export declare function repoctxDir(): string;
+export declare function ensureDirs(): Promise<void>;
+export declare function fileHash(file: string): Promise<string>;
+export declare function computePublicSurfaceHash(symbols: string[]): string;
+export declare function loadIndex(): Promise<RepoctxIndex>;
+export declare function saveIndex(idx: RepoctxIndex): Promise<void>;
+export declare function loadFileCache(relativePath: string): Promise<RepoctxFileCache | null>;
+export declare function saveFileCache(relativePath: string, data: RepoctxFileCache): Promise<void>;
+/** O(1) keyword lookup using the index */
+export declare function lookupByKeywords(keywords: string[]): Promise<string[]>;
+export declare function loadSymbolsIndex(): Promise<SymbolsIndex>;
+export declare function saveSymbolCard(data: SymbolCard): Promise<void>;
+export declare function loadAllSymbols(): Promise<SymbolCard[]>;
+export declare function getGitHead(): string | null;
+export declare function getGitBranch(): string | null;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"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"}

package/dist/cache.js

@@ -0,0 +1,155 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+import { execSync } from "node:child_process";
+// ── Paths ─────────────────────────────────────────────────────────────────────
+function repoRoot() {
+    return process.cwd();
+}
+export function repoctxDir() {
+    return path.join(repoRoot(), ".repoctx");
+}
+function filesDir() {
+    return path.join(repoctxDir(), "files");
+}
+function symbolsDir() {
+    return path.join(repoctxDir(), "symbols");
+}
+function indexFile() {
+    return path.join(repoctxDir(), "index.json");
+}
+function symbolsIndexFile() {
+    return path.join(repoctxDir(), "symbols-index.json");
+}
+export async function ensureDirs() {
+    await fs.mkdir(filesDir(), { recursive: true });
+    await fs.mkdir(symbolsDir(), { recursive: true });
+}
+// ── Hashing ───────────────────────────────────────────────────────────────────
+export async function fileHash(file) {
+    const buf = await fs.readFile(file);
+    return crypto.createHash("sha1").update(buf).digest("hex");
+}
+/** Stable short filename derived from the path (not content) */
+function refFromPath(p) {
+    return crypto.createHash("sha1").update(p).digest("hex").slice(0, 12) + ".json";
+}
+export function computePublicSurfaceHash(symbols) {
+    return crypto.createHash("sha1").update(symbols.slice().sort().join(",")).digest("hex").slice(0, 12);
+}
+// ── Module Card I/O ───────────────────────────────────────────────────────────
+export async function loadIndex() {
+    await ensureDirs();
+    try {
+        const raw = await fs.readFile(indexFile(), "utf8");
+        const parsed = JSON.parse(raw);
+        // back-compat: old index had no keywordIndex
+        if (!parsed.keywordIndex)
+            parsed.keywordIndex = {};
+        return parsed;
+    }
+    catch {
+        return { version: 1, files: {}, keywordIndex: {} };
+    }
+}
+export async function saveIndex(idx) {
+    await fs.writeFile(indexFile(), JSON.stringify(idx, null, 2), "utf8");
+}
+export async function loadFileCache(relativePath) {
+    const idx = await loadIndex();
+    const entry = idx.files[relativePath];
+    if (!entry)
+        return null;
+    try {
+        const raw = await fs.readFile(path.join(filesDir(), entry.ref), "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveFileCache(relativePath, data) {
+    const idx = await loadIndex();
+    const ref = refFromPath(relativePath);
+    await fs.writeFile(path.join(filesDir(), ref), JSON.stringify(data, null, 2), "utf8");
+    // Update file entry
+    idx.files[relativePath] = { hash: data.hash, ref };
+    // Rebuild keyword index for this path
+    const keywords = data.keywords ?? [];
+    // Remove this path from all existing keyword entries first
+    for (const kw of Object.keys(idx.keywordIndex)) {
+        idx.keywordIndex[kw] = (idx.keywordIndex[kw] ?? []).filter((p) => p !== relativePath);
+        if ((idx.keywordIndex[kw] ?? []).length === 0)
+            delete idx.keywordIndex[kw];
+    }
+    // Add to new keywords
+    for (const kw of keywords) {
+        if (!idx.keywordIndex[kw])
+            idx.keywordIndex[kw] = [];
+        if (!idx.keywordIndex[kw].includes(relativePath)) {
+            idx.keywordIndex[kw].push(relativePath);
+        }
+    }
+    await saveIndex(idx);
+}
+/** O(1) keyword lookup using the index */
+export async function lookupByKeywords(keywords) {
+    const idx = await loadIndex();
+    const sets = keywords.map((k) => new Set(idx.keywordIndex[k] ?? []));
+    // OR logic: union of all sets
+    const union = new Set();
+    for (const s of sets)
+        for (const p of s)
+            union.add(p);
+    return [...union];
+}
+// ── Symbol Card I/O ───────────────────────────────────────────────────────────
+export async function loadSymbolsIndex() {
+    await ensureDirs();
+    try {
+        const raw = await fs.readFile(symbolsIndexFile(), "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return { version: 1, symbols: {} };
+    }
+}
+export async function saveSymbolCard(data) {
+    const idx = await loadSymbolsIndex();
+    const fname = refFromPath("symbol:" + data.symbol);
+    await fs.writeFile(path.join(symbolsDir(), fname), JSON.stringify(data, null, 2), "utf8");
+    idx.symbols[data.symbol] = fname;
+    await fs.writeFile(symbolsIndexFile(), JSON.stringify(idx, null, 2), "utf8");
+}
+export async function loadAllSymbols() {
+    const idx = await loadSymbolsIndex();
+    const results = [];
+    for (const fname of Object.values(idx.symbols)) {
+        try {
+            const raw = await fs.readFile(path.join(symbolsDir(), fname), "utf8");
+            results.push(JSON.parse(raw));
+        }
+        catch {
+            // skip corrupt entries
+        }
+    }
+    return results;
+}
+// ── Git helpers ───────────────────────────────────────────────────────────────
+export function getGitHead() {
+    try {
+        return execSync("git rev-parse HEAD", { encoding: "utf8" }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+export function getGitBranch() {
+    try {
+        return execSync("git rev-parse --abbrev-ref HEAD", { encoding: "utf8" }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAsD9C,iFAAiF;AAEjF,SAAS,QAAQ;IACf,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC;AACvB,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,UAAU,CAAC,CAAC;AAC3C,CAAC;AAED,SAAS,QAAQ;IACf,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,OAAO,CAAC,CAAC;AAC1C,CAAC;AAED,SAAS,UAAU;IACjB,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,SAAS,CAAC,CAAC;AAC5C,CAAC;AAED,SAAS,SAAS;IAChB,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,YAAY,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,gBAAgB;IACvB,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,oBAAoB,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,MAAM,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,MAAM,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AACpD,CAAC;AAED,iFAAiF;AAEjF,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAY;IACzC,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC7D,CAAC;AAED,gEAAgE;AAChE,SAAS,WAAW,CAAC,CAAS;IAC5B,OAAO,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,OAAO,CAAC;AAClF,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,OAAiB;IACxD,OAAO,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACvG,CAAC;AAED,iFAAiF;AAEjF,MAAM,CAAC,KAAK,UAAU,SAAS;IAC7B,MAAM,UAAU,EAAE,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,EAAE,MAAM,CAAC,CAAC;QACnD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,6CAA6C;QAC7C,IAAI,CAAC,MAAM,CAAC,YAAY;YAAE,MAAM,CAAC,YAAY,GAAG,EAAE,CAAC;QACnD,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC;IACrD,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAiB;IAC/C,MAAM,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,YAAoB;IAEpB,MAAM,GAAG,GAAG,MAAM,SAAS,EAAE,CAAC;IAC9B,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACtC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;QACxE,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,YAAoB,EACpB,IAAsB;IAEtB,MAAM,GAAG,GAAG,MAAM,SAAS,EAAE,CAAC;IAC9B,MAAM,GAAG,GAAG,WAAW,CAAC,YAAY,CAAC,CAAC;IAEtC,MAAM,EAAE,CAAC,SAAS,CAChB,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,GAAG,CAAC,EAC1B,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAC7B,MAAM,CACP,CAAC;IAEF,oBAAoB;IACpB,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC;IAEnD,sCAAsC;IACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;IACrC,2DAA2D;IAC3D,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,YAAY,CAAC,CAAC;QACtF,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IAC7E,CAAC;IACD,sBAAsB;IACtB,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;QAC1B,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;YAAE,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC;QACrD,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAE,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;YAClD,GAAG,CAAC,YAAY,CAAC,EAAE,CAAE,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IAED,MAAM,SAAS,CAAC,GAAG,CAAC,CAAC;AACvB,CAAC;AAED,0CAA0C;AAC1C,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,QAAkB;IACvD,MAAM,GAAG,GAAG,MAAM,SAAS,EAAE,CAAC;IAC9B,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACrE,8BAA8B;IAC9B,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,CAAC,IAAI,IAAI;QAAE,KAAK,MAAM,CAAC,IAAI,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACtD,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC;AACpB,CAAC;AAED,iFAAiF;AAEjF,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,MAAM,UAAU,EAAE,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,gBAAgB,EAAE,EAAE,MAAM,CAAC,CAAC;QAC1D,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IACrC,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAgB;IACnD,MAAM,GAAG,GAAG,MAAM,gBAAgB,EAAE,CAAC;IACrC,MAAM,KAAK,GAAG,WAAW,CAAC,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IACnD,MAAM,EAAE,CAAC,SAAS,CAChB,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,KAAK,CAAC,EAC9B,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAC7B,MAAM,CACP,CAAC;IACF,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC;IACjC,MAAM,EAAE,CAAC,SAAS,CAAC,gBAAgB,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AAC/E,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,MAAM,GAAG,GAAG,MAAM,gBAAgB,EAAE,CAAC;IACrC,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QAC/C,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;YACtE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QAChC,CAAC;QAAC,MAAM,CAAC;YACP,uBAAuB;QACzB,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,iFAAiF;AAEjF,MAAM,UAAU,UAAU;IACxB,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,oBAAoB,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,iCAAiC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAClF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/checkpoint.d.ts

@@ -0,0 +1,9 @@
+type Checkpoint = {
+    head: string;
+    branch: string;
+    at: string;
+};
+export declare function saveCheckpoint(): Promise<Checkpoint>;
+export declare function loadCheckpoint(): Promise<Checkpoint | null>;
+export {};
+//# sourceMappingURL=checkpoint.d.ts.map

package/dist/checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../src/checkpoint.ts"],"names":[],"mappings":"AAKA,KAAK,UAAU,GAAG;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAWF,wBAAsB,cAAc,IAAI,OAAO,CAAC,UAAU,CAAC,CAc1D;AAED,wBAAsB,cAAc,IAAI,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAQjE"}

package/dist/checkpoint.js

@@ -0,0 +1,30 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import { repoctxDir, ensureDirs } from "./cache.js";
+function stateFile() {
+    return path.join(repoctxDir(), "state.json");
+}
+export async function saveCheckpoint() {
+    const head = execSync("git rev-parse HEAD", { encoding: "utf8" }).trim();
+    const branch = execSync("git rev-parse --abbrev-ref HEAD", { encoding: "utf8" }).trim();
+    const at = new Date().toISOString();
+    const state = {
+        repoRoot: process.cwd(),
+        lastCheckpoint: { head, branch, at },
+    };
+    await ensureDirs();
+    await fs.writeFile(stateFile(), JSON.stringify(state, null, 2), "utf8");
+    return { head, branch, at };
+}
+export async function loadCheckpoint() {
+    try {
+        const raw = await fs.readFile(stateFile(), "utf8");
+        const state = JSON.parse(raw);
+        return state.lastCheckpoint ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=checkpoint.js.map

package/dist/checkpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.js","sourceRoot":"","sources":["../src/checkpoint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAapD,SAAS,SAAS;IAChB,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,YAAY,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,MAAM,IAAI,GAAG,QAAQ,CAAC,oBAAoB,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACzE,MAAM,MAAM,GAAG,QAAQ,CAAC,iCAAiC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACxF,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAEpC,MAAM,KAAK,GAAiB;QAC1B,QAAQ,EAAE,OAAO,CAAC,GAAG,EAAE;QACvB,cAAc,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE;KACrC,CAAC;IAEF,MAAM,UAAU,EAAE,CAAC;IACnB,MAAM,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAExE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AAC9B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,EAAE,MAAM,CAAC,CAAC;QACnD,MAAM,KAAK,GAAiB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC5C,OAAO,KAAK,CAAC,cAAc,IAAI,IAAI,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/diff.d.ts

@@ -0,0 +1,4 @@
+export declare function runDiff({ top }?: {
+    top?: number;
+}): Promise<string>;
+//# sourceMappingURL=diff.d.ts.map

package/dist/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"AAoBA,wBAAsB,OAAO,CAAC,EAAE,GAAG,EAAE,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,mBAyE3D"}

package/dist/diff.js

@@ -0,0 +1,76 @@
+import { execSync } from "node:child_process";
+import { loadCheckpoint } from "./checkpoint.js";
+function parseNumstat(output) {
+    const results = [];
+    for (const line of output.trim().split("\n").filter(Boolean)) {
+        const parts = line.split("\t");
+        const file = parts[2];
+        if (!file)
+            continue;
+        results.push({ file, additions: Number(parts[0]), deletions: Number(parts[1]) });
+    }
+    return results;
+}
+export async function runDiff({ top } = {}) {
+    const checkpoint = await loadCheckpoint();
+    if (!checkpoint) {
+        return "No checkpoint found. Run `repoctx checkpoint` first.";
+    }
+    const { head, at } = checkpoint;
+    const shortHead = head.slice(0, 7);
+    let currentHead;
+    try {
+        currentHead = execSync("git rev-parse HEAD", { encoding: "utf8" }).trim();
+    }
+    catch {
+        return "Not in a git repository.";
+    }
+    if (currentHead === head) {
+        return `No changes since checkpoint (${shortHead}).`;
+    }
+    let numstatOutput;
+    try {
+        numstatOutput = execSync(`git diff ${head}..HEAD --numstat`, { encoding: "utf8" });
+    }
+    catch {
+        return `Could not compute diff from ${shortHead}.`;
+    }
+    let stats = parseNumstat(numstatOutput);
+    stats.sort((a, b) => (b.additions + b.deletions) - (a.additions + a.deletions));
+    const topStats = top ? stats.slice(0, top) : stats;
+    const lines = [];
+    lines.push(`# Repoctx Diff (since ${shortHead} — ${at})`);
+    lines.push("");
+    lines.push(`Files changed (${stats.length}):`);
+    lines.push("");
+    for (const s of topStats) {
+        lines.push(`- ${s.file} (+${s.additions} -${s.deletions})`);
+    }
+    if (top && stats.length > top) {
+        lines.push(`... and ${stats.length - top} more files`);
+    }
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+    for (const s of topStats) {
+        try {
+            const fileDiff = execSync(`git diff ${head}..HEAD -- "${s.file}"`, {
+                encoding: "utf8",
+            });
+            if (!fileDiff.trim())
+                continue;
+            lines.push(`[${s.file}]`);
+            const diffLines = fileDiff
+                .split("\n")
+                .filter((l) => (l.startsWith("+") || l.startsWith("-")) && !l.startsWith("+++") && !l.startsWith("---"))
+                .slice(0, 40);
+            lines.push(...diffLines);
+            lines.push("");
+        }
+        catch {
+            // skip if diff fails for a specific file
+        }
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=diff.js.map

package/dist/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"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"}

package/dist/get.d.ts

@@ -0,0 +1,10 @@
+export declare function getContext({ filterPath, keywords, symbol, }?: {
+    filterPath?: string;
+    keywords?: string[];
+    symbol?: string;
+}): Promise<string>;
+export declare function getStale(): Promise<{
+    path: string;
+    reason: string;
+}[]>;
+//# sourceMappingURL=get.d.ts.map

package/dist/get.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get.d.ts","sourceRoot":"","sources":["../src/get.ts"],"names":[],"mappings":"AASA,wBAAsB,UAAU,CAAC,EAC/B,UAAU,EACV,QAAQ,EACR,MAAM,GACP,GAAE;IACD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACZ,mBAsGL;AAID,wBAAsB,QAAQ,IAAI,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC,CAmB5E"}

package/dist/get.js

@@ -0,0 +1,119 @@
+import path from "node:path";
+import { loadIndex, loadFileCache, fileHash, loadAllSymbols, lookupByKeywords, } from "./cache.js";
+export async function getContext({ filterPath, keywords, symbol, } = {}) {
+    const lines = [];
+    // ── Symbol lookup ──────────────────────────────────────────────────────────
+    if (symbol) {
+        const allSymbols = await loadAllSymbols();
+        const match = allSymbols.find((s) => s.symbol.toLowerCase() === symbol.toLowerCase());
+        if (!match)
+            return `No symbol found: "${symbol}"`;
+        lines.push(`[symbol: ${match.symbol}]`);
+        lines.push(`Kind: ${match.kind}`);
+        lines.push(`File: ${match.file}`);
+        lines.push(`Purpose: ${match.purpose}`);
+        if (match.signature)
+            lines.push(`Signature: ${match.signature}`);
+        if (match.related?.length) {
+            lines.push(`Related:`);
+            for (const r of match.related)
+                lines.push(`  - ${r.symbol} (${r.relation})`);
+        }
+        if (match.keywords?.length)
+            lines.push(`Keywords: ${match.keywords.join(", ")}`);
+        lines.push(`Updated: ${match.updatedAt}`);
+        return lines.join("\n");
+    }
+    // ── Determine which paths to show ─────────────────────────────────────────
+    let targetPaths = null; // null = show all
+    if (keywords && keywords.length > 0) {
+        // O(1) lookup via keyword index
+        targetPaths = await lookupByKeywords(keywords);
+    }
+    // ── Module cards ───────────────────────────────────────────────────────────
+    const idx = await loadIndex();
+    const relFilter = filterPath
+        ? path.relative(process.cwd(), path.resolve(filterPath)).replaceAll("\\", "/")
+        : undefined;
+    const pathsToShow = targetPaths ?? Object.keys(idx.files);
+    for (const rel of pathsToShow) {
+        if (relFilter) {
+            const isCwd = relFilter === "" || relFilter === ".";
+            const isExact = rel === relFilter;
+            const isUnder = rel.startsWith(relFilter + "/");
+            if (!isCwd && !isExact && !isUnder)
+                continue;
+        }
+        const cache = await loadFileCache(rel);
+        if (!cache)
+            continue;
+        lines.push(`[${rel}]`);
+        lines.push(cache.summary);
+        if (cache.symbols.length > 0)
+            lines.push(`Symbols: ${cache.symbols.join(", ")}`);
+        if (cache.exports?.length) {
+            lines.push(`Exports: ${cache.exports.map((e) => `${e.name}(${e.kind})`).join(", ")}`);
+        }
+        if (cache.keywords?.length)
+            lines.push(`Keywords: ${cache.keywords.join(", ")}`);
+        if (cache.dependencies?.length)
+            lines.push(`Deps: ${cache.dependencies.join(", ")}`);
+        if (cache.footguns)
+            lines.push(`⚠ Footguns: ${cache.footguns}`);
+        if (cache.delta)
+            lines.push(`Δ Last change: ${cache.delta}`);
+        if (cache.hash !== "meta") {
+            try {
+                const currentHash = await fileHash(path.resolve(rel));
+                if (currentHash !== cache.hash) {
+                    lines.push("⚠ Context outdated (file changed since last save)");
+                }
+            }
+            catch {
+                lines.push("⚠ File not found (may have been deleted or moved)");
+            }
+        }
+        lines.push("");
+    }
+    // ── Symbol cards ───────────────────────────────────────────────────────────
+    const allSymbols = await loadAllSymbols();
+    let symbolsToShow = allSymbols;
+    if (keywords && keywords.length > 0) {
+        symbolsToShow = allSymbols.filter((s) => keywords.some((k) => s.keywords?.includes(k)));
+    }
+    if (symbolsToShow.length > 0 && !symbol) {
+        lines.push("── Symbols ──────────────────────────────────────────────");
+        for (const s of symbolsToShow) {
+            lines.push(`[symbol: ${s.symbol}] (${s.kind}) ${s.file}`);
+            lines.push(`  ${s.purpose}`);
+            if (s.signature)
+                lines.push(`  Sig: ${s.signature}`);
+            if (s.related?.length) {
+                lines.push(`  Related: ${s.related.map((r) => `${r.symbol} (${r.relation})`).join(", ")}`);
+            }
+            lines.push("");
+        }
+    }
+    return lines.join("\n");
+}
+// ── Stale check ───────────────────────────────────────────────────────────────
+export async function getStale() {
+    const idx = await loadIndex();
+    const stale = [];
+    for (const rel of Object.keys(idx.files)) {
+        const cache = await loadFileCache(rel);
+        if (!cache || cache.hash === "meta")
+            continue;
+        try {
+            const currentHash = await fileHash(path.resolve(rel));
+            if (currentHash !== cache.hash) {
+                stale.push({ path: rel, reason: "file content changed" });
+            }
+        }
+        catch {
+            stale.push({ path: rel, reason: "file not found" });
+        }
+    }
+    return stale;
+}
+//# sourceMappingURL=get.js.map

package/dist/get.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get.js","sourceRoot":"","sources":["../src/get.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { saveManual } from "./save.js";
+import { saveSymbol, parseRelated } from "./saveSymbol.js";
+import { getContext, getStale } from "./get.js";
+import { saveCheckpoint } from "./checkpoint.js";
+import { runDiff } from "./diff.js";
+import { getOnboardingText } from "./onboarding.js";
+import { repoctxDir } from "./cache.js";
+const program = new Command();
+program
+    .name("repoctx")
+    .description("Structured context layer for AI coding assistants")
+    .version("0.1.0");
+// ── repoctx save ──────────────────────────────────────────────────────────────
+program
+    .command("save")
+    .description("Save context for a file. Always include --keywords so future agents can find this module with repoctx get --keyword <topic>")
+    .argument("<file>", "File path (or virtual key with --meta)")
+    .argument("<summary>", "What this file does, its role, and conventions")
+    .option("--symbols <symbols>", "Comma-separated exported symbols/functions", "")
+    .option("--keywords <keywords>", "REQUIRED in practice: comma-separated tags (e.g. dal,payments,http). Used by repoctx get --keyword", "")
+    .option("--deps <deps>", "Comma-separated dependencies of this module", "")
+    .option("--footguns <text>", "Gotchas: things that break if touched wrong (e.g. soft-delete vs hard-delete)")
+    .option("--delta <text>", "What changed in this save — short description of the diff")
+    .option("--meta", "Virtual entry — no real file, skips hash check. Use for patterns, glossary, folder maps")
+    .action(async (file, summary, opts) => {
+    const split = (s) => s ? s.split(",").map((x) => x.trim()).filter(Boolean) : [];
+    const rel = await saveManual({
+        filePath: file,
+        summary,
+        symbols: split(opts.symbols),
+        keywords: split(opts.keywords),
+        dependencies: split(opts.deps),
+        footguns: opts.footguns,
+        delta: opts.delta,
+        meta: !!opts.meta,
+    });
+    console.log(`✓ Saved context for ${rel}`);
+});
+// ── repoctx save-symbol ───────────────────────────────────────────────────────
+program
+    .command("save-symbol")
+    .description("Save a Symbol Card for a specific function, class, or constant. Enables repoctx get --symbol <name> lookup")
+    .argument("<symbol>", "Symbol name (e.g. removeCharge)")
+    .argument("<purpose>", "One-line description of what this symbol does")
+    .requiredOption("--file <file>", "File where the symbol lives")
+    .option("--kind <kind>", "function | class | constant | type | other", "function")
+    .option("--signature <sig>", "Full signature (e.g. '({ chargeSchema }) => async ({ id }) => Promise<Result>')")
+    .option("--related <pairs>", "Typed relations: 'symbol:relation,symbol:relation' (e.g. 'deleteCharge:soft-delete variant')", "")
+    .option("--keywords <keywords>", "Same tags as the parent module so --keyword lookups include this symbol too", "")
+    .action(async (symbol, purpose, opts) => {
+    const split = (s) => s ? s.split(",").map((x) => x.trim()).filter(Boolean) : [];
+    await saveSymbol({
+        symbol,
+        purpose,
+        file: opts.file,
+        kind: opts.kind,
+        signature: opts.signature,
+        related: opts.related ? parseRelated(opts.related) : [],
+        keywords: split(opts.keywords),
+    });
+    console.log(`✓ Saved symbol card for ${symbol}`);
+});
+// ── repoctx get ───────────────────────────────────────────────────────────────
+program
+    .command("get")
+    .description("Print saved context. Prefer --keyword over bare get — it's faster, cheaper, and less noisy")
+    .argument("[path]", "Filter by file or directory path")
+    .option("--keyword <keywords>", "Filter by keyword(s), comma-separated OR logic. e.g. --keyword dal,payments. Use this before reaching for Read on a source file")
+    .option("--symbol <name>", "Look up a specific symbol card by name")
+    .action(async (filterPath, opts) => {
+    const keywords = opts.keyword
+        ? opts.keyword.split(",").map((s) => s.trim()).filter(Boolean)
+        : undefined;
+    const output = await getContext({
+        ...(filterPath !== undefined && { filterPath }),
+        ...(keywords !== undefined && { keywords }),
+        ...(opts.symbol !== undefined && { symbol: opts.symbol }),
+    });
+    if (!output.trim()) {
+        console.log("No context found. Use `repoctx save` to add context.");
+        return;
+    }
+    process.stdout.write(output + "\n");
+});
+// ── repoctx stale ─────────────────────────────────────────────────────────────
+program
+    .command("stale")
+    .description("List all indexed files whose content changed since last save")
+    .action(async () => {
+    const results = await getStale();
+    if (results.length === 0) {
+        console.log("✓ All context is up to date.");
+        return;
+    }
+    console.log(`${results.length} stale file(s):\n`);
+    for (const { path: p, reason } of results) {
+        console.log(`  ⚠ ${p}  (${reason})`);
+        console.log(`    → repoctx save ${p} "<updated summary>" --keywords "..." --delta "what changed"`);
+    }
+});
+// ── repoctx checkpoint ────────────────────────────────────────────────────────
+program
+    .command("checkpoint")
+    .description("Save current git HEAD as baseline for future diffs")
+    .action(async () => {
+    try {
+        const cp = await saveCheckpoint();
+        console.log(`✓ Checkpoint saved: ${cp.branch} @ ${cp.head.slice(0, 7)} (${cp.at})`);
+    }
+    catch (e) {
+        console.error(`Error: ${e?.message ?? e}`);
+        console.error("Make sure you are inside a git repository.");
+        process.exit(1);
+    }
+});
+// ── repoctx diff ──────────────────────────────────────────────────────────────
+program
+    .command("diff")
+    .description("Show changes since last checkpoint, formatted for Claude")
+    .option("--top <n>", "Show only top N changed files by lines modified")
+    .action(async (opts) => {
+    const top = opts.top ? Number(opts.top) : undefined;
+    const output = await runDiff(top !== undefined ? { top } : {});
+    process.stdout.write(output + "\n");
+});
+// ── repoctx init ──────────────────────────────────────────────────────────────
+program
+    .command("init")
+    .description("Initialize repoctx in the current repo: creates .repoctx/ and adds it to .gitignore")
+    .action(async () => {
+    await fs.mkdir(repoctxDir(), { recursive: true });
+    // Add .repoctx to .gitignore if not already there
+    const gitignorePath = path.join(process.cwd(), ".gitignore");
+    let alreadyIgnored = false;
+    try {
+        const content = await fs.readFile(gitignorePath, "utf8");
+        alreadyIgnored = content.split("\n").some((l) => l.trim() === ".repoctx");
+    }
+    catch {
+        // no .gitignore yet, will create
+    }
+    if (!alreadyIgnored) {
+        await fs.appendFile(gitignorePath, "\n# repoctx context index\n.repoctx\n");
+        console.log("✓ Added .repoctx to .gitignore");
+    }
+    else {
+        console.log("✓ .repoctx already in .gitignore");
+    }
+    console.log("✓ repoctx initialized. Run `repoctx onboarding` to get CLAUDE.md instructions.");
+});
+// ── repoctx onboarding ────────────────────────────────────────────────────────
+program
+    .command("onboarding")
+    .description("Print instructions for AI agents (paste into CLAUDE.md)")
+    .action(() => {
+    process.stdout.write(getOnboardingText() + "\n");
+});
+program.parseAsync(process.argv).catch((e) => {
+    console.error(e?.message ?? e);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/onboarding.d.ts

@@ -0,0 +1,2 @@
+export declare function getOnboardingText(): string;
+//# sourceMappingURL=onboarding.d.ts.map

package/dist/onboarding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding.d.ts","sourceRoot":"","sources":["../src/onboarding.ts"],"names":[],"mappings":"AAAA,wBAAgB,iBAAiB,IAAI,MAAM,CAyH1C"}

package/dist/onboarding.js

@@ -0,0 +1,123 @@
+export function getOnboardingText() {
+    return `
+# repoctx — Agent Instructions
+
+repoctx is a persistent context layer for this repo. It stores module
+summaries, symbol cards, patterns, and domain knowledge in .repoctx/.
+
+The index survives session resets — you never lose context when a
+conversation closes and reopens. Always read from repoctx first; it
+prevents hallucinations by grounding your understanding in committed,
+structured facts instead of memory.
+
+## Always start a session with
+
+\`\`\`bash
+repoctx get --keyword <topic>   # targeted: only what you need
+repoctx diff --top 8            # what changed since the last checkpoint
+\`\`\`
+
+Prefer \`--keyword\` over a bare \`repoctx get\` (which dumps everything).
+Use keywords to fetch only the modules relevant to the current task.
+This keeps context small and responses fast.
+
+## Targeted lookups — use these instead of reading source files
+
+\`\`\`bash
+repoctx get --keyword dal,users       # modules related to a topic
+repoctx get --keyword auth            # modules in the auth domain
+repoctx get --symbol deleteUser       # look up a specific function
+repoctx get src/users/                # everything indexed under a path
+\`\`\`
+
+Keywords are OR-filtered: \`--keyword dal,charge\` returns anything tagged
+with "dal" OR "charge". Each module and symbol has its own keyword list —
+use them to navigate without reading files.
+
+## Speed note
+
+Every file you skip reading = one fewer tool call = faster response.
+A \`repoctx get --keyword X\` is one call. Reading three source files is
+three calls. Always check repoctx before reaching for Read.
+
+## When to run \`repoctx save\` (public contract changed)
+
+Run it when any of these change:
+- Exported functions, classes, or constants
+- Module.exports / ESM exports
+- Route handlers or API surface
+- DAL/service patterns (factory signatures, argument shapes)
+- Business logic behavior (soft-delete vs hard-delete, idempotency, etc.)
+- A file is moved, renamed, or becomes a new entrypoint
+- A new convention or pattern is introduced
+
+Always include \`--keywords\` matching the domain and layer so future
+lookups via \`--keyword\` can find this module:
+
+\`\`\`bash
+repoctx save src/users/dal.js \\
+  "MongoDB DAL for users. CRUD operations." \\
+  --symbols "createUser,getUser,deleteUser" \\
+  --keywords "dal,users,mongodb" \\
+  --delta "Added deleteUser (soft delete)"
+\`\`\`
+
+Use \`--footguns\` to warn future agents about tricky behavior:
+
+\`\`\`bash
+  --footguns "deleteUser = soft delete. removeUser = hard delete. Don't confuse them."
+\`\`\`
+
+## When NOT to run \`repoctx save\`
+
+Skip it for:
+- Literals, log messages, comments, or formatting
+- Internal refactors with no change to the public interface
+- Test-only changes
+
+## Symbol Cards (fine-grained lookup)
+
+For key functions worth tracking individually:
+
+\`\`\`bash
+repoctx save-symbol deleteUser "Hard delete a user from MongoDB" \\
+  --file src/users/dal.js \\
+  --kind function \\
+  --signature "({ userSchema }) => async ({ id }) => Promise<DeleteResult>" \\
+  --related "softDeleteUser:soft-delete variant" \\
+  --keywords "dal,users,delete"
+\`\`\`
+
+Then look it up with: \`repoctx get --symbol deleteUser\`
+
+## Meta entries (patterns, glossary, folder map)
+
+For knowledge not tied to a single file, use \`--meta\`:
+
+\`\`\`bash
+repoctx save .meta/patterns "DAL pattern: ({ schema }) => async (args) => ..." \\
+  --keywords "pattern,convention,dal" --meta
+
+repoctx save .meta/glossary "user = registered account. session = active login token." \\
+  --keywords "glossary,domain" --meta
+
+repoctx save .meta/structure "src/users = user domain. src/auth = authentication. src/api = route handlers." \\
+  --keywords "structure,folders" --meta
+\`\`\`
+
+## Freshness
+
+If \`repoctx get\` shows \`⚠ Context outdated\` for a file, read it and
+run \`repoctx save\` with an updated summary before working on it.
+Refresh only the stale file — do not re-index the whole repo.
+
+## Output discipline
+
+- Always try \`repoctx get --keyword <topic>\` before reaching for Read.
+- If repoctx can answer your question, stop there.
+- If you must read a file, prefer a targeted slice (10–30 lines) to
+  confirm exact syntax, not to understand the module from scratch.
+- After a meaningful change, update repoctx for that module.
+`.trim();
+}
+//# sourceMappingURL=onboarding.js.map

package/dist/onboarding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding.js","sourceRoot":"","sources":["../src/onboarding.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,iBAAiB;IAC/B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuHR,CAAC,IAAI,EAAE,CAAC;AACT,CAAC"}

package/dist/save.d.ts

@@ -0,0 +1,13 @@
+import { type ExportEntry } from "./cache.js";
+export declare function saveManual({ filePath, summary, symbols, exports: exportsArg, keywords, dependencies, footguns, delta, meta, }: {
+    filePath: string;
+    summary: string;
+    symbols: string[];
+    exports?: ExportEntry[];
+    keywords: string[];
+    dependencies?: string[];
+    footguns?: string;
+    delta?: string;
+    meta?: boolean;
+}): Promise<string>;
+//# sourceMappingURL=save.d.ts.map

package/dist/save.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"save.d.ts","sourceRoot":"","sources":["../src/save.ts"],"names":[],"mappings":"AAEA,OAAO,EAKL,KAAK,WAAW,EACjB,MAAM,YAAY,CAAC;AAqBpB,wBAAsB,UAAU,CAAC,EAC/B,QAAQ,EACR,OAAO,EACP,OAAO,EACP,OAAO,EAAE,UAAU,EACnB,QAAQ,EACR,YAAY,EACZ,QAAQ,EACR,KAAK,EACL,IAAY,GACb,EAAE;IACD,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB,mBA+BA"}

package/dist/save.js

@@ -0,0 +1,53 @@
+import path from "node:path";
+import { execSync } from "node:child_process";
+import { fileHash, saveFileCache, getGitHead, computePublicSurfaceHash, } from "./cache.js";
+function findWhereUsed(relPath) {
+    try {
+        const basename = path.basename(relPath, path.extname(relPath));
+        const raw = execSync(`grep -r --include="*.js" --include="*.ts" -l "${basename}" . 2>/dev/null || true`, { encoding: "utf8", cwd: process.cwd() });
+        return raw
+            .trim()
+            .split("\n")
+            .filter(Boolean)
+            .filter((f) => !f.includes("node_modules") && !f.includes(".repoctx"))
+            .filter((f) => f !== `./${relPath}` && f !== relPath)
+            .slice(0, 5);
+    }
+    catch {
+        return [];
+    }
+}
+export async function saveManual({ filePath, summary, symbols, exports: exportsArg, keywords, dependencies, footguns, delta, meta = false, }) {
+    const rel = meta
+        ? filePath.replaceAll("\\", "/")
+        : path.relative(process.cwd(), path.resolve(filePath)).replaceAll("\\", "/");
+    const hash = meta ? "meta" : await fileHash(path.resolve(filePath));
+    const publicSurfaceHash = symbols.length > 0 ? computePublicSurfaceHash(symbols) : undefined;
+    const head = getGitHead();
+    const whereUsed = meta ? [] : findWhereUsed(rel);
+    const entry = {
+        path: rel,
+        hash,
+        summary: whereUsed.length > 0
+            ? `${summary}\nUsed in: ${whereUsed.join(", ")}`
+            : summary,
+        symbols,
+        keywords,
+        updatedAt: new Date().toISOString(),
+    };
+    if (publicSurfaceHash)
+        entry.publicSurfaceHash = publicSurfaceHash;
+    if (exportsArg && exportsArg.length > 0)
+        entry.exports = exportsArg;
+    if (dependencies && dependencies.length > 0)
+        entry.dependencies = dependencies;
+    if (footguns)
+        entry.footguns = footguns;
+    if (delta)
+        entry.delta = delta;
+    if (head)
+        entry.repoHeadAtSave = head;
+    await saveFileCache(rel, entry);
+    return rel;
+}
+//# sourceMappingURL=save.js.map

package/dist/save.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"save.js","sourceRoot":"","sources":["../src/save.ts"],"names":[],"mappings":"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"}

package/dist/saveSymbol.d.ts

@@ -0,0 +1,13 @@
+import { type SymbolCard, type SymbolRelation } from "./cache.js";
+export declare function saveSymbol({ symbol, kind, file, signature, purpose, related, keywords, }: {
+    symbol: string;
+    kind: SymbolCard["kind"];
+    file: string;
+    signature?: string;
+    purpose: string;
+    related?: SymbolRelation[];
+    keywords?: string[];
+}): Promise<string>;
+/** Parse "symbol:relation,symbol:relation" format from CLI */
+export declare function parseRelated(raw: string): SymbolRelation[];
+//# sourceMappingURL=saveSymbol.d.ts.map

package/dist/saveSymbol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saveSymbol.d.ts","sourceRoot":"","sources":["../src/saveSymbol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAElF,wBAAsB,UAAU,CAAC,EAC/B,MAAM,EACN,IAAI,EACJ,IAAI,EACJ,SAAS,EACT,OAAO,EACP,OAAO,EACP,QAAQ,GACT,EAAE;IACD,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB,mBAeA;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,EAAE,CAY1D"}

package/dist/saveSymbol.js

@@ -0,0 +1,33 @@
+import { saveSymbolCard } from "./cache.js";
+export async function saveSymbol({ symbol, kind, file, signature, purpose, related, keywords, }) {
+    const card = {
+        symbol,
+        kind,
+        file,
+        purpose,
+        updatedAt: new Date().toISOString(),
+    };
+    if (signature)
+        card.signature = signature;
+    if (related && related.length > 0)
+        card.related = related;
+    if (keywords && keywords.length > 0)
+        card.keywords = keywords;
+    await saveSymbolCard(card);
+    return symbol;
+}
+/** Parse "symbol:relation,symbol:relation" format from CLI */
+export function parseRelated(raw) {
+    return raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((s) => {
+        const [symbol, ...rest] = s.split(":");
+        return {
+            symbol: symbol.trim(),
+            relation: rest.join(":").trim() || "related",
+        };
+    });
+}
+//# sourceMappingURL=saveSymbol.js.map

package/dist/saveSymbol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"saveSymbol.js","sourceRoot":"","sources":["../src/saveSymbol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAwC,MAAM,YAAY,CAAC;AAElF,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,EAC/B,MAAM,EACN,IAAI,EACJ,IAAI,EACJ,SAAS,EACT,OAAO,EACP,OAAO,EACP,QAAQ,GAST;IACC,MAAM,IAAI,GAAe;QACvB,MAAM;QACN,IAAI;QACJ,IAAI;QACJ,OAAO;QACP,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;IAEF,IAAI,SAAS;QAAE,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC1C,IAAI,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC1D,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAE9D,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,GAAG;SACP,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,OAAO,CAAC;SACf,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACT,MAAM,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACvC,OAAO;YACL,MAAM,EAAE,MAAO,CAAC,IAAI,EAAE;YACtB,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,SAAS;SAC7C,CAAC;IACJ,CAAC,CAAC,CAAC;AACP,CAAC"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "type": "module",
+  "name": "repoctx",
+  "version": "0.1.0",
+  "description": "Structured context layer for AI coding assistants. Reduces token cost and exploration overhead by storing file summaries, symbol cards and git diffs in .repoctx/",
+  "bin": { "repoctx": "dist/index.js" },
+  "main": "dist/index.js",
+  "files": ["dist"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "claude",
+    "llm",
+    "context",
+    "tokens",
+    "developer-tools",
+    "cli",
+    "codebase",
+    "agent"
+  ],
+  "author": {
+    "name": "Ezequiel",
+    "url": "https://github.com/Ezequiiel98"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Ezequiiel98/repoctx"
+  },
+  "homepage": "https://github.com/Ezequiiel98/repoctx#readme",
+  "bugs": {
+    "url": "https://github.com/Ezequiiel98/repoctx/issues"
+  },
+  "dependencies": {
+    "commander": "^14.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}