@googlarz/agents-sync 1.4.0

package/dist/lib/claude-client.js

@@ -0,0 +1,74 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { AgentsSyncError } from "./errors.js";
+const MODEL = "claude-sonnet-4-6";
+const MAX_RETRIES = 3;
+const RETRY_DELAY_MS = 2000;
+let _client = null;
+function getClient() {
+    if (!_client) {
+        const apiKey = process.env.ANTHROPIC_API_KEY;
+        if (!apiKey) {
+            throw new AgentsSyncError("MISSING_API_KEY", "ANTHROPIC_API_KEY environment variable is not set.", "Export it: export ANTHROPIC_API_KEY=sk-ant-...");
+        }
+        _client = new Anthropic({ apiKey });
+    }
+    return _client;
+}
+function debug(msg) {
+    if (process.env.AGENTS_SYNC_DEBUG === "1") {
+        process.stderr.write(`[agents-sync:debug] ${msg}\n`);
+    }
+}
+export async function callClaude(systemPrompt, userPrompt, maxTokens = 4096) {
+    const client = getClient();
+    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            debug(`Claude call attempt ${attempt}, maxTokens=${maxTokens}`);
+            const response = await client.messages.create({
+                model: MODEL,
+                max_tokens: maxTokens,
+                system: [
+                    {
+                        type: "text",
+                        text: systemPrompt,
+                        cache_control: { type: "ephemeral" },
+                    },
+                ],
+                messages: [{ role: "user", content: userPrompt }],
+            });
+            const content = response.content
+                .filter((b) => b.type === "text")
+                .map((b) => b.text)
+                .join("");
+            const usage = {
+                inputTokens: response.usage.input_tokens,
+                outputTokens: response.usage.output_tokens,
+                cacheReadTokens: response.usage.cache_read_input_tokens ?? 0,
+                cacheWriteTokens: response.usage.cache_creation_input_tokens ?? 0,
+            };
+            debug(`Response: ${usage.outputTokens} out, ${usage.cacheReadTokens} cache_read, ${usage.cacheWriteTokens} cache_write`);
+            return { content, usage };
+        }
+        catch (e) {
+            const err = e;
+            if (err.status === 429 && attempt < MAX_RETRIES) {
+                debug(`Rate limited, retrying in ${RETRY_DELAY_MS * attempt}ms...`);
+                await sleep(RETRY_DELAY_MS * attempt);
+                continue;
+            }
+            if (err.status === 529 && attempt < MAX_RETRIES) {
+                debug(`Overloaded, retrying in ${RETRY_DELAY_MS}ms...`);
+                await sleep(RETRY_DELAY_MS);
+                continue;
+            }
+            throw new AgentsSyncError(err.status === 429 ? "RATE_LIMIT" : "API_ERROR", `Claude API error: ${err.message ?? String(e)}`, err.status === 429
+                ? "Rate limited. Try again in ~60 seconds. Use --fast flag to skip re-extraction."
+                : "Run with AGENTS_SYNC_DEBUG=1 to see full error.");
+        }
+    }
+    throw new AgentsSyncError("RATE_LIMIT", "Rate limited after 3 retries.", "Wait ~60 seconds and try again.");
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+//# sourceMappingURL=claude-client.js.map

package/dist/lib/claude-client.js.map

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

package/dist/lib/errors.d.ts

