@vgai/sdk 0.4.0-canary.20260715.0

package/src/editor/source-location-operations.ts

@@ -0,0 +1,106 @@
+/**
+ * `editor.sourceLocation.lookup` (B3, §8 B3 "source-location lookup for
+ * inspected React output ... READ-ONLY, must NOT rewrite JSX").
+ *
+ * Genuinely wired, real, and structurally read-only: it only ever GETs
+ * `/__ui-source/index` (the OID -> {file,line,col,component,tag} map built
+ * by `vite-plugin-ui-oid.ts`'s `OidStore`) and looks up one entry. It never
+ * calls any of that plugin's write endpoints (`/__ui-source/write|css|text|
+ * prop|struct|struct-many|restore`) — there is no code path in this file
+ * that could send one, which is what "must NOT rewrite JSX" means in
+ * practice here (not a runtime permission check, a STRUCTURAL guarantee:
+ * the transport interface this op is given, `EditorTransport.getSourceIndex`,
+ * has no write method to call).
+ */
+
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { defineOperation, type OperationRegistry } from '../registry.js';
+import {
+  EDITOR_NOT_RUNNING_ERROR,
+  EDITOR_READ_TIMEOUT_MS,
+  getTransport,
+  resolveEditorSession,
+  withTimeout,
+} from './transport.js';
+
+const SOURCE_INDEX_UNAVAILABLE_ERROR = {
+  code: 'SOURCE_INDEX_UNAVAILABLE',
+  summary: 'A session is connected but did not answer the source-location index read in time.',
+  data: z.object({}),
+} as const;
+
+const SOURCE_LOCATION_NOT_FOUND_ERROR = {
+  code: 'SOURCE_LOCATION_NOT_FOUND',
+  summary: 'No source-location entry is registered for the given oid.',
+  data: z.object({ oid: z.string() }),
+} as const;
+
+const EditorSourceLocationLookupInput = z
+  .object({ oid: z.string().describe('The data-oid identifier of an inspected React element.') })
+  .describe("Map an inspected React element's oid to its source location. Read-only.");
+
+const EditorSourceLocationLookupResult = z
+  .object({
+    file: z.string().describe('Absolute source file path.'),
+    line: z.number().describe('1-based line number.'),
+    col: z.number().describe('0-based column.'),
+    component: z.string().nullable().describe('Enclosing component name, or null.'),
+    tag: z.string().describe('JSX tag name at this location.'),
+  })
+  .describe('Source location for the given oid. Never mutates anything.');
+
+export const editorSourceLocationLookup = defineOperation({
+  name: 'editor.sourceLocation.lookup',
+  summary: "Map an inspected React element's oid to its exact component/source location.",
+  description:
+    'Reads GET /__ui-source/index (the live OID -> source-location map) and looks up one entry. ' +
+    'Read-only by construction: this op only ever calls a GET-index transport method, never any ' +
+    'of the write endpoints that same plugin also serves.',
+  input: EditorSourceLocationLookupInput,
+  result: EditorSourceLocationLookupResult,
+  errors: [
+    EDITOR_NOT_RUNNING_ERROR,
+    SOURCE_INDEX_UNAVAILABLE_ERROR,
+    SOURCE_LOCATION_NOT_FOUND_ERROR,
+  ],
+  requires: { editor: true },
+  host: 'editor-browser',
+  mutates: false,
+  supportsDryRun: false,
+  permission: {
+    risk: 'read',
+    summary: 'Reads the live OID -> source-location index only; never writes source.',
+  },
+  async impl(input, ctx) {
+    const transport = getTransport(ctx);
+    const session = await resolveEditorSession(ctx, transport);
+    const index = await withTimeout(
+      transport.getSourceIndex(session, EDITOR_READ_TIMEOUT_MS),
+      EDITOR_READ_TIMEOUT_MS,
+      'editor.sourceLocation.lookup',
+    ).catch(() => undefined);
+    if (!index) {
+      throw new OperationError(
+        'SOURCE_INDEX_UNAVAILABLE',
+        'The connected editor session did not answer the source-location index read in time.',
+        {},
+      );
+    }
+    const entry = index[input.oid];
+    if (!entry) {
+      throw new OperationError(
+        'SOURCE_LOCATION_NOT_FOUND',
+        `No source location for oid "${input.oid}".`,
+        {
+          oid: input.oid,
+        },
+      );
+    }
+    return entry;
+  },
+});
+
+export function registerSourceLocationOperations(registry: OperationRegistry): void {
+  registry.register(editorSourceLocationLookup);
+}