@xdelivered/emberflow 0.2.0

package/dist/server/infrastructure.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The committed, secrets-free infrastructure manifest the scout writes to
+ * `emberflow/infrastructure.json` and agents/studio read back. It describes
+ * what a (usually brownfield) project already uses — databases, external APIs,
+ * providers — with evidence pointing at the files that prove it. Env-var
+ * NAMES only ever appear here; never values.
+ */
+/** The closed set of infrastructure categories the scout classifies items into. */
+export declare const INFRASTRUCTURE_KINDS: readonly ["database", "http-api", "queue", "cache", "email", "llm", "auth", "framework", "storage", "other"];
+export type InfrastructureKind = (typeof INFRASTRUCTURE_KINDS)[number];
+/** A single file:note pointer proving an item exists. `note` is optional. */
+export interface InfrastructureEvidence {
+    file: string;
+    note?: string;
+    /** Unknown fields are preserved on read (forward-compatibility). */
+    [key: string]: unknown;
+}
+/** One discovered piece of infrastructure. */
+export interface InfrastructureItem {
+    id: string;
+    kind: InfrastructureKind;
+    name: string;
+    evidence: InfrastructureEvidence[];
+    /** Env-var NAMES this item likely needs (e.g. "DATABASE_URL") — never values. */
+    suggestedSecretRefs: string[];
+    /** Non-secret config var NAMES this item likely needs. */
+    suggestedVars: string[];
+    notes?: string;
+    /** Unknown fields are preserved on read (forward-compatibility). */
+    [key: string]: unknown;
+}
+export interface InfrastructureManifest {
+    version: number;
+    scannedAt?: string;
+    greenfield: boolean;
+    summary?: string;
+    items: InfrastructureItem[];
+    /** Unknown top-level fields are preserved on read (forward-compatibility). */
+    [key: string]: unknown;
+}
+export declare const INFRASTRUCTURE_FILENAME: string;
+/**
+ * Reads `emberflow/infrastructure.json` from `projectRoot`.
+ *
+ * - Absent file → `null` (no warning: not-scouted-yet is a normal state).
+ * - Malformed (unreadable, invalid JSON, or not the expected shape) → `null`
+ *   plus a single warning per path per process. The CALLER decides keep-last-good.
+ * - Valid → a leniently-normalized `InfrastructureManifest`: required fields
+ *   defaulted, item `kind`s clamped to the enum, unknown fields preserved.
+ */
+export declare function loadInfrastructure(projectRoot: string): InfrastructureManifest | null;

package/dist/server/infrastructure.js

