@xdelivered/emberflow 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick McCurley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# Emberflow
+
+Emberflow gives your project a visual studio for **API operations modelled as
+node graphs** — build an endpoint by wiring nodes, run it, test it, and ship it
+from one place. Every operation runs in two modes from day one: **real**
+(against your live environments) and **mock** (design-first, driven by scenario
+data, nothing real touched). It is **agent-native** — Codex and Claude Code can
+author flows, scenarios, nodes, and environments for you through installed
+skills, and a scout that reads your codebase so agents reuse the infrastructure
+you already have.
+
+A consumer should be running in about five minutes. Read on, or jump to the
+[CLI cheatsheet](#cli-cheatsheet).
+
+## Quick start
+
+> **⚠ Publish pending.** The package is scoped as `@xdelivered/emberflow`
+> (the bare name `emberflow` on npm belongs to an unrelated package — don't
+> `npm i emberflow`). Until the scoped package is published, install from
+> **git** or a **packed tarball** (both fully supported, both ship or build
+> the studio + runner). **Full instructions: [INSTALL.md](INSTALL.md).**
+
+```sh
+# add Emberflow to a project — git install (runs a guarded `prepare` build):
+npm i -D 'git+https://github.com/pmccurley87/emberflow.git'
+
+# …or from a packed tarball (built from a checkout of this repo):
+npm pack                     # in the emberflow checkout → xdelivered-emberflow-0.2.0.tgz
+npm i -D ../path/to/xdelivered-emberflow-0.2.0.tgz
+
+# then, in your project:
+npx emberflow init           # asks JS or TS, scaffolds config + a hello op + agent skills
+```
+
+Once published, this becomes `npm i -D @xdelivered/emberflow` /
+`npm create @xdelivered/emberflow` — the scaffolding is already wired for it.
+
+`init` asks one question — **JavaScript or TypeScript?** (`--js` / `--ts` to
+skip the prompt) — and that decides your runtime:
+
+- **`--js`** (default) scaffolds `emberflow.config.mjs` with JSDoc types. Runs
+  on **plain Node** against Emberflow's compiled `dist/` — **no `tsx`**.
+- **`--ts`** scaffolds `emberflow.config.ts` + a `tsconfig.json` and asks you to
+  `npm i -D tsx typescript`. The runner boots your TypeScript under `tsx`.
+
+`init` scaffolds: the config file, `emberflow/apis/default/hello` (a working
+example operation + its scenarios), and the four Emberflow agent skills into
+whatever harness it detects (`.claude/` and/or `.codex/`, global or local).
+
+## First run — the welcome checklist
+
+The studio opens on a **welcome checklist** for a fresh project (reach it any
+time from the toolbar's **Setup** item). Each row is one setup step with a
+status glyph and a button that deep-links to the surface that fixes it:
+
+- **Coding agent detected** — shows which of Codex / Claude Code is on your
+  `PATH`, with the detected **version** (a stale CLI that rejects modern models
+  is surfaced honestly, not hidden).
+- **Environments configured** — Emberflow splits config from secrets across two
+  files:
+  - `emberflow.environments.json` — **committed-safe**: environment names,
+    non-secret `vars` (URLs, ids, flags), `protected` flags, and the *names* of
+    the secrets each environment needs. Never any secret value.
+  - `emberflow.secrets.json` — **git-ignored, `chmod 600`**: the actual values,
+    keyed by environment. Agents never read it. A value of `"$ENV:VAR_NAME"`
+    resolves from `process.env` at load.
+- **Secrets present** for the default environment.
+- **Agent skills installed** (re-run `npx emberflow init` to add them).
+- **Infrastructure scouted** — dispatches the scout (below).
+- **First operation** — open the hello op or ask the agent to build one.
+
+A brand-new project **starts in Mock**: with no environments there is nothing
+real to serve against, so everything previews from scenarios until you
+deliberately create an environment. The environment dropdown (top-right) is the
+single mode control — **Mock** is its first row, real environments follow, and
+switching to a real one crosses a "Go live?" confirmation.
+
+## The infrastructure scout
+
+Point an agent at a brownfield repo and the **scout** reads it — dependencies,
+lockfiles, ORM schemas, config files, env-var references, HTTP/SDK usage — and
+writes a **committed, secrets-free manifest** at `emberflow/infrastructure.json`
+describing what your project already uses. The studio's **Infra** dock tab
+renders it, and agents read it before authoring operations so they **reuse**
+your real databases/APIs/providers instead of inventing parallel config.
+
+```json
+{
+  "version": 1,
+  "greenfield": false,
+  "summary": "Express app with Postgres (Prisma), Stripe, and SendGrid.",
+  "items": [
+    {
+      "id": "postgres-main",
+      "kind": "database",
+      "name": "Postgres (Prisma)",
+      "evidence": [{ "file": "prisma/schema.prisma", "note": "datasource provider=postgresql" }],
+      "suggestedSecretRefs": ["DATABASE_URL"],
+      "notes": "Schema defines User, Order, Invoice models."
+    }
+  ]
+}
+```
+
+Names and env-var **names** only — never values. Run it from the welcome
+checklist or the agent panel; it needs a coding agent on your `PATH`.
+
+## Building APIs
+
+You build operations visually (drag nodes, wire them, set HTTP metadata), and
+your own code plugs in as **custom nodes** registered in the config's
+`registerNodes(registry)` — they run server-side next to your app, so they reach
+your DB and services. Or hand it to an agent: the installed **skills** teach it
+Emberflow's file layout, node mechanics, and review rubric, and it consults the
+**scout manifest** first so it reuses your infrastructure. Ask in the agent
+panel ("build a checkout endpoint"), and it authors the flow, scenarios, and any
+new nodes, then runs `doctor` to clean up before finishing.
+
+**Operational commit posture** — an operation runs at one of three levels:
+
+- **Mock** — infrastructure nodes return canned scenario outputs; nothing real
+  is ever touched, no auth attached. Design-time default.
+- **Dry-run** — real environment, but mutation nodes with `config.commit`
+  unset (or a protected env's safe-mode on) perform reads and log what they
+  *would* write, without doing it.
+- **Commit** — `config.commit === true` on a real, unprotected env: mutation
+  nodes perform the real side effect. Faking success on the commit path is
+  forbidden and `doctor` flags it.
+
+## CLI cheatsheet
+
+| Command | What it does |
+|---|---|
+| `emberflow init [--js\|--ts] [--global\|--local] [--no-skills] [--no-launch]` | scaffold config, example op, agent skills |
+| `emberflow dev [--port N] [--project DIR]` | studio + runner in one process, opens the browser |
+| `emberflow serve [--port N] [--mock]` | run the API host headless (no studio) |
+| `emberflow test [opId] [--environment NAME] [--json]` | assert scenario `expect` blocks in-process (CI-ready) |
+| `emberflow doctor [opId] [--fix]` | report/repair operation invariants in-process |
+| `emberflow run <opId> [--scenario NAME]` | run an operation against a live runner |
+| `emberflow list-environments` / `login-environment <name>` | inspect / authenticate an environment |
+| `emberflow mcp` | serve the MCP tools (list/get/save/validate/run workflows) |
+
+## Docs
+
+Depth on each area lives under [`docs/superpowers/specs/`](docs/superpowers/specs/):
+
+- [Consuming Emberflow](docs/superpowers/specs/2026-07-05-consuming-emberflow.md) — config, custom nodes, runtime matrix.
+- [Agent-native usage](docs/superpowers/specs/2026-07-06-agent-native-usage.md) — how the studio dispatches agents.
+- [HTTP API endpoints](docs/superpowers/specs/2026-07-07-api-endpoints-usage.md) — auth policies, Response nodes, mock serving.
+- [Onboarding & scout design](docs/superpowers/specs/2026-07-12-onboarding-infra-scout-design.md) — welcome checklist + infrastructure scout.
+
+Working on Emberflow itself? See [CONTRIBUTING.md](CONTRIBUTING.md).
+</content>

package/bin/commands.test.ts

@@ -0,0 +1,185 @@
+import { mkdtempSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+// Spy on spawn so runDev/runServe/launchServer never actually spawn a child
+// process during these tests — we only care about what commands.ts decided
+// to launch (or not).
+const spawnCalls: Array<{ cmd: string; args: string[]; env: Record<string, string | undefined> }> = [];
+vi.mock('node:child_process', () => ({
+  spawn: (cmd: string, args: string[], opts: { env: Record<string, string | undefined> }) => {
+    spawnCalls.push({ cmd, args, env: opts.env });
+    const listeners: Record<string, ((code: number) => void)[]> = {};
+    queueMicrotask(() => listeners.exit?.forEach((cb) => cb(0)));
+    return { on: (event: string, cb: (code: number) => void) => {
+      (listeners[event] ??= []).push(cb);
+    } };
+  },
+}));
+
+const { parseArgs, runCommand } = await import('./commands');
+
+describe('parseArgs', () => {
+  it('parses dev with flags', () => {
+    expect(parseArgs(['dev', '--port', '9000', '--project', './x'])).toEqual({
+      command: 'dev', port: 9000, project: './x', scenario: undefined, rest: [],
+    });
+  });
+  it('defaults to help when no command', () => {
+    expect(parseArgs([]).command).toBe('help');
+  });
+  it('parses run with a flow and scenario', () => {
+    const p = parseArgs(['run', 'order-triage', '--scenario', 'vip']);
+    expect(p.command).toBe('run');
+    expect(p.rest).toEqual(['order-triage']);
+    expect(p.scenario).toBe('vip');
+  });
+  it('parses init with --no-skills', () => {
+    const p = parseArgs(['init', '--no-skills']);
+    expect(p.command).toBe('init');
+    expect(p.noSkills).toBe(true);
+  });
+  it('defaults noSkills to undefined when absent', () => {
+    expect(parseArgs(['init']).noSkills).toBeUndefined();
+  });
+  it('parses --global as scope global', () => {
+    expect(parseArgs(['init', '--global']).scope).toBe('global');
+  });
+  it('parses --local as scope repo', () => {
+    expect(parseArgs(['init', '--local']).scope).toBe('repo');
+  });
+  it('parses --no-launch', () => {
+    expect(parseArgs(['init', '--no-launch']).noLaunch).toBe(true);
+  });
+  it('parses the serve command with flags', () => {
+    expect(parseArgs(['serve', '--port', '9001', '--project', './p'])).toEqual({
+      command: 'serve', port: 9001, project: './p', scenario: undefined, rest: [],
+    });
+  });
+  it('parses --js', () => {
+    expect(parseArgs(['init', '--js']).js).toBe(true);
+  });
+  it('parses --ts', () => {
+    expect(parseArgs(['init', '--ts']).ts).toBe(true);
+  });
+});
+
+describe('runCommand init --js/--ts', () => {
+  it('errors when both --js and --ts are passed', async () => {
+    const errors: unknown[] = [];
+    const origError = console.error;
+    console.error = (...args: unknown[]) => { errors.push(args); };
+    try {
+      const code = await runCommand(parseArgs(['init', '--js', '--ts', '--no-skills', '--no-launch']));
+      expect(code).toBe(1);
+      expect(errors.join(' ')).toContain('mutually exclusive');
+    } finally {
+      console.error = origError;
+    }
+  });
+});
+
+// Repo root — a nested scratch dir here still resolves `tsx` by walking up to
+// this repo's own node_modules, which is what a "tsx IS resolvable" fixture
+// needs without faking a whole install.
+const REPO_ROOT = process.cwd();
+
+function withCwd<T>(dir: string, fn: () => Promise<T>): Promise<T> {
+  const prev = process.cwd();
+  process.chdir(dir);
+  return fn().finally(() => process.chdir(prev));
+}
+
+function silenceLog<T>(fn: () => Promise<T>): Promise<T> {
+  const orig = console.log;
+  console.log = () => {};
+  return fn().finally(() => { console.log = orig; });
+}
+
+describe('runCommand init --ts auto-launch (stale vs fresh runtime decision)', () => {
+  const dirs: string[] = [];
+  afterEach(() => {
+    for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+    spawnCalls.length = 0;
+  });
+
+  it('skips the launch and prints guidance when tsx is not resolvable from the project', async () => {
+    const d = mkdtempSync(join(tmpdir(), 'ef-cmd-notsx-'));
+    dirs.push(d);
+    const logs: string[] = [];
+    const origLog = console.log;
+    console.log = (...args: unknown[]) => { logs.push(args.join(' ')); };
+    try {
+      const code = await withCwd(d, () => runCommand(parseArgs(['init', '--ts', '--no-skills'])));
+      expect(code).toBe(0);
+      expect(spawnCalls).toEqual([]); // no launch attempt at all
+      const out = logs.join('\n');
+      expect(out).toContain('npm i -D tsx typescript');
+      expect(out).toContain('npx emberflow dev');
+    } finally {
+      console.log = origLog;
+    }
+  });
+
+  it('re-decides the runtime against the scaffolded project when tsx IS resolvable, instead of trusting the stale bin-startup context', async () => {
+    // A "consumer install" context decided BEFORE scaffolding: dist/ present,
+    // no src/, decided runnerMode 'node' (no config existed yet at bin startup).
+    const consumerRoot = mkdtempSync(join(tmpdir(), 'ef-cmd-consumer-'));
+    mkdirSync(join(consumerRoot, 'dist'));
+    dirs.push(consumerRoot);
+    // Project dir nested under THIS repo so tsx resolves via the repo's own
+    // node_modules (see REPO_ROOT comment above).
+    const projectDir = mkdtempSync(join(REPO_ROOT, '.tmp-ef-cmd-project-'));
+    dirs.push(projectDir);
+    const staleCtx = { runnerMode: 'node' as const, packageRoot: consumerRoot };
+
+    await silenceLog(async () => {
+      const code = await withCwd(projectDir, () =>
+        runCommand(parseArgs(['init', '--ts', '--no-skills']), staleCtx)
+      );
+      expect(code).toBe(0);
+    });
+
+    // The launched server process is spawned via `npx tsx …` (fresh decision),
+    // NOT plain `node …` (the stale decision passed in as staleCtx.runnerMode).
+    const serverLaunch = spawnCalls.find((c) =>
+      c.args.some((a) => a.endsWith('index.ts') || a.endsWith('index.js'))
+    );
+    expect(serverLaunch?.cmd).toBe('npx');
+    expect(serverLaunch?.args).toContain('tsx');
+  });
+});
+
+describe('runDev/runServe project-dir precedence (EMBERFLOW_PROJECT env first)', () => {
+  afterEach(() => { spawnCalls.length = 0; delete process.env.EMBERFLOW_PROJECT; });
+
+  it('dev: an already-set EMBERFLOW_PROJECT wins over cwd when --project is absent', async () => {
+    process.env.EMBERFLOW_PROJECT = '/env/project';
+    await runCommand(parseArgs(['dev']));
+    expect(spawnCalls[0]?.env.EMBERFLOW_PROJECT).toBe('/env/project');
+  });
+
+  it('dev: --project wins over cwd when EMBERFLOW_PROJECT is unset', async () => {
+    const code = await runCommand(parseArgs(['dev', '--project', './somewhere']));
+    void code;
+    expect(spawnCalls[0]?.env.EMBERFLOW_PROJECT).toBe(join(process.cwd(), 'somewhere'));
+  });
+
+  it('dev: EMBERFLOW_PROJECT wins over --project when both are set', async () => {
+    process.env.EMBERFLOW_PROJECT = '/env/project';
+    await runCommand(parseArgs(['dev', '--project', './somewhere']));
+    expect(spawnCalls[0]?.env.EMBERFLOW_PROJECT).toBe('/env/project');
+  });
+
+  it('dev: falls back to cwd when neither env nor --project is set', async () => {
+    await runCommand(parseArgs(['dev']));
+    expect(spawnCalls[0]?.env.EMBERFLOW_PROJECT).toBe(process.cwd());
+  });
+
+  it('serve: same precedence as dev', async () => {
+    process.env.EMBERFLOW_PROJECT = '/env/project';
+    await runCommand(parseArgs(['serve', '--project', './somewhere']));
+    expect(spawnCalls[0]?.env.EMBERFLOW_PROJECT).toBe('/env/project');
+  });
+});

package/bin/commands.ts

@@ -0,0 +1,306 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { createInterface } from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import { decideRuntime, resolveProjectDir } from './runtime.mjs';
+
+export interface ParsedArgs {
+  command: string;
+  port?: number;
+  project?: string;
+  scenario?: string;
+  noSkills?: boolean;
+  scope?: 'global' | 'repo';
+  noLaunch?: boolean;
+  mock?: boolean;
+  js?: boolean;
+  ts?: boolean;
+  rest: string[];
+}
+
+/** How the bin decided to run — passed down from bin/emberflow.mjs (see
+ *  bin/runtime.mjs). `runnerMode` selects `node dist/server/*.js` vs a tsx spawn;
+ *  `packageRoot` is the real package root (bin/emberflow.mjs is never in dist, so
+ *  it always resolves this correctly — unlike this module's own location, which
+ *  is dist/bin/commands.js when compiled). */
+export interface RuntimeContext {
+  runnerMode: 'node' | 'tsx';
+  packageRoot: string;
+}
+
+export function parseArgs(argv: string[]): ParsedArgs {
+  const [command = 'help', ...tail] = argv;
+  const out: ParsedArgs = { command, rest: [] };
+  for (let i = 0; i < tail.length; i++) {
+    const a = tail[i];
+    if (a === '--port') out.port = Number(tail[++i]);
+    else if (a === '--project') out.project = tail[++i];
+    else if (a === '--scenario') out.scenario = tail[++i];
+    else if (a === '--no-skills') out.noSkills = true;
+    else if (a === '--global') out.scope = 'global';
+    else if (a === '--local') out.scope = 'repo';
+    else if (a === '--no-launch') out.noLaunch = true;
+    else if (a === '--mock') out.mock = true;
+    else if (a === '--js') out.js = true;
+    else if (a === '--ts') out.ts = true;
+    else out.rest.push(a);
+  }
+  return out;
+}
+
+/** Ask the user whether to install skills globally or per-repo. Guarded on TTY so
+ *  it never hangs a non-interactive run (tests, CI, piped input). */
+function promptScope(): Promise<'global' | 'repo'> {
+  if (!process.stdin.isTTY) return Promise.resolve('repo');
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((res) => {
+    rl.question(
+      'Install Emberflow skills for [g]lobal (all projects) or [r]epo (this project)? [r] ',
+      (answer) => {
+        rl.close();
+        res(answer.trim().toLowerCase().startsWith('g') ? 'global' : 'repo');
+      }
+    );
+  });
+}
+
+/** Ask the user which language to author their APIs/nodes in. Same TTY guard as
+ *  promptScope — never hangs a non-interactive run (tests, CI, piped input),
+ *  defaulting to javascript. */
+function promptLanguage(): Promise<'javascript' | 'typescript'> {
+  if (!process.stdin.isTTY) return Promise.resolve('javascript');
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((res) => {
+    rl.question(
+      'Author your APIs in [j]avascript or [t]ypescript? [j] ',
+      (answer) => {
+        rl.close();
+        res(answer.trim().toLowerCase().startsWith('t') ? 'typescript' : 'javascript');
+      }
+    );
+  });
+}
+
+/** Fallback package root used when runCommand is called without a RuntimeContext
+ *  (e.g. a direct unit test). In normal use bin/emberflow.mjs passes the real
+ *  root — important because this module compiles to dist/bin/commands.js, whose
+ *  own `..` is dist/, not the package root. */
+const selfPkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+const defaultCtx: RuntimeContext = { runnerMode: 'tsx', packageRoot: selfPkgRoot };
+
+/** Spawn `tsx <entry>` inheriting stdio, with extra env. Returns the child's exit code. */
+function runTsx(
+  ctx: RuntimeContext,
+  entry: string,
+  env: Record<string, string>,
+  args: string[] = [],
+): Promise<number> {
+  return new Promise((res) => {
+    const child = spawn('npx', ['tsx', join(ctx.packageRoot, entry), ...args], {
+      stdio: 'inherit',
+      env: { ...process.env, ...env },
+    });
+    child.on('exit', (code) => res(code ?? 0));
+  });
+}
+
+/** Spawn `node <entry>` inheriting stdio, with extra env. Used for JS consumers,
+ *  where the compiled dist/server runs on plain Node (no tsx child — so it works
+ *  inside the codex sandbox). */
+function runNode(entry: string, env: Record<string, string>, args: string[] = []): Promise<number> {
+  return new Promise((res) => {
+    const child = spawn(process.execPath, [entry, ...args], {
+      stdio: 'inherit',
+      env: { ...process.env, ...env },
+    });
+    child.on('exit', (code) => res(code ?? 0));
+  });
+}
+
+/** Launch a server entry ('index' or 'mcp') in the mode the bin decided: plain
+ *  `node dist/server/<name>.js` for JS consumers, `tsx server/<name>.ts` otherwise. */
+function launchServer(
+  ctx: RuntimeContext,
+  name: 'index' | 'mcp',
+  env: Record<string, string>,
+  args: string[] = [],
+): Promise<number> {
+  if (ctx.runnerMode === 'node') {
+    return runNode(join(ctx.packageRoot, 'dist', 'server', `${name}.js`), env, args);
+  }
+  return runTsx(ctx, join('server', `${name}.ts`), env, args);
+}
+
+/** Build (if needed) and launch the studio dev server. Shared by `dev` and by
+ *  `init` (which launches after scaffolding unless --no-launch is passed). */
+async function runDev(p: ParsedArgs, ctx: RuntimeContext): Promise<number> {
+  // Same precedence as bin/runtime.mjs's decideRuntime (EMBERFLOW_PROJECT env →
+  // --project flag → cwd) so the launched process boots the same project the
+  // runtime decision was made against — a bare --project flag no longer
+  // silently overwrites an already-set EMBERFLOW_PROJECT.
+  const project = resolveProjectDir(p.project ? ['--project', p.project] : [], process.env, process.cwd());
+  // From a consumer install the shipped studio-dist exists; from source it may not.
+  if (!existsSync(join(ctx.packageRoot, 'studio-dist'))) {
+    console.log('[emberflow] building studio…');
+    await runTsx(ctx, 'node_modules/.bin/vite', {}, ['build']).catch(() => 0);
+  }
+  return launchServer(ctx, 'index', {
+    EMBERFLOW_SERVE_STUDIO: '1',
+    EMBERFLOW_PROJECT: project,
+    // `dev` runs a single (non-watch) process, so opening the browser once
+    // is the intended UX. (The server default is off so this repo's watch-mode
+    // `npm run server` doesn't spawn a tab per restart — see server/index.ts.)
+    EMBERFLOW_OPEN_BROWSER: '1',
+    ...(p.port ? { EMBERFLOW_RUNNER_PORT: String(p.port) } : {}),
+    ...(p.mock ? { EMBERFLOW_MOCK: '1' } : {}),
+  });
+}
+
+/** Run the runner headless: API + operation routes, NO studio, NO browser.
+ *  This is the production-ish API host — `dev` additionally serves the studio
+ *  and opens a browser tab. */
+function runServe(p: ParsedArgs, ctx: RuntimeContext): Promise<number> {
+  // See runDev's comment: same EMBERFLOW_PROJECT-first precedence as
+  // bin/runtime.mjs's resolveProjectDir.
+  const project = resolveProjectDir(p.project ? ['--project', p.project] : [], process.env, process.cwd());
+  return launchServer(ctx, 'index', {
+    EMBERFLOW_PROJECT: project,
+    ...(p.port ? { EMBERFLOW_RUNNER_PORT: String(p.port) } : {}),
+    ...(p.mock ? { EMBERFLOW_MOCK: '1' } : {}),
+  });
+}
+
+export async function runCommand(p: ParsedArgs, ctx: RuntimeContext = defaultCtx): Promise<number> {
+  const pkgRoot = ctx.packageRoot;
+  switch (p.command) {
+    case 'dev':
+      return runDev(p, ctx);
+    case 'serve':
+      return runServe(p, ctx);
+    case 'mcp':
+      return launchServer(ctx, 'mcp', {});
+    case 'run': {
+      // In-process via tsx's register() loader — NO `tsx` child spawn, so it
+      // works inside the codex sandbox (tsx's IPC pipe is blocked there).
+      const args = ['run', ...p.rest, ...(p.scenario ? ['--scenario', p.scenario] : [])];
+      return (await import('../server/cli')).runCli(args);
+    }
+    case 'list-nodes':
+    case 'node-schema':
+    case 'list-workflows':
+    case 'get-workflow':
+    case 'list-environments':
+    case 'login-environment':
+    case 'set-environment-auth':
+    case 'serving':
+    case 'validate':
+    case 'publish':
+    case 'save':
+    case 'samples':
+    case 'create':
+    case 'delete':
+    case 'rename': {
+      // Rich CLI operation commands, also in-process (no `tsx` child spawn).
+      return (await import('../server/cli')).runCli([p.command, ...p.rest]);
+    }
+    case 'test': {
+      // In-process scenario suite runner — NO runner process. Needs the
+      // project dir (server/cli.ts's `test` case reads EMBERFLOW_PROJECT),
+      // same convention runDev/runServe use for --project.
+      if (p.project) process.env.EMBERFLOW_PROJECT = resolve(process.cwd(), p.project);
+      // --mock is parsed globally (dev/serve read it as EMBERFLOW_MOCK), so it
+      // never lands in p.rest — thread it through explicitly here.
+      return (await import('../server/cli')).runCli(['test', ...p.rest, ...(p.mock ? ['--mock'] : [])]);
+    }
+    case 'doctor': {
+      // In-process operation diagnostics — NO runner process, same
+      // EMBERFLOW_PROJECT convention as `test`.
+      if (p.project) process.env.EMBERFLOW_PROJECT = resolve(process.cwd(), p.project);
+      return (await import('../server/cli')).runCli(['doctor', ...p.rest]);
+    }
+    case 'init': {
+      // bin/init compiles alongside this module (dist/bin/init.js when built),
+      // so resolve the guard against THIS module's own location + extension —
+      // init.ts under tsx source, init.js under plain-node dist.
+      const initExt = import.meta.url.endsWith('.js') ? '.js' : '.ts';
+      const initEntry = fileURLToPath(new URL(`./init${initExt}`, import.meta.url));
+      if (!existsSync(initEntry)) {
+        console.log('emberflow init lands in a later step');
+        return 0;
+      }
+      if (p.js && p.ts) {
+        console.error('[emberflow] --js and --ts are mutually exclusive');
+        return 1;
+      }
+      try {
+        const mod = (await import('./init')) as {
+          runInit: (
+            cwd: string,
+            opts?: {
+              skills?: false | { scope: 'repo' | 'global'; home: string };
+              packageRoot?: string;
+              language?: 'javascript' | 'typescript';
+            }
+          ) => Promise<number>;
+          tsxResolvable: (cwd: string) => boolean;
+        };
+        const scope = p.scope ?? (await promptScope());
+        const language = p.js ? 'javascript' : p.ts ? 'typescript' : await promptLanguage();
+        const code = await mod.runInit(
+          process.cwd(),
+          p.noSkills
+            ? { skills: false, packageRoot: pkgRoot, language }
+            : { skills: { scope, home: homedir() }, packageRoot: pkgRoot, language }
+        );
+        if (code !== 0) return code;
+
+        console.log('');
+        console.log('[emberflow] next steps:');
+        console.log('  - run `npx emberflow dev` any time to relaunch the studio');
+        console.log(
+          p.noSkills
+            ? '  - skills were not installed (--no-skills)'
+            : `  - skills installed at ${scope === 'global' ? '~' : '.'}/.claude (and/or .codex) /skills`
+        );
+        console.log('  - your operations live in emberflow/apis (open the studio to build them)');
+        console.log('');
+
+        if (p.noLaunch) return 0;
+
+        // `ctx` reflects the runtime decision made at bin startup — BEFORE
+        // scaffolding existed. For a fresh TS project that decision was made with
+        // no config on disk (→ node mode), which then dies launching against the
+        // just-scaffolded emberflow.config.ts. Re-decide against the now-real
+        // project instead of trusting the stale context.
+        if (language === 'typescript') {
+          if (!mod.tsxResolvable(process.cwd())) {
+            console.log('');
+            console.log('[emberflow] tsx is not installed — skipping auto-launch.');
+            console.log('  npm i -D tsx typescript');
+            console.log('  npx emberflow dev');
+            return 0;
+          }
+          const decision = decideRuntime({ packageRoot: pkgRoot, projectDir: process.cwd(), env: process.env });
+          console.log('[emberflow] Starting Emberflow…');
+          return runDev(p, { runnerMode: decision.runnerMode as 'node' | 'tsx', packageRoot: pkgRoot });
+        }
+
+        console.log('[emberflow] Starting Emberflow…');
+        return runDev(p, ctx);
+      } catch (err) {
+        console.error('[emberflow] init failed:', err instanceof Error ? err.message : err);
+        return 1;
+      }
+    }
+    default:
+      console.log(
+        'Usage: emberflow <dev|serve|mcp|init|run|test|doctor|list-nodes|node-schema|list-workflows|get-workflow|list-environments|login-environment|set-environment-auth|serving|validate|publish|save|create|delete|rename|samples> [--port N] [--project DIR] [--scenario NAME] [--no-skills] [--global|--local] [--no-launch] [--mock] [--js|--ts]\n' +
+          '  test [opId] [--environment NAME] [--json]   Run scenario expectations in-process (no runner) — exit 0/1/2\n' +
+          '  doctor [opId] [--fix]                       Diagnose operation(s) in-process (no runner); --fix seeds param defaults — exit 0/1/2'
+      );
+      return 0;
+  }
+}