@xdelivered/emberflow 0.4.0 → 0.5.0

package/src/engine/registry.ts

@@ -5,15 +5,98 @@ export interface RegisteredNode {
   implementation: NodeImplementation;
 }
 
+/** Where a node was registered from: absolute file path + 1-based line of the register() call. */
+export interface SourceRef {
+  file: string;
+  line?: number;
+}
+
+export interface RegisterOptions {
+  /** Explicit provenance escape hatch — wins over automatic capture. */
+  sourceRef?: SourceRef;
+}
+
+/**
+ * V8 stack-frame shape (structural — this module must stay browser-safe, so
+ * no @types/node CallSite import).
+ */
+interface V8CallSite {
+  getFileName?: () => string | null | undefined;
+  getLineNumber?: () => number | null | undefined;
+}
+
+/**
+ * Read the CALLER's file:line via a one-frame V8 stack capture.
+ * `Error.prepareStackTrace` is swapped for the duration of a single `new
+ * Error()` and restored in `finally`, so source-map hooks installed by
+ * tsx/vitest are back in place immediately. Frames arrive either as
+ * `file:///abs/path.ts` URLs (ESM) or plain absolute paths (CJS/transpilers);
+ * both normalize to a plain path. Returns undefined on any non-V8 runtime or
+ * anonymous/eval frames — capture is best-effort by design.
+ */
+function captureCallerSourceRef(skip: (...args: never[]) => unknown): SourceRef | undefined {
+  if (typeof Error.captureStackTrace !== 'function') return undefined;
+  const original = Error.prepareStackTrace;
+  try {
+    Error.prepareStackTrace = (_err, frames) => frames;
+    const holder: { stack?: unknown } = {};
+    Error.captureStackTrace(holder as Error, skip);
+    const frames = holder.stack;
+    if (!Array.isArray(frames) || frames.length === 0) return undefined;
+    const frame = frames[0] as V8CallSite;
+    const raw = typeof frame.getFileName === 'function' ? frame.getFileName() : undefined;
+    if (typeof raw !== 'string' || raw.length === 0) return undefined;
+    const lineRaw = typeof frame.getLineNumber === 'function' ? frame.getLineNumber() : undefined;
+    const line = typeof lineRaw === 'number' && lineRaw > 0 ? lineRaw : undefined;
+    let file = raw;
+    if (file.startsWith('file://')) {
+      // No node:url here (browser-safe module): URL parsing covers the
+      // file:///abs/path form these frames take on POSIX platforms.
+      try {
+        file = decodeURIComponent(new URL(file).pathname);
+      } catch {
+        return undefined;
+      }
+    }
+    // Loaders (vite-node hot imports) may suffix ?t=... cache-busters.
+    const q = file.indexOf('?');
+    if (q !== -1) file = file.slice(0, q);
+    return line !== undefined ? { file, line } : { file };
+  } catch {
+    return undefined;
+  } finally {
+    Error.prepareStackTrace = original;
+  }
+}
+
 export class NodeRegistry {
   nodes = new Map<string, RegisteredNode>();
   sources = new Map<string, string>();
+  /** Registration provenance per node type. Populated only when capture is on or opts.sourceRef given. */
+  sourceRefs = new Map<string, SourceRef>();
+  /** Types the RUNNER flagged builtin (registered from the package, not the project). */
+  builtinTypes = new Set<string>();
+  /** Automatic caller capture is opt-in (server registries only) so browser registries never pay/leak. */
+  private captureSourceRefs: boolean;
+
+  constructor(opts?: { captureSourceRefs?: boolean }) {
+    this.captureSourceRefs = opts?.captureSourceRefs ?? false;
+  }
 
-  register(definition: NodeDefinition, implementation: NodeImplementation): void {
+  register(definition: NodeDefinition, implementation: NodeImplementation, opts?: RegisterOptions): void {
     if (this.nodes.has(definition.type)) {
       throw new Error(`Node type already registered: ${definition.type}`);
     }
     this.nodes.set(definition.type, { definition, implementation });
+    const ref =
+      opts?.sourceRef ??
+      (this.captureSourceRefs ? captureCallerSourceRef(this.register) : undefined);
+    if (ref) this.sourceRefs.set(definition.type, ref);
+  }
+
+  /** Where `type` was registered from, when known. */
+  getSourceRef(type: string): SourceRef | undefined {
+    return this.sourceRefs.get(type);
   }
 
   get(type: string): RegisteredNode {
@@ -36,6 +119,13 @@ export class NodeRegistry {
   adopt(other: NodeRegistry): void {
     this.nodes = other.nodes;
     this.sources = other.sources;
+    this.sourceRefs = other.sourceRefs;
+    this.builtinTypes = other.builtinTypes;
+  }
+
+  /** Whether the runner flagged `type` as a package built-in (no servable source file). */
+  isBuiltin(type: string): boolean {
+    return this.builtinTypes.has(type);
   }
 
   list(): NodeDefinition[] {
@@ -47,7 +137,16 @@ export class NodeRegistry {
    * implementation is a stub that fails loudly if browser-executed — such
    * nodes run on the server. Never overwrites a real registration.
    */
-  registerDefinition(definition: NodeDefinition, source?: string): void {
+  registerDefinition(
+    definition: NodeDefinition,
+    source?: string,
+    opts?: { sourceRef?: SourceRef; builtin?: boolean },
+  ): void {
+    // Provenance is recorded even for already-registered types: the studio's
+    // bundled built-ins are real registrations, and the runner's builtin flag
+    // (or a project sourceRef shadowing one) must still land on them.
+    if (opts?.sourceRef) this.sourceRefs.set(definition.type, opts.sourceRef);
+    if (opts?.builtin) this.builtinTypes.add(definition.type);
     if (this.nodes.has(definition.type)) return;
     this.nodes.set(definition.type, {
       definition,
@@ -75,6 +174,8 @@ export class NodeRegistry {
     const next = new NodeRegistry();
     next.nodes = this.nodes;
     next.sources = this.sources;
+    next.sourceRefs = this.sourceRefs;
+    next.builtinTypes = this.builtinTypes;
     return next;
   }
 }

package/src/nodes/index.ts

@@ -8,9 +8,16 @@ import { registerPradarNodesModule } from './pradar';
 import { registerResponseNodes } from './response';
 import { registerRequireAuthNode } from './requireAuth';
 
-/** All built-in nodes: login examples, Open-Meteo weather, anomaly-detection API, EV charging demo, HTTP Response, requireAuth. */
-export function createDefaultRegistry(delayMs?: number): NodeRegistry {
-  const registry = createLoginRegistry(delayMs);
+/**
+ * All built-in nodes: login examples, Open-Meteo weather, anomaly-detection API, EV charging demo, HTTP Response, requireAuth.
+ * `opts.captureSourceRefs` is threaded from SERVER callers only (buildRegistries)
+ * — this function is shared with the browser bundle, where capture stays off.
+ */
+export function createDefaultRegistry(
+  delayMs?: number,
+  opts?: { captureSourceRefs?: boolean },
+): NodeRegistry {
+  const registry = createLoginRegistry(delayMs, opts);
   registerWeatherNodes(registry);
   registerAnomalyNodes(registry);
   registerFlowControlNodes(registry);

package/src/nodes/login.ts

@@ -12,8 +12,11 @@ function usernamePart(userId: string): string {
  * `delayMs` is injected into every implementation via `await sleep(delayMs)`
  * so tests can run with no delay by passing `0`.
  */
-export function createLoginRegistry(delayMs = 300): NodeRegistry {
-  const registry = new NodeRegistry();
+export function createLoginRegistry(
+  delayMs = 300,
+  opts?: { captureSourceRefs?: boolean },
+): NodeRegistry {
+  const registry = new NodeRegistry(opts);
 
   registry.register(
     {

package/src/store/builderStore.ts

@@ -994,8 +994,8 @@ export const useBuilderStore = create<BuilderState>((set, get) => {
       if (meta.length === 0) return;
       const registry = get().registry;
       for (const m of meta) {
-        const { source, ...definition } = m;
-        registry.registerDefinition(definition, source);
+        const { source, sourceRef, builtin, ...definition } = m;
+        registry.registerDefinition(definition, source, { sourceRef, builtin });
       }
       // Force palette/inspector consumers to re-read the registry: a new
       // top-level reference (Zustand uses Object.is) sharing the same node data.

package/src/store/nodeMeta.ts

@@ -1,7 +1,15 @@
 import type { NodeDefinition } from '../engine';
 
-/** A runner node definition plus its implementation source (for display). */
-export type NodeMeta = NodeDefinition & { source?: string };
+/**
+ * A runner node definition plus its implementation source (for display) and
+ * provenance: `sourceRef` (repo-relative registering file + line) when the
+ * node is project-owned, `builtin: true` when registered from the package.
+ */
+export type NodeMeta = NodeDefinition & {
+  source?: string;
+  sourceRef?: { file: string; line?: number };
+  builtin?: boolean;
+};
 
 /**
  * Fetch the runner's node metadata (GET /api/nodes, same-origin via the

package/src/store/sourceNavClient.ts

@@ -0,0 +1,48 @@
+/**
+ * Client for the runner's source navigator (GET /source-file), reached through
+ * the Vite proxy at /api → 127.0.0.1:8092, same-origin as setupClient.ts.
+ * Powers the Inspector's source-reference navigation (SourceNavigator).
+ *
+ * Types are imported TYPE-ONLY from server/sourceNav.ts — erased at build, so
+ * the browser bundle never pulls server code, and the shapes can't drift.
+ */
+import type { SourceFilePayload } from '../../server/sourceNav';
+
+export type {
+  SourceFilePayload,
+  SourceDeclaration,
+  SourceImport,
+  SourceReexport,
+  Resolution,
+} from '../../server/sourceNav';
+
+/** A fetch outcome the navigator can render either way — payload or error text. */
+export type SourceFileFetchResult =
+  | { ok: true; payload: SourceFilePayload }
+  | { ok: false; error: string };
+
+const BASE = '/api';
+
+/**
+ * GET /source-file?path=<repo-relative>. Never throws — errors come back as
+ * `{ok:false}` with status-aware text: 400 → denied, 404 → missing, network
+ * failure → runner unreachable.
+ */
+export async function fetchSourceFile(path: string): Promise<SourceFileFetchResult> {
+  try {
+    const response = await fetch(`${BASE}/source-file?${new URLSearchParams({ path })}`);
+    if (response.ok) {
+      return { ok: true, payload: (await response.json()) as SourceFilePayload };
+    }
+    const body = (await response.json().catch(() => ({}))) as { error?: string };
+    if (response.status === 400) {
+      return { ok: false, error: `Access denied: ${body.error ?? 'path not servable'}` };
+    }
+    if (response.status === 404) {
+      return { ok: false, error: `File not found: ${path}` };
+    }
+    return { ok: false, error: body.error ?? `Source fetch failed (HTTP ${response.status})` };
+  } catch {
+    return { ok: false, error: 'Runner unreachable — start the runner to view source' };
+  }
+}