@bachbntdev/devcmd 0.0.0-stage → 2.7.1

package/src/recipes/loader.js

@@ -0,0 +1,82 @@
+// Copyright (c) 2026 bachbnt
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const builtInRecipes = require('./built-ins.json');
+const { validateRecipe } = require('./schema');
+
+function attachSource(recipe, source, baseDir) {
+  return { ...recipe, source, baseDir };
+}
+
+function loadBuiltInRecipes() {
+  return builtInRecipes.map((recipe) => attachSource(validateRecipe(recipe), 'built-in', __dirname));
+}
+
+function loadRecipeFile(file, source, fsImpl = fs) {
+  let parsed;
+  try {
+    parsed = JSON.parse(fsImpl.readFileSync(file, 'utf8'));
+  } catch (error) {
+    throw new Error(`Unable to read recipe ${file}: ${error.message}`);
+  }
+  const recipes = Array.isArray(parsed) ? parsed : [parsed];
+  return recipes.map((recipe) => {
+    try {
+      return attachSource(validateRecipe(recipe), source, path.dirname(file));
+    } catch (error) {
+      throw new Error(`Invalid recipe ${file}: ${error.message}`);
+    }
+  });
+}
+
+function loadRecipeDirectory(directory, source, options = {}) {
+  const fsImpl = options.fsImpl || fs;
+  let entries;
+  try {
+    entries = fsImpl.readdirSync(directory, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === 'ENOENT') return [];
+    throw new Error(`Unable to read recipe directory ${directory}: ${error.message}`);
+  }
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+    .sort((left, right) => left.name.localeCompare(right.name))
+    .flatMap((entry) => loadRecipeFile(path.join(directory, entry.name), source, fsImpl));
+}
+
+function createRegistry(recipes) {
+  const registry = new Map();
+  for (const recipe of recipes) registry.set(recipe.name, recipe);
+  return registry;
+}
+
+function loadRecipeRegistry(options = {}) {
+  const home = options.home || os.homedir();
+  const userDirectory = options.userDirectory || path.join(home, '.devcmd', 'recipes');
+  const builtIns = options.builtIns || loadBuiltInRecipes();
+  const userRecipes = options.includeUser === false
+    ? []
+    : loadRecipeDirectory(userDirectory, 'user', options);
+  return createRegistry([...builtIns, ...userRecipes]);
+}
+
+function getRecipeDefinitions(registry) {
+  return Object.fromEntries(
+    [...registry.entries()].map(([name, recipe]) => [name, {
+      description: recipe.description,
+      capabilities: recipe.capabilities || {},
+      source: recipe.source,
+    }])
+  );
+}
+
+module.exports = {
+  createRegistry,
+  getRecipeDefinitions,
+  loadBuiltInRecipes,
+  loadRecipeDirectory,
+  loadRecipeFile,
+  loadRecipeRegistry,
+};

package/src/recipes/schema.js

