@salesforce/graphiti 10.10.2

package/dist/lib/introspect.js

@@ -0,0 +1,280 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any -- graphiti traverses untyped schema/introspection JSON; see follow-up to replace with `unknown` + narrowing */
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import { Org } from "@salesforce/core";
+import { atomicWriteJson, graphitiHome } from "./fs-utils.js";
+// Re-export for backward compatibility with existing graphiti consumers.
+export { graphitiHome };
+/** API version used for display-only endpoints where no live connection is available
+ *  to query the org's actual version (live requests use connection.getApiVersion()). */
+export const DEFAULT_API_VERSION = "67.0";
+async function getConnection(auth) {
+    const org = await Org.create({ aliasOrUsername: auth.alias });
+    return org.getConnection();
+}
+/** Resolves the directory holding cached introspection JSON files. */
+export function schemaDir() {
+    return path.join(graphitiHome(), "schemas");
+}
+const INTROSPECTION_QUERY = `
+query IntrospectionQuery {
+  __schema {
+    queryType { name }
+    mutationType { name }
+    types {
+      kind
+      name
+      description
+      fields(includeDeprecated: false) {
+        name
+        description
+        args {
+          name
+          description
+          type { ...TypeRef }
+          defaultValue
+        }
+        type { ...TypeRef }
+      }
+      inputFields {
+        name
+        description
+        type { ...TypeRef }
+        defaultValue
+      }
+      interfaces { ...TypeRef }
+      enumValues(includeDeprecated: false) {
+        name
+        description
+      }
+      possibleTypes { ...TypeRef }
+    }
+    directives {
+      name
+      description
+      locations
+      args {
+        name
+        description
+        type { ...TypeRef }
+        defaultValue
+      }
+    }
+  }
+}
+
+fragment TypeRef on __Type {
+  kind
+  name
+  ofType {
+    kind
+    name
+    ofType {
+      kind
+      name
+      ofType {
+        kind
+        name
+        ofType {
+          kind
+          name
+          ofType {
+            kind
+            name
+            ofType {
+              kind
+              name
+            }
+          }
+        }
+      }
+    }
+  }
+}`;
+// ── DLM/SSOT stripping ───────────────────────────────────────────────────────
+const DLM_SSOT_RE = /__dlm/i;
+function getNamedTypeNameFromRef(typeRef) {
+    if (!typeRef)
+        return null;
+    if (typeRef.name)
+        return typeRef.name;
+    return getNamedTypeNameFromRef(typeRef.ofType);
+}
+/**
+ * Strips Data Cloud (DLM/SSOT) types and their field references from a raw
+ * introspection result.  Matches type names containing `__dlm` (case-insensitive)
+ * or starting with `ssot__`.  Returns the mutated result and a count of removed types.
+ */
+export function stripDataCloudTypes(raw) {
+    const schema = raw?.data?.__schema ?? raw?.__schema;
+    if (!schema?.types)
+        return { result: raw, removedCount: 0 };
+    const removedNames = new Set();
+    for (const type of schema.types) {
+        if (type.name && (DLM_SSOT_RE.test(type.name) || type.name.startsWith("ssot__"))) {
+            removedNames.add(type.name);
+        }
+    }
+    if (removedNames.size === 0)
+        return { result: raw, removedCount: 0 };
+    const isRemoved = (ref) => {
+        const name = getNamedTypeNameFromRef(ref);
+        return name != null && removedNames.has(name);
+    };
+    schema.types = schema.types.filter((t) => !removedNames.has(t.name));
+    for (const type of schema.types) {
+        if (type.fields) {
+            type.fields = type.fields.filter((f) => !isRemoved(f.type));
+        }
+        if (type.inputFields) {
+            type.inputFields = type.inputFields.filter((f) => !isRemoved(f.type));
+        }
+        if (type.possibleTypes) {
+            type.possibleTypes = type.possibleTypes.filter((t) => !t.name || !removedNames.has(t.name));
+        }
+        if (type.interfaces) {
+            type.interfaces = type.interfaces.filter((t) => !t.name || !removedNames.has(t.name));
+        }
+    }
+    return { result: raw, removedCount: removedNames.size };
+}
+function _schemaPath(alias) {
+    return path.join(schemaDir(), `${alias}.json`);
+}
+export function normalizeInstanceUrl(instanceUrl) {
+    return instanceUrl.replace(/\/+$/, "").toLowerCase();
+}
+export function schemaCacheKeyForInstanceUrl(instanceUrl) {
+    const normalized = normalizeInstanceUrl(instanceUrl);
+    return crypto.createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+}
+function schemaPathForInstanceUrl(instanceUrl) {
+    const cacheKey = schemaCacheKeyForInstanceUrl(instanceUrl);
+    return path.join(schemaDir(), `${cacheKey}.json`);
+}
+export function schemaExists(instanceUrl) {
+    return fs.existsSync(schemaPathForInstanceUrl(normalizeInstanceUrl(instanceUrl)));
+}
+export function getSchemaMetadata(instanceUrl) {
+    const normalized = normalizeInstanceUrl(instanceUrl);
+    const fp = schemaPathForInstanceUrl(normalized);
+    if (!fs.existsSync(fp))
+        return null;
+    try {
+        const raw = JSON.parse(fs.readFileSync(fp, "utf-8"));
+        const types = (raw?.data?.__schema?.types ?? raw?.__schema?.types ?? []);
+        const stat = fs.statSync(fp);
+        return {
+            cacheKey: schemaCacheKeyForInstanceUrl(normalized),
+            instanceUrl: normalized,
+            typeCount: types.filter((t) => !t.name.startsWith("__")).length,
+            downloadedAt: stat.mtime.toISOString(),
+            filePath: fp,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function listCachedSchemas() {
+    const dir = schemaDir();
+    if (!fs.existsSync(dir))
+        return [];
+    return fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith(".json"))
+        .map((fileName) => {
+        try {
+            const fp = path.join(dir, fileName);
+            const raw = JSON.parse(fs.readFileSync(fp, "utf-8"));
+            const types = (raw?.data?.__schema?.types ?? raw?.__schema?.types ?? []);
+            const stat = fs.statSync(fp);
+            const instanceUrl = raw?.__graphiti?.instanceUrl;
+            if (typeof instanceUrl !== "string")
+                return null;
+            return {
+                cacheKey: fileName.replace(".json", ""),
+                instanceUrl,
+                typeCount: types.filter((t) => !t.name.startsWith("__")).length,
+                downloadedAt: stat.mtime.toISOString(),
+                filePath: fp,
+            };
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((m) => m !== null);
+}
+export async function downloadSchema(auth) {
+    const connection = await getConnection(auth);
+    const url = `${auth.instanceUrl}/services/data/v${connection.getApiVersion()}/graphql`;
+    const rawResult = (await connection.request({
+        method: "POST",
+        url,
+        body: JSON.stringify({ query: INTROSPECTION_QUERY }),
+        headers: { "Content-Type": "application/json", "X-Chatter-Entity-Encoding": "false" },
+    }));
+    if (rawResult?.errors?.length) {
+        const messages = rawResult.errors
+            .map((e) => e.message ?? JSON.stringify(e))
+            .join("\n  ");
+        throw new Error(`Introspection query returned errors:\n  ${messages}`);
+    }
+    const rawSchema = rawResult?.data?.__schema ?? rawResult?.__schema;
+    if (!rawSchema) {
+        throw new Error("Introspection query did not return a __schema field");
+    }
+    const { result, removedCount } = stripDataCloudTypes(rawResult);
+    const schema = result?.data?.__schema ?? result?.__schema;
+    const instanceUrl = normalizeInstanceUrl(auth.instanceUrl);
+    const filePath = schemaPathForInstanceUrl(instanceUrl);
+    const payload = {
+        ...result,
+        __graphiti: {
+            instanceUrl,
+            alias: auth.alias,
+            cachedAt: new Date().toISOString(),
+            cacheKey: schemaCacheKeyForInstanceUrl(instanceUrl),
+            strippedDataCloudTypes: removedCount,
+        },
+    };
+    atomicWriteJson(filePath, payload);
+    const typeCount = schema.types.filter((t) => !t.name.startsWith("__")).length;
+    return {
+        cacheKey: schemaCacheKeyForInstanceUrl(instanceUrl),
+        instanceUrl,
+        typeCount,
+        downloadedAt: new Date().toISOString(),
+        filePath,
+        strippedDataCloudTypes: removedCount || undefined,
+    };
+}
+export function loadIntrospectionResult(instanceUrl) {
+    const fp = schemaPathForInstanceUrl(normalizeInstanceUrl(instanceUrl));
+    if (!fs.existsSync(fp)) {
+        throw new Error(`No cached schema for "${instanceUrl}". Run \`graphiti connect <org>\` first.`);
+    }
+    return JSON.parse(fs.readFileSync(fp, "utf-8"));
+}
+/** Returns the absolute path to the cached introspection JSON file. */
+export function getSchemaFilePath(instanceUrl) {
+    return schemaPathForInstanceUrl(normalizeInstanceUrl(instanceUrl));
+}
+export async function executeGraphQL(auth, query, variables) {
+    const connection = await getConnection(auth);
+    const url = `${auth.instanceUrl}/services/data/v${connection.getApiVersion()}/graphql`;
+    return connection.request({
+        method: "POST",
+        url,
+        body: JSON.stringify({ query, variables }),
+        headers: { "Content-Type": "application/json", "X-Chatter-Entity-Encoding": "false" },
+    });
+}
+//# sourceMappingURL=introspect.js.map

package/dist/lib/introspect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspect.js","sourceRoot":"","sources":["../../src/lib/introspect.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,oKAAoK;AAEpK,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,GAAG,EAAmB,MAAM,kBAAkB,CAAC;AAExD,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE9D,yEAAyE;AACzE,OAAO,EAAE,YAAY,EAAE,CAAC;AAExB;wFACwF;AACxF,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAE1C,KAAK,UAAU,aAAa,CAAC,IAAa;IACzC,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,EAAE,eAAe,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IAC9D,OAAO,GAAG,CAAC,aAAa,EAAE,CAAC;AAC5B,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,SAAS;IACxB,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,SAAS,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0E1B,CAAC;AAEH,gFAAgF;AAEhF,MAAM,WAAW,GAAG,QAAQ,CAAC;AAE7B,SAAS,uBAAuB,CAAC,OAAY;IAC5C,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,IAAI,OAAO,CAAC,IAAI;QAAE,OAAO,OAAO,CAAC,IAAI,CAAC;IACtC,OAAO,uBAAuB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAQ;IAC3C,MAAM,MAAM,GAAG,GAAG,EAAE,IAAI,EAAE,QAAQ,IAAI,GAAG,EAAE,QAAQ,CAAC;IACpD,IAAI,CAAC,MAAM,EAAE,KAAK;QAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;IAE5D,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACvC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjC,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;YAClF,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;IACF,CAAC;IAED,IAAI,YAAY,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;IAErE,MAAM,SAAS,GAAG,CAAC,GAAQ,EAAE,EAAE;QAC9B,MAAM,IAAI,GAAG,uBAAuB,CAAC,GAAG,CAAC,CAAC;QAC1C,OAAO,IAAI,IAAI,IAAI,IAAI,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/C,CAAC,CAAC;IAEF,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAE1E,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QAClE,CAAC;QACD,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QAC5E,CAAC;QACD,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,CAC7C,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAChD,CAAC;QACH,CAAC;QACD,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QAC5F,CAAC;IACF,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,EAAE,YAAY,CAAC,IAAI,EAAE,CAAC;AACzD,CAAC;AAED,SAAS,WAAW,CAAC,KAAa;IACjC,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,WAAmB;IACvD,OAAO,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,WAAmB;IAC/D,MAAM,UAAU,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC;IACrD,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAClF,CAAC;AAED,SAAS,wBAAwB,CAAC,WAAmB;IACpD,MAAM,QAAQ,GAAG,4BAA4B,CAAC,WAAW,CAAC,CAAC;IAC3D,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,GAAG,QAAQ,OAAO,CAAC,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,WAAmB;IAC/C,OAAO,EAAE,CAAC,UAAU,CAAC,wBAAwB,CAAC,oBAAoB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;AACnF,CAAC;AAWD,MAAM,UAAU,iBAAiB,CAAC,WAAmB;IACpD,MAAM,UAAU,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC;IACrD,MAAM,EAAE,GAAG,wBAAwB,CAAC,UAAU,CAAC,CAAC;IAChD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,IAAI,CAAC;QACJ,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;QACrD,MAAM,KAAK,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,IAAI,GAAG,EAAE,QAAQ,EAAE,KAAK,IAAI,EAAE,CAAU,CAAC;QAClF,MAAM,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAC7B,OAAO;YACN,QAAQ,EAAE,4BAA4B,CAAC,UAAU,CAAC;YAClD,WAAW,EAAE,UAAU;YACvB,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM;YACpE,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE;YACtC,QAAQ,EAAE,EAAE;SACZ,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,CAAC;IACb,CAAC;AACF,CAAC;AAED,MAAM,UAAU,iBAAiB;IAChC,MAAM,GAAG,GAAG,SAAS,EAAE,CAAC;IACxB,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IACnC,OAAO,EAAE;SACP,WAAW,CAAC,GAAG,CAAC;SAChB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;SAClC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE;QACjB,IAAI,CAAC;YACJ,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;YACpC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;YACrD,MAAM,KAAK,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,IAAI,GAAG,EAAE,QAAQ,EAAE,KAAK,IAAI,EAAE,CAAU,CAAC;YAClF,MAAM,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;YAC7B,MAAM,WAAW,GAAG,GAAG,EAAE,UAAU,EAAE,WAAW,CAAC;YACjD,IAAI,OAAO,WAAW,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC;YACjD,OAAO;gBACN,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;gBACvC,WAAW;gBACX,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM;gBACpE,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE;gBACtC,QAAQ,EAAE,EAAE;aACZ,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,IAAI,CAAC;QACb,CAAC;IACF,CAAC,CAAC;SACD,MAAM,CAAC,CAAC,CAAC,EAAuB,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAa;IACjD,MAAM,UAAU,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,WAAW,mBAAmB,UAAU,CAAC,aAAa,EAAE,UAAU,CAAC;IAEvF,MAAM,SAAS,GAAG,CAAC,MAAM,UAAU,CAAC,OAAO,CAAC;QAC3C,MAAM,EAAE,MAAM;QACd,GAAG;QACH,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,mBAAmB,EAAE,CAAC;QACpD,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,2BAA2B,EAAE,OAAO,EAAE;KACrF,CAAC,CAAQ,CAAC;IAEX,IAAI,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAI,SAAS,CAAC,MAAgB;aAC1C,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;aAC/C,IAAI,CAAC,MAAM,CAAC,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,2CAA2C,QAAQ,EAAE,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,SAAS,GAAG,SAAS,EAAE,IAAI,EAAE,QAAQ,IAAI,SAAS,EAAE,QAAQ,CAAC;IACnE,IAAI,CAAC,SAAS,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;IAChE,MAAM,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,QAAQ,IAAI,MAAM,EAAE,QAAQ,CAAC;IAE1D,MAAM,WAAW,GAAG,oBAAoB,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC3D,MAAM,QAAQ,GAAG,wBAAwB,CAAC,WAAW,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG;QACf,GAAG,MAAM;QACT,UAAU,EAAE;YACX,WAAW;YACX,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,QAAQ,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YAClC,QAAQ,EAAE,4BAA4B,CAAC,WAAW,CAAC;YACnD,sBAAsB,EAAE,YAAY;SACpC;KACD,CAAC;IACF,eAAe,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAEnC,MAAM,SAAS,GAAI,MAAM,CAAC,KAAe,CAAC,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;IAE9F,OAAO;QACN,QAAQ,EAAE,4BAA4B,CAAC,WAAW,CAAC;QACnD,WAAW;QACX,SAAS;QACT,YAAY,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACtC,QAAQ;QACR,sBAAsB,EAAE,YAAY,IAAI,SAAS;KACjD,CAAC;AACH,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,WAAmB;IAC1D,MAAM,EAAE,GAAG,wBAAwB,CAAC,oBAAoB,CAAC,WAAW,CAAC,CAAC,CAAC;IACvE,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,yBAAyB,WAAW,0CAA0C,CAAC,CAAC;IACjG,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,iBAAiB,CAAC,WAAmB;IACpD,OAAO,wBAAwB,CAAC,oBAAoB,CAAC,WAAW,CAAC,CAAC,CAAC;AACpE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CACnC,IAAa,EACb,KAAa,EACb,SAAmC;IAEnC,MAAM,UAAU,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,WAAW,mBAAmB,UAAU,CAAC,aAAa,EAAE,UAAU,CAAC;IACvF,OAAO,UAAU,CAAC,OAAO,CAAC;QACzB,MAAM,EAAE,MAAM;QACd,GAAG;QACH,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QAC1C,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,2BAA2B,EAAE,OAAO,EAAE;KACrF,CAAC,CAAC;AACJ,CAAC"}

package/dist/lib/object-info.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import type { OrgAuth } from "./auth.js";
+export interface PicklistValue {
+    value: string | null;
+    label: string | null;
+}
+export interface PicklistFieldInfo {
+    apiName: string;
+    label: string;
+    required: boolean;
+    values: PicklistValue[];
+}
+export interface FieldMetadata {
+    apiName: string;
+    label: string | null;
+    dataType: string | null;
+    required: boolean;
+    createable: boolean;
+    updateable: boolean;
+    calculated: boolean;
+    custom: boolean;
+    filterable: boolean;
+    sortable: boolean;
+    nameField: boolean;
+    reference: boolean;
+    relationshipName: string | null;
+    compound: boolean;
+    compoundFieldName: string | null;
+    defaultedOnCreate: boolean;
+    extraTypeInfo: string | null;
+    inlineHelpText: string | null;
+    precision: number;
+    scale: number;
+    referenceToInfos: {
+        apiName: string;
+        nameFields: string[];
+    }[];
+    controllerName: string | null;
+    controllingFields: string[];
+}
+export interface ObjectInfoResult {
+    apiName: string;
+    label: string | null;
+    labelPlural: string | null;
+    createable: boolean;
+    deletable: boolean;
+    updateable: boolean;
+    queryable: boolean;
+    searchable: boolean;
+    custom: boolean;
+    keyPrefix: string | null;
+    nameFields: string[];
+    defaultRecordTypeId: string | null;
+    fields: FieldMetadata[];
+    childRelationships: {
+        childObjectApiName: string;
+        fieldName: string | null;
+        relationshipName: string | null;
+    }[];
+    recordTypeInfos: {
+        recordTypeId: string;
+        name: string | null;
+        available: boolean;
+        master: boolean;
+        defaultRecordTypeMapping: boolean;
+    }[];
+    picklists: PicklistFieldInfo[];
+    fetchedAt: string;
+}
+export declare function getObjectInfo(auth: OrgAuth, orgAlias: string, sObjectName: string, refresh?: boolean): Promise<ObjectInfoResult>;
+export declare function getCachedObjectInfo(orgAlias: string, sObjectName: string): ObjectInfoResult | null;
+export declare function setCachedObjectInfo(orgAlias: string, sObjectName: string, info: ObjectInfoResult): void;
+export declare function getRequiredCreateFields(info: ObjectInfoResult): FieldMetadata[];
+export declare function getPicklistValues(info: ObjectInfoResult, fieldName: string): PicklistValue[] | null;
+export declare function clearObjectInfoCache(orgAlias?: string): void;

package/dist/lib/object-info.js

@@ -0,0 +1,313 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any -- graphiti traverses untyped schema/introspection JSON; see follow-up to replace with `unknown` + narrowing */
+import fs from "fs";
+import path from "path";
+import { graphitiHome } from "./fs-utils.js";
+import { executeGraphQL } from "./introspect.js";
+// Re-read GRAPHITI_HOME on each call so tests redirecting via env vars
+// see the current value, not a frozen import-time snapshot.
+function cacheDir() {
+    return path.join(graphitiHome(), "cache", "objectInfos");
+}
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+const MASTER_RECORD_TYPE_ID = "012000000000000AAA";
+const OBJECT_INFO_QUERY = `
+query ObjectInfoQuery($inputs: [ObjectInfoInput!]) {
+  uiapi {
+    objectInfos(objectInfoInputs: $inputs) {
+      ApiName
+      label
+      labelPlural
+      createable
+      deletable
+      updateable
+      queryable
+      searchable
+      custom
+      keyPrefix
+      nameFields
+      defaultRecordTypeId
+      recordTypeInfos {
+        recordTypeId
+        name
+        available
+        master
+        defaultRecordTypeMapping
+      }
+      childRelationships {
+        childObjectApiName
+        fieldName
+        relationshipName
+      }
+      fields {
+        ApiName
+        label
+        dataType
+        required
+        createable
+        updateable
+        calculated
+        custom
+        filterable
+        sortable
+        nameField
+        reference
+        relationshipName
+        compound
+        compoundFieldName
+        defaultedOnCreate
+        extraTypeInfo
+        inlineHelpText
+        precision
+        scale
+        controllerName
+        controllingFields
+        referenceToInfos {
+          ApiName
+          nameFields
+        }
+        ... on PicklistField {
+          picklistValuesByRecordTypeIDs {
+            recordTypeID
+            picklistValues {
+              value
+              label
+            }
+          }
+        }
+      }
+    }
+  }
+}`;
+// Process-lifetime in-memory cache. Unbounded by design: graphiti runs as
+// short-lived CLI invocations and per-MCP-session servers, so the working
+// set is naturally capped by the SObjects an agent walks during one session.
+const memoryCache = new Map();
+function cacheKey(orgAlias, sObjectName) {
+    return `${orgAlias}:${sObjectName}`;
+}
+// Defense in depth: callers (the MCP boundary) already validate API-name
+// charsets, but cache paths are also reachable from CLI/library callers, so
+// re-validate here before joining and assert the resolved path stays inside
+// the cache root.
+const ORG_ALIAS_PATH_RE = /^[A-Za-z0-9_-]{1,80}$/;
+const SOBJECT_NAME_PATH_RE = /^[A-Za-z][A-Za-z0-9_]{0,79}$/;
+function cacheFilePath(orgAlias, sObjectName) {
+    if (!ORG_ALIAS_PATH_RE.test(orgAlias)) {
+        throw new Error(`Invalid org alias for cache path: "${orgAlias}"`);
+    }
+    if (!SOBJECT_NAME_PATH_RE.test(sObjectName)) {
+        throw new Error(`Invalid SObject name for cache path: "${sObjectName}"`);
+    }
+    const rootResolved = path.resolve(cacheDir());
+    const resolved = path.resolve(rootResolved, orgAlias, `${sObjectName}.json`);
+    if (!resolved.startsWith(rootResolved + path.sep)) {
+        throw new Error("Refusing to access cache path outside cache root");
+    }
+    return resolved;
+}
+function readDiskCache(orgAlias, sObjectName) {
+    let fp;
+    try {
+        fp = cacheFilePath(orgAlias, sObjectName);
+    }
+    catch {
+        return null;
+    }
+    if (!fs.existsSync(fp))
+        return null;
+    try {
+        const raw = JSON.parse(fs.readFileSync(fp, "utf-8"));
+        const age = Date.now() - new Date(raw.fetchedAt).getTime();
+        // Reject NaN (corrupt or missing fetchedAt) so a hand-edited cache
+        // can't read as fresh forever.
+        if (Number.isNaN(age) || age > CACHE_TTL_MS)
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+function writeDiskCache(orgAlias, sObjectName, data) {
+    let filePath;
+    try {
+        filePath = cacheFilePath(orgAlias, sObjectName);
+    }
+    catch {
+        return; // invalid inputs — refuse to write
+    }
+    try {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, JSON.stringify(data, null, 2), "utf-8");
+    }
+    catch {
+        // Non-critical
+    }
+}
+function parseObjectInfoResponse(raw) {
+    const fields = (raw.fields ?? []).map((f) => ({
+        apiName: f.ApiName,
+        label: f.label ?? null,
+        dataType: f.dataType ?? null,
+        required: f.required ?? false,
+        createable: f.createable ?? false,
+        updateable: f.updateable ?? false,
+        calculated: f.calculated ?? false,
+        custom: f.custom ?? false,
+        filterable: f.filterable ?? false,
+        sortable: f.sortable ?? false,
+        nameField: f.nameField ?? false,
+        reference: f.reference ?? false,
+        relationshipName: f.relationshipName ?? null,
+        compound: f.compound ?? false,
+        compoundFieldName: f.compoundFieldName ?? null,
+        defaultedOnCreate: f.defaultedOnCreate ?? false,
+        extraTypeInfo: f.extraTypeInfo ?? null,
+        inlineHelpText: f.inlineHelpText ?? null,
+        precision: f.precision ?? 0,
+        scale: f.scale ?? 0,
+        referenceToInfos: (f.referenceToInfos ?? []).map((r) => ({
+            apiName: r.ApiName,
+            nameFields: r.nameFields ?? [],
+        })),
+        controllerName: f.controllerName ?? null,
+        controllingFields: f.controllingFields ?? [],
+    }));
+    const picklists = (raw.fields ?? [])
+        .filter((f) => f.picklistValuesByRecordTypeIDs)
+        .map((f) => {
+        const allValues = (f.picklistValuesByRecordTypeIDs ?? []).flatMap((rt) => rt.picklistValues ?? []);
+        // Drop entries with no value rather than recording `value: null`.
+        // Keeps the on-disk cache shape identical to pre-change behavior so
+        // consumers that don't null-guard (commands/type.ts, commands/review.ts)
+        // can't read explicit nulls back out after a rollback.
+        return {
+            apiName: f.ApiName,
+            label: f.label ?? f.ApiName,
+            required: f.required ?? false,
+            values: allValues
+                .filter((v) => v?.value != null)
+                .map((v) => ({ value: v.value, label: v.label ?? null })),
+        };
+    });
+    return {
+        apiName: raw.ApiName,
+        label: raw.label ?? null,
+        labelPlural: raw.labelPlural ?? null,
+        createable: raw.createable ?? false,
+        deletable: raw.deletable ?? false,
+        updateable: raw.updateable ?? false,
+        queryable: raw.queryable ?? false,
+        searchable: raw.searchable ?? false,
+        custom: raw.custom ?? false,
+        keyPrefix: raw.keyPrefix ?? null,
+        nameFields: raw.nameFields ?? [],
+        defaultRecordTypeId: raw.defaultRecordTypeId ?? null,
+        fields,
+        childRelationships: (raw.childRelationships ?? []).map((cr) => ({
+            childObjectApiName: cr.childObjectApiName,
+            fieldName: cr.fieldName ?? null,
+            relationshipName: cr.relationshipName ?? null,
+        })),
+        recordTypeInfos: (raw.recordTypeInfos ?? []).map((rt) => ({
+            recordTypeId: rt.recordTypeId,
+            name: rt.name ?? null,
+            available: rt.available ?? false,
+            master: rt.master ?? false,
+            defaultRecordTypeMapping: rt.defaultRecordTypeMapping ?? false,
+        })),
+        picklists,
+        fetchedAt: new Date().toISOString(),
+    };
+}
+export async function getObjectInfo(auth, orgAlias, sObjectName, refresh = false) {
+    const key = cacheKey(orgAlias, sObjectName);
+    if (!refresh) {
+        const mem = memoryCache.get(key);
+        if (mem) {
+            const age = Date.now() - new Date(mem.fetchedAt).getTime();
+            if (age <= CACHE_TTL_MS)
+                return mem;
+        }
+        const disk = readDiskCache(orgAlias, sObjectName);
+        if (disk) {
+            memoryCache.set(key, disk);
+            return disk;
+        }
+    }
+    // Master record type is the union of all picklist values for the field;
+    // non-master record types only restrict (hide) values, never add them. So
+    // a single fetch with [MASTER_RECORD_TYPE_ID] returns the complete set.
+    const result = await executeGraphQL(auth, OBJECT_INFO_QUERY, {
+        inputs: [{ apiName: sObjectName, recordTypeIDs: [MASTER_RECORD_TYPE_ID] }],
+    });
+    const infos = result?.data?.uiapi?.objectInfos;
+    if (!infos || infos.length === 0) {
+        throw new Error(`No objectInfo returned for "${sObjectName}". Check that the object exists and is accessible.`);
+    }
+    const parsed = parseObjectInfoResponse(infos[0]);
+    memoryCache.set(key, parsed);
+    writeDiskCache(orgAlias, sObjectName, parsed);
+    return parsed;
+}
+export function getCachedObjectInfo(orgAlias, sObjectName) {
+    const key = cacheKey(orgAlias, sObjectName);
+    const mem = memoryCache.get(key);
+    if (mem)
+        return mem;
+    const disk = readDiskCache(orgAlias, sObjectName);
+    if (disk) {
+        memoryCache.set(key, disk);
+        return disk;
+    }
+    return null;
+}
+// Seed the in-memory ObjectInfo cache directly. Lets callers prime codegen
+// without going through the live UIAPI fetch in `getObjectInfo`. Used by
+// tests today; the planned MCP intent-layer prewarm helper (W-22694063)
+// will reuse the same write path after a successful network fetch.
+export function setCachedObjectInfo(orgAlias, sObjectName, info) {
+    memoryCache.set(cacheKey(orgAlias, sObjectName), info);
+}
+export function getRequiredCreateFields(info) {
+    return info.fields.filter((f) => f.required && f.createable && !f.defaultedOnCreate);
+}
+export function getPicklistValues(info, fieldName) {
+    const picklist = info.picklists.find((p) => p.apiName === fieldName);
+    return picklist?.values ?? null;
+}
+export function clearObjectInfoCache(orgAlias) {
+    if (orgAlias) {
+        for (const [key] of memoryCache) {
+            if (key.startsWith(`${orgAlias}:`))
+                memoryCache.delete(key);
+        }
+        if (!ORG_ALIAS_PATH_RE.test(orgAlias))
+            return;
+        const root = path.resolve(cacheDir());
+        const dir = path.resolve(root, orgAlias);
+        if (!dir.startsWith(root + path.sep))
+            return;
+        try {
+            fs.rmSync(dir, { recursive: true });
+        }
+        catch {
+            /* ok */
+        }
+    }
+    else {
+        memoryCache.clear();
+        try {
+            fs.rmSync(cacheDir(), { recursive: true });
+        }
+        catch {
+            /* ok */
+        }
+    }
+}
+//# sourceMappingURL=object-info.js.map