@xdelivered/emberflow 0.2.0

package/dist/server/environments.js

@@ -0,0 +1,486 @@
+import { chmodSync, copyFileSync, existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { resolve } from 'node:path';
+const ENVIRONMENTS_FILENAME = 'emberflow.environments.json';
+const SECRETS_FILENAME = 'emberflow.secrets.json';
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isStringRecord(value) {
+    if (!isPlainObject(value))
+        return false;
+    return Object.values(value).every((v) => typeof v === 'string');
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((v) => typeof v === 'string');
+}
+/** A nested `{ envName: { KEY: value } }` secrets-file map (new shape). */
+function isNestedSecretsMap(value) {
+    if (!isPlainObject(value))
+        return false;
+    return Object.values(value).every((v) => isStringRecord(v));
+}
+/**
+ * Validates an `EnvAuth` value's shape. Returns an error message (without any
+ * `environments.<name>.` prefix) naming the problem, or `null` if valid.
+ * Shared by `validateShape` (file load) and `setEnvironmentAuth` (writer) so
+ * the rules can't drift between the two call sites.
+ */
+function validateAuthShape(auth) {
+    if (!isPlainObject(auth)) {
+        return 'auth must be an object';
+    }
+    const attach = auth.attach;
+    if (!isPlainObject(attach)) {
+        return 'auth.attach must be an object';
+    }
+    if (attach.as !== 'cookie' && attach.as !== 'header') {
+        return 'auth.attach.as must be "cookie" or "header"';
+    }
+    if (typeof attach.name !== 'string') {
+        return 'auth.attach.name must be a string';
+    }
+    if (typeof attach.secretRef !== 'string') {
+        return 'auth.attach.secretRef must be a string';
+    }
+    if (attach.prefix !== undefined && typeof attach.prefix !== 'string') {
+        return 'auth.attach.prefix must be a string';
+    }
+    if (auth.login !== undefined && !isPlainObject(auth.login)) {
+        return 'auth.login must be an object';
+    }
+    return null;
+}
+/** Throws with a message pinpointing what's wrong in the file, for a clear boot-time failure. */
+function validateShape(parsed) {
+    const prefix = `${ENVIRONMENTS_FILENAME} is malformed`;
+    if (!isPlainObject(parsed)) {
+        throw new Error(`${prefix}: expected a JSON object at the top level`);
+    }
+    if (typeof parsed.defaultEnvironment !== 'string' || parsed.defaultEnvironment.length === 0) {
+        throw new Error(`${prefix}: "defaultEnvironment" must be a non-empty string`);
+    }
+    if (!isPlainObject(parsed.environments)) {
+        throw new Error(`${prefix}: "environments" must be an object of name -> environment`);
+    }
+    const names = Object.keys(parsed.environments);
+    if (names.length === 0) {
+        throw new Error(`${prefix}: "environments" must define at least one environment`);
+    }
+    for (const name of names) {
+        const env = parsed.environments[name];
+        if (!isPlainObject(env)) {
+            throw new Error(`${prefix}: environments.${name} must be an object`);
+        }
+        if (env.vars !== undefined && !isStringRecord(env.vars)) {
+            throw new Error(`${prefix}: environments.${name}.vars must be an object of string -> string`);
+        }
+        // `secrets` is a LIST of key names (new, structure-only shape). The old
+        // map-of-values shape is still accepted here so a pre-migration file loads;
+        // loadEnvironments migrates its values out on the next load.
+        if (env.secrets !== undefined && !isStringArray(env.secrets) && !isStringRecord(env.secrets)) {
+            throw new Error(`${prefix}: environments.${name}.secrets must be an array of key names or an object of string -> string`);
+        }
+        if (env.protected !== undefined && typeof env.protected !== 'boolean') {
+            throw new Error(`${prefix}: environments.${name}.protected must be a boolean`);
+        }
+        if (env.auth !== undefined) {
+            const authError = validateAuthShape(env.auth);
+            if (authError !== null) {
+                throw new Error(`${prefix}: environments.${name}.${authError}`);
+            }
+        }
+    }
+    if (!(parsed.defaultEnvironment in parsed.environments)) {
+        throw new Error(`${prefix}: defaultEnvironment "${parsed.defaultEnvironment}" is not one of the defined environments (${names.join(', ')})`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Secret VALUES live in emberflow.secrets.json, structure-only in
+// environments.json. Everything below implements that split: reading the
+// secrets file (new nested shape + legacy flat), $ENV indirection, file
+// hardening warnings, and the one-time auto-migration of old inline values.
+// ---------------------------------------------------------------------------
+const secretsFileMode = 0o600;
+/** One-shot per-process warning dedupe so repeated loads don't spam the log. */
+const warnedOnce = new Set();
+function warnOnce(key, message) {
+    if (warnedOnce.has(key))
+        return;
+    warnedOnce.add(key);
+    console.warn(message);
+}
+/**
+ * Reads `emberflow.secrets.json`. Accepts the new nested
+ * `{ envName: { KEY: value } }` shape and the legacy flat `{ KEY: value }`
+ * shape (mapped to env "local", preserving the historical synthesized-env
+ * behavior). Missing or invalid file → empty. Values may be `$ENV:VAR`
+ * indirections; they are resolved at merge time, not here.
+ */
+function readSecretsFile(secretsPath) {
+    if (!existsSync(secretsPath))
+        return { byEnv: {}, legacyFlat: false, existed: false };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(secretsPath, 'utf8'));
+    }
+    catch {
+        return { byEnv: {}, legacyFlat: false, existed: true };
+    }
+    if (isNestedSecretsMap(parsed)) {
+        // Empty {} is ambiguous but harmless as an empty nested map.
+        return { byEnv: parsed, legacyFlat: false, existed: true };
+    }
+    if (isStringRecord(parsed)) {
+        return { byEnv: { local: parsed }, legacyFlat: true, existed: true };
+    }
+    return { byEnv: {}, legacyFlat: false, existed: true };
+}
+/** Writes the nested secrets map and locks the file down to 0600. */
+function writeSecretsFile(secretsPath, byEnv) {
+    writeFileSync(secretsPath, JSON.stringify(byEnv, null, 2) + '\n');
+    try {
+        chmodSync(secretsPath, secretsFileMode);
+    }
+    catch {
+        // Best-effort on platforms/filesystems without POSIX modes.
+    }
+}
+/**
+ * Resolves a stored secret value. A value of the form `$ENV:VAR_NAME`
+ * indirects to `process.env.VAR_NAME`; a missing/empty env var resolves to ''
+ * and warns (once) naming the variable. All other values pass through.
+ */
+function resolveSecretValue(raw) {
+    const match = /^\$ENV:(.+)$/.exec(raw);
+    if (!match)
+        return raw;
+    const varName = match[1];
+    const fromEnv = process.env[varName];
+    if (fromEnv === undefined || fromEnv === '') {
+        warnOnce(`envvar:${varName}`, `[emberflow] secret indirection $ENV:${varName} is unset — resolving to empty. Set ${varName} in the environment.`);
+        return '';
+    }
+    return fromEnv;
+}
+/** True when the file is tracked by git. Safe/cheap; false when not a repo. */
+function isTrackedByGit(cwd, relPath) {
+    try {
+        execFileSync('git', ['ls-files', '--error-unmatch', relPath], {
+            cwd,
+            stdio: 'ignore',
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Warns (once per process) if the secrets file is group/other-readable or is
+ * tracked by git — both leak plaintext credentials.
+ */
+const hardeningChecked = new Set();
+function checkSecretsFileHardening(cwd, secretsPath) {
+    if (!existsSync(secretsPath))
+        return;
+    // Runs once per path per process — loadEnvironments is called on every
+    // GET /environments and we don't want to spawn `git` on that hot path.
+    if (hardeningChecked.has(secretsPath))
+        return;
+    hardeningChecked.add(secretsPath);
+    try {
+        const mode = statSync(secretsPath).mode & 0o777;
+        if ((mode & 0o077) !== 0) {
+            // Loose perms on a hand-written secrets file are fixable in place — do
+            // it and say so, rather than nagging on every load with no remediation.
+            try {
+                chmodSync(secretsPath, secretsFileMode);
+                console.info(`[emberflow] tightened ${SECRETS_FILENAME} to 0600`);
+            }
+            catch {
+                // Couldn't chmod (e.g. read-only filesystem) — fall back to warning
+                // since we weren't able to fix it ourselves.
+                warnOnce(`mode:${secretsPath}`, `[emberflow] SECURITY: ${SECRETS_FILENAME} is readable by group/other (mode 0${mode.toString(8)}); ` +
+                    `it holds plaintext secrets. Run: chmod 600 ${SECRETS_FILENAME}`);
+            }
+        }
+    }
+    catch {
+        // stat failure is non-fatal
+    }
+    if (isTrackedByGit(cwd, SECRETS_FILENAME)) {
+        warnOnce(`git:${secretsPath}`, `[emberflow] SECURITY: ${SECRETS_FILENAME} is tracked by git and holds plaintext secrets. ` +
+            `Remove it from the repo: git rm --cached ${SECRETS_FILENAME} (it should stay gitignored).`);
+    }
+}
+/** True when any environment still carries inline non-empty secret VALUES. */
+function needsMigration(parsed) {
+    for (const env of Object.values(parsed.environments)) {
+        const s = env.secrets;
+        if (s !== undefined && !Array.isArray(s) && Object.values(s).some((v) => v !== '')) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * One-time migration: moves inline secret VALUES out of environments.json into
+ * emberflow.secrets.json (0600), rewrites environments.json so each env's
+ * `secrets` is a list of key NAMES, and keeps a `.bak` of the original
+ * environments.json on first migration. Idempotent — after it runs there are
+ * no inline values left, so `needsMigration` returns false on the next load.
+ */
+function migrateEnvironmentsFile(environmentsPath, secretsPath, parsed) {
+    const backupPath = `${environmentsPath}.bak`;
+    if (!existsSync(backupPath)) {
+        copyFileSync(environmentsPath, backupPath);
+    }
+    const { byEnv } = readSecretsFile(secretsPath);
+    for (const [name, env] of Object.entries(parsed.environments)) {
+        const s = env.secrets;
+        if (s === undefined || Array.isArray(s))
+            continue;
+        const bucket = { ...(byEnv[name] ?? {}) };
+        for (const [key, value] of Object.entries(s)) {
+            // environments.json is the authoritative current source — its values win.
+            if (value !== '')
+                bucket[key] = value;
+        }
+        byEnv[name] = bucket;
+        env.secrets = Object.keys(s);
+    }
+    writeSecretsFile(secretsPath, byEnv);
+    writeFileSync(environmentsPath, JSON.stringify(parsed, null, 2) + '\n');
+    console.log(`[emberflow] Migrated inline secret values from ${ENVIRONMENTS_FILENAME} into ${SECRETS_FILENAME} (0600). ` +
+        `${ENVIRONMENTS_FILENAME} now holds secret key NAMES only; a .bak of the original was kept.`);
+}
+/**
+ * Merges an env's declared key names with the values present in the secrets
+ * file: resolved map = names ∪ secrets-file keys, value from the secrets file
+ * (with $ENV resolution) or '' when absent so requireSecret still throws.
+ */
+function resolveEnvironment(env, fileSecrets) {
+    const names = Array.isArray(env.secrets) ? env.secrets : Object.keys(env.secrets ?? {});
+    const keys = new Set([...names, ...Object.keys(fileSecrets ?? {})]);
+    const secrets = {};
+    for (const key of keys) {
+        const raw = fileSecrets?.[key];
+        secrets[key] = raw === undefined ? '' : resolveSecretValue(raw);
+    }
+    return {
+        vars: env.vars ?? {},
+        secrets,
+        ...(env.protected !== undefined ? { protected: env.protected } : {}),
+        ...(env.auth !== undefined ? { auth: env.auth } : {}),
+    };
+}
+/**
+ * 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 function resolveRunSafety(envName, env, request) {
+    const isProtected = !!env.protected;
+    if (request.safeMode === undefined) {
+        return { ok: true, safeMode: isProtected };
+    }
+    if (request.safeMode === false && isProtected && request.confirm !== envName) {
+        return { ok: false, error: `unsafe run on protected environment '${envName}' requires confirm` };
+    }
+    return { ok: true, safeMode: request.safeMode };
+}
+/**
+ * Loads `emberflow.environments.json` from `cwd`.
+ *
+ * - File present: parsed and validated; malformed files throw with a clear
+ *   message (meant to fail the boot loudly rather than run with bad config).
+ * - File absent but `emberflow.secrets.json` present: synthesizes a single
+ *   `local` environment from it (logs a hint to migrate) so existing setups
+ *   keep working.
+ * - Neither file present: an empty `local` environment (matches the previous
+ *   loadSecrets() behavior of defaulting to {} when nothing is configured).
+ *
+ * Secret VALUES are read from `emberflow.secrets.json` and merged onto the key
+ * NAMES declared in environments.json. A first load of an old-format file
+ * (inline values) auto-migrates the values out. See the helpers above.
+ */
+function parseEnvironmentsFile(environmentsPath) {
+    const raw = readFileSync(environmentsPath, 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${ENVIRONMENTS_FILENAME} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    validateShape(parsed);
+    return parsed;
+}
+export function loadEnvironments(cwd) {
+    const environmentsPath = resolve(cwd, ENVIRONMENTS_FILENAME);
+    const secretsPath = resolve(cwd, SECRETS_FILENAME);
+    if (existsSync(environmentsPath)) {
+        let parsed = parseEnvironmentsFile(environmentsPath);
+        if (needsMigration(parsed)) {
+            migrateEnvironmentsFile(environmentsPath, secretsPath, parsed);
+            // Re-read so the resolved view reflects the rewritten name-list file.
+            parsed = parseEnvironmentsFile(environmentsPath);
+        }
+        checkSecretsFileHardening(cwd, secretsPath);
+        const { byEnv } = readSecretsFile(secretsPath);
+        const environments = {};
+        for (const [name, env] of Object.entries(parsed.environments)) {
+            environments[name] = resolveEnvironment(env, byEnv[name]);
+        }
+        return { defaultEnvironment: parsed.defaultEnvironment, environments, configured: true };
+    }
+    if (existsSync(secretsPath)) {
+        console.log(`[emberflow] No ${ENVIRONMENTS_FILENAME} found; synthesizing a "local" environment from ${SECRETS_FILENAME}. ` +
+            `Create ${ENVIRONMENTS_FILENAME} to configure multiple environments (see emberflow.environments.example.json).`);
+        checkSecretsFileHardening(cwd, secretsPath);
+        const { byEnv } = readSecretsFile(secretsPath);
+        const names = Object.keys(byEnv);
+        const environments = {};
+        for (const name of names) {
+            environments[name] = resolveEnvironment({ secrets: Object.keys(byEnv[name]) }, byEnv[name]);
+        }
+        // Preserve the historical single synthesized-env behavior: always expose a
+        // "local" env even when the file was empty.
+        if (!environments.local) {
+            environments.local = { vars: {}, secrets: {} };
+        }
+        return {
+            defaultEnvironment: environments.local ? 'local' : names[0],
+            environments,
+            configured: true,
+        };
+    }
+    return {
+        defaultEnvironment: 'local',
+        environments: { local: { vars: {}, secrets: {} } },
+        configured: false,
+    };
+}
+// Serializes all environment-file read-modify-write cycles through a single
+// promise chain so concurrent setEnvironmentSecret calls can't clobber each
+// other (last-write-wins on a sync read-modify-write would drop a secret).
+let writeQueue = Promise.resolve();
+function enqueue(fn) {
+    const p = writeQueue.then(fn);
+    writeQueue = p.catch(() => { });
+    return p;
+}
+/** Current secret key NAMES for an env, from either on-disk shape. */
+function secretNames(env) {
+    return Array.isArray(env.secrets) ? [...env.secrets] : Object.keys(env.secrets ?? {});
+}
+/**
+ * Folds any pre-migration inline map VALUES into `bucket` so converting an
+ * env's `secrets` to a name list never drops a sibling key's value. File
+ * values already present win (they are the current source of truth).
+ */
+function foldInlineValues(env, bucket) {
+    if (Array.isArray(env.secrets) || !env.secrets)
+        return;
+    for (const [k, v] of Object.entries(env.secrets)) {
+        if (v !== '' && !(k in bucket))
+            bucket[k] = v;
+    }
+}
+/**
+ * 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 function setEnvironmentSecret(cwd, envName, key, value) {
+    return enqueue(() => {
+        const environmentsPath = resolve(cwd, ENVIRONMENTS_FILENAME);
+        const secretsPath = resolve(cwd, SECRETS_FILENAME);
+        const parsed = parseEnvironmentsFile(environmentsPath);
+        const env = parsed.environments[envName];
+        if (!env) {
+            throw new Error(`${ENVIRONMENTS_FILENAME}: unknown environment "${envName}"`);
+        }
+        // Value → secrets file (0600).
+        const { byEnv } = readSecretsFile(secretsPath);
+        const bucket = { ...(byEnv[envName] ?? {}) };
+        foldInlineValues(env, bucket);
+        bucket[key] = value;
+        byEnv[envName] = bucket;
+        writeSecretsFile(secretsPath, byEnv);
+        // Name → environments.json (list form).
+        const names = secretNames(env);
+        if (!names.includes(key))
+            names.push(key);
+        env.secrets = names;
+        writeFileSync(environmentsPath, JSON.stringify(parsed, null, 2) + '\n');
+    });
+}
+/**
+ * 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 function setEnvironmentAuth(cwd, envName, auth) {
+    return enqueue(() => {
+        if (auth !== null) {
+            const authError = validateAuthShape(auth);
+            if (authError !== null) {
+                throw new Error(`${ENVIRONMENTS_FILENAME}: environments.${envName}.${authError}`);
+            }
+        }
+        const environmentsPath = resolve(cwd, ENVIRONMENTS_FILENAME);
+        const parsed = parseEnvironmentsFile(environmentsPath);
+        const env = parsed.environments[envName];
+        if (!env) {
+            throw new Error(`${ENVIRONMENTS_FILENAME}: unknown environment "${envName}"`);
+        }
+        if (auth === null) {
+            delete env.auth;
+        }
+        else {
+            env.auth = auth;
+        }
+        writeFileSync(environmentsPath, JSON.stringify(parsed, null, 2) + '\n');
+    });
+}
+/**
+ * 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 function deleteEnvironmentSecret(cwd, envName, key) {
+    return enqueue(() => {
+        const environmentsPath = resolve(cwd, ENVIRONMENTS_FILENAME);
+        const secretsPath = resolve(cwd, SECRETS_FILENAME);
+        const parsed = parseEnvironmentsFile(environmentsPath);
+        const env = parsed.environments[envName];
+        if (!env) {
+            throw new Error(`${ENVIRONMENTS_FILENAME}: unknown environment "${envName}"`);
+        }
+        // Value out of the secrets file (preserving sibling inline values).
+        const { byEnv } = readSecretsFile(secretsPath);
+        const bucket = { ...(byEnv[envName] ?? {}) };
+        foldInlineValues(env, bucket);
+        delete bucket[key];
+        byEnv[envName] = bucket;
+        writeSecretsFile(secretsPath, byEnv);
+        // Name out of environments.json (normalizing to list form).
+        env.secrets = secretNames(env).filter((n) => n !== key);
+        writeFileSync(environmentsPath, JSON.stringify(parsed, null, 2) + '\n');
+    });
+}

package/dist/server/flowStore.d.ts

@@ -0,0 +1,37 @@
+import type { WorkflowDefinition } from '../src/engine/index.js';
+export interface FlowStoreOptions {
+    /**
+     * Project mode: scenarios live in <id>.scenarios.json next to the flow
+     * file (reviewable, hand-editable "stories"), not embedded in the flow.
+     */
+    scenarioSidecars?: boolean;
+}
+/**
+ * Runner-owned store of workflow files. Each flow lives at `<dir>/<id>.json`,
+ * pretty-printed. The directory is the source of truth when the runner is
+ * online; the browser adopts it on first successful health check.
+ */
+export declare class FlowStore {
+    readonly dir: string;
+    private readonly sidecars;
+    constructor(dir?: string, options?: FlowStoreOptions);
+    private sidecarPath;
+    /** Merge <id>.scenarios.json into the flow when sidecar mode is on. */
+    private withSidecar;
+    /** All parseable *.json flows. Unparseable files are skipped with a warning. */
+    list(): WorkflowDefinition[];
+    /** Load a single flow by id, or undefined when its file is missing/unparseable. */
+    load(id: string): WorkflowDefinition | undefined;
+    /** Persist a flow. Its id must be a non-empty string and names the file. */
+    save(flow: WorkflowDefinition): void;
+    /** Delete a flow file (and any scenario sidecar). Returns false when it did not exist. */
+    remove(id: string): boolean;
+    /** Seed the given flows only when the directory holds no json files yet. */
+    seedIfEmpty(flows: WorkflowDefinition[]): void;
+    /**
+     * Seed only flows the store doesn't know yet (by id). Existing copies —
+     * possibly user-edited — are never overwritten, so new built-in example
+     * flows appear after an upgrade without clobbering anything.
+     */
+    seedMissing(flows: WorkflowDefinition[]): void;
+}

package/dist/server/flowStore.js

@@ -0,0 +1,117 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+/**
+ * Runner-owned store of workflow files. Each flow lives at `<dir>/<id>.json`,
+ * pretty-printed. The directory is the source of truth when the runner is
+ * online; the browser adopts it on first successful health check.
+ */
+export class FlowStore {
+    dir;
+    sidecars;
+    constructor(dir = resolve(process.cwd(), 'workflows'), options = {}) {
+        this.dir = dir;
+        this.sidecars = options.scenarioSidecars ?? false;
+        mkdirSync(this.dir, { recursive: true });
+    }
+    sidecarPath(id) {
+        return join(this.dir, `${id}.scenarios.json`);
+    }
+    /** Merge <id>.scenarios.json into the flow when sidecar mode is on. */
+    withSidecar(flow) {
+        if (!this.sidecars)
+            return flow;
+        const path = this.sidecarPath(flow.id);
+        if (!existsSync(path))
+            return flow;
+        try {
+            const scenarios = JSON.parse(readFileSync(path, 'utf8'));
+            return Array.isArray(scenarios) && scenarios.length > 0 ? { ...flow, scenarios } : flow;
+        }
+        catch (err) {
+            console.warn(`[flowStore] skipping unparseable ${flow.id}.scenarios.json: ${String(err)}`);
+            return flow;
+        }
+    }
+    /** All parseable *.json flows. Unparseable files are skipped with a warning. */
+    list() {
+        const flows = [];
+        for (const file of readdirSync(this.dir)) {
+            if (!file.endsWith('.json') || file.endsWith('.scenarios.json'))
+                continue;
+            const path = join(this.dir, file);
+            try {
+                const flow = JSON.parse(readFileSync(path, 'utf8'));
+                flows.push(this.withSidecar(flow));
+            }
+            catch (err) {
+                console.warn(`[flowStore] skipping unparseable ${file}: ${String(err)}`);
+            }
+        }
+        return flows;
+    }
+    /** Load a single flow by id, or undefined when its file is missing/unparseable. */
+    load(id) {
+        const path = join(this.dir, `${id}.json`);
+        if (!existsSync(path))
+            return undefined;
+        try {
+            const flow = JSON.parse(readFileSync(path, 'utf8'));
+            return this.withSidecar(flow);
+        }
+        catch (err) {
+            console.warn(`[flowStore] skipping unparseable ${id}.json: ${String(err)}`);
+            return undefined;
+        }
+    }
+    /** Persist a flow. Its id must be a non-empty string and names the file. */
+    save(flow) {
+        if (!flow || typeof flow.id !== 'string' || flow.id.length === 0) {
+            throw new Error('Flow must have a non-empty string id');
+        }
+        const path = join(this.dir, `${flow.id}.json`);
+        if (this.sidecars) {
+            const { scenarios, ...rest } = flow;
+            writeFileSync(path, `${JSON.stringify(rest, null, 2)}\n`, 'utf8');
+            const sidecar = this.sidecarPath(flow.id);
+            if (scenarios && scenarios.length > 0) {
+                writeFileSync(sidecar, `${JSON.stringify(scenarios, null, 2)}\n`, 'utf8');
+            }
+            else if (existsSync(sidecar)) {
+                unlinkSync(sidecar);
+            }
+            return;
+        }
+        writeFileSync(path, `${JSON.stringify(flow, null, 2)}\n`, 'utf8');
+    }
+    /** Delete a flow file (and any scenario sidecar). Returns false when it did not exist. */
+    remove(id) {
+        const sidecar = this.sidecarPath(id);
+        if (existsSync(sidecar))
+            unlinkSync(sidecar);
+        const path = join(this.dir, `${id}.json`);
+        if (!existsSync(path))
+            return false;
+        unlinkSync(path);
+        return true;
+    }
+    /** Seed the given flows only when the directory holds no json files yet. */
+    seedIfEmpty(flows) {
+        const hasJson = readdirSync(this.dir).some((f) => f.endsWith('.json') && !f.endsWith('.scenarios.json'));
+        if (hasJson)
+            return;
+        for (const flow of flows)
+            this.save(flow);
+    }
+    /**
+     * Seed only flows the store doesn't know yet (by id). Existing copies —
+     * possibly user-edited — are never overwritten, so new built-in example
+     * flows appear after an upgrade without clobbering anything.
+     */
+    seedMissing(flows) {
+        const known = new Set(this.list().map((f) => f.id));
+        for (const flow of flows) {
+            if (!known.has(flow.id))
+                this.save(flow);
+        }
+    }
+}

package/dist/server/httpOperations.d.ts

@@ -0,0 +1,32 @@
+import type { RequestHandler } from 'express';
+import { type AuthPolicy, type WorkflowDefinition } from '../src/engine/index.js';
+import type { RunRegistry } from './runRegistry.js';
+import type { VerifierRegistry } from './auth/verifiers.js';
+/**
+ * Build the Express handler for a single routed operation: request in
+ * ({params, query, body, headers}), schema-validate the body, run the
+ * operation through the SAME engine path the studio "Run" uses
+ * (`RunRegistry`), map the finished run to an HTTP response.
+ *
+ * The run input is the request body's own fields spread at the top level
+ * (so `from('input', 'ppv')` resolves a domain field posted in the body),
+ * PLUS the full request shape (`params`/`query`/`body`/`headers`/`user`)
+ * layered on top — the latter always wins on key collisions, and ops that
+ * read `input.body.x` keep working unchanged.
+ */
+/** The environment values a routed operation runs with — resolved once at
+ *  boot from the project's default environment (see server/index.ts). Falls
+ *  back to empty secrets/vars when omitted (e.g. in unit tests). */
+export interface OperationRunEnv {
+    secrets: Record<string, string>;
+    vars: Record<string, string>;
+    environment: string;
+    safeMode: boolean;
+}
+export declare function makeOperationHandler(deps: {
+    runs: RunRegistry;
+    op: WorkflowDefinition;
+    env?: OperationRunEnv;
+    policy?: AuthPolicy | null;
+    verifiers?: VerifierRegistry;
+}): RequestHandler;