@@ -0,0 +1,225 @@
+// Copyright (c) 2026 bachbnt
+
+const { LIFECYCLE_COMMANDS, SYSTEM_COMMANDS, DEVICE_COMMANDS } = require('../constants');
+
+const RECIPE_NAME = /^[a-z][a-z0-9_]*$/;
+const INPUT_NAME = /^[A-Za-z][A-Za-z0-9_]*$/;
+const ACTION_TYPES = new Set(['run', 'mkdir', 'write', 'copy']);
+const CAPABILITIES = new Set(['language', 'packageManager', 'git', 'eslint', 'noInstall', 'python']);
+const PACKAGE_MANAGERS = new Set(['npm', 'pnpm', 'yarn']);
+const RESERVED_RECIPES = new Set([...LIFECYCLE_COMMANDS, ...SYSTEM_COMMANDS, ...DEVICE_COMMANDS, 'help']);
+const RESERVED_INPUTS = new Set([
+  'target', 'packageManager', 'typescript', 'git', 'eslint', 'vueDefault', 'noInstall',
+  'python', 'venvDirectory', 'projectPython', 'pythonGenerator',
+]);
+
+function assertPlainObject(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${label} must be an object.`);
+  }
+}
+
+function validateCondition(condition, label) {
+  assertPlainObject(condition, label);
+  if (!INPUT_NAME.test(condition.option || '')) {
+    throw new Error(`${label}.option must be a valid option name.`);
+  }
+  const keys = Object.keys(condition);
+  if (!keys.includes('equals') || keys.some((key) => !['option', 'equals'].includes(key))) {
+    throw new Error(`${label} must contain only option and equals.`);
+  }
+}
+
+function validateValueSpec(spec, label) {
+  if (typeof spec === 'string') return;
+  if (Array.isArray(spec)) {
+    spec.forEach((item, index) => validateValueSpec(item, `${label}[${index}]`));
+    return;
+  }
+  assertPlainObject(spec, label);
+  if (Object.hasOwn(spec, 'value')) {
+    const keys = Object.keys(spec);
+    if (!spec.when || keys.some((key) => !['value', 'when'].includes(key))) {
+      throw new Error(`${label} conditional value must contain only value and when.`);
+    }
+    validateCondition(spec.when, `${label}.when`);
+    validateValueSpec(spec.value, `${label}.value`);
+    return;
+  }
+  if (Object.hasOwn(spec, 'option')) {
+    const keys = Object.keys(spec);
+    if (!INPUT_NAME.test(spec.option || '') || !spec.map || keys.some((key) => !['option', 'map'].includes(key))) {
+      throw new Error(`${label} option mapping must contain only a valid option and map.`);
+    }
+    assertPlainObject(spec.map, `${label}.map`);
+    for (const [key, value] of Object.entries(spec.map)) {
+      validateValueSpec(value, `${label}.map.${key}`);
+    }
+    return;
+  }
+  throw new Error(`${label} must be a string, array, conditional value, or option mapping.`);
+}
+
+function validateAction(action, index, prefix = 'actions') {
+  const label = `${prefix}[${index}]`;
+  assertPlainObject(action, label);
+  if (!ACTION_TYPES.has(action.type)) throw new Error(`${label}.type is unsupported: ${action.type}`);
+  if (action.when) validateCondition(action.when, `${label}.when`);
+
+  if (action.type === 'run') {
+    const allowed = ['type', 'executable', 'args', 'cwd', 'when'];
+    if (Object.keys(action).some((key) => !allowed.includes(key))) {
+      throw new Error(`${label} contains unsupported run fields.`);
+    }
+    validateValueSpec(action.executable, `${label}.executable`);
+    if (!Array.isArray(action.args)) throw new Error(`${label}.args must be an array.`);
+    action.args.forEach((arg, argIndex) => validateValueSpec(arg, `${label}.args[${argIndex}]`));
+    if (action.cwd !== undefined) validateValueSpec(action.cwd, `${label}.cwd`);
+    return;
+  }
+
+  const allowedByType = {
+    mkdir: ['type', 'path', 'when'],
+    write: ['type', 'path', 'content', 'when'],
+    copy: ['type', 'source', 'destination', 'when'],
+  };
+  if (Object.keys(action).some((key) => !allowedByType[action.type].includes(key))) {
+    throw new Error(`${label} contains unsupported ${action.type} fields.`);
+  }
+  if (action.type === 'mkdir') validateValueSpec(action.path, `${label}.path`);
+  if (action.type === 'write') {
+    validateValueSpec(action.path, `${label}.path`);
+    validateValueSpec(action.content, `${label}.content`);
+  }
+  if (action.type === 'copy') {
+    validateValueSpec(action.source, `${label}.source`);
+    validateValueSpec(action.destination, `${label}.destination`);
+  }
+}
+
+function validateDetect(detect, recipeName) {
+  assertPlainObject(detect, `Recipe ${recipeName} detect`);
+  if (Object.keys(detect).some((key) => !['priority', 'rules'].includes(key))) {
+    throw new Error(`Recipe ${recipeName} detect contains unsupported fields.`);
+  }
+  if (detect.priority !== undefined && !Number.isInteger(detect.priority)) {
+    throw new Error(`Recipe ${recipeName} detect priority must be an integer.`);
+  }
+  if (!Array.isArray(detect.rules) || detect.rules.length === 0) {
+    throw new Error(`Recipe ${recipeName} detect rules must be a non-empty array.`);
+  }
+  detect.rules.forEach((rule, index) => {
+    const label = `Recipe ${recipeName} detect.rules[${index}]`;
+    assertPlainObject(rule, label);
+    if (Object.keys(rule).some((key) => !['files', 'dependencies', 'contains'].includes(key))) {
+      throw new Error(`${label} contains unsupported fields.`);
+    }
+    if (!rule.files && !rule.dependencies && !rule.contains) {
+      throw new Error(`${label} must define files, dependencies, or contains.`);
+    }
+    for (const key of ['files', 'dependencies']) {
+      if (rule[key] !== undefined && (
+        !Array.isArray(rule[key]) ||
+        rule[key].length === 0 ||
+        rule[key].some((item) => typeof item !== 'string' || !item || pathIsUnsafe(item))
+      )) {
+        throw new Error(`${label}.${key} must contain safe relative names.`);
+      }
+    }
+    if (rule.contains !== undefined) {
+      assertPlainObject(rule.contains, `${label}.contains`);
+      if (Object.entries(rule.contains).some(([file, text]) => pathIsUnsafe(file) || typeof text !== 'string' || !text)) {
+        throw new Error(`${label}.contains must map safe relative files to non-empty text.`);
+      }
+    }
+  });
+}
+
+function pathIsUnsafe(value) {
+  return value.startsWith('/') || /^[A-Za-z]:[\\/]/.test(value) || value.split(/[\\/]/).includes('..');
+}
+
+function validateLifecycle(lifecycle, recipeName) {
+  assertPlainObject(lifecycle, `Recipe ${recipeName} lifecycle`);
+  const actionNames = new Set(LIFECYCLE_COMMANDS);
+  if (lifecycle.adapter !== undefined) {
+    if (Object.keys(lifecycle).length !== 1 || !RECIPE_NAME.test(lifecycle.adapter)) {
+      throw new Error(`Recipe ${recipeName} lifecycle adapter must be a valid adapter name.`);
+    }
+    return;
+  }
+  if (Object.keys(lifecycle).length === 0) {
+    throw new Error(`Recipe ${recipeName} lifecycle must define an adapter or actions.`);
+  }
+  for (const [action, actions] of Object.entries(lifecycle)) {
+    if (!actionNames.has(action) || !Array.isArray(actions) || actions.length === 0) {
+      throw new Error(`Recipe ${recipeName} lifecycle action is unsupported: ${action}`);
+    }
+    actions.forEach((item, index) => validateAction(item, index, `lifecycle.${action}`));
+  }
+}
+
+function validateRecipe(recipe) {
+  assertPlainObject(recipe, 'Recipe');
+  const allowed = [
+    'name', 'description', 'capabilities', 'inputs', 'requirements', 'actions', 'detect', 'lifecycle',
+  ];
+  const unknown = Object.keys(recipe).filter((key) => !allowed.includes(key));
+  if (unknown.length > 0) throw new Error(`Recipe contains unsupported fields: ${unknown.join(', ')}`);
+  if (!RECIPE_NAME.test(recipe.name || '')) {
+    throw new Error('Recipe name must use lowercase letters, numbers, and underscores.');
+  }
+  if (RESERVED_RECIPES.has(recipe.name)) {
+    throw new Error(`Recipe name is reserved by DevCmd: ${recipe.name}`);
+  }
+  if (typeof recipe.description !== 'string' || !recipe.description.trim()) {
+    throw new Error(`Recipe ${recipe.name} requires a description.`);
+  }
+
+  assertPlainObject(recipe.capabilities || {}, `Recipe ${recipe.name} capabilities`);
+  for (const [key, value] of Object.entries(recipe.capabilities || {})) {
+    if (!CAPABILITIES.has(key)) throw new Error(`Recipe ${recipe.name} has unsupported capability: ${key}`);
+    if (key === 'packageManager' && Array.isArray(value)) {
+      if (value.length === 0 || value.some((item) => !PACKAGE_MANAGERS.has(item))) {
+        throw new Error(`Recipe ${recipe.name} packageManager capability must list supported managers.`);
+      }
+    } else if (value !== true && value !== false) {
+      throw new Error(`Recipe ${recipe.name} capability ${key} must be true or false.`);
+    }
+  }
+
+  assertPlainObject(recipe.inputs || {}, `Recipe ${recipe.name} inputs`);
+  for (const [name, input] of Object.entries(recipe.inputs || {})) {
+    if (!INPUT_NAME.test(name)) throw new Error(`Recipe ${recipe.name} has invalid input name: ${name}`);
+    if (RESERVED_INPUTS.has(name)) throw new Error(`Recipe ${recipe.name} input is reserved: ${name}`);
+    assertPlainObject(input, `Recipe ${recipe.name} input ${name}`);
+    if (Object.keys(input).some((key) => !['description', 'required', 'default'].includes(key))) {
+      throw new Error(`Recipe ${recipe.name} input ${name} contains unsupported fields.`);
+    }
+    if (input.description !== undefined && typeof input.description !== 'string') {
+      throw new Error(`Recipe ${recipe.name} input ${name} description must be a string.`);
+    }
+    if (input.required !== undefined && typeof input.required !== 'boolean') {
+      throw new Error(`Recipe ${recipe.name} input ${name} required must be true or false.`);
+    }
+    if (input.default !== undefined && typeof input.default !== 'string') {
+      throw new Error(`Recipe ${recipe.name} input ${name} default must be a string.`);
+    }
+  }
+
+  if (!Array.isArray(recipe.requirements)) throw new Error(`Recipe ${recipe.name} requirements must be an array.`);
+  recipe.requirements.forEach((item, index) => validateValueSpec(item, `requirements[${index}]`));
+  if (!Array.isArray(recipe.actions) || recipe.actions.length === 0) {
+    throw new Error(`Recipe ${recipe.name} must define at least one action.`);
+  }
+  recipe.actions.forEach((action, index) => validateAction(action, index));
+  if (recipe.detect !== undefined) validateDetect(recipe.detect, recipe.name);
+  if (recipe.lifecycle !== undefined) validateLifecycle(recipe.lifecycle, recipe.name);
+  return recipe;
+}
+
+module.exports = {
+  validateAction,
+  validateRecipe,
+  validateValueSpec,
+};

package/src/runner/captured.js

@@ -0,0 +1,125 @@
+// Copyright (c) 2026 bachbnt
+
+const { spawn } = require('child_process');
+const { SIGNAL_EXIT_CODES } = require('./process');
+
+function runProcessCaptured(command, options = {}) {
+  const spawnImpl = options.spawnImpl || spawn;
+  const maxOutputBytes = Number.isInteger(options.maxOutputBytes) && options.maxOutputBytes >= 0
+    ? options.maxOutputBytes
+    : Infinity;
+  const timeoutMs = Number.isInteger(options.timeoutMs) && options.timeoutMs > 0
+    ? options.timeoutMs
+    : 0;
+  return new Promise((resolve) => {
+    let settled = false;
+    let stdout = '';
+    let stderr = '';
+    let outputBytes = 0;
+    let outputTruncated = false;
+    let exitResult;
+    let timedOut = false;
+    let child;
+    let timer;
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve({ ...result, stdout, stderr, outputTruncated });
+    };
+
+    const appendOutput = (stream, data) => {
+      const buffer = Buffer.isBuffer(data) ? data : Buffer.from(String(data));
+      const remaining = maxOutputBytes - outputBytes;
+      if (remaining <= 0) {
+        if (buffer.length > 0) outputTruncated = true;
+        return;
+      }
+      const chunkBuffer = buffer.length > remaining ? buffer.subarray(0, remaining) : buffer;
+      const chunk = chunkBuffer.toString();
+      if (stream === 'stdout') stdout += chunk;
+      else stderr += chunk;
+      outputBytes += chunkBuffer.length;
+      if (chunkBuffer.length < buffer.length) outputTruncated = true;
+    };
+
+    try {
+      const spawnOptions = { shell: false, stdio: 'pipe' };
+      if (command.cwd) spawnOptions.cwd = command.cwd;
+      child = spawnImpl(command.executable, command.args, spawnOptions);
+    } catch (error) {
+      finish({ ok: false, exitCode: error.code === 'ENOENT' ? 127 : 1, error });
+      return;
+    }
+
+    if (timeoutMs) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        try {
+          if (child && !child.killed) child.kill('SIGTERM');
+        } catch {}
+        finish({
+          ok: false,
+          exitCode: SIGNAL_EXIT_CODES.SIGTERM || 143,
+          signal: 'SIGTERM',
+          timedOut: true,
+        });
+      }, timeoutMs);
+    }
+
+    child.stdout?.on('data', (data) => appendOutput('stdout', data));
+    child.stderr?.on('data', (data) => appendOutput('stderr', data));
+
+    child.once('error', (error) => {
+      finish({ ok: false, exitCode: error.code === 'ENOENT' ? 127 : 1, error });
+    });
+    child.once('exit', (code, signal) => {
+      if (signal) {
+        exitResult = {
+          ok: false,
+          exitCode: SIGNAL_EXIT_CODES[signal] || 1,
+          signal,
+          timedOut,
+        };
+        if (!child.stdout && !child.stderr) finish(exitResult);
+        return;
+      }
+      exitResult = { ok: code === 0, exitCode: code ?? 1 };
+      if (!child.stdout && !child.stderr) finish(exitResult);
+    });
+    child.once('close', (code, signal) => {
+      if (exitResult) {
+        finish(exitResult);
+        return;
+      }
+      if (signal) {
+        finish({ ok: false, exitCode: SIGNAL_EXIT_CODES[signal] || 1, signal, timedOut });
+        return;
+      }
+      finish({ ok: code === 0, exitCode: code ?? 1 });
+    });
+  });
+}
+
+async function runSequenceCaptured(commands, options = {}) {
+  let output = '';
+  let outputTruncated = false;
+  for (let index = 0; index < commands.length; index += 1) {
+    const remaining = Number.isInteger(options.maxOutputBytes) && options.maxOutputBytes >= 0
+      ? Math.max(options.maxOutputBytes - output.length, 0)
+      : undefined;
+    const result = await runProcessCaptured(commands[index], {
+      ...options,
+      maxOutputBytes: remaining,
+    });
+    output += result.stdout + result.stderr;
+    outputTruncated ||= result.outputTruncated;
+    if (!result.ok) {
+      return { ...result, output, outputTruncated, failedCommand: commands[index], failedIndex: index };
+    }
+  }
+  return { ok: true, exitCode: 0, output, outputTruncated };
+}
+
+module.exports = { runProcessCaptured, runSequenceCaptured };

package/src/runner/check.js

@@ -0,0 +1,93 @@
+// Copyright (c) 2026 bachbnt
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function findExecutable(executable, options = {}) {
+  const env = options.env || process.env;
+  const fsImpl = options.fsImpl || fs;
+  if (executable.includes(path.sep)) {
+    const candidate = path.resolve(options.cwd || process.cwd(), executable);
+    return fsImpl.existsSync(candidate) ? candidate : undefined;
+  }
+
+  const extensions = process.platform === 'win32'
+    ? (env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';')
+    : [''];
+  for (const directory of (env.PATH || '').split(path.delimiter).filter(Boolean)) {
+    for (const extension of extensions) {
+      const candidate = path.join(directory, `${executable}${extension}`);
+      try {
+        fsImpl.accessSync(candidate, fs.constants.X_OK);
+        return candidate;
+      } catch (error) {
+        // Continue searching PATH.
+      }
+    }
+  }
+  return undefined;
+}
+
+function getVersion(executable, args = ['--version'], options = {}) {
+  const spawnSyncImpl = options.spawnSyncImpl || spawnSync;
+  const result = spawnSyncImpl(executable, args, { encoding: 'utf8' });
+  if (result.error || result.status !== 0) return undefined;
+  const output = `${result.stdout || result.stderr || ''}`.trim();
+  try {
+    const data = JSON.parse(output);
+    return data.frameworkVersion || data.version || 'available';
+  } catch (error) {
+    return output
+      .replace(/\u001b\[[0-9;?]*[ -/]*[@-~]/g, '')
+      .split('\n')
+      .map((line) => line.trim())
+      .find(Boolean) || 'available';
+  }
+}
+
+function checkTools(config, options = {}) {
+  const tools = [
+    { name: 'Node.js', executable: 'node', args: ['--version'], required: true, hint: 'Install from https://nodejs.org or run: nvm install --lts' },
+    { name: 'npm', executable: 'npm', args: ['--version'], required: true, hint: 'npm ships with Node.js. Reinstall Node.js.' },
+    { name: 'Git', executable: 'git', args: ['--version'], required: true, hint: 'macOS: xcode-select --install | Linux: sudo apt install git' },
+    { name: 'pnpm', executable: 'pnpm', args: ['--version'], hint: 'Run: corepack enable pnpm (or npm install --global pnpm)' },
+    { name: 'Yarn', executable: 'yarn', args: ['--version'], hint: 'Run: corepack enable yarn' },
+    { name: 'Python', executable: config.python, args: ['--version'], hint: 'macOS: brew install python | Linux: sudo apt install python3 python3-venv' },
+    { name: 'Docker', executable: 'docker', args: ['--version'], hint: 'Install Docker Desktop from https://docs.docker.com/get-docker/' },
+    { name: 'Flutter', executable: 'flutter', args: ['--version', '--machine'], hint: 'See https://docs.flutter.dev/get-started/install' },
+    { name: 'Android adb', executable: 'adb', args: ['version'], hint: 'Install Android Studio and add platform-tools to PATH' },
+    { name: 'Android emulator', executable: 'emulator', args: ['-version'], hint: 'Install Android Studio and add emulator to PATH' },
+  ];
+  if (process.platform === 'darwin') {
+    tools.push({ name: 'Xcode', executable: 'xcodebuild', args: ['-version'], hint: 'Install Xcode from the App Store, then: xcode-select --install' });
+  }
+
+  return tools.map((tool) => {
+    const found = findExecutable(tool.executable, options);
+    return {
+      ...tool,
+      found: Boolean(found),
+      path: found,
+      version: found ? getVersion(tool.executable, tool.args, options) : undefined,
+    };
+  });
+}
+
+function assertExecutables(requirements, options = {}) {
+  const missing = [...new Set(requirements)].filter(
+    (executable) => !findExecutable(executable, options)
+  );
+  if (missing.length > 0) {
+    throw new Error(
+      `Missing required executable${missing.length > 1 ? 's' : ''}: ${missing.join(', ')}. Run dev doctor for setup details.`
+    );
+  }
+}
+
+module.exports = {
+  assertExecutables,
+  checkTools,
+  findExecutable,
+  getVersion,
+};

package/src/runner/command.js

@@ -0,0 +1,43 @@
+// Copyright (c) 2026 bachbnt
+
+function createCommand(executable, args = [], options = {}) {
+  const command = { executable, args: args.map(String) };
+  if (options.cwd) command.cwd = options.cwd;
+  return command;
+}
+
+function formatArgument(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(text)) return text;
+  return `'${text.replace(/'/g, `'\\''`)}'`;
+}
+
+function formatCommand(command) {
+  const formatted = [command.executable, ...command.args].map(formatArgument).join(' ');
+  return command.cwd ? `(cd ${formatArgument(command.cwd)} && ${formatted})` : formatted;
+}
+
+function formatSequence(commands) {
+  return commands.map(formatCommand).join(' && ');
+}
+
+function isCommand(value) {
+  return Boolean(
+    value &&
+      typeof value.executable === 'string' &&
+      Array.isArray(value.args) &&
+      value.args.every((arg) => typeof arg === 'string') &&
+      (value.cwd === undefined || typeof value.cwd === 'string')
+  );
+}
+
+function isCommandSequence(value) {
+  return Array.isArray(value) && value.length > 0 && value.every(isCommand);
+}
+
+module.exports = {
+  createCommand,
+  formatCommand,
+  formatSequence,
+  isCommandSequence,
+};

