@xdelivered/emberflow 0.2.0 → 0.5.0

package/server/index.ts

@@ -1,4 +1,5 @@
 import { existsSync, watch } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -9,6 +10,7 @@ import {
   mergeMocks,
   validateFlow,
   verifyArtifact,
+  type LogLine,
   type ScenarioDefinition,
   type WorkflowDefinition,
 } from '../src/engine';
@@ -30,10 +32,12 @@ import { loadInfrastructure } from './infrastructure';
 import { configPathFor, loadProjectConfig } from './projectConfig';
 import { buildApiStore, buildRegistries, requireProjectWhenExplicit } from './projectMode';
 import { nodesPayload } from './nodesPayload';
+import { getSourceFile } from './sourceNav';
 import { openBrowser } from './openBrowser';
 import { AgentRunManager, AgentStartError } from './agents/runManager';
+import { isGitRepo } from './agents/gitScope';
 import { isMountablePath } from './pathGuard';
-import { detectAgents } from './agents/detect';
+import { detectAgentsCached } from './agents/detect';
 import type { AgentEvent } from './agents/types';
 import type { AgentIntent } from './agents/prompt';
 import { ExpressAdapter } from './runtime/expressAdapter';
@@ -44,6 +48,7 @@ import { isPathWithin } from './pathSafety';
 import { attachCredential } from './authAttach';
 import { redactSecrets } from './redact';
 import { runScenarioSuiteFor, ScenarioTestUsageError } from './testRunner';
+import { checkForUpdate, isLinkedInstall, ownVersion, runNpmInstall } from './updateCheck';
 import { diagnoseOperation } from '../src/engine/diagnostics';
 import { seedParamDefaults } from './normalizeFlow';
 
@@ -155,11 +160,32 @@ const agentRuns = new AgentRunManager(
   project ? project.root : projectDir,
   apiStore.dir,
   apiStore.pathOf.bind(apiStore),
-  () => nodesPayload(validationRegistry).nodes.map(({ type, label, description }) => ({ type, label, description })),
+  () => 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),
+  // Runner-verified setup snapshot for guided-setup prompts: the same facts
+  // /setup-status reports, computed fresh at run start, so the agent starts
+  // from KNOWN state instead of probing for it.
+  () => {
+    const root = project ? project.root : process.cwd();
+    let envs = environmentsFile;
+    try {
+      envs = loadEnvironments(root);
+    } catch {
+      /* keep last good */
+    }
+    const ops = apiStore.list();
+    return {
+      gitRepo: isGitRepo(root),
+      skillsInstalled: skillInstalled(root, 'claude') || skillInstalled(root, 'codex'),
+      environmentsConfigured: envs.configured,
+      infrastructurePresent: readInfrastructure() !== null,
+      opCount: ops.length,
+      onlyHello: ops.length === 1 && ops[0]?.id === 'default/hello',
+    };
+  },
 );
 
 // Hot-reload agent-authored nodes: watch the project's config and rebuild the
