@xdelivered/emberflow 0.2.0

package/bin/runtime.test.ts

@@ -0,0 +1,167 @@
+import { describe, expect, it } from 'vitest';
+import { join } from 'node:path';
+import {
+  configBasenameFor,
+  decideRuntime,
+  resolveProjectDir,
+  TSX_MISSING_MESSAGE,
+} from './runtime.mjs';
+
+// A fake filesystem: `decideRuntime`/`configBasenameFor` take an injectable
+// `fsExists`, so the whole decision matrix runs without touching disk.
+function fsWith(paths: string[]) {
+  const set = new Set(paths);
+  return (p: import('node:fs').PathLike) => set.has(String(p));
+}
+
+// An installed JS consumer: package under node_modules, dist present, no src.
+const CONSUMER_ROOT = '/app/node_modules/emberflow';
+const PROJECT = '/app';
+
+function consumerFs(configBasename?: string) {
+  const paths = [join(CONSUMER_ROOT, 'dist')];
+  if (configBasename) paths.push(join(PROJECT, configBasename));
+  return fsWith(paths);
+}
+
+describe('configBasenameFor', () => {
+  it('finds .mjs before .ts', () => {
+    const fsExists = fsWith([join(PROJECT, 'emberflow.config.mjs')]);
+    expect(configBasenameFor(PROJECT, fsExists)).toBe('emberflow.config.mjs');
+  });
+  it('finds a .ts config', () => {
+    const fsExists = fsWith([join(PROJECT, 'emberflow.config.ts')]);
+    expect(configBasenameFor(PROJECT, fsExists)).toBe('emberflow.config.ts');
+  });
+  it('returns undefined when no config exists', () => {
+    expect(configBasenameFor(PROJECT, () => false)).toBeUndefined();
+  });
+});
+
+describe('resolveProjectDir', () => {
+  it('prefers EMBERFLOW_PROJECT (absolute) over --project and cwd', () => {
+    expect(
+      resolveProjectDir(['--project', './other'], { EMBERFLOW_PROJECT: '/env/proj' }, '/cwd')
+    ).toBe('/env/proj');
+  });
+  it('resolves a relative EMBERFLOW_PROJECT against cwd', () => {
+    expect(resolveProjectDir([], { EMBERFLOW_PROJECT: 'proj' }, '/cwd')).toBe('/cwd/proj');
+  });
+  it('falls back to --project when no env var', () => {
+    expect(resolveProjectDir(['--project', 'p'], {}, '/cwd')).toBe('/cwd/p');
+  });
+  it('falls back to cwd when neither is set', () => {
+    expect(resolveProjectDir([], {}, '/cwd')).toBe('/cwd');
+  });
+});
+
+describe('decideRuntime — JS consumer (installed under node_modules, dist present)', () => {
+  it('.mjs config → plain node, use dist, no tsx', () => {
+    const d = decideRuntime({
+      packageRoot: CONSUMER_ROOT,
+      projectDir: PROJECT,
+      env: {},
+      fsExists: consumerFs('emberflow.config.mjs'),
+    });
+    expect(d).toMatchObject({ needsTsx: false, runnerMode: 'node', useDist: true, sourceMode: false });
+  });
+
+  it('no config → still plain node + dist (e.g. `init`)', () => {
+    const d = decideRuntime({
+      packageRoot: CONSUMER_ROOT,
+      projectDir: PROJECT,
+      env: {},
+      fsExists: consumerFs(),
+    });
+    expect(d).toMatchObject({ needsTsx: false, runnerMode: 'node', useDist: true });
+  });
+
+  it('.ts config → needs tsx, still imports dist commands', () => {
+    const d = decideRuntime({
+      packageRoot: CONSUMER_ROOT,
+      projectDir: PROJECT,
+      env: {},
+      fsExists: consumerFs('emberflow.config.ts'),
+    });
+    expect(d).toMatchObject({ needsTsx: true, runnerMode: 'tsx', useDist: true });
+  });
+
+  it('EMBERFLOW_FORCE_TSX=1 forces tsx even with a .mjs config', () => {
+    const d = decideRuntime({
+      packageRoot: CONSUMER_ROOT,
+      projectDir: PROJECT,
+      env: { EMBERFLOW_FORCE_TSX: '1' },
+      fsExists: consumerFs('emberflow.config.mjs'),
+    });
+    expect(d).toMatchObject({ needsTsx: true, runnerMode: 'tsx' });
+  });
+
+  it('no dist installed → falls back to tsx AND requires it (importing .ts source without tsx would die with ERR_UNKNOWN_FILE_EXTENSION)', () => {
+    const d = decideRuntime({
+      packageRoot: CONSUMER_ROOT,
+      projectDir: PROJECT,
+      env: {},
+      fsExists: fsWith([join(PROJECT, 'emberflow.config.mjs')]), // no dist
+    });
+    expect(d).toMatchObject({ needsTsx: true, runnerMode: 'tsx', useDist: false });
+  });
+});
+
+describe('decideRuntime — source checkout (repo dev loop)', () => {
+  const REPO_ROOT = '/work/emberflow';
+  // src/ present, NOT under node_modules — the checkout signal. dist/ may or may
+  // not exist (after build:lib); source-mode must ignore it.
+  function repoFs(withDist: boolean, configBasename?: string) {
+    const paths = [join(REPO_ROOT, 'src')];
+    if (withDist) paths.push(join(REPO_ROOT, 'dist'));
+    if (configBasename) paths.push(join(PROJECT, configBasename));
+    return fsWith(paths);
+  }
+
+  it('always tsx + source commands, even with a .mjs project config', () => {
+    const d = decideRuntime({
+      packageRoot: REPO_ROOT,
+      projectDir: PROJECT,
+      env: {},
+      fsExists: repoFs(false, 'emberflow.config.mjs'),
+    });
+    expect(d).toMatchObject({ needsTsx: true, runnerMode: 'tsx', useDist: false, sourceMode: true });
+  });
+
+  it('dist present in the repo does NOT switch to node/dist', () => {
+    const d = decideRuntime({
+      packageRoot: REPO_ROOT,
+      projectDir: PROJECT,
+      env: {},
+      fsExists: repoFs(true, 'emberflow.config.mjs'),
+    });
+    expect(d).toMatchObject({ sourceMode: true, useDist: false, needsTsx: true });
+  });
+
+  it('EMBERFLOW_SOURCE=0 escape hatch opts a checkout out of source mode', () => {
+    const d = decideRuntime({
+      packageRoot: REPO_ROOT,
+      projectDir: PROJECT,
+      env: { EMBERFLOW_SOURCE: '0' },
+      fsExists: repoFs(true, 'emberflow.config.mjs'),
+    });
+    expect(d).toMatchObject({ sourceMode: false, runnerMode: 'node', useDist: true });
+  });
+
+  it('EMBERFLOW_SOURCE=1 forces source mode for an installed package', () => {
+    const d = decideRuntime({
+      packageRoot: CONSUMER_ROOT,
+      projectDir: PROJECT,
+      env: { EMBERFLOW_SOURCE: '1' },
+      fsExists: consumerFs('emberflow.config.mjs'),
+    });
+    expect(d).toMatchObject({ sourceMode: true, needsTsx: true, useDist: false });
+  });
+});
+
+describe('TSX_MISSING_MESSAGE', () => {
+  it('is actionable: names the install command and the JS-config alternative', () => {
+    expect(TSX_MISSING_MESSAGE).toContain('npm i -D tsx');
+    expect(TSX_MISSING_MESSAGE).toMatch(/emberflow\.config\.mjs/);
+  });
+});

