@xdelivered/emberflow 0.2.0

package/dist/server/client.d.ts

@@ -0,0 +1,130 @@
+import type { LogLine, NodeExecutionSample, NodeRunState, PublishedArtifact, WorkflowDefinition, WorkflowRun } from '../src/engine/index.js';
+import type { ApiTree, OpSummary } from './apiStore.js';
+export type { ApiTree, FolderNode, ApiNode, OpSummary } from './apiStore.js';
+/** SSE-shaped events emitted on GET /runs/:id/events — mirrors server/runRegistry.ts RunEvent. */
+export type RunEvent = {
+    type: 'nodeState';
+    nodeId: string;
+    state: NodeRunState;
+} | {
+    type: 'log';
+    line: LogLine;
+} | {
+    type: 'finished';
+    run: WorkflowRun;
+};
+/** Thrown when the runner cannot be reached at all (connection refused, DNS, etc). */
+export declare class RunnerUnreachableError extends Error {
+    constructor(cause?: unknown);
+}
+export declare function health(): Promise<{
+    status: string;
+}>;
+export declare function listWorkflows(): Promise<WorkflowDefinition[]>;
+/** Fetches a single flow by id from the full workflow list (no single-flow GET endpoint). */
+export declare function getWorkflow(id: string): Promise<WorkflowDefinition | undefined>;
+export interface NodeMeta {
+    type: string;
+    label?: string;
+    description?: string;
+    category?: string;
+    traceKind?: string;
+    effects?: string;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+    source?: string;
+}
+/** The runner's LIVE node registry (built-ins + the project's registerNodes),
+ *  so the CLI sees the same nodes execution does — not a project-blind local
+ *  createDefaultRegistry(). */
+export declare function listNodes(): Promise<NodeMeta[]>;
+/** Validate a flow against the runner's live registry (built-ins + project nodes). */
+export declare function validateOperation(flow: WorkflowDefinition): Promise<{
+    valid: boolean;
+    issues: unknown[];
+}>;
+export declare function saveWorkflow(flow: WorkflowDefinition): Promise<void>;
+/** One summary per operation with its on-disk `path` (id === path) and `http`
+ *  trigger metadata (undefined for internal sub-flows). Sourced from the
+ *  `operations[]` array of `GET /workflows`. */
+export declare function listOperations(): Promise<OpSummary[]>;
+/** Builds the API tree (apis → folders → operations) client-side from the flat
+ *  `operations[]` summaries, splitting each op's `path` into [api, …folders, op].
+ *  Mirrors the server's `ApiStore.tree()` so no extra runner route is needed. */
+export declare function apiTree(): Promise<ApiTree>;
+/** Result of a create-operation attempt: `ok: false` always carries a message
+ *  (e.g. a 409 collision) so a creation failure is never silent. */
+export interface CreateOperationResult {
+    ok: boolean;
+    error?: string;
+}
+/**
+ * Creates a brand-new operation at an explicit `apis/` path via
+ * `POST /operations { flow, path }`. The runner enforces `flow.id === path` and
+ * 409s if an operation already exists at that path (never overwrites — that's
+ * `saveWorkflow`/PUT). Mirrors `src/store/serverRunner.ts createOperationOnServer`.
+ */
+/** Delete an operation by id (its apis-tree path). id is URL-encoded so slash
+ *  ids match the /workflows/:id route. Returns ok:false with a message on 404. */
+export declare function deleteOperation(id: string): Promise<CreateOperationResult>;
+export declare function createOperation(flow: WorkflowDefinition, path: string): Promise<CreateOperationResult>;
+export interface StartRunOptions {
+    /** A flow to run under dev semantics (mutually exclusive with `artifact`). */
+    flow?: WorkflowDefinition;
+    /** A sealed artifact to run under production semantics (mutually exclusive with `flow`). */
+    artifact?: PublishedArtifact;
+    /** Pinned node outputs; ignored/rejected by the runner in production. */
+    pins?: Record<string, unknown>;
+    /** The invocation payload, exposed to nodes as ctx.runInput. */
+    input?: Record<string, unknown>;
+    /** Explicit env override; artifact runs always force 'production' regardless. */
+    env?: 'dev' | 'production';
+    /** Named environment to run against (from emberflow.environments.json); omitted → runner default. */
+    environment?: string;
+    /** Explicit safe-mode override; omitted → environment's default (protected ⇒ true). */
+    safeMode?: boolean;
+    /** Required to equal `environment` when explicitly disabling safe mode on a protected environment. */
+    confirm?: string;
+}
+export declare function startRun(opts: StartRunOptions): Promise<string>;
+export interface EnvironmentSummary {
+    name: string;
+    protected: boolean;
+    varKeys: string[];
+    secretKeys: string[];
+    auth?: {
+        configured: boolean;
+        authenticated: boolean;
+        secretRef?: string;
+    };
+}
+export declare function listEnvironments(): Promise<{
+    defaultEnvironment: string;
+    environments: EnvironmentSummary[];
+}>;
+/** Performs the named environment's configured login, storing the captured
+ *  credential runner-side. Never returns the secret value — only whether the
+ *  login succeeded and which secret it landed in. */
+export declare function loginEnvironment(name: string): Promise<{
+    authenticated: boolean;
+    secretRef: string;
+}>;
+/** Sets (or, when `auth` is `null`, clears) an environment's auth config via
+ *  `PUT /environments/:name/auth`. Never sends secret values — `auth` carries
+ *  only refs/names (attach.secretRef, login.request.bodyRef). 204 on success. */
+export declare function setEnvironmentAuth(name: string, auth: unknown): Promise<void>;
+/** Flips whether mounted HTTP endpoints execute for real or answer from
+ *  scenario expectations (mock), via `POST /serving`. 204 on success; a
+ *  bogus mode is rejected by the runner (surfaced via request()'s error path). */
+export declare function setServingMode(mode: 'real' | 'mock'): Promise<void>;
+export declare function samples(nodeId: string): Promise<NodeExecutionSample[]>;
+/**
+ * Opens the run's SSE stream and collects events until `finished`.
+ * Parses the stream by hand: messages are separated by a blank line, each
+ * made of `event:`/`data:` lines; lines starting with `:` are heartbeat
+ * comments and are ignored.
+ */
+export declare function waitForRun(runId: string): Promise<{
+    run: WorkflowRun;
+    logs: LogLine[];
+}>;

