sf-intelligence 0.3.2 → 0.4.0

package/README.md

@@ -1,107 +1,113 @@
 # sf-intelligence
 
-A **grounded, fail-closed backend for AI assistants** working in one Salesforce
-org — answers come from the org's **real metadata**, not a guess.
-
-`sf-intelligence` is an **offline-first, read-only, MCP-first knowledge base**
-for a single Salesforce org. You run one `sf project retrieve`; it builds a local
-Markdown vault and a DuckDB dependency graph, then answers questions locally
-through an MCP server (the `sfi.*` tools) — no network egress for vault answers.
-It is not a standalone chatbot: a semantic router **advises** — it turns each
-plain-language question into a meaning-ranked shortlist of the `sfi.*` tools
-that can answer it, tagged with the plane it needs (offline vault / opt-in live
-/ hybrid) and a confidence band — and your **host LLM decides** which tools to
-run. It **fails closed**: write imperatives, prompt injection, and
-record-value exfiltration are refused by shape (with a read-only alternative
-offered), unanswerable asks get an honest gap instead of a lookalike tool, and
-genuine ambiguity gets a clarifying question instead of a guess. Terse
-follow-ups resolve through an optional host-passed `context.previous` param —
-the server itself stores no conversation state. An opt-in live read-only plane
-can answer record counts and samples. MIT + Commons Clause.
-
-## Upgrading to 0.3.0 (breaking)
-
-0.3.0 changes defaults. If you are coming from 0.2.x, read this before upgrading —
-full detail in [CHANGELOG.md](https://github.com/PranavNagrecha/Salesforce-Intelligence/blob/main/CHANGELOG.md).
-
-- **`SFI_TOOL_PROFILE` now defaults to `core`.** 19 tools are advertised and
-  directly invokable; the other ~190 are reached with
-  `sfi.run_analysis { name: 'sfi.<tool>', args }`. Set `SFI_TOOL_PROFILE=full`
-  to restore the previous advertise-and-invoke-everything behavior.
-- **`liveEnabled: true` no longer opens the live plane.** Grant standing consent
-  with `sfi.live_consent { grant: true }` (OrgId + principal bound, scoped,
-  7-day expiry) or set `SFI_LIVE_PLANE_ENABLED=1`.
-- **Existing on-disk live grants stop working** — v1 consent records are dropped.
-  Re-grant once.
-- **The update check is now opt-in.** Set `SFI_UPDATE_CHECK=1` (default network
-  mode is `off`).
-- **Every success envelope gains a `contentPolicy` block** (~280 bytes) marking
-  org metadata as untrusted data for hosts.
-
-## Install
-
-Requires **Node.js 20+** and an authenticated **Salesforce CLI** (`sf`).
+Ask your AI what breaks before you change Salesforce. Offline, read-only, cited answers. Website and docs: **[sfi.auditforce.cloud](https://sfi.auditforce.cloud)**
+
+A **grounded, fail-closed backend for AI assistants** working in one Salesforce org — answers come from the org's **real metadata**, not a guess.
+
+`sf-intelligence` is an **offline-first, read-only, MCP-first knowledge base** for a single Salesforce org. One `sf project retrieve` builds a local vault (Markdown + a DuckDB dependency graph); a semantic router **advises** a ranked tool shortlist and your **host LLM decides** which to run. It **fails closed** — write imperatives and prompt injection are refused by shape, an unanswerable ask gets an honest gap instead of a lookalike tool, and genuine ambiguity gets a clarifying question instead of a guess. MIT + Commons Clause.
+
+Requires **Node.js 20+**. `npx -y sf-intelligence …` needs no install; `npm install -g sf-intelligence` puts `sfi` on your PATH for shorter commands. Upgrading from an earlier version? Breaking changes and upgrade steps for every release are in the [CHANGELOG](https://github.com/PranavNagrecha/Salesforce-Intelligence/blob/main/CHANGELOG.md).
+
+## Try it now — no Salesforce org needed
+
+One command serves a built-in **synthetic demo org** ("Verdant Energy," a fictional solar installer) over MCP — fully offline, no auth, no `sf` CLI, builds in a few seconds:
 
 ```sh
-npm install -g sf-intelligence
+claude mcp add --transport stdio --scope user sf-intelligence-demo -- npx -y sf-intelligence demo
 ```
 
-(or run it ad hoc with `npx -y sf-intelligence …` — no global install needed)
+Any other MCP client — same registration as the "real org" block below, except `"args": ["-y", "sf-intelligence", "demo"]` and **no `--vault`**: `sfi demo` manages its own cached vault under `~/.sf-intelligence/demo`. Ask it *"what happens when I save a Project?"* or *"what breaks if I delete `Invoice__c.Amount__c`?"*. When you're ready for your own org, keep reading.
+
+## Register the MCP server (your real org)
+
+Also requires an authenticated **Salesforce CLI** (`sf`). Each host reads a **different config file in a different format**, and most don't run inside your Salesforce project — always pass an **absolute `--vault` path**. Full per-host, per-platform detail (exact paths, logs, troubleshooting): [docs/guides/mcp-hosts.md](https://github.com/PranavNagrecha/Salesforce-Intelligence/blob/main/docs/guides/mcp-hosts.md).
 
-## Register the MCP server
+| Host | Config file | Top-level key |
+|---|---|---|
+| Claude Code | `.mcp.json` (project) or `~/.claude.json` | `mcpServers` |
+| Claude Desktop | `claude_desktop_config.json` | `mcpServers` |
+| Cursor | `.cursor/mcp.json` | `mcpServers` |
+| Codex | `~/.codex/config.toml` | `[mcp_servers.*]` (TOML) |
+| VS Code + GitHub Copilot | `.vscode/mcp.json` | **`servers`** — not `mcpServers` |
 
-**Claude Code** (from your Salesforce DX repo):
+**Claude Code** — from your Salesforce DX repo:
 
 ```sh
-claude mcp add --transport stdio --scope project sf-intelligence -- npx -y sf-intelligence mcp
+claude mcp add --scope project sf-intelligence -- \
+  npx -y sf-intelligence mcp --vault "$PWD/org-kb"
 ```
 
-**Claude Desktop, or any other MCP client** — add to the client's MCP config:
+**Claude Desktop, Cursor, or any `mcpServers`-style client** — add to its config, then fully restart the app:
 
 ```json
 {
   "mcpServers": {
+    "sf-intelligence": {
+      "command": "npx",
+      "args": ["-y", "sf-intelligence", "mcp", "--vault", "/abs/path/to/org-kb"]
+    }
+  }
+}
+```
+
+**VS Code + GitHub Copilot** — create `.vscode/mcp.json`. The top-level key is `servers`, **not** `mcpServers` — pasting the block above here parses fine and registers nothing:
+
+```json
+{
+  "servers": {
     "sf-intelligence": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "sf-intelligence", "mcp"]
+      "args": ["-y", "sf-intelligence", "mcp", "--vault", "/abs/path/to/org-kb"]
     }
   }
 }
 ```
 
+**Codex** — `codex mcp add sf-intelligence -- npx -y sf-intelligence mcp --vault /abs/path/to/org-kb`
+(or the TOML equivalent in `~/.codex/config.toml`).
+
 ## First run
 
 From your Salesforce DX repo (the directory with `sfdx-project.json`):
 
 ```sh
-sfi init                               # create the local org-kb/ vault
-sfi refresh --target-org my-org-alias  # retrieve metadata, build the vault
-sfi status                             # freshness, source-tree hash, counts
-sfi doctor                             # diagnose sf CLI / vault / auth issues
+sfi init --target-org my-org-alias    # create the vault, bind it to one org
+sfi refresh --target-org my-org-alias # retrieve metadata, build the vault
+sfi status                            # freshness, source-tree hash, counts
+sfi doctor                            # diagnose sf CLI / vault / auth issues
 ```
 
-Then ask anything in your MCP client — *"what fields does Account have?"*,
-*"what breaks if I delete this field?"*, *"why can't this profile see
-Opportunities?"*, *"give me a tour of this org."*
+`--target-org` is **required** on `sfi init` whenever stdin isn't a terminal — which includes every MCP host, so always pass it there.
+
+Then ask anything in your MCP client — *"what fields does Account have?"*, *"what breaks if I delete this field?"*, *"who can edit Salary__c?"*, *"why can't this profile see Opportunities?"*, *"what happens when I save a Project?"*, *"give me a tour of this org."*
+
+**Connected, but the org looks empty?** Before the first `sfi refresh` finishes, the server boots in setup mode and exposes exactly one tool, `sfi.setup_status` — ask your chat "what do you need from me?" and it will name the exact next command (and where it's looking for the vault).
 
 ## Boundaries
 
-Read-only and offline by default. Static analysis, not runtime. No business
-record data in the vault. The product names its limits plainly rather than
-guessing.
+Read-only and offline by default. Static analysis, not runtime. No business record data in the vault. The product names its limits plainly rather than guessing.
+
+## Feedback
+
+A weak or wrong answer, or a question it couldn't route — that's the most useful thing to send back. It's captured **locally**, nothing phones home:
+
+```sh
+sfi feedback mark "where is the SSN field used" --wrong   # or --weak
+sfi feedback export                                       # → sfi-feedback.json (scrubbed)
+```
+
+Share it, or just describe the gap, at <https://github.com/PranavNagrecha/Salesforce-Intelligence/issues>.
 
 ## Documentation
 
-Full guides, capabilities, the tool catalog, and configuration:
-**https://sfi.auditforce.cloud**
+Full guides, capabilities, the tool catalog, and configuration: **https://sfi.auditforce.cloud**
 
-- [Getting started](https://sfi.auditforce.cloud/getting-started.html)
-- [Capabilities](https://sfi.auditforce.cloud/capabilities.html) · [All tools](https://sfi.auditforce.cloud/tools.html)
-- [Configuration](https://sfi.auditforce.cloud/configuration.html) · [FAQ](https://sfi.auditforce.cloud/faq.html)
-- [Quality & trust](https://sfi.auditforce.cloud/trust.html)
+- [Try the demo](https://sfi.auditforce.cloud/demo) · [Getting started](https://sfi.auditforce.cloud/getting-started) · [Quality & trust](https://sfi.auditforce.cloud/trust)
+- [Capabilities](https://sfi.auditforce.cloud/capabilities) · [All tools](https://sfi.auditforce.cloud/tools)
+- [Configuration](https://sfi.auditforce.cloud/configuration) · [FAQ](https://sfi.auditforce.cloud/faq)
 
 ## License
 
 MIT + Commons Clause — see the `LICENSE` file shipped in this package, or
-<https://sfi.auditforce.cloud/licensing.html>.
+<https://sfi.auditforce.cloud/licensing>.

package/bin/sfi.js

@@ -1,5 +1,17 @@
 #!/usr/bin/env node
-import { createProgram } from '../dist/index.js';
+// PERF-11: the CLI is one ~8 MB bundle that every invocation (including the
+// MCP server a host spawns) parses from scratch. Node >= 22.1 can cache the
+// compiled code on disk; enable it before loading the bundle. Best-effort:
+// older Node lacks the API, and NODE_DISABLE_COMPILE_CACHE=1 turns it off.
+import module from 'node:module';
+
+try {
+  module.enableCompileCache?.();
+} catch {
+  // A cache that cannot be created only costs speed.
+}
+
+const { createProgram } = await import('../dist/index.js');
 
 createProgram()
   .parseAsync(process.argv)

package/dist/apex-ast-worker.js

@@ -44,6 +44,21 @@ var SYSTEM_TYPES = /* @__PURE__ */ new Set([
   "Http",
   "Trigger"
 ]);
+var elementTypeOf = (t) => {
+  if (t === null)
+    return null;
+  const compact = t.replace(/\s+/g, "");
+  const arr = /^(.+)\[\]$/.exec(compact);
+  if (arr !== null)
+    return arr[1] ?? null;
+  const list = /^(?:List|Set)<(.+)>$/i.exec(compact);
+  if (list !== null)
+    return list[1] ?? null;
+  const map = /^Map<[^,<>]+,(.+)>$/i.exec(compact);
+  if (map !== null)
+    return map[1] ?? null;
+  return null;
+};
 var SYSTEM_CALL_ALLOW = {
   Database: "*",
   Type: /* @__PURE__ */ new Set(["forName"]),
@@ -79,6 +94,9 @@ var Collecting = class extends ApexErrorListener {
 };
 var extractApexAstEdges = (source, className, options = {}) => {
   const known = options.knownClasses ?? /* @__PURE__ */ new Set();
+  const objectCase = /* @__PURE__ */ new Map();
+  for (const o of options.knownObjects ?? [])
+    objectCase.set(o.toLowerCase(), o);
   const listener = new Collecting();
   let tree;
   try {
@@ -114,6 +132,7 @@ var extractApexAstEdges = (source, className, options = {}) => {
     if (idx === 0 && ext >= 0)
       extendsType = kidList[ext + 1]?.getText() ?? null;
   });
+  const canonicalType = (t) => objectCase.size === 0 ? t : t.replace(/[A-Za-z_][A-Za-z0-9_]*/g, (tok) => objectCase.get(tok.toLowerCase()) ?? tok);
   const scopeFor = (node) => {
     const md = ancestorWhere(node, (c) => ctxName(c) === "MethodDeclaration");
     if (md === null)
@@ -128,7 +147,7 @@ var extractApexAstEdges = (source, className, options = {}) => {
   const declareVar = (typeText, varName, scope) => {
     if (typeText === void 0 || varName === void 0 || typeText.length === 0)
       return;
-    scope.set(varName.toLowerCase(), typeText.trim());
+    scope.set(varName.toLowerCase(), canonicalType(typeText.trim()));
   };
   for (const md of findAll(tree, "MethodDeclaration")) {
     const id = kids(md).find((k) => ctxName(k) === "Id")?.getText();
@@ -137,7 +156,7 @@ var extractApexAstEdges = (source, className, options = {}) => {
     ownMethods.add(id.toLowerCase());
     const ret = kids(md).find((k) => ctxName(k) === "TypeRef")?.getText();
     if (ret !== void 0 && ret.length > 0) {
-      methodReturnTypes.set(id.toLowerCase(), ret.trim());
+      methodReturnTypes.set(id.toLowerCase(), canonicalType(ret.trim()));
     }
   }
   for (const fd of findAll(tree, "FieldDeclaration")) {
@@ -210,7 +229,8 @@ var extractApexAstEdges = (source, className, options = {}) => {
     const txt = findAll(list, "FieldName")[0]?.getText();
     return txt === void 0 || txt.length === 0 ? void 0 : txt;
   };
-  const soqlFrom = (queryCtx) => {
+  const literalReads = /* @__PURE__ */ new Set();
+  const soqlFrom = (queryCtx, into = reads) => {
     const SCOPE = /* @__PURE__ */ new Set(["Query", "SubQuery"]);
     for (const fn of findAll(queryCtx, "FieldName")) {
       if (ancestorWhere(fn, (c) => ctxName(c) === "FromNameList", SCOPE) !== null)
@@ -226,7 +246,7 @@ var extractApexAstEdges = (source, className, options = {}) => {
       const obj = FROM_OBJ(scope);
       if (obj === void 0)
         continue;
-      reads.add(`${obj}.${fn.getText()}`);
+      into.add(`${obj}.${fn.getText()}`);
     }
   };
   for (const q of findAll(tree, "Query"))
@@ -241,7 +261,7 @@ var extractApexAstEdges = (source, className, options = {}) => {
         qp.addErrorListener(c);
         const qt = qp.query();
         if (c.errors.length === 0)
-          soqlFrom(qt);
+          soqlFrom(qt, literalReads);
       } catch {
       }
     }
@@ -267,7 +287,13 @@ var extractApexAstEdges = (source, className, options = {}) => {
   const resolveRootType = (seg) => {
     const rootLower = seg.root.toLowerCase();
     if (/^new\s*/i.test(seg.root) || ctxName(seg.rootNode) === "NewExpression") {
-      return seg.root.replace(/^new\s*/i, "").replace(/\(.*\)$/, "").replace(/[<>].*$/, "");
+      return canonicalType(seg.root.replace(/^new\s*/i, "").replace(/\(.*\)$/, "").replace(/[<>].*$/, ""));
+    }
+    if (ctxName(seg.rootNode) === "ArrayExpression") {
+      const base = kids(seg.rootNode)[0];
+      if (base === void 0 || ctxName(base) !== "PrimaryExpression")
+        return null;
+      return elementTypeOf(resolveVarType(base.getText(), base));
     }
     if (rootLower === "this")
       return className;
@@ -303,6 +329,8 @@ var extractApexAstEdges = (source, className, options = {}) => {
         if (record)
           recordCall(`${type}.${method}`, at);
         type = null;
+      } else if (method.toLowerCase() === "get" && elementTypeOf(type) !== null) {
+        type = elementTypeOf(type);
       } else {
         type = null;
       }
@@ -384,11 +412,22 @@ var extractApexAstEdges = (source, className, options = {}) => {
     if (id !== void 0 && ownMethods.has(id.toLowerCase()))
       recordCall(`${className}.${id}`, mc);
   }
+  const literalOnly = [...literalReads].filter((r) => !reads.has(r));
+  for (const r of literalOnly)
+    reads.add(r);
   return {
     calls: [...calls].sort(),
     reads: [...reads].sort(),
+    ...literalOnly.length > 0 ? { literalQueryReads: literalOnly.sort() } : {},
     writes: [...writes].sort(),
     innerTypes: [...innerClasses.keys()].sort(),
+    variables: [
+      .../* @__PURE__ */ new Set([
+        ...fieldTypes.keys(),
+        ...orphanLocals.keys(),
+        ...[...methodLocals.values()].flatMap((m) => [...m.keys()])
+      ])
+    ].sort(),
     callSites: [...callSites].sort((a, b) => a.callee < b.callee ? -1 : a.callee > b.callee ? 1 : a.callerMethod < b.callerMethod ? -1 : a.callerMethod > b.callerMethod ? 1 : 0)
   };
 };
@@ -400,9 +439,13 @@ if (parentPort === null) {
 var knownClasses = new Set(
   Array.isArray(workerData?.knownClasses) ? workerData.knownClasses : []
 );
+var knownObjects = new Set(
+  Array.isArray(workerData?.knownObjects) ? workerData.knownObjects : []
+);
 parentPort.on("message", (job) => {
   const result = extractApexAstEdges(job.source, job.apiName, {
     knownClasses,
+    knownObjects,
     kind: job.kind
   });
   parentPort.postMessage({ index: job.index, result });