@@ -0,0 +1,10 @@
+export type ErrorCode = "MISSING_API_KEY" | "INVALID_PROJECT_PATH" | "NO_SNAPSHOT" | "RATE_LIMIT" | "API_ERROR" | "EXTRACTION_FAILED" | "GENERATION_FAILED" | "WRITE_ERROR" | "PARSE_ERROR" | "TIMEOUT";
+export declare class AgentsSyncError extends Error {
+    readonly code: ErrorCode;
+    readonly hint?: string | undefined;
+    constructor(code: ErrorCode, message: string, hint?: string | undefined);
+    format(): string;
+}
+export declare function isAgentsSyncError(e: unknown): e is AgentsSyncError;
+export declare function toMcpError(e: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/lib/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GACjB,iBAAiB,GACjB,sBAAsB,GACtB,aAAa,GACb,YAAY,GACZ,WAAW,GACX,mBAAmB,GACnB,mBAAmB,GACnB,aAAa,GACb,aAAa,GACb,SAAS,CAAC;AAEd,qBAAa,eAAgB,SAAQ,KAAK;aAEtB,IAAI,EAAE,SAAS;aAEf,IAAI,CAAC,EAAE,MAAM;gBAFb,IAAI,EAAE,SAAS,EAC/B,OAAO,EAAE,MAAM,EACC,IAAI,CAAC,EAAE,MAAM,YAAA;IAM/B,MAAM,IAAI,MAAM;CAKjB;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,eAAe,CAElE;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAI7C"}

package/dist/lib/errors.js

@@ -0,0 +1,27 @@
+export class AgentsSyncError extends Error {
+    code;
+    hint;
+    constructor(code, message, hint) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+        this.name = "AgentsSyncError";
+    }
+    format() {
+        const lines = [`[${this.code}] ${this.message}`];
+        if (this.hint)
+            lines.push(`  → ${this.hint}`);
+        return lines.join("\n");
+    }
+}
+export function isAgentsSyncError(e) {
+    return e instanceof AgentsSyncError;
+}
+export function toMcpError(e) {
+    if (e instanceof AgentsSyncError)
+        return e.format();
+    if (e instanceof Error)
+        return e.message;
+    return String(e);
+}
+//# sourceMappingURL=errors.js.map

package/dist/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAYA,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAEtB;IAEA;IAHlB,YACkB,IAAe,EAC/B,OAAe,EACC,IAAa;QAE7B,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,SAAI,GAAJ,IAAI,CAAW;QAEf,SAAI,GAAJ,IAAI,CAAS;QAG7B,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;IAED,MAAM;QACJ,MAAM,KAAK,GAAG,CAAC,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QACjD,IAAI,IAAI,CAAC,IAAI;YAAE,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QAC9C,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;CACF;AAED,MAAM,UAAU,iBAAiB,CAAC,CAAU;IAC1C,OAAO,CAAC,YAAY,eAAe,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,CAAU;IACnC,IAAI,CAAC,YAAY,eAAe;QAAE,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC;IACpD,IAAI,CAAC,YAAY,KAAK;QAAE,OAAO,CAAC,CAAC,OAAO,CAAC;IACzC,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;AACnB,CAAC"}

package/dist/lib/file-utils.d.ts

@@ -0,0 +1,7 @@
+export declare function readFileSafe(filePath: string): Promise<string | null>;
+export declare function writeFileAtomic(filePath: string, content: string): Promise<void>;
+export declare function dirExists(p: string): Promise<boolean>;
+export declare function fileExists(p: string): Promise<boolean>;
+export declare function assertAbsolutePath(p: string): void;
+export declare function assertProjectDir(p: string): Promise<void>;
+//# sourceMappingURL=file-utils.d.ts.map

package/dist/lib/file-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-utils.d.ts","sourceRoot":"","sources":["../../src/lib/file-utils.ts"],"names":[],"mappings":"AAIA,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAM3E;AAED,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CActF;AAED,wBAAsB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO3D;AAED,wBAAsB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO5D;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAQlD;AAED,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAS/D"}

package/dist/lib/file-utils.js

