@xdelivered/emberflow 0.4.0 → 0.5.0

package/dist/server/index.js

@@ -16,6 +16,7 @@ import { loadInfrastructure } from './infrastructure.js';
 import { configPathFor, loadProjectConfig } from './projectConfig.js';
 import { buildApiStore, buildRegistries, requireProjectWhenExplicit } from './projectMode.js';
 import { nodesPayload } from './nodesPayload.js';
+import { getSourceFile } from './sourceNav.js';
 import { openBrowser } from './openBrowser.js';
 import { AgentRunManager, AgentStartError } from './agents/runManager.js';
 import { isGitRepo } from './agents/gitScope.js';
@@ -127,7 +128,7 @@ if (!project) {
             apiStore.save(flow, flow.id.includes('/') ? flow.id : `default/${flow.id}`);
     }
 }
-const agentRuns = new AgentRunManager(project ? project.root : projectDir, apiStore.dir, apiStore.pathOf.bind(apiStore), () => nodesPayload(validationRegistry).nodes.map(({ type, label, description }) => ({ type, label, description })), project?.language ?? 'typescript', 
+const agentRuns = new AgentRunManager(project ? project.root : projectDir, apiStore.dir, apiStore.pathOf.bind(apiStore), () => nodesPayload(validationRegistry, project ? project.root : process.cwd()).nodes.map(({ type, label, description }) => ({ type, label, description })), project?.language ?? 'typescript', 
 // Fresh per run: re-read emberflow/infrastructure.json so a scout that ran
 // earlier this session primes later prompts. Malformed → null (agent guesses).
 () => loadInfrastructure(project ? project.root : projectDir), 
@@ -212,7 +213,27 @@ api.post('/serving', (req, res) => {
     res.status(204).end();
 });
 api.get('/nodes', (_req, res) => {
-    res.json(nodesPayload(validationRegistry));
+    res.json(nodesPayload(validationRegistry, project ? project.root : process.cwd()));
+});
+// Whole-file source view + symbol table for the studio's source navigator.
+// Works in project mode AND no-project mode (root = cwd) — path guards in
+// sourceNav (isPathWithin, node_modules, secret basenames) bound what is
+// servable either way. 400s stay generic: the requested path is never echoed.
+api.get('/source-file', (req, res) => {
+    void (async () => {
+        const path = req.query.path;
+        if (typeof path !== 'string' || path.length === 0) {
+            res.status(400).json({ error: 'Query param path is required' });
+            return;
+        }
+        const root = project ? project.root : process.cwd();
+        const result = await getSourceFile(root, path);
+        if (!result.ok) {
+            res.status(result.status).json({ error: result.error });
+            return;
+        }
+        res.json(result.payload);
+    })();
 });
 // Validate a flow against the runner's LIVE registry (built-ins + project
 // nodes) so the CLI `validate` command doesn't false-reject ops that use

package/dist/server/nodesPayload.d.ts

@@ -5,10 +5,23 @@ import type { NodeDefinition, NodeRegistry } from '../src/engine/index.js';
  * implementation's toString() so the Inspector can show a node's code without
  * the browser bundling the implementation — the key to consumer nodes
  * appearing in the palette without a per-project browser build.
+ *
+ * `sourceRef` (repo-relative file + line of the register() call) is present
+ * only when registration provenance was captured AND the file lives inside
+ * the project root — the studio uses it to open the real source via
+ * GET /source-file. A captured ref OUTSIDE the root (Emberflow's own
+ * built-ins registered from the package) is flagged `builtin: true` instead:
+ * those files are never served (node_modules exposure rule), so the
+ * Inspector keeps the toString() view for them.
  */
 export interface NodeMetaPayload {
     nodes: Array<NodeDefinition & {
         source?: string;
+        sourceRef?: {
+            file: string;
+            line?: number;
+        };
+        builtin?: boolean;
     }>;
 }
-export declare function nodesPayload(registry: NodeRegistry): NodeMetaPayload;
+export declare function nodesPayload(registry: NodeRegistry, projectRoot?: string): NodeMetaPayload;

package/dist/server/nodesPayload.js

@@ -1,4 +1,6 @@
-export function nodesPayload(registry) {
+import { isAbsolute, relative, resolve } from 'node:path';
+export function nodesPayload(registry, projectRoot) {
+    const root = resolve(projectRoot ?? process.cwd());
     return {
         nodes: registry.list().map((definition) => {
             let source;
@@ -8,7 +10,18 @@ export function nodesPayload(registry) {
             catch {
                 source = undefined;
             }
-            return { ...definition, source };
+            const ref = registry.getSourceRef(definition.type);
+            if (!ref)
+                return { ...definition, source };
+            const rel = relative(root, resolve(root, ref.file));
+            const inside = rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+            if (!inside)
+                return { ...definition, source, builtin: true };
+            return {
+                ...definition,
+                source,
+                sourceRef: ref.line !== undefined ? { file: rel, line: ref.line } : { file: rel },
+            };
         }),
     };
 }

package/dist/server/projectMode.js

@@ -34,8 +34,11 @@ export function buildApiStore(project) {
     return new ApiStore(apisDir);
 }
 export function buildRegistries(project) {
-    const validation = createDefaultRegistry();
-    const execution = createDefaultRegistry();
+    // Server-side registries capture registration provenance (file:line of each
+    // register() call) so the studio can navigate to a node's real source.
+    // Browser registries never enable this — see createDefaultRegistry.
+    const validation = createDefaultRegistry(undefined, { captureSourceRefs: true });
+    const execution = createDefaultRegistry(undefined, { captureSourceRefs: true });
     if (project?.registerNodes) {
         project.registerNodes(validation);
         project.registerNodes(execution);

package/dist/server/sourceNav.d.ts

@@ -0,0 +1,77 @@
+import type * as TS from 'typescript';
+/**
+ * Source navigation for the studio's node-implementation view: serve a whole
+ * project file plus a flat symbol table (top-level declarations, imports with
+ * resolutions, re-exports) so the client can render identifiers as links and
+ * navigate file-by-file. One flat parse per file, mtime-cached; recursion
+ * happens client-side by fetching the next file — except re-export chains,
+ * which the server follows (bounded, cycle-safe) so an import through an
+ * index module resolves straight to the declaring file.
+ *
+ * TypeScript is loaded lazily on first use (`await import('typescript')`);
+ * when that fails the file is still served with `resolver: 'unavailable'`
+ * and empty symbols, and the studio shows unresolved-with-reason.
+ */
+export type Resolution = {
+    kind: 'project';
+    path: string;
+    line?: number;
+} | {
+    kind: 'external';
+    package: string;
+} | {
+    kind: 'builtin';
+} | {
+    kind: 'unresolved';
+    reason: string;
+};
+export interface SourceDeclaration {
+    name: string;
+    kind: 'fn' | 'const' | 'class' | 'other';
+    line: number;
+    endLine: number;
+    exported: boolean;
+}
+export interface SourceImport {
+    /** Imported name in the source module ('default', '*' for namespace, 'import()' for dynamic). */
+    name: string;
+    /** Local binding name in the served file ('' when there is none). */
+    local: string;
+    /** The specifier as written. */
+    from: string;
+    resolution: Resolution;
+}
+export interface SourceReexport {
+    name: string;
+    from: string;
+    resolution: Resolution;
+}
+export interface SourceFilePayload {
+    path: string;
+    content: string;
+    language: 'ts' | 'js';
+    /** Present (as 'unavailable') only when the typescript module could not be loaded. */
+    resolver?: 'unavailable';
+    symbols: {
+        declarations: SourceDeclaration[];
+        imports: SourceImport[];
+        reexports: SourceReexport[];
+    };
+}
+export type SourceFileResult = {
+    ok: true;
+    payload: SourceFilePayload;
+} | {
+    ok: false;
+    status: 400 | 404;
+    error: string;
+};
+export interface SourceNavOptions {
+    /** Test seam: overrides the lazy `import('typescript')` for this call only. */
+    tsLoader?: () => Promise<TsModule>;
+}
+type TsModule = typeof TS;
+/** Clears all sourceNav caches (parse, tsconfig, ts module) — tests only. */
+export declare function resetSourceNavCaches(): void;
+export declare function getSourceFile(projectRoot: string, relPath: string, opts?: SourceNavOptions): Promise<SourceFileResult>;
+export {};