package/dist/server/client.js

@@ -0,0 +1,247 @@
+const DEFAULT_BASE_URL = 'http://127.0.0.1:8092';
+function baseUrl() {
+    return process.env.EMBERFLOW_RUNNER_URL ?? DEFAULT_BASE_URL;
+}
+/** Thrown when the runner cannot be reached at all (connection refused, DNS, etc). */
+export class RunnerUnreachableError extends Error {
+    constructor(cause) {
+        super(`runner unreachable at ${baseUrl()} — is \`npm run server\` running?`);
+        this.name = 'RunnerUnreachableError';
+        this.cause = cause;
+    }
+}
+async function request(path, init) {
+    let res;
+    try {
+        res = await fetch(`${baseUrl()}${path}`, init);
+    }
+    catch (err) {
+        throw new RunnerUnreachableError(err);
+    }
+    if (!res.ok) {
+        let message = `${res.status} ${res.statusText}`;
+        try {
+            const body = (await res.json());
+            if (body && typeof body.error === 'string')
+                message = body.error;
+        }
+        catch {
+            /* body wasn't JSON — keep the status text */
+        }
+        throw new Error(message);
+    }
+    if (res.status === 204)
+        return undefined;
+    return (await res.json());
+}
+export async function health() {
+    return request('/healthz');
+}
+export async function listWorkflows() {
+    const { flows } = await request('/workflows');
+    return flows;
+}
+/** Fetches a single flow by id from the full workflow list (no single-flow GET endpoint). */
+export async function getWorkflow(id) {
+    const flows = await listWorkflows();
+    return flows.find((f) => f.id === id);
+}
+/** The runner's LIVE node registry (built-ins + the project's registerNodes),
+ *  so the CLI sees the same nodes execution does — not a project-blind local
+ *  createDefaultRegistry(). */
+export async function listNodes() {
+    const { nodes } = await request('/nodes');
+    return nodes;
+}
+/** Validate a flow against the runner's live registry (built-ins + project nodes). */
+export async function validateOperation(flow) {
+    return request('/validate', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ flow }),
+    });
+}
+export async function saveWorkflow(flow) {
+    await request(`/workflows/${encodeURIComponent(flow.id)}`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(flow),
+    });
+}
+/** One summary per operation with its on-disk `path` (id === path) and `http`
+ *  trigger metadata (undefined for internal sub-flows). Sourced from the
+ *  `operations[]` array of `GET /workflows`. */
+export async function listOperations() {
+    const { operations } = await request('/workflows');
+    return operations;
+}
+/** Builds the API tree (apis → folders → operations) client-side from the flat
+ *  `operations[]` summaries, splitting each op's `path` into [api, …folders, op].
+ *  Mirrors the server's `ApiStore.tree()` so no extra runner route is needed. */
+export async function apiTree() {
+    const ops = await listOperations();
+    const apis = new Map();
+    const folderAt = (parent, name) => {
+        let f = parent.folders.find((x) => x.name === name);
+        if (!f) {
+            f = { name, folders: [], operations: [] };
+            parent.folders.push(f);
+        }
+        return f;
+    };
+    for (const op of ops) {
+        const parts = op.path.split('/'); // [api, ...folders, opName]
+        const apiName = parts[0];
+        let api = apis.get(apiName);
+        if (!api) {
+            api = { name: apiName, folders: [], operations: [] };
+            apis.set(apiName, api);
+        }
+        let container = api;
+        for (const fp of parts.slice(1, -1))
+            container = folderAt(container, fp);
+        container.operations.push(op);
+    }
+    return { apis: [...apis.values()] };
+}
+/**
+ * Creates a brand-new operation at an explicit `apis/` path via
+ * `POST /operations { flow, path }`. The runner enforces `flow.id === path` and
+ * 409s if an operation already exists at that path (never overwrites — that's
+ * `saveWorkflow`/PUT). Mirrors `src/store/serverRunner.ts createOperationOnServer`.
+ */
+/** Delete an operation by id (its apis-tree path). id is URL-encoded so slash
+ *  ids match the /workflows/:id route. Returns ok:false with a message on 404. */
+export async function deleteOperation(id) {
+    let res;
+    try {
+        res = await fetch(`${baseUrl()}/workflows/${encodeURIComponent(id)}`, { method: 'DELETE' });
+    }
+    catch (err) {
+        throw new RunnerUnreachableError(err);
+    }
+    if (res.status === 204 || res.ok)
+        return { ok: true };
+    const body = (await res.json().catch(() => undefined));
+    return { ok: false, error: body?.error ?? `Delete failed with status ${res.status}` };
+}
+export async function createOperation(flow, path) {
+    let res;
+    try {
+        res = await fetch(`${baseUrl()}/operations`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ flow, path }),
+        });
+    }
+    catch (err) {
+        throw new RunnerUnreachableError(err);
+    }
+    if (res.ok)
+        return { ok: true };
+    const body = (await res.json().catch(() => undefined));
+    return { ok: false, error: body?.error ?? `Request failed with status ${res.status}` };
+}
+export async function startRun(opts) {
+    const { flow, artifact, pins, input, env, environment, safeMode, confirm } = opts;
+    const { runId } = await request('/runs', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ flow, artifact, mode: 'run', pins, input, env, environment, safeMode, confirm }),
+    });
+    return runId;
+}
+export async function listEnvironments() {
+    return request('/environments');
+}
+/** Performs the named environment's configured login, storing the captured
+ *  credential runner-side. Never returns the secret value — only whether the
+ *  login succeeded and which secret it landed in. */
+export async function loginEnvironment(name) {
+    return request(`/environments/${encodeURIComponent(name)}/login`, { method: 'POST' });
+}
+/** Sets (or, when `auth` is `null`, clears) an environment's auth config via
+ *  `PUT /environments/:name/auth`. Never sends secret values — `auth` carries
+ *  only refs/names (attach.secretRef, login.request.bodyRef). 204 on success. */
+export async function setEnvironmentAuth(name, auth) {
+    await request(`/environments/${encodeURIComponent(name)}/auth`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(auth),
+    });
+}
+/** Flips whether mounted HTTP endpoints execute for real or answer from
+ *  scenario expectations (mock), via `POST /serving`. 204 on success; a
+ *  bogus mode is rejected by the runner (surfaced via request()'s error path). */
+export async function setServingMode(mode) {
+    await request('/serving', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ mode }),
+    });
+}
+export async function samples(nodeId) {
+    const { samples: results } = await request(`/samples?nodeId=${encodeURIComponent(nodeId)}`);
+    return results;
+}
+/**
+ * Opens the run's SSE stream and collects events until `finished`.
+ * Parses the stream by hand: messages are separated by a blank line, each
+ * made of `event:`/`data:` lines; lines starting with `:` are heartbeat
+ * comments and are ignored.
+ */
+export async function waitForRun(runId) {
+    let res;
+    try {
+        res = await fetch(`${baseUrl()}/runs/${encodeURIComponent(runId)}/events`);
+    }
+    catch (err) {
+        throw new RunnerUnreachableError(err);
+    }
+    if (!res.ok || !res.body) {
+        throw new Error(`Failed to open event stream for run ${runId}: ${res.status} ${res.statusText}`);
+    }
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    const logs = [];
+    let finalRun;
+    const processMessage = (raw) => {
+        const dataLines = [];
+        for (const line of raw.split('\n')) {
+            if (line.length === 0 || line.startsWith(':'))
+                continue;
+            if (line.startsWith('data:'))
+                dataLines.push(line.slice(5).trimStart());
+        }
+        if (dataLines.length === 0)
+            return;
+        const event = JSON.parse(dataLines.join('\n'));
+        if (event.type === 'log')
+            logs.push(event.line);
+        else if (event.type === 'finished')
+            finalRun = event.run;
+    };
+    try {
+        while (!finalRun) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            let sepIndex;
+            while ((sepIndex = buffer.indexOf('\n\n')) !== -1) {
+                const raw = buffer.slice(0, sepIndex);
+                buffer = buffer.slice(sepIndex + 2);
+                processMessage(raw);
+                if (finalRun)
+                    break;
+            }
+        }
+    }
+    finally {
+        reader.cancel().catch(() => { });
+    }
+    if (!finalRun)
+        throw new Error(`Run ${runId} stream ended before a "finished" event was received`);
+    return { run: finalRun, logs };
+}