@@ -0,0 +1,116 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * The committed, secrets-free infrastructure manifest the scout writes to
+ * `emberflow/infrastructure.json` and agents/studio read back. It describes
+ * what a (usually brownfield) project already uses — databases, external APIs,
+ * providers — with evidence pointing at the files that prove it. Env-var
+ * NAMES only ever appear here; never values.
+ */
+/** The closed set of infrastructure categories the scout classifies items into. */
+export const INFRASTRUCTURE_KINDS = [
+    'database',
+    'http-api',
+    'queue',
+    'cache',
+    'email',
+    'llm',
+    'auth',
+    'framework',
+    'storage',
+    'other',
+];
+export const INFRASTRUCTURE_FILENAME = join('emberflow', 'infrastructure.json');
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isInfrastructureKind(value) {
+    return typeof value === 'string' && INFRASTRUCTURE_KINDS.includes(value);
+}
+/**
+ * Leniently coerces one raw item into an `InfrastructureItem`. Missing/invalid
+ * required fields are defaulted rather than rejected (name/id fall back,
+ * unknown `kind` normalizes to "other") and unknown fields pass through, so a
+ * slightly-off item from the agent still renders instead of nuking the whole
+ * manifest. Returns null only when the item isn't an object at all.
+ */
+function coerceItem(raw, index) {
+    if (!isPlainObject(raw))
+        return null;
+    const evidenceRaw = Array.isArray(raw.evidence) ? raw.evidence : [];
+    const evidence = evidenceRaw
+        .filter(isPlainObject)
+        .map((e) => ({ ...e, file: typeof e.file === 'string' ? e.file : '', note: typeof e.note === 'string' ? e.note : undefined }));
+    const secretRefs = Array.isArray(raw.suggestedSecretRefs)
+        ? raw.suggestedSecretRefs.filter((s) => typeof s === 'string')
+        : [];
+    const vars = Array.isArray(raw.suggestedVars)
+        ? raw.suggestedVars.filter((s) => typeof s === 'string')
+        : [];
+    return {
+        ...raw,
+        id: typeof raw.id === 'string' && raw.id.length > 0 ? raw.id : `item-${index}`,
+        kind: isInfrastructureKind(raw.kind) ? raw.kind : 'other',
+        name: typeof raw.name === 'string' && raw.name.length > 0 ? raw.name : 'Unnamed',
+        evidence,
+        suggestedSecretRefs: secretRefs,
+        suggestedVars: vars,
+        ...(typeof raw.notes === 'string' ? { notes: raw.notes } : {}),
+    };
+}
+/** One-shot per-path warn dedupe so repeated GETs don't spam the log. */
+const warnedOnce = new Set();
+/**
+ * Reads `emberflow/infrastructure.json` from `projectRoot`.
+ *
+ * - Absent file → `null` (no warning: not-scouted-yet is a normal state).
+ * - Malformed (unreadable, invalid JSON, or not the expected shape) → `null`
+ *   plus a single warning per path per process. The CALLER decides keep-last-good.
+ * - Valid → a leniently-normalized `InfrastructureManifest`: required fields
+ *   defaulted, item `kind`s clamped to the enum, unknown fields preserved.
+ */
+export function loadInfrastructure(projectRoot) {
+    const path = join(projectRoot, INFRASTRUCTURE_FILENAME);
+    if (!existsSync(path))
+        return null;
+    const warn = (message) => {
+        if (!warnedOnce.has(path)) {
+            warnedOnce.add(path);
+            console.warn(`[emberflow] ${INFRASTRUCTURE_FILENAME} ${message} — ignoring it (keeping last good state). Re-run the infrastructure scout to regenerate it.`);
+        }
+        return null;
+    };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        // Deliberately NOT interpolating the parse error's message: on malformed
+        // JSON, JSON.parse's error text often echoes a fragment of the file
+        // content around the failure point (e.g. "Unexpected token o in JSON at
+        // position 5 ... <10 chars of the file>"), which could leak a fragment of
+        // a secret value if one was pasted into this file. Keep the warning generic.
+        return warn('is not valid JSON');
+    }
+    if (!isPlainObject(parsed)) {
+        return warn('is not a JSON object at the top level');
+    }
+    if (parsed.items !== undefined && !Array.isArray(parsed.items)) {
+        return warn('has an "items" field that is not an array');
+    }
+    // A successful read clears any prior warning for this path, so a fixed file
+    // warns again cleanly if it later regresses.
+    warnedOnce.delete(path);
+    const rawItems = Array.isArray(parsed.items) ? parsed.items : [];
+    const items = rawItems
+        .map((item, i) => coerceItem(item, i))
+        .filter((item) => item !== null);
+    return {
+        ...parsed,
+        version: typeof parsed.version === 'number' ? parsed.version : 1,
+        ...(typeof parsed.scannedAt === 'string' ? { scannedAt: parsed.scannedAt } : {}),
+        greenfield: parsed.greenfield === true,
+        ...(typeof parsed.summary === 'string' ? { summary: parsed.summary } : {}),
+        items,
+    };
+}

package/dist/server/login.d.ts

@@ -0,0 +1,21 @@
+import { type EnvironmentDefinition } from './environments.js';
+/** Minimal response shape performLogin needs from the injected fetch. */
+interface LoginResponse {
+    status: number;
+    headers: Headers;
+    json: () => Promise<any>;
+}
+export interface PerformLoginDeps {
+    fetch: (url: string, init?: RequestInit) => Promise<LoginResponse>;
+}
+/**
+ * Fires the configured login request for `envName`, captures the resulting
+ * credential per `envDef.auth.login.capture`, and persists it into the
+ * environment's secrets under `envDef.auth.attach.secretRef`.
+ *
+ * Never returns or logs the captured value — only the secretRef name.
+ */
+export declare function performLogin(cwd: string, envName: string, envDef: EnvironmentDefinition, deps?: PerformLoginDeps): Promise<{
+    secretRef: string;
+}>;
+export {};

package/dist/server/login.js

