@xdelivered/emberflow 0.2.0

package/bin/emberflow.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { decideRuntime, resolveProjectDir, TSX_MISSING_MESSAGE } from './runtime.mjs';
+
+// Decide the runtime BEFORE importing anything TypeScript: a JS consumer runs on
+// plain Node (no tsx), a source checkout / `.ts` config runs under tsx.
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const argv = process.argv.slice(2);
+const projectDir = resolveProjectDir(argv, process.env, process.cwd());
+const decision = decideRuntime({ packageRoot, projectDir, env: process.env });
+
+if (process.env.EMBERFLOW_DEBUG_RUNTIME) {
+  console.error(`[emberflow] runtime ${JSON.stringify(decision)}`);
+}
+
+if (decision.needsTsx) {
+  try {
+    const { register } = await import('tsx/esm/api');
+    register();
+  } catch {
+    console.error(TSX_MISSING_MESSAGE);
+    process.exit(1);
+  }
+}
+
+// Compiled commands for JS consumers (plain node); TypeScript source under tsx
+// for the repo dev loop. The dynamic specifier is a string literal in each
+// branch so Node's ESM loader resolves it directly.
+const { parseArgs, runCommand } = decision.useDist
+  ? await import('../dist/bin/commands.js')
+  : await import('./commands.ts');
+
+const code = await runCommand(parseArgs(argv), {
+  runnerMode: decision.runnerMode,
+  packageRoot,
+});
+process.exit(code);

package/bin/init.test.ts