package/dist/server/environments.d.ts

@@ -0,0 +1,103 @@
+/** Describes how the runner authenticates studio runs against an environment. */
+export interface EnvAuth {
+    attach: {
+        as: 'cookie' | 'header';
+        name: string;
+        secretRef: string;
+        prefix?: string;
+    };
+    login?: {
+        request: {
+            method: string;
+            url: string;
+            headers?: Record<string, string>;
+            bodyRef?: string;
+        };
+        capture: {
+            from: 'set-cookie';
+            cookieName?: string;
+        } | {
+            from: 'json';
+            path: string;
+        } | {
+            from: 'header';
+            name: string;
+        };
+    };
+}
+/** A named value-set the runner injects into a run. */
+export interface EnvironmentDefinition {
+    /** Non-secret values (API base URLs, seed ids, flags) — visible in UI/logs. */
+    vars: Record<string, string>;
+    /**
+     * Resolved secret map (KEY -> value) as seen by the runtime. Values live in
+     * `emberflow.secrets.json` (never in `emberflow.environments.json`, which
+     * carries only the list of key NAMES). A key that is declared but has no
+     * value in the secrets file resolves to '' so `requireSecret` still throws a
+     * helpful "missing secret" error. Masked everywhere: keys visible, values
+     * never shown.
+     */
+    secrets: Record<string, string>;
+    /** Marks environments where mistakes are expensive (e.g. prod). Forces safe mode by default. */
+    protected?: boolean;
+    /** Optional studio-run auth injection config. Absent means no auth injection (backward compatible). */
+    auth?: EnvAuth;
+}
+export interface EnvironmentsFile {
+    defaultEnvironment: string;
+    environments: Record<string, EnvironmentDefinition>;
+    /** True when the project deliberately configured environments (an
+     *  emberflow.environments.json exists, or legacy secrets were found) —
+     *  false when the loader synthesized the bare "local" fallback. Drives the
+     *  default serving mode: an unconfigured project boots in mock. */
+    configured: boolean;
+}
+export interface RunSafetyRequest {
+    safeMode?: boolean;
+    confirm?: string;
+}
+export type RunSafetyResolution = {
+    ok: true;
+    safeMode: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Resolves the effective `safeMode` for a run against a given environment.
+ *
+ * - Omitted `safeMode` defaults to the environment's protection: `true` when
+ *   `protected`, `false` otherwise.
+ * - Explicitly requesting `safeMode: false` on a protected environment is
+ *   refused unless `confirm` matches the environment name exactly.
+ * - Any other explicit request (including `safeMode: true` on any env, or
+ *   `safeMode: false` on a non-protected env) is honored as-is.
+ */
+export declare function resolveRunSafety(envName: string, env: EnvironmentDefinition, request: RunSafetyRequest): RunSafetyResolution;
+export declare function loadEnvironments(cwd: string): EnvironmentsFile;
+/**
+ * Sets a single secret's VALUE in `emberflow.secrets.json` (0600) and ensures
+ * its key NAME is listed on the environment in `emberflow.environments.json`,
+ * both at `cwd`. The value never touches environments.json. Throws if the
+ * environments file is missing/malformed or the environment name is unknown.
+ * Concurrent calls are serialized so two in-flight writes never clobber each other.
+ */
+export declare function setEnvironmentSecret(cwd: string, envName: string, key: string, value: string): Promise<void>;
+/**
+ * Sets (or, when `auth` is `null`, clears) an environment's `auth` config in
+ * `emberflow.environments.json` at `cwd` and persists the change. Validates
+ * the auth shape before writing. Throws if the environments file is
+ * missing/malformed, the environment name is unknown, or `auth` is invalid.
+ * Preserves the environment's other fields (secrets, vars, protected,
+ * unknown fields). Shares the write queue with `setEnvironmentSecret` so
+ * concurrent writers can't clobber each other.
+ */
+export declare function setEnvironmentAuth(cwd: string, envName: string, auth: EnvAuth | null): Promise<void>;
+/**
+ * Removes a single secret from an environment: drops its key NAME from
+ * `emberflow.environments.json` and its VALUE from `emberflow.secrets.json`,
+ * both at `cwd`. Missing key resolves without error. Throws if the environments
+ * file is missing/malformed or the environment name is unknown. Shares the
+ * write queue with the other writers.
+ */
+export declare function deleteEnvironmentSecret(cwd: string, envName: string, key: string): Promise<void>;