@xdelivered/emberflow 0.2.0 → 0.5.0

package/dist/server/index.js

@@ -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';
@@ -15,10 +16,12 @@ 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';
 import { isMountablePath } from './pathGuard.js';
-import { detectAgents } from './agents/detect.js';
+import { detectAgentsCached } from './agents/detect.js';
 import { ExpressAdapter } from './runtime/expressAdapter.js';
 import { makeOperationHandler } from './httpOperations.js';
 import { mockResponseFor } from './mockHandler.js';
@@ -27,6 +30,7 @@ import { isPathWithin } from './pathSafety.js';
 import { attachCredential } from './authAttach.js';
 import { redactSecrets } from './redact.js';
 import { runScenarioSuiteFor, ScenarioTestUsageError } from './testRunner.js';
+import { checkForUpdate, isLinkedInstall, ownVersion, runNpmInstall } from './updateCheck.js';
 import { diagnoseOperation } from '../src/engine/diagnostics.js';
 import { seedParamDefaults } from './normalizeFlow.js';
 const PORT = Number(process.env.EMBERFLOW_RUNNER_PORT ?? 8092);
@@ -124,10 +128,32 @@ 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));
+() => 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
 // node registries IN-PROCESS (no process restart), so registering a node in
 // `registerNodes` takes effect live. Critically, this survives an in-flight
@@ -187,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
@@ -660,6 +706,8 @@ api.post('/runs', async (req, res) => {
             input: effectiveInput,
             mockRun,
             mocks: effectiveMocks,
+            // Step-mode runs get drill-in subflow stepping (see RunRegistry.step).
+            stepped: mode === 'step',
         }));
     }
     catch (err) {
@@ -673,22 +721,98 @@ api.post('/runs', async (req, res) => {
     }
     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, res) => {
+    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 = [];
+    const log = (level, message) => {
+        logs.push({ timestamp: new Date().toISOString(), level, runId, message });
+    };
+    const nodeInput = (input ?? {});
+    let result;
+    try {
+        const output = await implementation({
+            input: nodeInput,
+            config: (config ?? {}),
+            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();
 });
 api.get('/runs/:id/events', (req, res) => {
@@ -709,7 +833,7 @@ api.get('/runs/:id/events', (req, res) => {
     unsubscribe = runs.subscribe(runId, listener);
 });
 api.get('/agent/available', (_req, res) => {
-    res.json({ agents: detectAgents() });
+    res.json({ agents: detectAgentsCached() });
 });
 // First-run onboarding aggregate for the Welcome checklist (studio's
 // WelcomeDialog). Recomputed per request (cheap; mirrors /environments'
@@ -732,7 +856,10 @@ api.get('/setup-status', (_req, res) => {
     // 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.
@@ -758,6 +885,52 @@ api.get('/setup-status', (_req, res) => {
 function skillInstalled(root, harness) {
     return [root, homedir()].some((base) => existsSync(join(base, `.${harness}`, 'skills', 'emberflow-basics', 'SKILL.md')));
 }
+// 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, res) => {
+    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, res) => {
+    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() {
     const manifest = readInfrastructure();
@@ -786,10 +959,11 @@ api.post('/agent', (req, res) => {
         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;
     }
@@ -805,7 +979,9 @@ api.post('/agent', (req, res) => {
             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') {
@@ -899,7 +1075,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) {
     return RESERVED_ROOT_PATHS.some((reserved) => path === reserved || path.startsWith(`${reserved}/`));
 }
@@ -1007,6 +1183,22 @@ if (serveStudio) {
         console.warn(`[runner] EMBERFLOW_SERVE_STUDIO=1 but no studio-dist found near ${here} — run \`npm run build:studio\``);
     }
 }
+// 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']) {
+    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/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/runRegistry.d.ts

@@ -1,8 +1,12 @@
 import type { LogLine, NodeExecutionSample, NodeRunState, WorkflowDefinition, WorkflowRun } from '../src/engine/index.js';
 import { InMemoryTraceSink, type FlowRun, type NodeRegistry } from '../src/engine/index.js';
 /** SSE-shaped events, mirroring ExecutorEvents 1:1. */
-export type RunEvent = {
+export type RunEvent = 
+/** `workflowId` is the flow the node belongs to: the root flow for the
+ *  run's own nodes, the CHILD flow's id for a stepped subflow's nodes. */
+{
     type: 'nodeState';
+    workflowId: string;
     nodeId: string;
     state: NodeRunState;
 } | {
@@ -18,6 +22,17 @@ export type RunEvent = {
     };
 };
 type Listener = (event: RunEvent) => void;
+/** Result of one composite step on a stepped run (see RunRegistry.step). */
+export interface StepResult {
+    done: boolean;
+    /** Set when this step drove execution INTO a subflow child. */
+    entered?: {
+        workflowId: string;
+        nodeId: string;
+    };
+    /** Set when this step completed the deepest child and popped back out. */
+    exited?: true;
+}
 /** Manages live runs: buffers engine events per run and fans them out to SSE subscribers. */
 export declare class RunRegistry {
     private readonly loadFlow?;
@@ -62,10 +77,46 @@ export declare class RunRegistry {
          *  error-handler run — stamped onto this run's `finished` event as
          *  `errorHandler: { firedBy }`. Only meaningful alongside isErrorHandler. */
         errorHandlerFiredBy?: string;
+        /** When true (a step-mode run), Subflow children become step-drivable:
+         *  entering one pauses inside it instead of running it to completion in
+         *  a single opaque step. Drive the run via `step(runId)`. */
+        stepped?: boolean;
     }): {
         runId: string;
         handle: FlowRun;
     };
+    /**
+     * One composite step of a run, drill-aware. For stepped runs a Subflow node
+     * is no longer one opaque step: entering it pauses inside the child
+     * (`entered`), subsequent steps drive the child's nodes, and completing the
+     * child pops back out (`exited`). Non-stepped runs (no drill state) fall
+     * back to a plain executor step. Unknown run → undefined.
+     */
+    step(runId: string): Promise<StepResult | undefined>;
+    /**
+     * One composite step, drill-aware. Structured as a loop over levels: each
+     * pass drives the current deepest level (a pending stashed step, or a fresh
+     * executor step) while racing "a new child started". Popping a finished
+     * child continues the loop on its parent's stashed step WITH the race still
+     * armed — the parent's still-pending Subflow node execution may call
+     * runSubflow again (retry, or a custom node making sequential calls), and
+     * that re-entry must surface as `entered`, not deadlock the fold.
+     */
+    private stepLevels;
+    /**
+     * Cancel a run, drill-aware. For a stepped run drilled into subflows this
+     * cancels every stacked child deepest-first and rejects the promise each
+     * parent's Subflow node execution is blocked on — those pending executions
+     * then unwind in the background exactly like an in-flight node after a
+     * plain root cancel today (recorded, but the run is already finished).
+     * step() after cancel reports { done: true } without executing anything.
+     * Returns false for an unknown run.
+     */
+    /** Cancels every live (non-finished) run — the server's shutdown path, so
+     *  in-flight executions (and their drilled subflow children) don't keep
+     *  running headless after the process is asked to die. */
+    shutdown(): void;
+    cancel(runId: string): boolean;
     /**
      * Best-effort: fires `errorOperation` (resolved via the same `loadFlow`
      * callback Subflow nodes use) as a new run when `failedRun` finished with