@@ -0,0 +1,44 @@
+import { captureCredential } from './authAttach.js';
+import { setEnvironmentSecret } from './environments.js';
+/**
+ * Fires the configured login request for `envName`, captures the resulting
+ * credential per `envDef.auth.login.capture`, and persists it into the
+ * environment's secrets under `envDef.auth.attach.secretRef`.
+ *
+ * Never returns or logs the captured value — only the secretRef name.
+ */
+export async function performLogin(cwd, envName, envDef, deps = { fetch: globalThis.fetch }) {
+    const login = envDef.auth?.login;
+    if (!login) {
+        throw new Error(`environment "${envName}" has no auth.login configured`);
+    }
+    const { method, url, headers, bodyRef } = login.request;
+    const init = { method, ...(headers ? { headers } : {}) };
+    if (bodyRef !== undefined) {
+        const rawBody = envDef.secrets[bodyRef];
+        let parsed;
+        try {
+            parsed = JSON.parse(rawBody);
+        }
+        catch {
+            // Never include the secret content in the message — only names.
+            throw new Error(`login body secret "${bodyRef}" for environment "${envName}" is not valid JSON`);
+        }
+        init.body = JSON.stringify(parsed);
+        // Lowercase all caller header keys so an explicit content-type (any casing)
+        // wins over — and never duplicates — the auto-added default.
+        const callerHeaders = Object.fromEntries(Object.entries(headers ?? {}).map(([k, v]) => [k.toLowerCase(), v]));
+        init.headers = { 'content-type': 'application/json', ...callerHeaders };
+    }
+    const res = await deps.fetch(url, init);
+    if (res.status < 200 || res.status >= 300) {
+        throw new Error(`login failed: ${res.status}`);
+    }
+    const value = await captureCredential(res, login.capture);
+    if (value === null) {
+        throw new Error('login succeeded but no credential captured');
+    }
+    const secretRef = envDef.auth.attach.secretRef;
+    await setEnvironmentSecret(cwd, envName, secretRef, value);
+    return { secretRef };
+}

package/dist/server/mcp.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/mcp.js