@@ -0,0 +1,165 @@
+// bin/init.test.ts
+import { mkdtempSync, rmSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { runInit, tsxResolvable } from './init';
+
+const dirs: string[] = [];
+function scratch(): string { const d = mkdtempSync(join(tmpdir(), 'ef-init-')); dirs.push(d); return d; }
+afterEach(() => { for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true }); });
+
+describe('runInit', () => {
+  it('scaffolds config, an example apis/ operation, and its scenario sidecar', async () => {
+    const d = scratch();
+    writeFileSync(join(d, 'package.json'), JSON.stringify({ name: 'consumer', scripts: {} }));
+    const code = await runInit(d);
+    expect(code).toBe(0);
+    expect(existsSync(join(d, 'emberflow.config.mjs'))).toBe(true);
+    // No legacy flows/ tree — the current model is apis/ only.
+    expect(existsSync(join(d, 'emberflow/flows'))).toBe(false);
+    expect(existsSync(join(d, 'emberflow/apis/default/hello.json'))).toBe(true);
+    expect(existsSync(join(d, 'emberflow/apis/default/hello.scenarios.json'))).toBe(true);
+    const pkg = JSON.parse(readFileSync(join(d, 'package.json'), 'utf8'));
+    expect(pkg.scripts.emberflow).toBe('emberflow dev');
+    const op = JSON.parse(readFileSync(join(d, 'emberflow/apis/default/hello.json'), 'utf8'));
+    expect(op.id).toBe('default/hello');
+    expect(op.http).toEqual({ method: 'GET', path: '/hello' });
+    expect(op.nodes.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('defaults to a javascript scaffold with language field and JSDoc typing', async () => {
+    const d = scratch();
+    await runInit(d, { skills: false });
+    const config = readFileSync(join(d, 'emberflow.config.mjs'), 'utf8');
+    expect(config).toContain("language: 'javascript'");
+    expect(config).toContain("@param {import('@xdelivered/emberflow').NodeRegistry} registry");
+    expect(existsSync(join(d, 'emberflow.config.ts'))).toBe(false);
+    expect(existsSync(join(d, 'tsconfig.json'))).toBe(false);
+  });
+
+  it('scaffolds a typescript config, tsconfig.json, and a typed registerNodes when language: typescript', async () => {
+    const d = scratch();
+    await runInit(d, { skills: false, language: 'typescript' });
+    expect(existsSync(join(d, 'emberflow.config.mjs'))).toBe(false);
+    const config = readFileSync(join(d, 'emberflow.config.ts'), 'utf8');
+    expect(config).toContain("language: 'typescript'");
+    expect(config).toContain("import type { NodeRegistry } from '@xdelivered/emberflow'");
+    expect(config).toContain('registerNodes(registry: NodeRegistry)');
+    expect(existsSync(join(d, 'tsconfig.json'))).toBe(true);
+    const tsconfig = JSON.parse(readFileSync(join(d, 'tsconfig.json'), 'utf8'));
+    expect(tsconfig.compilerOptions.strict).toBe(true);
+    expect(tsconfig.include).toContain('emberflow.config.ts');
+  });
+
+  it('does not overwrite an existing tsconfig.json on re-init', async () => {
+    const d = scratch();
+    writeFileSync(join(d, 'tsconfig.json'), '{"custom": true}\n');
+    await runInit(d, { skills: false, language: 'typescript' });
+    expect(readFileSync(join(d, 'tsconfig.json'), 'utf8')).toContain('custom');
+  });
+
+  it('refuses to scaffold a second config in the OTHER language (dead-config guard)', async () => {
+    const d = scratch();
+    await runInit(d, { skills: false, language: 'javascript' });
+    const code = await runInit(d, { skills: false, language: 'typescript' });
+    expect(code).toBe(1);
+    expect(existsSync(join(d, 'emberflow.config.ts'))).toBe(false);
+    // And the mirror direction: existing .ts config blocks a javascript init.
+    const d2 = scratch();
+    await runInit(d2, { skills: false, language: 'typescript' });
+    const code2 = await runInit(d2, { skills: false, language: 'javascript' });
+    expect(code2).toBe(1);
+    expect(existsSync(join(d2, 'emberflow.config.mjs'))).toBe(false);
+  });
+
+  it('does not clobber an existing config or emberflow script', async () => {
+    const d = scratch();
+    writeFileSync(join(d, 'emberflow.config.mjs'), 'export default { custom: true };\n');
+    writeFileSync(join(d, 'package.json'), JSON.stringify({ scripts: { emberflow: 'mine' } }));
+    await runInit(d);
+    expect(readFileSync(join(d, 'emberflow.config.mjs'), 'utf8')).toContain('custom: true');
+    expect(JSON.parse(readFileSync(join(d, 'package.json'), 'utf8')).scripts.emberflow).toBe('mine');
+  });
+
+  it('copies skills into .claude/skills by default (repo scope)', async () => {
+    const d = scratch();
+    await runInit(d, { skills: { scope: 'repo', home: d } });
+    expect(existsSync(join(d, '.claude/skills/emberflow-basics/SKILL.md'))).toBe(true);
+  });
+
+  it('skips skills entirely when skills: false', async () => {
+    const d = scratch();
+    await runInit(d, { skills: false });
+    expect(existsSync(join(d, '.claude'))).toBe(false);
+  });
+
+  it('creates .gitignore for emberflow infra, keeping apis + config committed', async () => {
+    const d = scratch();
+    await runInit(d, { skills: false });
+    const gi = readFileSync(join(d, '.gitignore'), 'utf8');
+    // infra ignored
+    for (const line of ['node_modules/', 'studio-dist/', 'emberflow.secrets.json', 'emberflow.environments.json']) {
+      expect(gi).toContain(line);
+    }
+    // the value stays committed — no ignore LINE for config or flows (the header
+    // comment may name them, but they must not appear as active patterns)
+    const patterns = gi.split('\n').filter((l) => l.trim() && !l.trim().startsWith('#'));
+    expect(patterns).not.toContain('emberflow.config.mjs');
+    expect(patterns).not.toContain('emberflow/');
+    expect(patterns).not.toContain('emberflow/flows/');
+  });
+
+  it('scaffolds emberflow/apis/default so the API host is ready out of the box', async () => {
+    const d = scratch();
+    await runInit(d, { skills: false });
+    expect(existsSync(join(d, 'emberflow', 'apis', 'default'))).toBe(true);
+  });
+
+  it('appends to an existing .gitignore without duplicating on re-run', async () => {
+    const d = scratch();
+    writeFileSync(join(d, '.gitignore'), 'bin/\nobj/\n');
+    await runInit(d, { skills: false });
+    await runInit(d, { skills: false });
+    const gi = readFileSync(join(d, '.gitignore'), 'utf8');
+    expect(gi).toContain('bin/'); // pre-existing preserved
+    expect((gi.match(/emberflow\.secrets\.json/g) ?? []).length).toBe(1);
+  });
+
+  it('warns when stamping "type": "module" on an existing package.json without a type field', async () => {
+    const d = scratch();
+    writeFileSync(join(d, 'package.json'), JSON.stringify({ name: 'consumer', scripts: {} }));
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      await runInit(d, { skills: false, language: 'typescript' });
+      expect(JSON.parse(readFileSync(join(d, 'package.json'), 'utf8')).type).toBe('module');
+      expect(warnSpy.mock.calls.flat().join(' ')).toContain('set "type": "module" in package.json');
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it('does not warn about stamping type:module when it is already set', async () => {
+    const d = scratch();
+    writeFileSync(join(d, 'package.json'), JSON.stringify({ name: 'consumer', type: 'module', scripts: {} }));
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      await runInit(d, { skills: false, language: 'typescript' });
+      expect(warnSpy.mock.calls.flat().join(' ')).not.toContain('set "type": "module" in package.json');
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+});
+
+describe('tsxResolvable', () => {
+  it('returns true when tsx resolves from a project (this repo has it as a devDependency)', () => {
+    expect(tsxResolvable(process.cwd())).toBe(true);
+  });
+
+  it('returns false in an isolated scratch dir with no node_modules', () => {
+    const d = scratch();
+    writeFileSync(join(d, 'package.json'), JSON.stringify({ name: 'isolated' }));
+    expect(tsxResolvable(d)).toBe(false);
+  });
+});

package/bin/init.ts

@@ -0,0 +1,297 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, copyFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { detectHarnesses, resolveSkillDirs } from './skillTargets';
+
+const MCP_SNIPPET = {
+  mcpServers: {
+    emberflow: { command: 'npx', args: ['emberflow', 'mcp'] },
+  },
+};
+
+function copySkillsRecursive(src: string, dest: string, log: string[]): void {
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    if (statSync(srcPath).isDirectory()) {
+      copySkillsRecursive(srcPath, destPath, log);
+    } else if (!existsSync(destPath)) {
+      copyFileSync(srcPath, destPath);
+      log.push(destPath);
+    }
+  }
+}
+
+const JS_CONFIG_CONTENT =
+  "import { defineConfig } from '@xdelivered/emberflow';\n\n" +
+  'export default defineConfig({\n' +
+  "  language: 'javascript',\n" +
+  '  // Anchor only: this path is never created and holds no files. It just tells\n' +
+  '  // Emberflow where your project root is — operations always live in the\n' +
+  '  // SIBLING apis/ tree next to it:\n' +
+  '  //   emberflow/apis/<api>/<folder…>/<op>.json — each op id = its path under apis/.\n' +
+  "  flowsDir: 'emberflow/flows',\n" +
+  '  // Author your nodes here: registry.register(definition, async (ctx) => output).\n' +
+  "  /** @param {import('@xdelivered/emberflow').NodeRegistry} registry */\n" +
+  '  registerNodes(registry) {\n' +
+  '    /* register your nodes */\n' +
+  '  },\n' +
+  '});\n';
+
+const TS_CONFIG_CONTENT =
+  "import { defineConfig } from '@xdelivered/emberflow';\n" +
+  "import type { NodeRegistry } from '@xdelivered/emberflow';\n\n" +
+  'export default defineConfig({\n' +
+  "  language: 'typescript',\n" +
+  '  // Anchor only: this path is never created and holds no files. It just tells\n' +
+  '  // Emberflow where your project root is — operations always live in the\n' +
+  '  // SIBLING apis/ tree next to it:\n' +
+  '  //   emberflow/apis/<api>/<folder…>/<op>.json — each op id = its path under apis/.\n' +
+  "  flowsDir: 'emberflow/flows',\n" +
+  '  // Author your nodes here: registry.register(definition, async (ctx) => output).\n' +
+  '  registerNodes(registry: NodeRegistry) {\n' +
+  '    /* register your nodes */\n' +
+  '  },\n' +
+  '});\n';
+
+// Minimal — the consumer only needs their config + nodes typechecked, not a full
+// project tsconfig. `noEmit` because emberflow.config.ts runs via tsx, never tsc.
+const TSCONFIG_CONTENT =
+  JSON.stringify(
+    {
+      compilerOptions: {
+        target: 'es2022',
+        module: 'nodenext',
+        moduleResolution: 'nodenext',
+        strict: true,
+        skipLibCheck: true,
+        esModuleInterop: true,
+        resolveJsonModule: true,
+        noEmit: true,
+      },
+      include: ['emberflow.config.ts', 'emberflow/**/*'],
+    },
+    null,
+    2
+  ) + '\n';
+
+/** 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 function tsxResolvable(cwd: string): boolean {
+  try {
+    createRequire(join(cwd, 'package.json')).resolve('tsx');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// The example HTTP operation: GET /hello, Input({params,query,body,headers}) →
+// Response({status,body}). Its `id` equals its path under the apis dir.
+const HELLO_OP = {
+  id: 'default/hello',
+  name: 'Hello',
+  version: 1,
+  http: { method: 'GET', path: '/hello' },
+  nodes: [
+    {
+      id: 'input',
+      type: 'Input',
+      label: 'Request',
+      position: { x: 0, y: 0 },
+      config: {
+        fields: [
+          { name: 'params', type: 'object' },
+          { name: 'query', type: 'object' },
+          { name: 'body', type: 'object' },
+          { name: 'headers', type: 'object' },
+        ],
+        defaults: { query: { name: 'world' } },
+      },
+    },
+    {
+      id: 'response',
+      type: 'Response',
+      label: 'Response',
+      position: { x: 300, y: 0 },
+      config: {},
+      inputMap: {
+        body: { sourceNodeId: 'input', sourceField: 'query' },
+      },
+    },
+  ],
+  edges: [{ id: 'e0', source: 'input', target: 'response', targetHandle: 'body' }],
+  createdAt: '2026-07-05T00:00:00Z',
+  updatedAt: '2026-07-05T00:00:00Z',
+};
+
+const HELLO_OP_SCENARIOS = [{ id: 's-hi', name: 'greet', input: { query: { name: 'Ember' } } }];
+
+// Emberflow infra that is machine-local, generated, or secret — never committed.
+// NOTE: emberflow.config.mjs and emberflow/ (apis + scenarios) are deliberately
+// NOT here — those are the value and SHOULD be checked in.
+const GITIGNORE_HEADER = '# Emberflow (local infra — emberflow.config.mjs and emberflow/apis ARE committed)';
+const GITIGNORE_LINES = [
+  'node_modules/',
+  'studio-dist/',
+  'emberflow.secrets.json',
+  'emberflow.environments.json',
+];
+
+function writeFileIfAbsent(path: string, content: string, log: string[]): void {
+  if (existsSync(path)) return;
+  writeFileSync(path, content);
+  log.push(path);
+}
+
+export async 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> {
+  const written: string[] = [];
+  const language = opts?.language ?? 'javascript';
+
+  // Refuse to scaffold a SECOND config in another extension: the loader probes
+  // .mjs before .js before .ts, so a new config of a different flavor would sit
+  // dead on disk while init claims success. Language switching is a manual
+  // migration (rename/port the existing config), not a re-init.
+  const existingOther = ['emberflow.config.mjs', 'emberflow.config.js', 'emberflow.config.ts']
+    .filter((name) => (language === 'typescript' ? !name.endsWith('.ts') : name.endsWith('.ts')))
+    .find((name) => existsSync(join(cwd, name)));
+  if (existingOther) {
+    console.error(
+      `[emberflow] this project already has ${existingOther} — refusing to scaffold a ${language} config alongside it. ` +
+        `To switch languages, port ${existingOther} manually and delete it.`,
+    );
+    return 1;
+  }
+
+  if (language === 'typescript') {
+    writeFileIfAbsent(join(cwd, 'emberflow.config.ts'), TS_CONFIG_CONTENT, written);
+    writeFileIfAbsent(join(cwd, 'tsconfig.json'), TSCONFIG_CONTENT, written);
+    if (!tsxResolvable(cwd)) {
+      console.log('[emberflow] TypeScript config needs tsx to run this project.');
+      console.log('  npm i -D tsx typescript');
+    }
+  } else {
+    writeFileIfAbsent(join(cwd, 'emberflow.config.mjs'), JS_CONFIG_CONTENT, written);
+  }
+
+  // Scaffold the apis/ tree with an example HTTP operation so the API host has a
+  // routed endpoint the moment the project boots. The operation's `id`
+  // ("default/hello") equals its path under the apis dir.
+  const apisDefaultDir = join(cwd, 'emberflow', 'apis', 'default');
+  const apisDefaultDirExisted = existsSync(apisDefaultDir);
+  mkdirSync(apisDefaultDir, { recursive: true });
+  if (!apisDefaultDirExisted) written.push(apisDefaultDir + '/');
+
+  writeFileIfAbsent(
+    join(apisDefaultDir, 'hello.json'),
+    JSON.stringify(HELLO_OP, null, 2) + '\n',
+    written
+  );
+  writeFileIfAbsent(
+    join(apisDefaultDir, 'hello.scenarios.json'),
+    JSON.stringify(HELLO_OP_SCENARIOS, null, 2) + '\n',
+    written
+  );
+
+  const pkgPath = join(cwd, 'package.json');
+  if (existsSync(pkgPath)) {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as {
+      scripts?: Record<string, string>;
+      type?: string;
+      [key: string]: unknown;
+    };
+    let pkgDirty = false;
+    if (!pkg.scripts) pkg.scripts = {};
+    if (!pkg.scripts.emberflow) {
+      pkg.scripts.emberflow = 'emberflow dev';
+      pkgDirty = true;
+    }
+    // A TypeScript project MUST load as ESM: `emberflow` is an ESM-only package,
+    // and under a CommonJS package.json tsx transpiles emberflow.config.ts to CJS
+    // and then require()s the ESM `emberflow` — which Node rejects with
+    // ERR_REQUIRE_CYCLE_MODULE. Stamp "type":"module" when the project hasn't
+    // declared one. (JS scaffolds a .mjs config, which is ESM regardless.)
+    if (language === 'typescript') {
+      if (pkg.type === undefined) {
+        pkg.type = 'module';
+        pkgDirty = true;
+        console.warn(
+          '[emberflow] set "type": "module" in package.json — required for emberflow.config.ts; ' +
+            'if this project has existing CommonJS .js files, audit them (they are now parsed as ESM)',
+        );
+      } else if (pkg.type !== 'module') {
+        console.warn(
+          `[emberflow] warning: package.json has "type": "${pkg.type}", but a TypeScript ` +
+            'emberflow.config.ts must load as ESM. Set "type": "module" or the runner will fail ' +
+            'to load your config.',
+        );
+      }
+    }
+    if (pkgDirty) {
+      writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+      written.push(pkgPath);
+    }
+  }
+
+  const gitignorePath = join(cwd, '.gitignore');
+  const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf8') : '';
+  const missing = GITIGNORE_LINES.filter((line) => !existing.includes(line));
+  if (missing.length > 0) {
+    // Create .gitignore if absent, or append only the lines not already present.
+    const header = existing.includes(GITIGNORE_HEADER) ? '' : `${GITIGNORE_HEADER}\n`;
+    const sep = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+    const block = (existing.length > 0 ? '\n' : '') + header + missing.join('\n') + '\n';
+    writeFileSync(gitignorePath, existing + sep + block);
+    written.push(gitignorePath);
+  }
+
+  for (const path of written) {
+    console.log(`[emberflow] created ${path}`);
+  }
+
+  const skillsOpt = opts?.skills === undefined ? { scope: 'repo' as const, home: homedir() } : opts.skills;
+  if (skillsOpt !== false) {
+    const pkgRoot = opts?.packageRoot ?? join(dirname(fileURLToPath(import.meta.url)), '..');
+    const skillsSrc = join(pkgRoot, 'templates', 'skills');
+    if (existsSync(skillsSrc)) {
+      const presence = detectHarnesses(cwd, skillsOpt.home);
+      const skillDirs = resolveSkillDirs(presence, skillsOpt.scope, cwd, skillsOpt.home);
+      const skillsWritten: string[] = [];
+      for (const dir of skillDirs) {
+        copySkillsRecursive(skillsSrc, dir, skillsWritten);
+      }
+      for (const path of skillsWritten) {
+        console.log(`[emberflow] created ${path}`);
+      }
+    }
+    console.log('');
+    console.log(
+      '[emberflow] To let your agent drive Emberflow directly, register the emberflow MCP server:'
+    );
+    console.log(
+      "  - Claude Code: add the snippet below to .mcp.json at your project root."
+    );
+    console.log(
+      "  - Other agents: add it to your agent's MCP server config (name/location varies by tool)."
+    );
+    console.log(JSON.stringify(MCP_SNIPPET, null, 2));
+  }
+
+  return 0;
+}

package/bin/runtime.mjs

@@ -0,0 +1,105 @@
+// Runtime-mode decision for the Emberflow bin.
+//
+// The bin must decide — BEFORE loading any TypeScript — whether this invocation
+// needs the tsx loader (source checkout, a `.ts` project config, or an explicit
+// override) or can run on plain Node against the compiled `dist/`. A JS consumer
+// with a `.mjs`/`.js` config runs entirely on `node` with NO tsx: no tsx child
+// IPC, so the agent in-process CLI works inside the codex sandbox.
+//
+// This module is plain JS on purpose — it imports NO server/TS code, so probing
+// it never triggers the tsx requirement it is trying to decide about. Everything
+// here is pure and injectable (fsExists/env) so the decision matrix is unit
+// testable without touching a real filesystem.
+
+import { existsSync } from 'node:fs';
+import { isAbsolute, join, resolve, sep } from 'node:path';
+
+// Mirrors server/projectConfig.ts CONFIG_BASENAMES. Kept as a tiny local copy
+// (not imported) because that module is TypeScript and pulls in server code.
+const CONFIG_BASENAMES = ['emberflow.config.mjs', 'emberflow.config.js', 'emberflow.config.ts'];
+
+/** Actionable message shown when a `.ts` config / source mode needs tsx but it
+ *  isn't installed. Exported so both the bin and its tests reference one string. */
+export const TSX_MISSING_MESSAGE =
+  '[emberflow] This project needs tsx to run, but tsx is not installed.\n' +
+  '  Either a TypeScript config (emberflow.config.ts) or source mode requires the tsx loader.\n' +
+  '  Fix: install it as a dev dependency —  npm i -D tsx\n' +
+  '  Or:  rename emberflow.config.ts to emberflow.config.mjs (plain JS) so Emberflow runs on plain Node.';
+
+/** The emberflow.config.* basename present in `dir`, or undefined. Local probe
+ *  of the same basenames server/projectConfig.ts#configPathFor checks. */
+export function configBasenameFor(dir, fsExists = existsSync) {
+  const root = resolve(dir);
+  return CONFIG_BASENAMES.find((b) => fsExists(join(root, b)));
+}
+
+/** Resolve the project directory the same way the commands do, in the binding
+ *  order EMBERFLOW_PROJECT → --project → cwd. Values are resolved against cwd. */
+export function resolveProjectDir(argv, env, cwd) {
+  const fromEnv = env.EMBERFLOW_PROJECT;
+  if (fromEnv) return isAbsolute(fromEnv) ? fromEnv : resolve(cwd, fromEnv);
+  const i = argv.indexOf('--project');
+  if (i !== -1 && argv[i + 1]) return resolve(cwd, argv[i + 1]);
+  return cwd;
+}
+
+/**
+ * Decide how to run.
+ *
+ * @param packageRoot absolute path to the package root (dir above bin/).
+ * @param projectDir  resolved project dir (see resolveProjectDir).
+ * @param env         process.env-shaped object.
+ * @param fsExists    existsSync-shaped probe (injectable for tests).
+ *
+ * Returns:
+ *   needsTsx    – register tsx and spawn the runner under tsx.
+ *   runnerMode  – 'node' (spawn `node dist/server/*.js`) or 'tsx' (spawn tsx source).
+ *   useDist     – import the compiled `dist/bin/commands.js` rather than source.
+ *   sourceMode  – repo checkout (dev loop) rather than an installed package.
+ *   configBasename / reason – for the EMBERFLOW_DEBUG_RUNTIME trace.
+ */
+export function decideRuntime({ packageRoot, projectDir, env = {}, fsExists = existsSync }) {
+  const hasDist = fsExists(join(packageRoot, 'dist'));
+  const hasSrc = fsExists(join(packageRoot, 'src'));
+  const underNodeModules = packageRoot.split(sep).includes('node_modules');
+
+  // source-mode = repo checkout, where we always run the TypeScript sources under
+  // tsx (the dev loop). `dist/` may EXIST in the repo after `build:lib`, so its
+  // presence can't be the signal. Heuristic: src/ exists AND we're not installed
+  // under node_modules. EMBERFLOW_SOURCE is an explicit escape hatch either way.
+  let sourceMode;
+  if (env.EMBERFLOW_SOURCE === '1') sourceMode = true;
+  else if (env.EMBERFLOW_SOURCE === '0') sourceMode = false;
+  else sourceMode = hasSrc && !underNodeModules;
+
+  const configBasename = configBasenameFor(projectDir, fsExists);
+  const tsConfig = configBasename?.endsWith('.ts') ?? false;
+  const forced = env.EMBERFLOW_FORCE_TSX === '1';
+
+  // Import compiled commands only when we have a dist AND we're not in the source
+  // dev loop. Otherwise fall back to the TypeScript source (which requires tsx —
+  // and needsTsx is already true whenever sourceMode is).
+  const useDist = hasDist && !sourceMode;
+
+  // INVARIANT: importing TypeScript source requires tsx. When there is no dist
+  // to fall back on (`!useDist`), the launcher will import ./commands.ts, so tsx
+  // is required even if nothing else demanded it — otherwise plain node dies
+  // with a cryptic ERR_UNKNOWN_FILE_EXTENSION instead of TSX_MISSING_MESSAGE.
+  const needsTsx = sourceMode || forced || tsConfig || !useDist;
+
+  // A node-mode runner needs the compiled server; if there's no dist we can't run
+  // plain node, so fall back to tsx even when nothing else demanded it.
+  const runnerMode = !needsTsx && hasDist ? 'node' : 'tsx';
+
+  const reason = sourceMode
+    ? 'source-mode (repo checkout)'
+    : forced
+      ? 'EMBERFLOW_FORCE_TSX=1'
+      : tsConfig
+        ? `ts-config (${configBasename})`
+        : runnerMode === 'node'
+          ? 'js-consumer (plain node)'
+          : 'no-dist fallback';
+
+  return { needsTsx, runnerMode, useDist, sourceMode, hasDist, configBasename, reason };
+}