@ryanstark24/sfgraph-server 1.1.0

package/dist/tools/_project-root.js

@@ -0,0 +1,44 @@
+import { existsSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { ConfigError } from "@ryanstark24/sfgraph-shared";
+/**
+ * Resolve and sanity-check a user-supplied `project_root` for the WIP tools.
+ *
+ * The WIP tools walk the local filesystem under `project_root`. Without a
+ * containment check, a malicious or careless caller can point them at `/`,
+ * `/etc`, or anywhere the user can read — turning local read-access into
+ * an MCP-mediated arbitrary-file read.
+ *
+ * This helper:
+ *   1. Resolves `project_root` to an absolute path via `path.resolve`.
+ *   2. Verifies the path exists and is a directory.
+ *   3. Requires an `sfdx-project.json` at the root (proof this is a real
+ *      Salesforce DX project, not `/home/victim`).
+ *   4. Returns the `realpath`-resolved root so downstream walkers operate
+ *      on a stable, symlink-resolved path.
+ *
+ * Throws `ConfigError` on any failure.
+ */
+export function resolveWipProjectRoot(rawProjectRoot) {
+    const abs = path.resolve(rawProjectRoot);
+    if (!existsSync(abs)) {
+        throw new ConfigError(`project_root does not exist: ${rawProjectRoot}`);
+    }
+    let stats;
+    try {
+        stats = statSync(abs);
+    }
+    catch (e) {
+        throw new ConfigError(`project_root not readable: ${e.message}`);
+    }
+    if (!stats.isDirectory()) {
+        throw new ConfigError(`project_root is not a directory: ${rawProjectRoot}`);
+    }
+    const real = realpathSync(abs);
+    const sfdxProject = path.join(real, "sfdx-project.json");
+    if (!existsSync(sfdxProject)) {
+        throw new ConfigError(`project_root is not a Salesforce DX project (no sfdx-project.json at ${real}). WIP tools refuse to walk arbitrary filesystem locations.`);
+    }
+    return real;
+}
+//# sourceMappingURL=_project-root.js.map

package/dist/tools/_project-root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_project-root.js","sourceRoot":"","sources":["../../src/tools/_project-root.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC7D,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE1D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,qBAAqB,CAAC,cAAsB;IAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IACzC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,WAAW,CAAC,gCAAgC,cAAc,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,IAAI,KAAkC,CAAC;IACvC,IAAI,CAAC;QACH,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,WAAW,CAAC,8BAA+B,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9E,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;QACzB,MAAM,IAAI,WAAW,CAAC,oCAAoC,cAAc,EAAE,CAAC,CAAC;IAC9E,CAAC;IACD,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAC/B,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC;IACzD,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,WAAW,CACnB,wEAAwE,IAAI,6DAA6D,CAC1I,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/tools/analyze_field.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=analyze_field.d.ts.map

package/dist/tools/analyze_field.d.ts.map

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

package/dist/tools/analyze_field.js

@@ -0,0 +1,77 @@
+import { render } from "@ryanstark24/sfgraph-core";
+import { REL_TYPES } from "@ryanstark24/sfgraph-core";
+import { asQualifiedName } from "@ryanstark24/sfgraph-shared";
+import { getToolContext } from "../context.js";
+import { defineTool, z } from "./_define.js";
+// Salesforce SObject and Field API names are letters/digits/underscore only
+// (custom suffix `__c` / `__r` / etc. is allowed). Reject anything else
+// up-front rather than silently returning "field not found" — agents that
+// pass `object: "Account.Tier__c"` should see the validation error.
+const SF_API_NAME_RE = /^[A-Za-z][A-Za-z0-9_]*(?:__[a-zA-Z])?$/;
+const inputSchema = z.object({
+    org: z.string().min(1),
+    object: z
+        .string()
+        .min(1)
+        .regex(SF_API_NAME_RE, "object must be a Salesforce SObject API name (no dots or spaces)"),
+    field: z
+        .string()
+        .min(1)
+        .regex(SF_API_NAME_RE, "field must be a Salesforce field API name (no dots or spaces)"),
+});
+defineTool({
+    name: "analyze_field",
+    description: "USE THIS for any 'where is X.Y field used' / 'who reads or writes Account.Status__c' / 'who has access to this field' question about a Salesforce CustomField. Returns every Apex method, Flow, LWC, validation rule, and formula that reads/writes the field, plus FLS grants (which Profile/PermSet can see or edit it). Prefer this over grep / file search for any field-impact question.",
+    inputSchema,
+    async execute(input) {
+        const ctx = await getToolContext({ orgId: input.org });
+        const qname = asQualifiedName(`CustomField:${input.object}.${input.field}`);
+        const node = ctx.graphStore.getNode(ctx.orgId, qname);
+        if (!node) {
+            return {
+                summary: "field not found",
+                markdown: `> no node \`${qname}\``,
+                data: { found: false },
+            };
+        }
+        const readers = ctx.graphStore.listEdgesTo(ctx.orgId, qname, REL_TYPES.READS_FIELD);
+        const writers = ctx.graphStore.listEdgesTo(ctx.orgId, qname, REL_TYPES.WRITES_FIELD);
+        const grants = ctx.graphStore.listEdgesTo(ctx.orgId, qname, REL_TYPES.GRANTS_FIELD_ACCESS);
+        const allEdges = [...readers, ...writers, ...grants];
+        const nodeSet = new Map();
+        nodeSet.set(qname, { qualifiedName: qname, label: "CustomField" });
+        for (const e of allEdges) {
+            const src = ctx.graphStore.getNode(ctx.orgId, e.srcQualifiedName);
+            nodeSet.set(e.srcQualifiedName, {
+                qualifiedName: e.srcQualifiedName,
+                label: src?.label ?? "Unknown",
+            });
+        }
+        const mermaid = render.renderDependencyGraph({
+            nodes: Array.from(nodeSet.values()),
+            edges: allEdges.map((e) => ({
+                srcQualifiedName: e.srcQualifiedName,
+                dstQualifiedName: e.dstQualifiedName,
+                relType: e.relType,
+            })),
+            title: `field ${qname}`,
+        });
+        const md = [
+            `**${qname}** — readers ${readers.length} · writers ${writers.length} · grants ${grants.length}`,
+            "",
+            "```mermaid",
+            mermaid,
+            "```",
+        ].join("\n");
+        return {
+            summary: `${readers.length} readers / ${writers.length} writers`,
+            markdown: md,
+            data: {
+                readers: readers.map((e) => e.srcQualifiedName),
+                writers: writers.map((e) => e.srcQualifiedName),
+                grants: grants.map((e) => e.srcQualifiedName),
+            },
+        };
+    },
+});
+//# sourceMappingURL=analyze_field.js.map

package/dist/tools/analyze_field.js.map

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

package/dist/tools/cross_layer_flow_map.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cross_layer_flow_map.d.ts.map

package/dist/tools/cross_layer_flow_map.d.ts.map

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

package/dist/tools/cross_layer_flow_map.js

@@ -0,0 +1,104 @@
+import { render } from "@ryanstark24/sfgraph-core";
+import { REL_TYPES } from "@ryanstark24/sfgraph-core";
+import { asQualifiedName } from "@ryanstark24/sfgraph-shared";
+import { getToolContext } from "../context.js";
+import { defineTool, z } from "./_define.js";
+const inputSchema = z.object({
+    org: z.string().min(1),
+    entry: z.string().min(1),
+});
+const REL_PRIORITY = [
+    REL_TYPES.CALLS_APEX_FROM_LWC,
+    REL_TYPES.CALLS,
+    REL_TYPES.EXECUTES_SOQL,
+    REL_TYPES.READS_FIELD,
+];
+function layerFor(label) {
+    if (label === "LWC" || label === "LightningComponentBundle")
+        return "LWC";
+    if (label.startsWith("Apex"))
+        return "Apex";
+    if (label === "CustomField")
+        return "Field";
+    if (label === "CustomObject")
+        return "SOQL";
+    return label;
+}
+defineTool({
+    name: "cross_layer_flow_map",
+    description: "USE THIS for any 'how does X flow from UI to DB' / 'trace this LWC end-to-end' / 'show the full path from accountTile to the database' question about a Salesforce entry point (LWC bundle, ApexPage, Flow). Returns the layered LWC -> Apex -> SOQL -> CustomField sequence + Mermaid sequenceDiagram.",
+    inputSchema,
+    async execute(input) {
+        const ctx = await getToolContext({ orgId: input.org });
+        const entry = asQualifiedName(input.entry);
+        const participants = new Map();
+        const messages = [];
+        const visited = new Set();
+        const queue = [entry];
+        visited.add(entry);
+        const entryNode = ctx.graphStore.getNode(ctx.orgId, entry);
+        if (entryNode) {
+            participants.set(entry, {
+                id: entry,
+                label: entry,
+                layer: layerFor(entryNode.label),
+            });
+        }
+        else {
+            participants.set(entry, { id: entry, label: entry, layer: "Entry" });
+        }
+        // Per-node visit cap, not per-edge step cap. Previously `steps < 50`
+        // counted every edge traversed across the BFS, so any moderately-fanned
+        // LWC -> Apex chain (30 fields + 25 SOQL reads) would silently truncate
+        // mid-tree. Capping visited *nodes* gives predictable depth and lets us
+        // emit an explicit "_truncated_" marker the user can act on.
+        const NODE_CAP = 100;
+        let truncated = false;
+        bfs: while (queue.length > 0) {
+            if (visited.size >= NODE_CAP) {
+                truncated = true;
+                break;
+            }
+            const cur = queue.shift();
+            if (!cur)
+                break;
+            for (const rt of REL_PRIORITY) {
+                const out = ctx.graphStore.listEdgesFrom(ctx.orgId, cur, rt);
+                for (const e of out) {
+                    const dstNode = ctx.graphStore.getNode(ctx.orgId, e.dstQualifiedName);
+                    if (!participants.has(e.dstQualifiedName)) {
+                        participants.set(e.dstQualifiedName, {
+                            id: e.dstQualifiedName,
+                            label: e.dstQualifiedName,
+                            layer: layerFor(dstNode?.label ?? "Unknown"),
+                        });
+                    }
+                    messages.push({ fromId: cur, toId: e.dstQualifiedName, label: rt });
+                    if (!visited.has(e.dstQualifiedName)) {
+                        visited.add(e.dstQualifiedName);
+                        queue.push(e.dstQualifiedName);
+                        if (visited.size >= NODE_CAP) {
+                            truncated = true;
+                            break bfs;
+                        }
+                    }
+                }
+            }
+        }
+        const mermaid = render.renderSequence({
+            participants: Array.from(participants.values()),
+            messages,
+        });
+        const mdLines = ["```mermaid", mermaid, "```"];
+        if (truncated) {
+            mdLines.push("", `_truncated_ — BFS hit the ${NODE_CAP}-node ceiling; deeper paths from this entry were not explored.`);
+        }
+        const md = mdLines.join("\n");
+        return {
+            summary: `${participants.size} participants across layers${truncated ? " (truncated)" : ""}`,
+            markdown: md,
+            data: { participants: Array.from(participants.values()), messages, truncated },
+        };
+    },
+});
+//# sourceMappingURL=cross_layer_flow_map.js.map

package/dist/tools/cross_layer_flow_map.js.map

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

package/dist/tools/cross_org_diff.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cross_org_diff.d.ts.map

package/dist/tools/cross_org_diff.d.ts.map

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

package/dist/tools/cross_org_diff.js

@@ -0,0 +1,59 @@
+import { analyze, render } from "@ryanstark24/sfgraph-core";
+import { getToolContext } from "../context.js";
+import { defineTool, z } from "./_define.js";
+const inputSchema = z.object({
+    org_a: z.string().min(1),
+    org_b: z.string().min(1),
+    category: z.string().default("all"),
+});
+defineTool({
+    name: "cross_org_diff",
+    description: "USE THIS for any 'what is different between prod and sandbox' / 'compare two orgs' / 'org drift' question. Set difference of metadata between two ingested Salesforce orgs by category. Returns onlyInA / onlyInB / changed lists.",
+    inputSchema,
+    async execute(input) {
+        // Each org has its own SQLite file. Open BOTH contexts so onlyInA/onlyInB
+        // are computed against the right rows. getToolContext resolves aliases
+        // for both org_a and org_b.
+        const ctxA = await getToolContext({ orgId: input.org_a });
+        const ctxB = await getToolContext({ orgId: input.org_b });
+        const diff = analyze.diffOrgs({
+            storeA: ctxA.graphStore,
+            orgA: ctxA.orgId,
+            storeB: ctxB.graphStore,
+            orgB: ctxB.orgId,
+            category: input.category,
+        });
+        const mermaid = render.renderDiff({
+            added: diff.onlyInB.slice(0, 30).map((n) => ({ qualifiedName: n.qualifiedName })),
+            removed: diff.onlyInA.slice(0, 30).map((n) => ({ qualifiedName: n.qualifiedName })),
+            changed: diff.changed.slice(0, 30).map((c) => ({ qualifiedName: c.a.qualifiedName })),
+        });
+        const md = [
+            "| metric | count |",
+            "|---|---|",
+            `| only in A | ${diff.onlyInA.length} |`,
+            `| only in B | ${diff.onlyInB.length} |`,
+            `| changed | ${diff.changed.length} |`,
+            "",
+            "```mermaid",
+            mermaid,
+            "```",
+        ].join("\n");
+        const truncationNote = diff.truncated
+            ? ` — results capped at ${analyze.CROSS_ORG_PER_LABEL_CAP}/label; narrow with category filter`
+            : "";
+        return {
+            summary: `A-only:${diff.onlyInA.length} B-only:${diff.onlyInB.length} changed:${diff.changed.length}${truncationNote}`,
+            markdown: diff.truncated
+                ? `${md}\n\n> _Note: at least one label hit the ${analyze.CROSS_ORG_PER_LABEL_CAP}-row cap. Diff is incomplete — pass a narrower \`category\` to investigate._`
+                : md,
+            data: {
+                onlyInA: diff.onlyInA.map((n) => n.qualifiedName),
+                onlyInB: diff.onlyInB.map((n) => n.qualifiedName),
+                changed: diff.changed.map((c) => c.a.qualifiedName),
+                truncated: diff.truncated ?? false,
+            },
+        };
+    },
+});
+//# sourceMappingURL=cross_org_diff.js.map

package/dist/tools/cross_org_diff.js.map

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

package/dist/tools/dead_code_audit.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=dead_code_audit.d.ts.map

package/dist/tools/dead_code_audit.d.ts.map

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

package/dist/tools/dead_code_audit.js

@@ -0,0 +1,67 @@
+import { analyze } from "@ryanstark24/sfgraph-core";
+import { getToolContext } from "../context.js";
+import { defineTool, z } from "./_define.js";
+const inputSchema = z.object({ org: z.string().min(1) });
+function readCachedDeadCode(db, orgId) {
+    try {
+        const d = db;
+        const rows = d
+            .prepare("SELECT qualified_name, score, confidence, reasons FROM _sfgraph_dead_code_scores WHERE org_id = ? ORDER BY score ASC")
+            .all(orgId);
+        if (!rows || rows.length === 0)
+            return null;
+        return rows.map((r) => ({
+            qualifiedName: r.qualified_name,
+            score: r.score,
+            confidence: r.confidence,
+            reasons: (() => {
+                try {
+                    return JSON.parse(r.reasons);
+                }
+                catch {
+                    return [];
+                }
+            })(),
+        }));
+    }
+    catch {
+        return null;
+    }
+}
+defineTool({
+    name: "dead_code_audit",
+    description: "USE THIS for any 'what can I delete' / 'find unused Apex / LWC / Flow' / 'dead code' / 'orphan metadata' question about a Salesforce org. Returns nodes with low freshness AND zero incoming edges, bucketed by confidence with reasons.",
+    inputSchema,
+    async execute(input) {
+        const ctx = await getToolContext({ orgId: input.org });
+        const cached = ctx.db ? readCachedDeadCode(ctx.db, ctx.orgId) : null;
+        if (cached) {
+            const md = cached.length
+                ? [
+                    "| qname | confidence | score | reasons |",
+                    "|---|---|---|---|",
+                    ...cached.map((d) => `| \`${d.qualifiedName}\` | ${d.confidence} | ${d.score.toFixed(2)} | ${d.reasons.join(", ")} |`),
+                ].join("\n")
+                : "_no dead code detected_";
+            return {
+                summary: `${cached.length} dead-code candidates (cached)`,
+                markdown: md,
+                data: { dead: cached, cached: true },
+            };
+        }
+        const dead = analyze.findDeadCode(ctx.graphStore, ctx.orgId);
+        const md = dead.length
+            ? [
+                "| qname | label |",
+                "|---|---|",
+                ...dead.map((d) => `| \`${d.qualifiedName}\` | ${d.label} |`),
+            ].join("\n")
+            : "_no dead code detected_";
+        return {
+            summary: `${dead.length} dead-code candidates`,
+            markdown: md,
+            data: { dead: dead.map((d) => d.qualifiedName), cached: false },
+        };
+    },
+});
+//# sourceMappingURL=dead_code_audit.js.map

package/dist/tools/dead_code_audit.js.map

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

package/dist/tools/deployment_manifest_gen.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=deployment_manifest_gen.d.ts.map

package/dist/tools/deployment_manifest_gen.d.ts.map

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

package/dist/tools/deployment_manifest_gen.js

@@ -0,0 +1,43 @@
+import { analyze } from "@ryanstark24/sfgraph-core";
+import { getToolContext } from "../context.js";
+import { defineTool, z } from "./_define.js";
+const inputSchema = z.object({
+    from_org: z.string().min(1),
+    to_org: z.string().min(1),
+    category: z.string().optional(),
+});
+defineTool({
+    name: "deployment_manifest_gen",
+    description: "Generate package.xml + destructiveChanges.xml from cross-org diff.",
+    inputSchema,
+    async execute(input) {
+        // Open BOTH org contexts so the manifest sees the target org's actual
+        // node set (each org has its own SQLite file). Aliases for both inputs
+        // are resolved by getToolContext.
+        const ctxA = await getToolContext({ orgId: input.from_org });
+        const ctxB = await getToolContext({ orgId: input.to_org });
+        const manifest = analyze.generateManifest({
+            storeA: ctxA.graphStore,
+            orgA: ctxA.orgId,
+            storeB: ctxB.graphStore,
+            orgB: ctxB.orgId,
+            category: input.category ?? "all",
+        });
+        return {
+            summary: `${manifest.summary.addedOrChanged} added/changed, ${manifest.summary.removed} removed`,
+            markdown: [
+                "### package.xml",
+                "```xml",
+                manifest.packageXml.trimEnd(),
+                "```",
+                "",
+                "### destructiveChanges.xml",
+                "```xml",
+                manifest.destructiveXml.trimEnd(),
+                "```",
+            ].join("\n"),
+            data: manifest,
+        };
+    },
+});
+//# sourceMappingURL=deployment_manifest_gen.js.map

package/dist/tools/deployment_manifest_gen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment_manifest_gen.js","sourceRoot":"","sources":["../../src/tools/deployment_manifest_gen.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,cAAc,CAAC;AAE7C,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACzB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAChC,CAAC,CAAC;AAEH,UAAU,CAAC;IACT,IAAI,EAAE,yBAAyB;IAC/B,WAAW,EAAE,oEAAoE;IACjF,WAAW;IACX,KAAK,CAAC,OAAO,CAAC,KAAK;QACjB,sEAAsE;QACtE,uEAAuE;QACvE,kCAAkC;QAClC,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC7D,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QAC3D,MAAM,QAAQ,GAAG,OAAO,CAAC,gBAAgB,CAAC;YACxC,MAAM,EAAE,IAAI,CAAC,UAAU;YACvB,IAAI,EAAE,IAAI,CAAC,KAAK;YAChB,MAAM,EAAE,IAAI,CAAC,UAAU;YACvB,IAAI,EAAE,IAAI,CAAC,KAAK;YAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,KAAK;SAClC,CAAC,CAAC;QACH,OAAO;YACL,OAAO,EAAE,GAAG,QAAQ,CAAC,OAAO,CAAC,cAAc,mBAAmB,QAAQ,CAAC,OAAO,CAAC,OAAO,UAAU;YAChG,QAAQ,EAAE;gBACR,iBAAiB;gBACjB,QAAQ;gBACR,QAAQ,CAAC,UAAU,CAAC,OAAO,EAAE;gBAC7B,KAAK;gBACL,EAAE;gBACF,4BAA4B;gBAC5B,QAAQ;gBACR,QAAQ,CAAC,cAAc,CAAC,OAAO,EAAE;gBACjC,KAAK;aACN,CAAC,IAAI,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,QAAQ;SACf,CAAC;IACJ,CAAC;CACF,CAAC,CAAC"}

package/dist/tools/explain_code.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=explain_code.d.ts.map

package/dist/tools/explain_code.d.ts.map

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

package/dist/tools/explain_code.js

@@ -0,0 +1,109 @@
+import { asQualifiedName } from "@ryanstark24/sfgraph-shared";
+import { getToolContext } from "../context.js";
+import { defineTool, z } from "./_define.js";
+// Cap annotation size at 16 KiB. Cached explanations are echoed back inside
+// markdown blockquotes; unbounded input bloats the SQLite row and would let
+// a poisoned graph break the host's markdown renderer.
+const ANNOTATION_MAX_BYTES = 16 * 1024;
+const inputSchema = z.object({
+    org: z.string().min(1),
+    qname: z.string().min(1),
+    refresh: z.boolean().default(false),
+    annotation: z.string().max(ANNOTATION_MAX_BYTES, "annotation exceeds 16 KiB cap").optional(),
+});
+defineTool({
+    name: "explain_code",
+    description: "USE THIS for any 'explain this method' / 'walk me through X' / 'what does Apex method Y do' question about a stored Salesforce code snippet. Returns the source text + cached LLM explanation (if any). Pass annotation to cache the LLM's explanation back to the graph for future use.",
+    inputSchema,
+    async execute(input) {
+        const ctx = await getToolContext({ orgId: input.org });
+        const qname = asQualifiedName(input.qname);
+        // Annotation write path
+        if (typeof input.annotation === "string" && input.annotation.length > 0) {
+            const now = Date.now();
+            const ok = ctx.graphStore.updateSnippetExplanation(ctx.orgId, qname, input.annotation, now);
+            if (!ok) {
+                return {
+                    summary: `no snippet stored for ${input.qname} — annotation not persisted`,
+                    markdown: `> No snippet exists for \`${input.qname}\`. Likely a non-code metadata type, or the org has not been ingested yet.`,
+                    data: {
+                        qname: input.qname,
+                        sourceFormat: null,
+                        sourceText: null,
+                        startLine: null,
+                        endLine: null,
+                        cachedExplanation: null,
+                        cachedAt: null,
+                        stored: false,
+                    },
+                };
+            }
+            const snippet = ctx.graphStore.getSnippet(ctx.orgId, qname);
+            return {
+                summary: `cached explanation for ${input.qname}`,
+                markdown: `> Explanation cached for \`${input.qname}\` at ${new Date(now).toISOString()}.`,
+                data: {
+                    qname: input.qname,
+                    sourceFormat: snippet?.sourceFormat ?? null,
+                    sourceText: snippet?.sourceText ?? null,
+                    startLine: snippet?.startLine ?? null,
+                    endLine: snippet?.endLine ?? null,
+                    cachedExplanation: snippet?.llmExplanation ?? input.annotation,
+                    cachedAt: snippet?.explainedAt ?? now,
+                    stored: true,
+                },
+            };
+        }
+        // Read path
+        const snippet = ctx.graphStore.getSnippet(ctx.orgId, qname);
+        if (!snippet) {
+            return {
+                summary: `no snippet stored for ${input.qname} — likely a non-code metadata type`,
+                markdown: `> No snippet stored for \`${input.qname}\`. Snippets are emitted only for code parsers (currently Apex methods). For declarative metadata, use \`analyze_field\` or \`trace_upstream\` instead.`,
+                data: {
+                    qname: input.qname,
+                    sourceFormat: null,
+                    sourceText: null,
+                    startLine: null,
+                    endLine: null,
+                    cachedExplanation: null,
+                    cachedAt: null,
+                    stored: false,
+                },
+            };
+        }
+        const showCached = !input.refresh && snippet.llmExplanation;
+        const md = [
+            `**${input.qname}** — \`${snippet.sourceFormat}\`${snippet.startLine != null ? ` (lines ${snippet.startLine}–${snippet.endLine ?? "?"})` : ""}`,
+            "",
+            `\`\`\`${snippet.sourceFormat}`,
+            snippet.sourceText,
+            "```",
+            "",
+        ];
+        if (showCached) {
+            md.push("**Cached explanation:**", "", `> ${snippet.llmExplanation}`);
+        }
+        else {
+            md.push("> No explanation cached yet — generate one and call `explain_code` again with `annotation` to persist it.");
+        }
+        md.push("", "_follow_up_tools: `analyze_field`, `trace_upstream`, `trace_downstream`_");
+        return {
+            summary: showCached
+                ? `snippet + cached explanation for ${input.qname}`
+                : `snippet for ${input.qname} (no cached explanation)`,
+            markdown: md.join("\n"),
+            data: {
+                qname: input.qname,
+                sourceFormat: snippet.sourceFormat,
+                sourceText: snippet.sourceText,
+                startLine: snippet.startLine ?? null,
+                endLine: snippet.endLine ?? null,
+                cachedExplanation: showCached ? (snippet.llmExplanation ?? null) : null,
+                cachedAt: showCached ? (snippet.explainedAt ?? null) : null,
+                stored: false,
+            },
+        };
+    },
+});
+//# sourceMappingURL=explain_code.js.map

package/dist/tools/explain_code.js.map

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

package/dist/tools/freshness_report.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=freshness_report.d.ts.map

package/dist/tools/freshness_report.d.ts.map

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