package/bin/skillTargets.test.ts

@@ -0,0 +1,108 @@
+// bin/skillTargets.test.ts
+import { mkdtempSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { detectHarnesses, resolveSkillDirs } from './skillTargets';
+
+const dirs: string[] = [];
+function scratch(): string {
+  const d = mkdtempSync(join(tmpdir(), 'ef-skilltargets-'));
+  dirs.push(d);
+  return d;
+}
+afterEach(() => {
+  for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+});
+
+describe('detectHarnesses', () => {
+  it('detects neither present when no markers exist', () => {
+    const cwd = scratch();
+    const home = scratch();
+    expect(detectHarnesses(cwd, home)).toEqual({ claude: false, codex: false });
+  });
+
+  it('detects claude present via repo dir', () => {
+    const cwd = scratch();
+    const home = scratch();
+    mkdirSync(join(cwd, '.claude'));
+    expect(detectHarnesses(cwd, home)).toEqual({ claude: true, codex: false });
+  });
+
+  it('detects claude present via home dir', () => {
+    const cwd = scratch();
+    const home = scratch();
+    mkdirSync(join(home, '.claude'));
+    expect(detectHarnesses(cwd, home)).toEqual({ claude: true, codex: false });
+  });
+
+  it('detects codex present via repo dir', () => {
+    const cwd = scratch();
+    const home = scratch();
+    mkdirSync(join(cwd, '.codex'));
+    expect(detectHarnesses(cwd, home)).toEqual({ claude: false, codex: true });
+  });
+
+  it('detects codex present via home dir', () => {
+    const cwd = scratch();
+    const home = scratch();
+    mkdirSync(join(home, '.codex'));
+    expect(detectHarnesses(cwd, home)).toEqual({ claude: false, codex: true });
+  });
+
+  it('detects both present', () => {
+    const cwd = scratch();
+    const home = scratch();
+    mkdirSync(join(cwd, '.claude'));
+    mkdirSync(join(home, '.codex'));
+    expect(detectHarnesses(cwd, home)).toEqual({ claude: true, codex: true });
+  });
+});
+
+describe('resolveSkillDirs', () => {
+  it('picks repo dirs for present harnesses at repo scope', () => {
+    const cwd = scratch();
+    const home = scratch();
+    const dirs = resolveSkillDirs({ claude: true, codex: true }, 'repo', cwd, home);
+    expect(dirs.sort()).toEqual(
+      [join(cwd, '.claude', 'skills'), join(cwd, '.codex', 'skills')].sort()
+    );
+  });
+
+  it('picks home dirs for present harnesses at global scope', () => {
+    const cwd = scratch();
+    const home = scratch();
+    const dirs = resolveSkillDirs({ claude: true, codex: true }, 'global', cwd, home);
+    expect(dirs.sort()).toEqual(
+      [join(home, '.claude', 'skills'), join(home, '.codex', 'skills')].sort()
+    );
+  });
+
+  it('returns only the present harness dir when just one is present (repo scope)', () => {
+    const cwd = scratch();
+    const home = scratch();
+    const dirs = resolveSkillDirs({ claude: true, codex: false }, 'repo', cwd, home);
+    expect(dirs).toEqual([join(cwd, '.claude', 'skills')]);
+  });
+
+  it('returns only the present harness dir when just one is present (global scope)', () => {
+    const cwd = scratch();
+    const home = scratch();
+    const dirs = resolveSkillDirs({ claude: false, codex: true }, 'global', cwd, home);
+    expect(dirs).toEqual([join(home, '.codex', 'skills')]);
+  });
+
+  it('falls back to claude at repo scope when neither harness is present', () => {
+    const cwd = scratch();
+    const home = scratch();
+    const dirs = resolveSkillDirs({ claude: false, codex: false }, 'repo', cwd, home);
+    expect(dirs).toEqual([join(cwd, '.claude', 'skills')]);
+  });
+
+  it('falls back to claude at global scope when neither harness is present', () => {
+    const cwd = scratch();
+    const home = scratch();
+    const dirs = resolveSkillDirs({ claude: false, codex: false }, 'global', cwd, home);
+    expect(dirs).toEqual([join(home, '.claude', 'skills')]);
+  });
+});

package/bin/skillTargets.ts

@@ -0,0 +1,36 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export type Harness = 'claude' | 'codex';
+export interface HarnessPresence {
+  claude: boolean;
+  codex: boolean;
+}
+
+const HARNESSES: Harness[] = ['claude', 'codex'];
+
+/** Detect which harnesses the project/user uses: a harness counts as present if
+ *  its repo dir (<cwd>/.claude or /.codex) OR its home dir (<home>/.claude or /.codex) exists. */
+export function detectHarnesses(cwd: string, home: string): HarnessPresence {
+  const presence = {} as HarnessPresence;
+  for (const h of HARNESSES) {
+    presence[h] = existsSync(join(cwd, `.${h}`)) || existsSync(join(home, `.${h}`));
+  }
+  return presence;
+}
+
+/** The skills destination dirs to install into. For each PRESENT harness, choose
+ *  the repo root (<cwd>/.<harness>/skills) when scope='repo', else the home root
+ *  (<home>/.<harness>/skills). If NEITHER harness is present, default to Claude Code
+ *  at the chosen scope (so a fresh project still gets skills). Returns absolute dirs. */
+export function resolveSkillDirs(
+  presence: HarnessPresence,
+  scope: 'repo' | 'global',
+  cwd: string,
+  home: string
+): string[] {
+  const root = scope === 'repo' ? cwd : home;
+  const present = HARNESSES.filter((h) => presence[h]);
+  const targets = present.length > 0 ? present : (['claude'] as Harness[]);
+  return targets.map((h) => join(root, `.${h}`, 'skills'));
+}

package/bin/skillTemplates.test.ts

@@ -0,0 +1,37 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const skill = (name: string): string =>
+  readFileSync(join('templates', 'skills', name, 'SKILL.md'), 'utf8');
+
+describe('Emberflow skill templates', () => {
+  it('prevents scenario-only verification from hiding missing Input defaults', () => {
+    const basics = skill('emberflow-basics');
+    const newWorkflow = skill('emberflow-new-workflow');
+    const modelProcess = skill('emberflow-model-process');
+    const review = skill('emberflow-review-workflow');
+
+    expect(basics).toContain('Plain Run');
+    expect(newWorkflow).toContain('Run both: plain Run and scenarios');
+    expect(modelProcess).toContain('Run both: plain Run and every scenario');
+    expect(review).toContain('Plain Run / default input check');
+  });
+
+  it('documents the committed infrastructure manifest and points the intake skills at it first', () => {
+    const basics = skill('emberflow-basics');
+    const newWorkflow = skill('emberflow-new-workflow');
+    const modelProcess = skill('emberflow-model-process');
+
+    // Basics: file-layout entry — committed, structure-only, written by the scout.
+    expect(basics).toContain('emberflow/infrastructure.json');
+    expect(basics).toMatch(/committed.*structure-only|structure-only.*committed/i);
+    expect(basics).toMatch(/scout/i);
+
+    // Intake sections: check the manifest FIRST before interviewing about infra.
+    for (const skillText of [newWorkflow, modelProcess]) {
+      expect(skillText).toContain('emberflow/infrastructure.json');
+      expect(skillText).toMatch(/FIRST/);
+    }
+  });
+});

package/bin/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "../node_modules/.tmp/tsconfig.bin.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023", "DOM"],
+    "types": ["node"],
+    "skipLibCheck": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "allowJs": true
+  },
+  "include": ["."],
+  "exclude": ["emberflow.mjs"]
+}