package/src/runner/parallel.js

@@ -0,0 +1,110 @@
+// Copyright (c) 2026 bachbnt
+
+const { spawn } = require('child_process');
+const { SIGNAL_EXIT_CODES } = require('./process');
+
+function createLinePrefixer(label, write) {
+  let pending = '';
+  return {
+    push(data) {
+      pending += data.toString();
+      const lines = pending.split(/\r?\n/);
+      pending = lines.pop();
+      for (const line of lines) write(`[${label}] ${line}\n`);
+    },
+    flush() {
+      if (pending) write(`[${label}] ${pending}\n`);
+      pending = '';
+    },
+  };
+}
+
+function runJob(job, context) {
+  const prefixer = createLinePrefixer(job.label, context.write);
+  return new Promise((resolve) => {
+    let index = 0;
+    const next = () => {
+      if (context.stopped) {
+        prefixer.flush();
+        resolve({ label: job.label, ok: false, exitCode: context.signalCode || 1 });
+        return;
+      }
+      if (index >= job.commands.length) {
+        prefixer.flush();
+        resolve({ label: job.label, ok: true, exitCode: 0 });
+        return;
+      }
+      const command = job.commands[index];
+      let child;
+      try {
+        const spawnOptions = { shell: false, stdio: ['ignore', 'pipe', 'pipe'] };
+        if (command.cwd) spawnOptions.cwd = command.cwd;
+        child = context.spawnImpl(command.executable, command.args, spawnOptions);
+      } catch (error) {
+        prefixer.push(`${error.message}\n`);
+        prefixer.flush();
+        resolve({ label: job.label, ok: false, exitCode: error.code === 'ENOENT' ? 127 : 1 });
+        return;
+      }
+      context.children.add(child);
+      child.stdout?.on('data', (data) => prefixer.push(data));
+      child.stderr?.on('data', (data) => prefixer.push(data));
+      let settled = false;
+      const done = (result) => {
+        if (settled) return;
+        settled = true;
+        context.children.delete(child);
+        if (!result.ok) {
+          prefixer.flush();
+          resolve({ label: job.label, ...result });
+          return;
+        }
+        index += 1;
+        next();
+      };
+      child.once('error', (error) => {
+        prefixer.push(`${error.message}\n`);
+        done({ ok: false, exitCode: error.code === 'ENOENT' ? 127 : 1 });
+      });
+      child.once('close', (code, signal) => {
+        if (signal) done({ ok: false, exitCode: SIGNAL_EXIT_CODES[signal] || 1, signal });
+        else done({ ok: code === 0, exitCode: code ?? 1 });
+      });
+    };
+    next();
+  });
+}
+
+async function runParallel(jobs, options = {}) {
+  const signalSource = options.signalSource || process;
+  const context = {
+    spawnImpl: options.spawnImpl || spawn,
+    write: options.write || ((text) => process.stdout.write(text)),
+    children: new Set(),
+    stopped: false,
+    signalCode: undefined,
+  };
+  const stop = (signal) => {
+    context.stopped = true;
+    context.signalCode = SIGNAL_EXIT_CODES[signal];
+    for (const child of context.children) {
+      try {
+        child.kill(signal);
+      } catch {}
+    }
+  };
+  const onSigint = () => stop('SIGINT');
+  const onSigterm = () => stop('SIGTERM');
+  signalSource.once('SIGINT', onSigint);
+  signalSource.once('SIGTERM', onSigterm);
+  try {
+    const results = await Promise.all(jobs.map((job) => runJob(job, context)));
+    const failed = results.find((result) => !result.ok);
+    return { ok: !failed, exitCode: failed ? failed.exitCode : 0, results };
+  } finally {
+    signalSource.removeListener('SIGINT', onSigint);
+    signalSource.removeListener('SIGTERM', onSigterm);
+  }
+}
+
+module.exports = { createLinePrefixer, runParallel };