@@ -0,0 +1,182 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { findScenario, publishFlow, scenarioNames, validateFlow, } from '../src/engine/index.js';
+import { createDefaultRegistry } from '../src/nodes/index.js';
+import * as client from './client.js';
+/** Wraps any value as an MCP text-content result. */
+function json(value, isError = false) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+/** Runs a handler, turning any thrown error into an isError text result. */
+async function guard(fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        return json({ error: err instanceof Error ? err.message : String(err) }, true);
+    }
+}
+const server = new McpServer({ name: 'emberflow', version: '0.0.0' });
+server.tool('list_nodes', 'List all registered node types', {}, () => guard(async () => {
+    const registry = createDefaultRegistry();
+    return json(registry.list().map((d) => ({
+        type: d.type,
+        label: d.label,
+        category: d.category,
+        description: d.description,
+    })));
+}));
+server.tool('get_node_schema', 'Get the full NodeDefinition for a node type', { type: z.string() }, ({ type }) => guard(async () => {
+    const registry = createDefaultRegistry();
+    if (!registry.has(type))
+        return json({ error: `Unknown node type: ${type}` }, true);
+    return json(registry.get(type).definition);
+}));
+server.tool('list_operations', 'List every operation the runner knows, annotated with its API location. Each entry: ' +
+    '{ id, name, path, folder, http }. "path" is the apis/ tree location (api/…folders/op) ' +
+    'and equals the id. "http" is the HTTP trigger { method, path } for operations exposed as ' +
+    'endpoints — an HTTP operation runs as Input({ params, query, body, headers }) → ' +
+    'Response({ status, body }); "http" is null for internal sub-flow operations invoked by ' +
+    'other operations rather than over HTTP.', {}, () => guard(async () => {
+    const ops = await client.listOperations();
+    return json(ops.map((op) => ({
+        id: op.id,
+        name: op.name,
+        path: op.path,
+        folder: op.path.split('/')[0],
+        http: op.http ? { method: op.http.method, path: op.http.path } : null,
+    })));
+}));
+server.tool('list_apis', 'Return the API tree: top-level APIs → folders → operations (each op carries its ' +
+    'id, name, path, and http trigger, if any). Built from the operations\' apis/ paths so an ' +
+    'agent can see how operations are organised across APIs and which are HTTP endpoints ' +
+    'vs internal sub-flows.', {}, () => guard(async () => json(await client.apiTree())));
+server.tool('get_operation', "Get an operation's full JSON by id (its nodes, edges, http trigger + auth, scenarios). " +
+    'The id equals the operation\'s apis/ path.', { id: z.string() }, ({ id }) => guard(async () => {
+    const flow = await client.getWorkflow(id);
+    if (!flow)
+        return json({ error: `Unknown operation: ${id}` }, true);
+    return json(flow);
+}));
+server.tool('create_operation', 'Create a brand-new operation at an explicit apis/ path via POST /operations. "path" is the ' +
+    'apis/ tree location (api/…folders/op) and MUST equal flow.id — the runner rejects a ' +
+    'mismatch and 409s if an operation already exists at that path (use save_operation to ' +
+    'update an existing one). Set flow.http = { method, path[, auth] } to expose it as an HTTP ' +
+    'endpoint (Input({ params, query, body, headers }) → Response({ status, body })); omit http ' +
+    'for an internal sub-flow.', {
+    flow: z.record(z.string(), z.unknown()),
+    path: z.string(),
+}, ({ flow, path }) => guard(async () => {
+    const definition = flow;
+    const registry = createDefaultRegistry();
+    const issues = validateFlow(definition, registry);
+    if (issues.some((i) => i.severity === 'error'))
+        return json({ issues }, true);
+    const result = await client.createOperation(definition, path);
+    if (!result.ok)
+        return json({ error: result.error }, true);
+    return json({ ok: true, id: definition.id, path });
+}));
+server.tool('delete_operation', 'Delete an operation by id (its apis/ tree path, e.g. "billing/charge"). Removes the ' +
+    'operation file and its scenarios sidecar from the runner. Prefer this over editing files ' +
+    'for removals — a deleted op is unmounted immediately. Returns { ok } or an error if the id ' +
+    'is unknown.', { id: z.string() }, ({ id }) => guard(async () => {
+    const result = await client.deleteOperation(id);
+    if (!result.ok)
+        return json({ error: result.error }, true);
+    return json({ ok: true, id });
+}));
+server.tool('save_operation', 'Validate then save an existing operation to the runner (rejects operations with ' +
+    'error-severity issues). Persists the whole flow including its http trigger ' +
+    '({ method, path, auth }) and auth fields. Use create_operation for a brand-new op.', { flow: z.record(z.string(), z.unknown()) }, ({ flow }) => guard(async () => {
+    const definition = flow;
+    const registry = createDefaultRegistry();
+    const issues = validateFlow(definition, registry);
+    if (issues.some((i) => i.severity === 'error'))
+        return json({ issues }, true);
+    await client.saveWorkflow(definition);
+    return json({ ok: true, id: definition.id });
+}));
+server.tool('validate_operation', 'Validate an operation flow and return its issues (does not save).', { flow: z.record(z.string(), z.unknown()) }, ({ flow }) => guard(async () => {
+    const registry = createDefaultRegistry();
+    const issues = validateFlow(flow, registry);
+    const valid = !issues.some((i) => i.severity === 'error');
+    return json({ valid, issues });
+}));
+server.tool('run_operation', 'Run an operation to completion by id or inline flow; returns status, nodeStates, logs. ' +
+    'Accepts either an explicit "input" payload or a "scenario" name/id naming a test input ' +
+    'embedded in the operation. For an HTTP operation the input is the request shape ' +
+    '{ params, query, body, headers } and the run resolves a Response({ status, body }). ' +
+    '"environment" selects a named environment from emberflow.environments.json (default: the ' +
+    "runner's default environment). \"safeMode\" overrides safe mode (default: the environment's " +
+    'default — protected environments default to safe). Disabling safe mode on a protected ' +
+    'environment additionally requires "confirm" to equal "environment" exactly, or the run is ' +
+    'rejected.', {
+    id: z.string().optional(),
+    flow: z.record(z.string(), z.unknown()).optional(),
+    input: z.record(z.string(), z.unknown()).optional(),
+    scenario: z.string().optional(),
+    environment: z.string().optional(),
+    safeMode: z.boolean().optional(),
+    confirm: z.string().optional(),
+}, ({ id, flow, input, scenario, environment, safeMode, confirm }) => guard(async () => {
+    let definition;
+    if (flow) {
+        definition = flow;
+    }
+    else if (id) {
+        definition = await client.getWorkflow(id);
+        if (!definition)
+            return json({ error: `Unknown operation: ${id}` }, true);
+    }
+    else {
+        return json({ error: 'run_operation requires either "id" or "flow"' }, true);
+    }
+    if (scenario && input) {
+        return json({ error: 'run_operation accepts either "scenario" or "input", not both' }, true);
+    }
+    let resolvedInput = input;
+    if (scenario) {
+        const found = findScenario(definition, scenario);
+        if (!found) {
+            const names = scenarioNames(definition);
+            return json({ error: `Unknown scenario: "${scenario}". Available: ${names.length ? names.join(', ') : 'none'}` }, true);
+        }
+        resolvedInput = found.input;
+    }
+    const runId = await client.startRun({
+        flow: definition,
+        input: resolvedInput,
+        environment,
+        safeMode,
+        confirm,
+    });
+    const { run, logs } = await client.waitForRun(runId);
+    return json({ status: run.status, environment: run.environment, safeMode: run.safeMode, nodeStates: run.nodeStates, logs }, run.status !== 'succeeded');
+}));
+server.tool('list_environments', 'List the named environments the runner offers (from emberflow.environments.json): each ' +
+    'entry is { name, protected, varKeys, secretKeys } — only key NAMES are returned, never ' +
+    'values/secrets. Also returns defaultEnvironment. Use a name as run_operation\'s ' +
+    '"environment". Protected environments default to safe mode.', {}, () => guard(async () => json(await client.listEnvironments())));
+server.tool('publish_operation', 'Publish an operation by id into a sealed emberflow/v1 artifact (validates, strips pins, ' +
+    'hashes node implementations); does not write any files.', { id: z.string() }, ({ id }) => guard(async () => {
+    const flow = await client.getWorkflow(id);
+    if (!flow)
+        return json({ error: `Unknown operation: ${id}` }, true);
+    const registry = createDefaultRegistry();
+    const artifact = await publishFlow(flow, registry);
+    return json(artifact);
+}));
+server.tool('get_node_samples', 'Get recorded execution samples for a node', { nodeId: z.string() }, ({ nodeId }) => guard(async () => json(await client.samples(nodeId))));
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    process.stderr.write(`${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/server/migrateFlows.d.ts

@@ -0,0 +1,8 @@
+/** One-time relocation of the legacy flat flows layout into `<apisDir>/default/`.
+ *  Ids and sidecars are preserved; subflow references (by id) stay valid.
+ *  Idempotent: a no-op once `apisDir` exists or `flowsDir` is absent.
+ *  `flowsDir` is the actual configured flows directory — callers must not
+ *  assume it is literally named `flows` (project configs can rename it). */
+export declare function migrateFlowsToApis(flowsDir: string, apisDir: string): {
+    moved: string[];
+};

package/dist/server/migrateFlows.js

@@ -0,0 +1,25 @@
+import { existsSync, mkdirSync, readdirSync, renameSync, rmdirSync } from 'node:fs';
+import { join } from 'node:path';
+/** One-time relocation of the legacy flat flows layout into `<apisDir>/default/`.
+ *  Ids and sidecars are preserved; subflow references (by id) stay valid.
+ *  Idempotent: a no-op once `apisDir` exists or `flowsDir` is absent.
+ *  `flowsDir` is the actual configured flows directory — callers must not
+ *  assume it is literally named `flows` (project configs can rename it). */
+export function migrateFlowsToApis(flowsDir, apisDir) {
+    if (existsSync(apisDir) || !existsSync(flowsDir))
+        return { moved: [] };
+    const target = join(apisDir, 'default');
+    mkdirSync(target, { recursive: true });
+    const moved = [];
+    for (const file of readdirSync(flowsDir)) {
+        renameSync(join(flowsDir, file), join(target, file));
+        if (file.endsWith('.json') && !file.endsWith('.scenarios.json')) {
+            moved.push(file.slice(0, -'.json'.length));
+        }
+    }
+    try {
+        rmdirSync(flowsDir);
+    }
+    catch { /* non-empty or already gone — leave it */ }
+    return { moved };
+}

package/dist/server/mockHandler.d.ts

@@ -0,0 +1,15 @@
+import type { ScenarioDefinition, WorkflowDefinition } from '../src/engine/index.js';
+export interface MockResponse {
+    status: number;
+    body: unknown;
+    scenario?: string;
+}
+/** Pure scenario→response selection for mock mode. No I/O, no auth, no node
+ *  execution. Selection: `x-emberflow-scenario` header (exact scenario name)
+ *  → `__scenario` query param → first scenario with an `expect`. A named but
+ *  unknown scenario is a 404; a named scenario without an `expect` is a 501;
+ *  no scenario with an `expect` at all is a 501. */
+export declare function mockResponseFor(_flow: WorkflowDefinition, scenarios: ScenarioDefinition[], req: {
+    headers: Record<string, unknown>;
+    query: Record<string, unknown>;
+}): MockResponse;

package/dist/server/mockHandler.js

@@ -0,0 +1,35 @@
+const SCENARIO_HEADER = 'x-emberflow-scenario';
+const SCENARIO_QUERY = '__scenario';
+function fromExpect(scenario) {
+    const expect = scenario.expect;
+    if (!expect) {
+        return {
+            status: 501,
+            body: { error: `scenario "${scenario.name}" has no expect to mock from` },
+        };
+    }
+    return { status: expect.status ?? 200, body: expect.body ?? {}, scenario: scenario.name };
+}
+function asScenarioName(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+/** Pure scenario→response selection for mock mode. No I/O, no auth, no node
+ *  execution. Selection: `x-emberflow-scenario` header (exact scenario name)
+ *  → `__scenario` query param → first scenario with an `expect`. A named but
+ *  unknown scenario is a 404; a named scenario without an `expect` is a 501;
+ *  no scenario with an `expect` at all is a 501. */
+export function mockResponseFor(_flow, scenarios, req) {
+    const requestedName = asScenarioName(req.headers[SCENARIO_HEADER]) ?? asScenarioName(req.query[SCENARIO_QUERY]);
+    if (requestedName !== undefined) {
+        const named = scenarios.find((s) => s.name === requestedName);
+        if (!named) {
+            return { status: 404, body: { error: `unknown scenario "${requestedName}"` } };
+        }
+        return fromExpect(named);
+    }
+    const defaultScenario = scenarios.find((s) => s.expect !== undefined);
+    if (!defaultScenario) {
+        return { status: 501, body: { error: 'no mockable scenario (add an expect to a scenario)' } };
+    }
+    return fromExpect(defaultScenario);
+}

package/dist/server/nodesPayload.d.ts

@@ -0,0 +1,14 @@
+import type { NodeDefinition, NodeRegistry } from '../src/engine/index.js';
+/**
+ * Node metadata served to the studio over HTTP. Definitions carry everything
+ * the UI needs (label, schemas, category, tags); `source` is the
+ * 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.
+ */
+export interface NodeMetaPayload {
+    nodes: Array<NodeDefinition & {
+        source?: string;
+    }>;
+}
+export declare function nodesPayload(registry: NodeRegistry): NodeMetaPayload;

package/dist/server/nodesPayload.js

@@ -0,0 +1,14 @@
+export function nodesPayload(registry) {
+    return {
+        nodes: registry.list().map((definition) => {
+            let source;
+            try {
+                source = registry.get(definition.type).implementation.toString();
+            }
+            catch {
+                source = undefined;
+            }
+            return { ...definition, source };
+        }),
+    };
+}

package/dist/server/normalizeFlow.d.ts

@@ -0,0 +1,21 @@
+import type { WorkflowDefinition } from '../src/engine/index.js';
+export interface SeedParamDefaultsResult {
+    flow: WorkflowDefinition;
+    /** Path-param names that were newly seeded with `''`, in path order. */
+    seeded: string[];
+}
+/**
+ * Pure normalization step run before validation/persist on every write path
+ * (PUT /workflows/:id, POST /operations): seeds an empty-string placeholder
+ * under the first Input node's `config.defaults.params` for every `:param`
+ * in `flow.http.path` that has no default yet, so a plain Run reaches nodes
+ * with `params.<name> === ''` instead of crashing on `undefined` (same
+ * scaffold shape `emberflow create` already produces).
+ *
+ * Mirrors the `missing-param-default` guard semantics (src/engine/diagnostics.ts):
+ * presence, not meaningfulness, is what's checked/seeded. No-ops (returning
+ * the SAME `flow` object, unmodified) when there's no `:param` in the path,
+ * no Input node, or every param already has a default — never overwrites an
+ * existing value, whatever it is (including `''`).
+ */
+export declare function seedParamDefaults(flow: WorkflowDefinition): SeedParamDefaultsResult;

package/dist/server/normalizeFlow.js

@@ -0,0 +1,48 @@
+import { parsePathParams } from '../src/lib/pathParams.js';
+/**
+ * Pure normalization step run before validation/persist on every write path
+ * (PUT /workflows/:id, POST /operations): seeds an empty-string placeholder
+ * under the first Input node's `config.defaults.params` for every `:param`
+ * in `flow.http.path` that has no default yet, so a plain Run reaches nodes
+ * with `params.<name> === ''` instead of crashing on `undefined` (same
+ * scaffold shape `emberflow create` already produces).
+ *
+ * Mirrors the `missing-param-default` guard semantics (src/engine/diagnostics.ts):
+ * presence, not meaningfulness, is what's checked/seeded. No-ops (returning
+ * the SAME `flow` object, unmodified) when there's no `:param` in the path,
+ * no Input node, or every param already has a default — never overwrites an
+ * existing value, whatever it is (including `''`).
+ */
+export function seedParamDefaults(flow) {
+    const path = flow.http?.path;
+    const params = path ? parsePathParams(path) : [];
+    if (params.length === 0)
+        return { flow, seeded: [] };
+    const inputNode = flow.nodes.find((n) => n.type === 'Input');
+    if (!inputNode)
+        return { flow, seeded: [] };
+    const existingDefaults = inputNode.config?.defaults;
+    const existingParams = existingDefaults && typeof existingDefaults === 'object' && !Array.isArray(existingDefaults)
+        ? existingDefaults.params
+        : undefined;
+    const seeded = params.filter((name) => !existingParams || existingParams[name] === undefined);
+    if (seeded.length === 0)
+        return { flow, seeded: [] };
+    const newParams = { ...(existingParams ?? {}) };
+    for (const name of seeded)
+        newParams[name] = '';
+    const newInputNode = {
+        ...inputNode,
+        config: {
+            ...(inputNode.config ?? {}),
+            defaults: { ...(existingDefaults ?? {}), params: newParams },
+        },
+    };
+    return {
+        flow: {
+            ...flow,
+            nodes: flow.nodes.map((n) => (n === inputNode ? newInputNode : n)),
+        },
+        seeded,
+    };
+}

package/dist/server/openBrowser.d.ts

@@ -0,0 +1,8 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+interface OpenDeps {
+    platform?: NodeJS.Platform;
+    spawn?: typeof nodeSpawn;
+}
+/** Open the default browser at `url`. Best-effort — never throws into the caller. */
+export declare function openBrowser(url: string, deps?: OpenDeps): void;
+export {};

package/dist/server/openBrowser.js

@@ -0,0 +1,16 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+/** Open the default browser at `url`. Best-effort — never throws into the caller. */
+export function openBrowser(url, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const spawn = deps.spawn ?? nodeSpawn;
+    const [cmd, args] = platform === 'darwin' ? ['open', [url]]
+        : platform === 'win32' ? ['cmd', ['/c', 'start', '', url]]
+            : ['xdg-open', [url]];
+    try {
+        const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+        child.unref?.();
+    }
+    catch {
+        // headless / no browser — the URL is printed by the caller anyway
+    }
+}

package/dist/server/operationResult.d.ts

@@ -0,0 +1,12 @@
+import { type WorkflowDefinition, type WorkflowRun } from '../src/engine/index.js';
+/** Map a finished operation run to an HTTP response. A flow can have more than
+ *  one `Response` node (e.g. a success branch and an error branch) — only one
+ *  of them actually ran. Among the `Response`-type nodes, pick the one whose
+ *  run state actually succeeded (first such node by array order if somehow
+ *  more than one did); its output (already `{ status, body }`) wins.
+ *  Otherwise — no Response node, or none of them succeeded — fall back to
+ *  200 + the run's Result output. */
+export declare function extractResponse(run: WorkflowRun, flow: WorkflowDefinition): {
+    status: number;
+    body: unknown;
+};