package/dist/bin/commands.d.ts

@@ -0,0 +1,24 @@
+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 declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function runCommand(p: ParsedArgs, ctx?: RuntimeContext): Promise<number>;

package/dist/bin/commands.js

@@ -0,0 +1,252 @@
+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 function parseArgs(argv) {
+    const [command = 'help', ...tail] = argv;
+    const out = { 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() {
+    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() {
+    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 = { runnerMode: 'tsx', packageRoot: selfPkgRoot };
+/** Spawn `tsx <entry>` inheriting stdio, with extra env. Returns the child's exit code. */
+function runTsx(ctx, entry, env, args = []) {
+    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, env, args = []) {
+    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, name, env, args = []) {
+    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, ctx) {
+    // 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, ctx) {
+    // 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, ctx = defaultCtx) {
+    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.js')).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.js')).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.js')).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.js')).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.js'));
+                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, 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;
+    }
+}

package/dist/bin/init.d.ts

@@ -0,0 +1,17 @@
+/** Whether `tsx` resolves from the project's own node_modules (peer dep — optional).
+ *  Exported so bin/commands.ts can reuse it when deciding whether `init --ts` can
+ *  launch dev immediately after scaffolding, or must defer to the user. */
+export declare function tsxResolvable(cwd: string): boolean;
+export declare function runInit(cwd: string, opts?: {
+    skills?: false | {
+        scope: 'repo' | 'global';
+        home: string;
+    };
+    /** Real package root, passed by the bin. Falls back to this module's own
+     *  location — which is wrong when compiled to dist/bin/init.js (its `..` is
+     *  dist/, not the package root that holds templates/), so the bin supplies it. */
+    packageRoot?: string;
+    /** Which language to scaffold the config/nodes in. Defaults to javascript
+     *  (matches the non-TTY prompt default in bin/commands.ts). */
+    language?: 'javascript' | 'typescript';
+}): Promise<number>;