@@ -0,0 +1,56 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { AgentsSyncError } from "./errors.js";
+export async function readFileSafe(filePath) {
+    try {
+        return await fs.readFile(filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeFileAtomic(filePath, content) {
+    const tmp = filePath + ".agents-sync.tmp";
+    try {
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        await fs.writeFile(tmp, content, "utf-8");
+        await fs.rename(tmp, filePath);
+    }
+    catch (e) {
+        try {
+            await fs.unlink(tmp);
+        }
+        catch { /* ignore */ }
+        throw new AgentsSyncError("WRITE_ERROR", `Cannot write to ${filePath}: ${e.message}`, "Check file permissions and disk space.");
+    }
+}
+export async function dirExists(p) {
+    try {
+        const stat = await fs.stat(p);
+        return stat.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export async function fileExists(p) {
+    try {
+        await fs.stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function assertAbsolutePath(p) {
+    if (!path.isAbsolute(p)) {
+        throw new AgentsSyncError("INVALID_PROJECT_PATH", `Path must be absolute: ${p}`, "Pass the full path, e.g. /Users/you/my-project");
+    }
+}
+export async function assertProjectDir(p) {
+    assertAbsolutePath(p);
+    if (!(await dirExists(p))) {
+        throw new AgentsSyncError("INVALID_PROJECT_PATH", `Project path not found: ${p}`, "Make sure the directory exists and the path is correct.");
+    }
+}
+//# sourceMappingURL=file-utils.js.map

package/dist/lib/file-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-utils.js","sourceRoot":"","sources":["../../src/lib/file-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,QAAgB;IACjD,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,QAAgB,EAAE,OAAe;IACrE,MAAM,GAAG,GAAG,QAAQ,GAAG,kBAAkB,CAAC;IAC1C,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5D,MAAM,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC1C,MAAM,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC;YAAC,MAAM,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;QACpD,MAAM,IAAI,eAAe,CACvB,aAAa,EACb,mBAAmB,QAAQ,KAAM,CAAW,CAAC,OAAO,EAAE,EACtD,wCAAwC,CACzC,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,CAAS;IACvC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC9B,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,CAAS;IACxC,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,CAAS;IAC1C,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,eAAe,CACvB,sBAAsB,EACtB,0BAA0B,CAAC,EAAE,EAC7B,gDAAgD,CACjD,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,CAAS;IAC9C,kBAAkB,CAAC,CAAC,CAAC,CAAC;IACtB,IAAI,CAAC,CAAC,MAAM,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,eAAe,CACvB,sBAAsB,EACtB,2BAA2B,CAAC,EAAE,EAC9B,yDAAyD,CAC1D,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/lib/token-estimate.d.ts

@@ -0,0 +1,7 @@
+/** Rough token estimate: ~4 chars per token for code */
+export declare function estimateTokens(text: string): number;
+export declare function truncateToTokenBudget(text: string, maxTokens: number): {
+    text: string;
+    truncated: boolean;
+};
+//# sourceMappingURL=token-estimate.d.ts.map

package/dist/lib/token-estimate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-estimate.d.ts","sourceRoot":"","sources":["../../src/lib/token-estimate.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAChB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAStC"}

package/dist/lib/token-estimate.js

@@ -0,0 +1,15 @@
+/** Rough token estimate: ~4 chars per token for code */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+export function truncateToTokenBudget(text, maxTokens) {
+    const estimated = estimateTokens(text);
+    if (estimated <= maxTokens)
+        return { text, truncated: false };
+    const maxChars = maxTokens * 4;
+    return {
+        text: text.slice(0, maxChars) + `\n\n[... truncated at ~${maxTokens} tokens]`,
+        truncated: true,
+    };
+}
+//# sourceMappingURL=token-estimate.js.map

package/dist/lib/token-estimate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-estimate.js","sourceRoot":"","sources":["../../src/lib/token-estimate.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,IAAY,EACZ,SAAiB;IAEjB,MAAM,SAAS,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,SAAS,IAAI,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAE9D,MAAM,QAAQ,GAAG,SAAS,GAAG,CAAC,CAAC;IAC/B,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,GAAG,0BAA0B,SAAS,UAAU;QAC7E,SAAS,EAAE,IAAI;KAChB,CAAC;AACJ,CAAC"}

package/dist/scanner/codegraph.d.ts

@@ -0,0 +1,13 @@
+export interface CodegraphSummary {
+    available: boolean;
+    communities: CodegraphCommunity[];
+    hubNodes: string[];
+    entryPoints: string[];
+}
+export interface CodegraphCommunity {
+    name: string;
+    files: string[];
+}
+export declare function readCodegraphIndex(projectPath: string): Promise<CodegraphSummary>;
+export declare function formatCodegraphContext(summary: CodegraphSummary): string;
+//# sourceMappingURL=codegraph.d.ts.map

package/dist/scanner/codegraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegraph.d.ts","sourceRoot":"","sources":["../../src/scanner/codegraph.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,kBAAkB,EAAE,CAAC;IAClC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAcD,wBAAsB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAqCvF;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAuBxE"}

package/dist/scanner/codegraph.js

@@ -0,0 +1,65 @@
+/**
+ * codegraph scanner
+ *
+ * Reads .codegraph/index.json (if present) and returns a lightweight summary
+ * of community clusters + hub nodes that can be injected into the corpus.
+ * This enriches AGENTS.md with evidence-backed architecture notes.
+ *
+ * Gracefully no-ops when .codegraph/ is absent — works without codegraph.
+ */
+import path from "node:path";
+import fs from "node:fs/promises";
+export async function readCodegraphIndex(projectPath) {
+    const candidates = [
+        path.join(projectPath, ".codegraph", "index.json"),
+        path.join(projectPath, ".codegraph", "graph.json"),
+        path.join(projectPath, "codegraph.json"),
+    ];
+    for (const candidate of candidates) {
+        const raw = await fs.readFile(candidate, "utf-8").catch(() => null);
+        if (!raw)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        const communities = (parsed.communities ?? []).slice(0, 8).map((c) => ({
+            name: c.label ?? c.name ?? "unnamed",
+            files: (c.files ?? c.nodes?.map((n) => n.file ?? n.path ?? "").filter(Boolean) ?? []).slice(0, 5),
+        }));
+        const hubNodes = (parsed.hubNodes ?? parsed.nodes?.filter((n) => (n.hubScore ?? 0) > 0.5) ?? [])
+            .slice(0, 10)
+            .map((n) => n.file ?? n.path ?? n.name ?? "")
+            .filter(Boolean);
+        const entryPoints = (parsed.entryPoints ?? parsed.nodes?.filter((n) => n.isEntry) ?? [])
+            .slice(0, 8)
+            .map((n) => n.file ?? n.path ?? "")
+            .filter(Boolean);
+        return { available: true, communities, hubNodes, entryPoints };
+    }
+    return { available: false, communities: [], hubNodes: [], entryPoints: [] };
+}
+export function formatCodegraphContext(summary) {
+    if (!summary.available)
+        return "";
+    const lines = ["## Code Graph (from .codegraph/)"];
+    if (summary.communities.length > 0) {
+        lines.push("\n### Architecture clusters");
+        for (const c of summary.communities) {
+            lines.push(`- **${c.name}**: ${c.files.join(", ")}`);
+        }
+    }
+    if (summary.hubNodes.length > 0) {
+        lines.push("\n### High-connectivity files (call hubs)");
+        lines.push(summary.hubNodes.map((n) => `- ${n}`).join("\n"));
+    }
+    if (summary.entryPoints.length > 0) {
+        lines.push("\n### Entry points");
+        lines.push(summary.entryPoints.map((n) => `- ${n}`).join("\n"));
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=codegraph.js.map

package/dist/scanner/codegraph.js.map

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

package/dist/scanner/docs.d.ts

@@ -0,0 +1,13 @@
+export interface DocData {
+    readme: string | null;
+    contributing: string | null;
+    architecture: string | null;
+    existingAgentsMd: string | null;
+    existingClaudeMd: string | null;
+    existingCursorRules: string | null;
+    hasExistingClaudeMd: boolean;
+    hasExistingAgentsMd: boolean;
+    totalTokens: number;
+}
+export declare function scanDocs(projectPath: string): Promise<DocData>;
+//# sourceMappingURL=docs.d.ts.map

package/dist/scanner/docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/scanner/docs.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,mBAAmB,EAAE,OAAO,CAAC;IAC7B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;CACrB;AAyCD,wBAAsB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAkCpE"}

package/dist/scanner/docs.js

@@ -0,0 +1,63 @@
+import path from "node:path";
+import { readFileSafe } from "../lib/file-utils.js";
+import { estimateTokens, truncateToTokenBudget } from "../lib/token-estimate.js";
+const DOC_SPECS = [
+    { field: "existingAgentsMd", candidates: ["AGENTS.md"], budget: 3000 },
+    { field: "existingClaudeMd", candidates: ["CLAUDE.md"], budget: 2000 },
+    { field: "readme", candidates: ["README.md", "readme.md", "README.rst"], budget: 2500 },
+    { field: "contributing", candidates: ["CONTRIBUTING.md", "contributing.md"], budget: 1000 },
+    {
+        field: "architecture",
+        candidates: [
+            "ARCHITECTURE.md",
+            "architecture.md",
+            "docs/ARCHITECTURE.md",
+            "docs/architecture.md",
+        ],
+        budget: 1500,
+    },
+    { field: "existingCursorRules", candidates: [".cursorrules"], budget: 500 },
+];
+async function readFirstMatch(projectPath, candidates, budget) {
+    for (const candidate of candidates) {
+        const raw = await readFileSafe(path.join(projectPath, candidate));
+        if (raw !== null) {
+            const { text } = truncateToTokenBudget(raw, budget);
+            return text;
+        }
+    }
+    return null;
+}
+export async function scanDocs(projectPath) {
+    const result = {
+        readme: null,
+        contributing: null,
+        architecture: null,
+        existingAgentsMd: null,
+        existingClaudeMd: null,
+        existingCursorRules: null,
+        hasExistingClaudeMd: false,
+        hasExistingAgentsMd: false,
+        totalTokens: 0,
+    };
+    for (const spec of DOC_SPECS) {
+        try {
+            const content = await readFirstMatch(projectPath, spec.candidates, spec.budget);
+            result[spec.field] = content;
+        }
+        catch {
+            // leave null
+        }
+    }
+    result.hasExistingClaudeMd = result.existingClaudeMd !== null;
+    result.hasExistingAgentsMd = result.existingAgentsMd !== null;
+    result.totalTokens =
+        estimateTokens(result.readme ?? "") +
+            estimateTokens(result.contributing ?? "") +
+            estimateTokens(result.architecture ?? "") +
+            estimateTokens(result.existingAgentsMd ?? "") +
+            estimateTokens(result.existingClaudeMd ?? "") +
+            estimateTokens(result.existingCursorRules ?? "");
+    return result;
+}
+//# sourceMappingURL=docs.js.map

package/dist/scanner/docs.js.map

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

package/dist/scanner/gotchas.d.ts

@@ -0,0 +1,8 @@
+export interface Gotcha {
+    file: string;
+    line: number;
+    type: "HACK" | "FIXME" | "WARNING" | "IMPORTANT" | "TODO" | "NOTE";
+    comment: string;
+}
+export declare function scanGotchas(projectPath: string, maxResults?: number): Promise<Gotcha[]>;
+//# sourceMappingURL=gotchas.d.ts.map

package/dist/scanner/gotchas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gotchas.d.ts","sourceRoot":"","sources":["../../src/scanner/gotchas.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC;IACnE,OAAO,EAAE,MAAM,CAAC;CACjB;AAmDD,wBAAsB,WAAW,CAC/B,WAAW,EAAE,MAAM,EACnB,UAAU,SAAK,GACd,OAAO,CAAC,MAAM,EAAE,CAAC,CA6DnB"}

package/dist/scanner/gotchas.js

@@ -0,0 +1,107 @@
+import path from "node:path";
+import fg from "fast-glob";
+import { readFileSafe } from "../lib/file-utils.js";
+const IGNORE_PATTERNS = [
+    "**/node_modules/**",
+    "**/.git/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/__pycache__/**",
+    "**/.venv/**",
+    "**/target/**",
+    "**/.next/**",
+    "**/coverage/**",
+    "**/.cache/**",
+    "**/*.min.js",
+    "**/*.gen.*",
+    "**/*.d.ts",
+    "**/package-lock.json",
+    "**/yarn.lock",
+    "**/pnpm-lock.yaml",
+    "**/Cargo.lock",
+    "**/poetry.lock",
+];
+const TYPE_RANK = {
+    HACK: 0,
+    FIXME: 1,
+    WARNING: 2,
+    IMPORTANT: 3,
+    TODO: 4,
+    NOTE: 5,
+};
+// Regex to match keyword and capture everything after it on the line
+const GOTCHA_REGEX = /\b(HACK|FIXME|WARNING|IMPORTANT|TODO|NOTE)\b[:\s]*(.*)/i;
+function extractComment(rawMatch) {
+    // Remove leading comment markers: //, #, *, /*, etc.
+    return rawMatch
+        .replace(/^[/*#\s]+/, "")
+        .replace(/\*\/$/, "")
+        .trim();
+}
+function isBinary(content) {
+    const probe = content.slice(0, 512);
+    return probe.includes("\0");
+}
+export async function scanGotchas(projectPath, maxResults = 20) {
+    try {
+        const files = await fg("**/*", {
+            cwd: projectPath,
+            onlyFiles: true,
+            ignore: IGNORE_PATTERNS,
+            dot: false,
+        });
+        const found = [];
+        const seenComments = new Map(); // text → count
+        for (const relPath of files) {
+            const absPath = path.join(projectPath, relPath);
+            const raw = await readFileSafe(absPath);
+            if (!raw)
+                continue;
+            if (isBinary(raw))
+                continue;
+            const lines = raw.split("\n");
+            for (let i = 0; i < lines.length; i++) {
+                const line = lines[i];
+                const match = GOTCHA_REGEX.exec(line);
+                if (!match)
+                    continue;
+                const type = match[1].toUpperCase();
+                const rawComment = match[2] ?? "";
+                const comment = extractComment(rawComment);
+                if (!comment)
+                    continue;
+                const count = (seenComments.get(comment) ?? 0) + 1;
+                seenComments.set(comment, count);
+                // Deduplicate: if same text seen 3+ times, skip subsequent occurrences
+                if (count >= 3 && count > 1) {
+                    if (count > 3)
+                        continue;
+                    // Keep the first occurrence (count=1 already added), skip count 2+
+                    continue;
+                }
+                if (count === 2)
+                    continue;
+                found.push({
+                    file: relPath,
+                    line: i + 1,
+                    type,
+                    comment,
+                });
+            }
+        }
+        // Sort by rank (HACK first, NOTE last), then by file/line for stable order
+        found.sort((a, b) => {
+            const rankDiff = TYPE_RANK[a.type] - TYPE_RANK[b.type];
+            if (rankDiff !== 0)
+                return rankDiff;
+            if (a.file !== b.file)
+                return a.file.localeCompare(b.file);
+            return a.line - b.line;
+        });
+        return found.slice(0, maxResults);
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=gotchas.js.map

package/dist/scanner/gotchas.js.map

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

package/dist/scanner/index.d.ts

@@ -0,0 +1,26 @@
+import { type ManifestData } from "./manifest.js";
+import { type StructureData } from "./structure.js";
+import { type SourceData } from "./source.js";
+import { type DocData } from "./docs.js";
+import { type Gotcha } from "./gotchas.js";
+import { type CodegraphSummary } from "./codegraph.js";
+import { type McpScanResult } from "./mcp.js";
+export type { ManifestData, StructureData, SourceData, DocData, Gotcha };
+export type { CodegraphSummary, McpScanResult };
+export interface RawCorpus {
+    manifest: ManifestData;
+    structure: StructureData;
+    source: SourceData;
+    docs: DocData;
+    gotchas: Gotcha[];
+    codegraph: CodegraphSummary;
+    mcp: McpScanResult;
+    totalEstimatedTokens: number;
+    scanDurationMs: number;
+}
+export interface ScanOptions {
+    /** Path to a repomix output file. When provided, replaces filesystem source sampling. */
+    repomixPath?: string;
+}
+export declare function scan(projectPath: string, options?: ScanOptions): Promise<RawCorpus>;
+//# sourceMappingURL=index.d.ts.map

package/dist/scanner/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scanner/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAY,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAe,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAExD,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9D,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AACzE,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,CAAC;AAEhD,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,aAAa,CAAC;IACzB,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,GAAG,EAAE,aAAa,CAAC;IACnB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;CACxB;AAuDD,MAAM,WAAW,WAAW;IAC1B,yFAAyF;IACzF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAsB,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,CAkD7F"}