@@ -228,7 +254,28 @@ api.post('/serving', (req: Request, res: Response) => {
 });
 
 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: Request, res: Response) => {
+  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
@@ -717,6 +764,8 @@ api.post('/runs', async (req: Request, res: Response) => {
       input: effectiveInput,
       mockRun,
       mocks: effectiveMocks,
+      // Step-mode runs get drill-in subflow stepping (see RunRegistry.step).
+      stepped: mode === 'step',
     }));
   } catch (err) {
     res.status(400).json({ error: err instanceof Error ? err.message : String(err) });
@@ -731,23 +780,101 @@ api.post('/runs', async (req: Request, res: Response) => {
   res.status(201).json({ runId });
 });
 
+// Run a single node in isolation (studio's "Run node" affordance). Executes the
+// node's implementation in-process against the resolved environment's
+// secrets/vars, honouring safe mode via resolveRunSafety, and redacts the
+// output through the same choke point runs use. Unknown type → 404. The studio
+// bundles no implementations, so this is the ONLY path to a lone node run.
+api.post('/node-run', async (req: Request, res: Response) => {
+  const { type, input, config, environment, safeMode, confirm } = req.body ?? {};
+  if (typeof type !== 'string' || type.length === 0) {
+    res.status(400).json({ error: 'Body must include a node "type"' });
+    return;
+  }
+  if (input !== undefined && (typeof input !== 'object' || input === null || Array.isArray(input))) {
+    res.status(400).json({ error: 'input must be a plain object' });
+    return;
+  }
+  if (config !== undefined && (typeof config !== 'object' || config === null || Array.isArray(config))) {
+    res.status(400).json({ error: 'config must be a plain object' });
+    return;
+  }
+  if (environment !== undefined && typeof environment !== 'string') {
+    res.status(400).json({ error: 'environment must be a string' });
+    return;
+  }
+  if (safeMode !== undefined && typeof safeMode !== 'boolean') {
+    res.status(400).json({ error: 'safeMode must be a boolean' });
+    return;
+  }
+  if (!runs.executionRegistry.has(type)) {
+    res.status(404).json({ error: `Unknown node type: ${type}` });
+    return;
+  }
+  const environmentName = environment ?? environmentsFile.defaultEnvironment;
+  const environmentDef = environmentsFile.environments[environmentName];
+  if (!environmentDef) {
+    res.status(400).json({ error: `Unknown environment: '${environmentName}'` });
+    return;
+  }
+  const safety = resolveRunSafety(environmentName, environmentDef, { safeMode, confirm });
+  if (!safety.ok) {
+    res.status(400).json({ error: safety.error });
+    return;
+  }
+
+  const { implementation } = runs.executionRegistry.get(type);
+  const runId = `node-run-${randomUUID().slice(0, 8)}`;
+  const logs: LogLine[] = [];
+  const log = (level: LogLine['level'], message: string): void => {
+    logs.push({ timestamp: new Date().toISOString(), level, runId, message });
+  };
+  const nodeInput = (input ?? {}) as Record<string, unknown>;
+
+  let result: { output?: unknown; error?: string; logs: LogLine[] };
+  try {
+    const output = await implementation({
+      input: nodeInput,
+      config: (config ?? {}) as Record<string, unknown>,
+      secrets: environmentDef.secrets,
+      vars: environmentDef.vars,
+      environment: environmentName,
+      safeMode: safety.safeMode,
+      runInput: nodeInput,
+      log,
+      // A node run in isolation has no flow context to resolve child workflows.
+      runSubflow: async () => ({
+        status: 'failed',
+        error: 'Subflow nodes cannot be run in isolation — run the whole operation instead',
+      }),
+    });
+    result = { output, logs };
+  } catch (err) {
+    result = { error: err instanceof Error ? err.message : String(err), logs };
+  }
+  // Redact secret values from the output AND captured logs before responding.
+  res.json(redactSecrets(result, environmentDef.secrets));
+});
+
 api.post('/runs/:id/step', async (req, res) => {
-  const handle = runs.get(req.params.id);
-  if (!handle) {
+  // Drill-aware composite step: stepping INTO a Subflow reports
+  // `entered: { workflowId, nodeId }`, completing the child reports
+  // `exited: true` (see RunRegistry.step). Plain steps report just `done`.
+  const result = await runs.step(req.params.id);
+  if (!result) {
     res.status(404).json({ error: `Unknown run: ${req.params.id}` });
     return;
   }
-  const more = await handle.step();
-  res.json({ done: !more });
+  res.json(result);
 });
 
 api.post('/runs/:id/cancel', (req, res) => {
-  const handle = runs.get(req.params.id);
-  if (!handle) {
+  // Drill-aware: a stepped run drilled into subflows also cancels every
+  // stacked child and unblocks the parent executions (see RunRegistry.cancel).
+  if (!runs.cancel(req.params.id)) {
     res.status(404).json({ error: `Unknown run: ${req.params.id}` });
     return;
   }
-  handle.cancel();
   res.status(204).end();
 });
 
@@ -773,7 +900,7 @@ api.get('/runs/:id/events', (req, res) => {
 });
 
 api.get('/agent/available', (_req: Request, res: Response) => {
-  res.json({ agents: detectAgents() });
+  res.json({ agents: detectAgentsCached() });
 });
 
 // First-run onboarding aggregate for the Welcome checklist (studio's
@@ -796,7 +923,10 @@ api.get('/setup-status', (_req: Request, res: Response) => {
   // A pristine project ships exactly the single `default/hello` example op.
   const onlyHello = ops.length === 1 && ops[0]?.id === 'default/hello';
   res.json({
-    agents: detectAgents(),
+    agents: detectAgentsCached(),
+    // Agent features snapshot changes with git (server/agents/runManager.ts);
+    // the checklist gates them on this. Same notion gitScope's isGitRepo uses.
+    git: { repo: isGitRepo(root) },
     environments: {
       configured: envs.configured,
       // The synthesized "local" fallback is "no environments yet" — report 0.
@@ -826,6 +956,53 @@ function skillInstalled(root: string, harness: 'claude' | 'codex'): boolean {
   );
 }
 
+// Package update notifier: the studio asks once per page load; checkForUpdate
+// caches registry hits for an hour and fails silent — an unreachable registry
+// (or a pre-publish package) just reports "no update".
+api.get('/update-status', async (_req: Request, res: Response) => {
+  const current = ownVersion() ?? '0.0.0';
+  const check = await checkForUpdate(current);
+  if (!check) {
+    res.json({ current, updateAvailable: false });
+    return;
+  }
+  res.json(check);
+});
+
+// One-click updater: npm-installs the latest package into the consumer
+// project. Single-flight — a second click while npm runs gets a 409, not a
+// second npm process fighting over node_modules.
+let updateInFlight = false;
+api.post('/update', async (_req: Request, res: Response) => {
+  if (!project) {
+    res.status(400).json({ ok: false, error: 'not a consumer project — no project is loaded to update' });
+    return;
+  }
+  if (isLinkedInstall(project.root)) {
+    res.status(400).json({
+      ok: false,
+      error:
+        'node_modules/@xdelivered/emberflow is a symlink (file:/npm-link dev setup) — refusing to npm install over it',
+    });
+    return;
+  }
+  if (updateInFlight) {
+    res.status(409).json({ ok: false, error: 'update already running' });
+    return;
+  }
+  updateInFlight = true;
+  try {
+    const result = await runNpmInstall(project.root);
+    if (result.ok) {
+      res.json({ ok: true, restartRequired: true });
+    } else {
+      res.status(500).json({ ok: false, error: result.error });
+    }
+  } finally {
+    updateInFlight = false;
+  }
+});
+
 /** The /setup-status `infrastructure` field: presence + a shallow summary. */
 function infraStatus(): { present: boolean; scannedAt?: string; itemCount?: number } {
   const manifest = readInfrastructure();
@@ -855,11 +1032,12 @@ api.post('/agent', (req: Request, res: Response) => {
     intent.action !== 'setup-auth' &&
     intent.action !== 'setup-environments' &&
     intent.action !== 'scout-infrastructure' &&
+    intent.action !== 'guided-setup' &&
     intent.action !== 'cover-operation' &&
     intent.action !== 'ask'
   ) {
     res.status(400).json({
-      error: `Unsupported intent.action: ${intent.action}. Must be one of new-scenario, edit-node, edit-flow, new-operation, setup-auth, setup-environments, scout-infrastructure, cover-operation, ask.`,
+      error: `Unsupported intent.action: ${intent.action}. Must be one of new-scenario, edit-node, edit-flow, new-operation, setup-auth, setup-environments, scout-infrastructure, guided-setup, cover-operation, ask.`,
     });
     return;
   }
@@ -873,7 +1051,11 @@ api.post('/agent', (req: Request, res: Response) => {
       res.status(400).json({ error: 'Body must include intent: { action: "setup-auth", environment, instruction }' });
       return;
     }
-  } else if (intent.action === 'setup-environments' || intent.action === 'scout-infrastructure') {
+  } else if (
+    intent.action === 'setup-environments' ||
+    intent.action === 'scout-infrastructure' ||
+    intent.action === 'guided-setup'
+  ) {
     // instruction alone is required, already validated above; no flowId/environment needed.
   } else if (intent.action === 'ask') {
     if (intent.flowId !== undefined && typeof intent.flowId !== 'string') {
@@ -975,7 +1157,7 @@ const operationRunEnv = {
 // operation whose http.path collides with one of these would silently never
 // be reached (the internal route, registered first, always wins) — guarded
 // against below rather than left as a silent trap.
-const RESERVED_ROOT_PATHS = ['/healthz', '/nodes', '/samples', '/environments', '/workflows', '/runs', '/agent', '/serving'];
+const RESERVED_ROOT_PATHS = ['/healthz', '/nodes', '/samples', '/environments', '/workflows', '/runs', '/node-run', '/agent', '/serving'];
 
 function collidesWithReservedPath(path: string): boolean {
   return RESERVED_ROOT_PATHS.some((reserved) => path === reserved || path.startsWith(`${reserved}/`));
@@ -1097,6 +1279,22 @@ if (serveStudio) {
   }
 }
 
+// Agent CLIs and node executions must not outlive the runner: agents are
+// spawned detached (their own process group), so without this a killed runner
+// leaves an orphaned agent editing the project — and possibly writing files
+// long after the studio is gone (observed in the wild). Cancel everything,
+// then exit.
+for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+  process.on(signal, () => {
+    try {
+      agentRuns.shutdown();
+      runs.shutdown();
+    } finally {
+      process.exit(0);
+    }
+  });
+}
+
 app.listen(PORT, HOST, () => {
   console.log(`[emberflow-runner] listening on http://${HOST}:${PORT} — ${runs.nodeCount} nodes registered`);
   if (serveStudio) {

package/server/nodeRun.test.ts

@@ -0,0 +1,189 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// Verifies POST /node-run: the studio's "Run node" affordance runs a single
+// node in-process on the runner (execution moved server-side; the studio bundles
+// no node implementations). Boots the actual runner subprocess against a scratch
+// project dir, mirroring runsAuth.test.ts / apiMount.test.ts.
+
+let proc: ChildProcess;
+const PORT = 8155;
+const base = `http://127.0.0.1:${PORT}`;
+let projectDir: string;
+
+async function waitHealthy(url: string, tries = 40): Promise<void> {
+  for (let i = 0; i < tries; i++) {
+    try {
+      if ((await fetch(url)).ok) return;
+    } catch {
+      /* not up yet */
+    }
+    await new Promise((r) => setTimeout(r, 150));
+  }
+  throw new Error('runner did not become healthy');
+}
+
+function bootRunner(port: number, env: Record<string, string | undefined>): ChildProcess {
+  return spawn('npx', ['tsx', 'server/index.ts'], {
+    env: { ...process.env, EMBERFLOW_RUNNER_PORT: String(port), ...env },
+    stdio: 'ignore',
+  });
+}
+
+async function nodeRun(body: unknown): Promise<{ status: number; json: any }> {
+  const res = await fetch(`${base}/api/node-run`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  return { status: res.status, json: await res.json().catch(() => undefined) };
+}
+
+// Fixture secret value — looks like a real credential to redaction logic
+// (>= 6 chars) but is clearly a test fixture, never a live secret.
+const FIXTURE_SECRET = 'fixture-secret-123';
+
+beforeAll(async () => {
+  projectDir = mkdtempSync(join(tmpdir(), 'noderun-'));
+  mkdirSync(join(projectDir, 'emberflow', 'apis', 'default'), { recursive: true });
+  writeFileSync(
+    join(projectDir, 'emberflow.config.mjs'),
+    `export default {
+  registerNodes(registry) {
+    // Embeds a secret in its output AND in a log line — exercises redaction
+    // across both response fields.
+    registry.register(
+      { type: 'EchoSecret', label: 'Echo Secret', traceKind: 'pure', inputSchema: { fields: [] } },
+      async (ctx) => {
+        ctx.log('info', \`fetched key \${ctx.secrets.API_KEY}\`);
+        return { message: \`key is \${ctx.secrets.API_KEY}\` };
+      },
+    );
+    // Throws with the secret embedded in the error message — exercises
+    // redaction on the error path.
+    registry.register(
+      { type: 'ThrowSecret', label: 'Throw Secret', traceKind: 'pure', inputSchema: { fields: [] } },
+      async (ctx) => {
+        throw new Error(\`boom \${ctx.secrets.API_KEY}\`);
+      },
+    );
+    // Echoes ctx.safeMode so tests can observe the resolved safety mode.
+    registry.register(
+      { type: 'EchoSafeMode', label: 'Echo Safe Mode', traceKind: 'pure', inputSchema: { fields: [] } },
+      async (ctx) => ({ safeMode: ctx.safeMode }),
+    );
+  },
+};\n`,
+  );
+  writeFileSync(
+    join(projectDir, 'emberflow.environments.json'),
+    JSON.stringify({
+      defaultEnvironment: 'local',
+      environments: {
+        local: { vars: {}, secrets: {} },
+        leaky: { vars: {}, secrets: { API_KEY: FIXTURE_SECRET } },
+        prod: { protected: true, vars: {}, secrets: {} },
+      },
+    }),
+  );
+
+  proc = bootRunner(PORT, { EMBERFLOW_PROJECT: projectDir });
+  await waitHealthy(`${base}/healthz`);
+}, 20_000);
+
+afterAll(() => {
+  proc?.kill();
+  if (projectDir) rmSync(projectDir, { recursive: true, force: true });
+});
+
+describe('POST /node-run', () => {
+  it('runs a single built-in node in-process and returns its output + logs', async () => {
+    // CheckPlan is a pure built-in: input.user.plan -> { plan, features } + a log.
+    const { status, json } = await nodeRun({
+      type: 'CheckPlan',
+      input: { user: { plan: 'pro' } },
+    });
+    expect(status).toBe(200);
+    expect(json.output).toEqual({ plan: 'pro', features: ['sso', 'audit-log', 'priority-support'] });
+    expect(json.error).toBeUndefined();
+    expect(json.logs.some((l: { message: string }) => l.message.includes('pro'))).toBe(true);
+  });
+
+  it('404s for an unknown node type', async () => {
+    const { status, json } = await nodeRun({ type: 'NoSuchNode', input: {} });
+    expect(status).toBe(404);
+    expect(json.error).toContain('Unknown node type');
+  });
+
+  it('400s when the body omits a node type', async () => {
+    const { status } = await nodeRun({ input: {} });
+    expect(status).toBe(400);
+  });
+
+  it('400s for an unknown environment', async () => {
+    const { status, json } = await nodeRun({
+      type: 'CheckPlan',
+      input: { user: {} },
+      environment: 'ghost',
+    });
+    expect(status).toBe(400);
+    expect(json.error).toContain('Unknown environment');
+  });
+});
+
+describe('POST /node-run redacts secrets at the boundary', () => {
+  it('redacts a secret value embedded in the output and logs, never leaking the raw value', async () => {
+    const { status, json } = await nodeRun({ type: 'EchoSecret', input: {}, environment: 'leaky' });
+    expect(status).toBe(200);
+    expect(json.error).toBeUndefined();
+
+    expect(json.output.message).toContain('«secret:API_KEY»');
+    expect(json.output.message).not.toContain(FIXTURE_SECRET);
+
+    const logMessages = json.logs.map((l: { message: string }) => l.message).join('\n');
+    expect(logMessages).toContain('«secret:API_KEY»');
+    expect(logMessages).not.toContain(FIXTURE_SECRET);
+  });
+
+  it('redacts a secret value embedded in a thrown error message', async () => {
+    const { status, json } = await nodeRun({ type: 'ThrowSecret', input: {}, environment: 'leaky' });
+    expect(status).toBe(200);
+    expect(json.output).toBeUndefined();
+    expect(json.error).toContain('«secret:API_KEY»');
+    expect(json.error).not.toContain(FIXTURE_SECRET);
+  });
+});
+
+describe('POST /node-run gates unsafe runs on protected environments', () => {
+  it('400s an explicit safeMode:false on a protected environment without a matching confirm', async () => {
+    const { status, json } = await nodeRun({
+      type: 'EchoSafeMode',
+      input: {},
+      environment: 'prod',
+      safeMode: false,
+    });
+    expect(status).toBe(400);
+    expect(json.error).toContain("unsafe run on protected environment 'prod' requires confirm");
+  });
+
+  it('accepts safeMode:false on a protected environment with the matching confirm, and the node observes it', async () => {
+    const { status, json } = await nodeRun({
+      type: 'EchoSafeMode',
+      input: {},
+      environment: 'prod',
+      safeMode: false,
+      confirm: 'prod',
+    });
+    expect(status).toBe(200);
+    expect(json.output).toEqual({ safeMode: false });
+  });
+
+  it('defaults to safeMode:true on a protected environment when unspecified', async () => {
+    const { status, json } = await nodeRun({ type: 'EchoSafeMode', input: {}, environment: 'prod' });
+    expect(status).toBe(200);
+    expect(json.output).toEqual({ safeMode: true });
+  });
+});

package/server/nodesPayload.test.ts

@@ -26,4 +26,42 @@ describe('nodesPayload', () => {
     expect(round.nodes[0].type).toBe('A');
     expect(typeof round.nodes[0].source).toBe('string');
   });
+
+  it('adds a repo-relative sourceRef when the captured file is inside the project root', () => {
+    const r = new NodeRegistry();
+    r.register({ type: 'X', label: 'X' }, async () => ({}), {
+      sourceRef: { file: '/proj/nodes/logic.mjs', line: 12 },
+    });
+    const node = nodesPayload(r, '/proj').nodes[0];
+    expect(node.sourceRef).toEqual({ file: 'nodes/logic.mjs', line: 12 });
+    expect(node.builtin).toBeUndefined();
+  });
+
+  it('flags builtin: true when the sourceRef points outside the project root', () => {
+    const r = new NodeRegistry();
+    r.register({ type: 'Y', label: 'Y' }, async () => ({}), {
+      sourceRef: { file: '/somewhere/else/pkg/node.ts', line: 3 },
+    });
+    const node = nodesPayload(r, '/proj').nodes[0];
+    expect(node.builtin).toBe(true);
+    expect(node.sourceRef).toBeUndefined();
+  });
+
+  it('omits sourceRef and builtin entirely when nothing was captured', () => {
+    const r = new NodeRegistry();
+    r.register({ type: 'Z', label: 'Z' }, async () => ({}));
+    const node = nodesPayload(r, '/proj').nodes[0];
+    expect('sourceRef' in node).toBe(false);
+    expect('builtin' in node).toBe(false);
+  });
+
+  it('preserves the source (toString) field alongside sourceRef', () => {
+    const r = new NodeRegistry();
+    r.register({ type: 'W', label: 'W' }, async () => ({ shout: true }), {
+      sourceRef: { file: '/proj/w.mjs', line: 1 },
+    });
+    const node = nodesPayload(r, '/proj').nodes[0];
+    expect(node.source).toContain('shout');
+    expect(node.sourceRef).toEqual({ file: 'w.mjs', line: 1 });
+  });
 });

package/server/nodesPayload.ts

@@ -1,3 +1,4 @@
+import { isAbsolute, relative, resolve } from 'node:path';
 import type { NodeDefinition, NodeRegistry } from '../src/engine';
 
 /**
@@ -6,12 +7,27 @@ import type { NodeDefinition, NodeRegistry } from '../src/engine';
  * 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 }>;
+  nodes: Array<
+    NodeDefinition & {
+      source?: string;
+      sourceRef?: { file: string; line?: number };
+      builtin?: boolean;
+    }
+  >;
 }
 
-export function nodesPayload(registry: NodeRegistry): NodeMetaPayload {
+export function nodesPayload(registry: NodeRegistry, projectRoot?: string): NodeMetaPayload {
+  const root = resolve(projectRoot ?? process.cwd());
   return {
     nodes: registry.list().map((definition) => {
       let source: string | undefined;
@@ -20,7 +36,16 @@ export function nodesPayload(registry: NodeRegistry): NodeMetaPayload {
       } 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/server/projectMode.ts

@@ -49,8 +49,11 @@ export function buildRegistries(project: ProjectConfig | null): {
   validation: NodeRegistry;
   execution: NodeRegistry;
 } {
-  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);