@salesforce/graphiti 10.10.2

package/dist/lib/query-commands.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { COMMANDS } from "./command-registry.js";
+import type { QuerySession } from "./session.js";
+import type { WalkerResult } from "./walker.js";
+export declare function setInteractiveMode(on: boolean): void;
+export declare function isInteractiveMode(): boolean;
+export { COMMANDS as QUERY_COMMANDS };
+export declare function formatHelp(topic?: string): string;
+export interface NextStepsContext {
+    sessionId: string;
+    command: string;
+    walkerResult?: WalkerResult;
+    session?: QuerySession;
+}
+export declare function formatNextSteps(ctx: NextStepsContext): string;

package/dist/lib/query-commands.js

@@ -0,0 +1,262 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { COMMANDS } from "./command-registry.js";
+// ── Interactive mode flag ─────────────────────────────────────────────────────
+let _interactiveMode = false;
+export function setInteractiveMode(on) {
+    _interactiveMode = on;
+}
+export function isInteractiveMode() {
+    return _interactiveMode;
+}
+// ── Backward-compatible re-export ─────────────────────────────────────────────
+// QUERY_COMMANDS was the original registry. It now delegates to the canonical
+// COMMANDS array in command-registry.ts so there is a single source of truth.
+export { COMMANDS as QUERY_COMMANDS };
+// ── Formatting helpers ───────────────────────────────────────────────────────
+export function formatHelp(topic) {
+    const lines = [];
+    if (topic) {
+        const spec = COMMANDS.find((c) => c.name === topic);
+        if (!spec) {
+            return `Unknown help topic: "${topic}". Run \`help\` with no arguments for a full list.`;
+        }
+        lines.push(`${spec.name} — ${spec.summary}`);
+        lines.push("");
+        const usagePrefix = _interactiveMode ? "" : "graphiti ";
+        const usageStr = spec.usage.startsWith("graphiti ")
+            ? spec.usage
+            : `${usagePrefix}${spec.usage}`;
+        lines.push(`Usage: ${usageStr}`);
+        if (spec.subcommands && spec.subcommands.length > 0) {
+            lines.push("");
+            lines.push("Subcommands:");
+            for (const sub of spec.subcommands) {
+                lines.push(`  ${sub.usage.padEnd(32)} ${sub.description}`);
+            }
+        }
+        if (topic === "ls") {
+            lines.push("");
+            lines.push("Search behavior (--search):");
+            lines.push('  Multiple terms are OR-matched: --search "Name Id" matches fields');
+            lines.push('  containing either "Name" or "Id". Each term is prefix-matched');
+            lines.push('  against CamelCase word segments, so "Id" matches "AccountId"');
+            lines.push('  but not "Hide".');
+        }
+        if (topic === "alias" || topic === "mkdir") {
+            lines.push("");
+            lines.push("Multi-query composition:");
+            lines.push("  Use alias to create multiple named instances of the same field,");
+            lines.push("  each with different arguments. This lets you combine several queries");
+            lines.push("  into a single GraphQL request (e.g. dashboard tiles + lists).");
+            lines.push("");
+            lines.push("  # Full end-to-end example (from /query/uiapi/query):");
+            lines.push("  alias newCases Case");
+            lines.push('  set newCases/@args/where \'{"Status":{"eq":"New"}}\'');
+            lines.push("  set newCases/@args/first 10");
+            lines.push("  select newCases/edges/node/Id newCases/edges/node/Subject/value");
+            lines.push("");
+            lines.push("  alias myCases Case");
+            lines.push("  set myCases/@args/scope MINE");
+            lines.push("  set myCases/@args/first 20");
+            lines.push("  select myCases/edges/node/Id myCases/edges/node/Status/value");
+            lines.push("");
+            lines.push("  show   # see the combined query");
+        }
+        if (topic === "chain") {
+            lines.push("");
+            lines.push("Note: session management commands (new, use, connect, describe,");
+            lines.push("interactive) must be run as separate commands before chaining.");
+            lines.push("Only session-scoped commands (cd, ls, select, set, var, etc.)");
+            lines.push("can be used inside a chain.");
+        }
+        if (topic === "set" || topic === "assign") {
+            lines.push("");
+            lines.push("Inline key=value syntax (preferred):");
+            lines.push("  set first=10                              # set on current field");
+            lines.push("  set uiapi/query/Case first=10 scope=MINE  # with absolute field path");
+            lines.push('  set where=\'{"Status":{"eq":"New"}}\'       # JSON value');
+            lines.push("");
+            lines.push("Legacy pair syntax:");
+            lines.push("  set @args/first 10");
+            lines.push('  set @args/where/Name/like "Acme%"');
+        }
+        lines.push("");
+        lines.push("Examples:");
+        for (const ex of spec.examples) {
+            const exPrefix = _interactiveMode ? "  " : "  ";
+            lines.push(`${exPrefix}${ex}`);
+        }
+        return lines.join("\n");
+    }
+    lines.push("Graphiti CLI — Progressive GraphQL query builder for Salesforce");
+    lines.push("");
+    lines.push("Session resolution: --session / -s flag > GRAPHITI_SESSION env var > ~/.graphiti/active");
+    lines.push("JSON output: --json flag or GRAPHITI_AGENT=1 env var");
+    lines.push("");
+    lines.push("Setup:");
+    for (const name of ["new", "use", "connect"]) {
+        const spec = COMMANDS.find((c) => c.name === name);
+        if (spec)
+            lines.push(`  ${spec.name.padEnd(12)} ${spec.summary}`);
+    }
+    lines.push("");
+    lines.push("Navigation:");
+    for (const name of ["pwd", "ls", "cd"]) {
+        const spec = COMMANDS.find((c) => c.name === name);
+        lines.push(`  ${spec.name.padEnd(12)} ${spec.summary}`);
+    }
+    lines.push("");
+    lines.push("Query Building:");
+    for (const name of ["select", "drop", "alias", "optional", "undo"]) {
+        const spec = COMMANDS.find((c) => c.name === name);
+        lines.push(`  ${spec.name.padEnd(12)} ${spec.summary}`);
+    }
+    lines.push("");
+    lines.push("Arguments & Variables:");
+    for (const name of ["set", "unset", "var"]) {
+        const spec = COMMANDS.find((c) => c.name === name);
+        lines.push(`  ${spec.name.padEnd(12)} ${spec.summary}`);
+    }
+    lines.push("");
+    lines.push("Review & Execute:");
+    for (const name of ["show", "check", "run", "describe", "codegen"]) {
+        const spec = COMMANDS.find((c) => c.name === name);
+        lines.push(`  ${spec.name.padEnd(12)} ${spec.summary}`);
+    }
+    lines.push("");
+    lines.push("Session Management:");
+    for (const name of ["sessions", "clone", "reset"]) {
+        const spec = COMMANDS.find((c) => c.name === name);
+        lines.push(`  ${spec.name.padEnd(12)} ${spec.summary}`);
+    }
+    lines.push("");
+    lines.push("Other:");
+    const otherCommands = _interactiveMode ? ["chain", "help"] : ["chain", "help", "interactive"];
+    for (const name of otherCommands) {
+        const spec = COMMANDS.find((c) => c.name === name);
+        if (spec)
+            lines.push(`  ${spec.name.padEnd(12)} ${spec.summary}`);
+    }
+    lines.push("");
+    lines.push("Run `help <subcommand>` for detailed usage and examples.");
+    return lines.join("\n");
+}
+export function formatNextSteps(ctx) {
+    const { sessionId: sid, command, walkerResult: wr, session } = ctx;
+    const lines = [];
+    const p = (cmd, desc) => {
+        if (_interactiveMode) {
+            lines.push(`  ${cmd.padEnd(36)} # ${desc}`);
+        }
+        else {
+            lines.push(`  graphiti query ${sid} ${cmd.padEnd(36)} # ${desc}`);
+        }
+    };
+    const isRoot = !session || session.navigationPath.length === 0;
+    const hasSelections = session ? session.nodes.length > 0 : false;
+    const hasArgs = wr && wr.args.length > 0;
+    const isLeaf = wr?.isLeaf ?? false;
+    const _hasFragments = wr && wr.possibleTypes.length > 0;
+    const hasFields = wr && !wr.isLeaf && wr.fields.length > 0;
+    lines.push("");
+    lines.push("Next steps:");
+    switch (command) {
+        case "new": {
+            p("cd query", "navigate into the query tree");
+            p("ls", "see available root fields");
+            p("interactive", "start an interactive session");
+            break;
+        }
+        case "ls": {
+            if (isLeaf) {
+                if (!isRoot && session) {
+                    const leaf = session.navigationPath[session.navigationPath.length - 1];
+                    p(`cd ..`, "go up to parent directory");
+                    p(`select ${leaf}`, "select this leaf field");
+                }
+            }
+            else {
+                if (hasFields) {
+                    const firstDir = wr.fields.find((f) => f.typeKind !== "SCALAR" && f.typeKind !== "ENUM");
+                    const firstLeaf = wr.fields.find((f) => f.typeKind === "SCALAR" || f.typeKind === "ENUM");
+                    if (firstDir)
+                        p(`cd ${firstDir.name}`, `navigate into ${firstDir.name}/`);
+                    if (firstLeaf)
+                        p(`select ${firstLeaf.name}`, `add ${firstLeaf.name} to projection`);
+                    const hasConnections = wr.fields.some((f) => f.typeName.includes("Connection"));
+                    if (hasConnections && firstDir)
+                        p(`alias myAlias ${firstDir.name}`, "compose multiple queries via aliases");
+                }
+                if (hasArgs)
+                    p(`cd @args`, "navigate into arguments");
+                if (!isRoot)
+                    p(`cd ..`, "go up one level");
+            }
+            break;
+        }
+        case "cd": {
+            p(`ls`, "see contents at this path");
+            if (hasArgs)
+                p(`cd @args`, "configure field arguments");
+            if (hasFields) {
+                const firstLeaf = wr.fields.find((f) => f.typeKind === "SCALAR" || f.typeKind === "ENUM");
+                if (firstLeaf)
+                    p(`select ${firstLeaf.name}`, `add ${firstLeaf.name} to projection`);
+            }
+            break;
+        }
+        case "select": {
+            p(`ls`, "see more available fields");
+            if (!isRoot)
+                p(`cd ..`, "go up to parent");
+            if (hasSelections) {
+                p(`show`, "preview the current query string");
+                p(`check`, "validate the query");
+            }
+            break;
+        }
+        case "assign":
+        case "set": {
+            p(`show`, "preview query with arguments");
+            p(`ls`, "see other fields to set");
+            if (hasSelections)
+                p(`check`, "validate the query");
+            break;
+        }
+        case "define":
+        case "var": {
+            p(`cd /variables/$varName`, "navigate into the variable to set values");
+            p(`show`, "preview the query signature");
+            break;
+        }
+        case "show": {
+            p(`check`, "validate the query");
+            if (hasSelections)
+                p(`run`, "execute the query against the org");
+            break;
+        }
+        case "validate":
+        case "check": {
+            if (hasSelections)
+                p(`run`, "execute the validated query");
+            p(`show`, "preview the query string");
+            break;
+        }
+        default: {
+            p(`ls`, "list contents at current path");
+            p(`show`, "preview the current query");
+            if (hasSelections)
+                p(`check`, "validate the query");
+            break;
+        }
+    }
+    if (lines.length <= 2) {
+        p(`help`, "show all available commands");
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=query-commands.js.map

package/dist/lib/query-commands.js.map

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

package/dist/lib/session.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+export interface DirectiveNode {
+    name: string;
+    args: Record<string, string>;
+}
+export interface VariableDefinition {
+    name: string;
+    type: string;
+    defaultValue?: string;
+    runtimeValue?: string;
+}
+export interface BaseProjectionNode {
+    id: string;
+    kind: "field" | "fragment";
+    parentId: string | null;
+    schemaPath: string[];
+    directives: DirectiveNode[];
+}
+export interface FieldProjectionNode extends BaseProjectionNode {
+    kind: "field";
+    fieldName: string;
+    alias?: string;
+    args: Record<string, string>;
+}
+export interface FragmentProjectionNode extends BaseProjectionNode {
+    kind: "fragment";
+    onType: string;
+}
+export type ProjectionNode = FieldProjectionNode | FragmentProjectionNode;
+export type OperationType = "query" | "mutation" | "aggregate";
+export interface QuerySession {
+    id: string;
+    name?: string;
+    /** GraphQL operation name emitted by `renderQuery`. Distinct from `name`, which is the session's user-facing label. */
+    operationName?: string;
+    orgAlias: string;
+    /** Resolved Salesforce instance URL stored at session creation to avoid repeated sf-auth calls. */
+    instanceUrl?: string;
+    operation: OperationType;
+    navigationPath: string[];
+    nodes: ProjectionNode[];
+    variables: VariableDefinition[];
+    focusByPath: Record<string, string>;
+    createdAt: string;
+    undoStack?: string[];
+}
+/**
+ * Snapshots the current session state (excluding undoStack) and pushes it
+ * onto the undo stack. Call this before any state-mutating operation.
+ */
+export declare function pushUndoSnapshot(session: QuerySession): void;
+/**
+ * Pops the most recent undo snapshot and returns a restored session.
+ * The restored session inherits the current (truncated) undo stack.
+ * Returns null if there is nothing to undo.
+ */
+export declare function popUndo(session: QuerySession): QuerySession | null;
+export declare function isFragmentSegment(segment: string): boolean;
+/**
+ * Normalizes a fragment segment to the canonical `[Type]` form.
+ * Accepts `on:Type` as a shell-safe alternative that avoids zsh glob/redirect
+ * issues with `[Type]` and `<Type>`.
+ *
+ * Examples: `on:User` → `[User]`, `[User]` stays as-is.
+ */
+export declare function normalizeFragmentSegment(segment: string): string;
+/** Returns true for alias-encoded path segments like `openOpps(Opportunity)`. */
+export declare function isAliasedSegment(segment: string): boolean;
+/**
+ * Parses an alias-encoded segment into its alias name and underlying field name.
+ * Returns null for plain or fragment segments.
+ */
+export declare function parseAliasedSegment(segment: string): {
+    alias: string;
+    fieldName: string;
+} | null;
+/** Strips the alias wrapper from a single path segment, leaving just the schema field name. */
+export declare function schemaSegment(segment: string): string;
+/**
+ * Converts a navigation path (which may contain alias-encoded segments) to a
+ * pure schema path suitable for schema resolution and focus-map lookups.
+ */
+export declare function toSchemaPath(navPath: string[]): string[];
+export declare function pathKey(pathSegments: string[]): string;
+export declare function formatPath(pathSegments: string[]): string;
+export declare function createSession(orgAlias: string, operation?: OperationType, instanceUrl?: string, name?: string): QuerySession;
+export declare function cloneSession(source: QuerySession, newName?: string): QuerySession;
+export declare function getNodeById(session: QuerySession, id: string | null | undefined): ProjectionNode | null;
+export declare function getChildren(session: QuerySession, parentId: string | null): ProjectionNode[];
+export declare function listInstancesAtPath(session: QuerySession, schemaPath: string[]): ProjectionNode[];
+export declare function getFocusedNodeAtPath(session: QuerySession, schemaPath: string[], createMissing?: boolean): ProjectionNode | null;
+export declare function ensureFocusedChain(session: QuerySession, schemaPath: string[]): ProjectionNode | null;
+/**
+ * Walks the query portion of the navigation path and syncs focusByPath entries
+ * for any aliased segments (e.g. `recentAccounts(Account)`). This ensures that
+ * subsequent select/assign operations target the correct aliased instance.
+ */
+export declare function syncFocusFromNavigationPath(session: QuerySession): void;
+export declare function focusNodeAtPath(session: QuerySession, schemaPath: string[], nodeId: string): void;
+export declare function createSiblingFieldInstance(session: QuerySession, schemaPath: string[], alias?: string): FieldProjectionNode;
+export declare function setAliasOnPath(session: QuerySession, schemaPath: string[], aliasName: string): FieldProjectionNode;
+export declare function clearAliasOnPath(session: QuerySession, schemaPath: string[]): void;
+export declare function focusInstanceByAliasOrId(session: QuerySession, schemaPath: string[], selector: string): ProjectionNode;
+export declare function setArg(session: QuerySession, schemaPath: string[], argName: string, value: string): void;
+export declare function getArg(session: QuerySession, schemaPath: string[], argName: string): string | undefined;
+export declare function removeArg(session: QuerySession, schemaPath: string[], argName: string): boolean;
+export declare function getEffectiveArgs(_session: QuerySession, node: ProjectionNode): Record<string, string>;
+export type NavigationContext = "root" | "query" | "variables";
+export declare function getNavigationContext(navPath: string[]): NavigationContext;
+export declare const ARGS_SEGMENT = "@args";
+export declare function isArgsSegment(segment: string): boolean;
+/** Returns the index of the @args segment in the path, or -1 if not present. */
+export declare function argsSegmentIndex(navPath: string[]): number;
+/** Returns true if the navigation path is inside an @args context. */
+export declare function isInArgsContext(navPath: string[]): boolean;
+/**
+ * Extracts the schema path of the field whose args are being navigated.
+ * E.g. ["query", "uiapi", "query", "Account", "@args", "where", "Name"]
+ *   → ["uiapi", "query", "Account"]
+ */
+export declare function getArgsFieldPath(navPath: string[]): string[];
+/**
+ * Extracts the input sub-path after @args.
+ * E.g. ["query", "uiapi", "query", "Account", "@args", "where", "Name"]
+ *   → ["where", "Name"]
+ */
+export declare function getInputSubPath(navPath: string[]): string[];
+/**
+ * For paths in the /query context, strips the "query" prefix and alias wrappers
+ * to produce a pure schema path. Stops at @args if present.
+ * E.g. ["query", "uiapi", "query", "Account"] → ["uiapi", "query", "Account"]
+ */
+export declare function queryNavToSchemaPath(navPath: string[]): string[];
+/**
+ * For paths in /variables, extracts the variable name (without $) and the
+ * sub-path into its input type.
+ */
+export declare function parseVariablePath(navPath: string[]): {
+    varName: string;
+    inputSubPath: string[];
+} | null;
+/**
+ * Incrementally sets a value deep inside a field argument's JSON structure.
+ * If inputPath is empty, sets the top-level arg directly.
+ * E.g. deepSetArg(session, path, "where", ["Name", "like"], '"Acme%"')
+ * results in node.args["where"] = '{"Name":{"like":"Acme%"}}'
+ */
+export declare function deepSetArg(session: QuerySession, schemaPath: string[], argName: string, inputPath: string[], value: string): void;
+/**
+ * Reads the current value at a nested path inside a field argument.
+ */
+export declare function deepGetArg(session: QuerySession, schemaPath: string[], argName: string, inputPath: string[]): unknown;
+/**
+ * Removes a value at a nested path inside a field argument.
+ */
+export declare function deepRemoveArg(session: QuerySession, schemaPath: string[], argName: string, inputPath: string[]): boolean;
+/**
+ * Incrementally sets a value deep inside a variable's runtime value.
+ * If inputPath is empty, sets the runtime value directly.
+ */
+export declare function deepSetVariableValue(session: QuerySession, varName: string, inputPath: string[], value: string): void;
+/**
+ * Appends a new empty object to a list-type arg array. Returns the new index.
+ */
+export declare function appendListElement(session: QuerySession, schemaPath: string[], argName: string, inputPath: string[]): number;
+/**
+ * Removes an element from a list-type arg by index and compacts remaining indices.
+ */
+export declare function removeListElement(session: QuerySession, schemaPath: string[], argName: string, inputPath: string[], index: number): boolean;
+export declare function selectLeaf(session: QuerySession, schemaPath: string[], alias?: string): FieldProjectionNode;
+export declare function removeSelectionAtPath(session: QuerySession, schemaPath: string[], selector?: string): boolean;
+export declare function findDescendantByAlias(session: QuerySession, parentId: string | null, alias: string): FieldProjectionNode | null;
+export declare function removeNodeByIdWithPrune(session: QuerySession, nodeId: string): boolean;
+export declare function addVariable(session: QuerySession, name: string, type: string, defaultValue?: string): void;
+export declare function setVariableRuntimeValue(session: QuerySession, name: string, runtimeValue: string): void;
+export declare function setVariableDefault(session: QuerySession, name: string, defaultValue: string | undefined): void;
+/**
+ * Finds all arg paths where a variable is referenced.
+ * Returns entries like `["Account", "where"] → "$filter"` for display.
+ */
+export declare function findVariableReferences(session: QuerySession, varName: string): {
+    fieldPath: string[];
+    argName: string;
+    subPath: string[];
+}[];
+export declare function removeVariable(session: QuerySession, name: string): boolean;
+/**
+ * Builds the variables map for query execution.
+ * Priority: ad-hoc overrides > session runtimeValue > defaultValue.
+ */
+export declare function buildRuntimeVariables(session: QuerySession, overrides?: Record<string, string>): Record<string, unknown>;
+export declare function saveSession(session: QuerySession): void;
+export declare function loadSession(id: string): QuerySession;
+export declare function listSessions(): {
+    id: string;
+    name?: string;
+    orgAlias: string;
+    operation: string;
+    createdAt: string;
+}[];
+export declare function deleteSession(id: string): boolean;