@hfossli/dev 0.1.0

package/bin/_dev.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+require("../src/cli.js").main().catch((error) => {
+  const message = error && error.message ? error.message : String(error);
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@hfossli/dev",
+  "version": "0.1.0",
+  "dependencies": {
+    "@hfossli/dev-helpers": "0.1.0",
+    "@hfossli/dev-sdk": "0.1.0"
+  },
+  "bin": {
+    "dev": "bin/_dev.js",
+    "_dev": "bin/_dev.js"
+  }
+}

package/src/cli.js

@@ -0,0 +1,174 @@
+const path = require("node:path");
+const { usage } = require("./internal/usage.js");
+const { parseArgs } = require("./internal/parse-args.js");
+const { findConfigPath, loadRuntimeConfig } = require("./internal/config/load-config.js");
+const { getItemDescription, createUsageError } = require("./internal/config/normalize-config.js");
+const { createTmuxController } = require("./internal/runtime/tmux.js");
+const { die } = require("./internal/runtime/process.js");
+const { sessionName } = require("@hfossli/dev-helpers/worktree");
+const { handleTool } = require("./internal/commands/tool.js");
+const { handleCmd } = require("./internal/commands/cmd.js");
+const { handleStartOrRestart } = require("./internal/commands/start-restart.js");
+const { handleStop } = require("./internal/commands/stop.js");
+const { handleLogs } = require("./internal/commands/logs.js");
+const { handleTail } = require("./internal/commands/tail.js");
+const { handleAttach } = require("./internal/commands/attach.js");
+
+function buildRuntime({ root, config, configPath }) {
+  const sessionId = sessionName(root);
+  const tmuxSession = `dev-e2e-${sessionId}`;
+  const apps = config.apps;
+  const tools = config.tools;
+  const appNames = Object.keys(apps).sort();
+  const toolNames = Object.keys(tools).sort();
+  const appEntries = appNames.map((name) => ({
+    name,
+    description: getItemDescription(apps[name]),
+  }));
+  const toolEntries = toolNames.map((name) => ({
+    name,
+    description: getItemDescription(tools[name]),
+  }));
+
+  return {
+    appNames,
+    apps,
+    configPath,
+    root,
+    tmux: createTmuxController({
+      cliScriptPath: path.resolve(__dirname, "../bin/_dev.js"),
+    }),
+    tmuxSession,
+    toolNames,
+    tools,
+    usageText: usage(appEntries, toolEntries),
+  };
+}
+
+function validateParsedArgs(parsed, baseUsageText) {
+  const validCommands = new Set([
+    "start",
+    "restart",
+    "stop",
+    "attach",
+    "logs",
+    "tail",
+    "tool",
+    "cmd",
+  ]);
+
+  if (!validCommands.has(parsed.command)) {
+    const error = new Error(`Error: unknown command "${parsed.command}"`);
+    error.isUsageError = true;
+    error.usageText = baseUsageText;
+    throw error;
+  }
+
+  const isStartLike = parsed.command === "start" || parsed.command === "restart";
+  if (!isStartLike && parsed.attachRequested) {
+    throw createUsageError("Error: --attach is only supported for start/restart.");
+  }
+  const allowsLines =
+    parsed.command === "logs" ||
+    parsed.command === "tail" ||
+    (parsed.command === "attach" && !parsed.app) ||
+    (isStartLike && parsed.attachRequested && parsed.app === "all");
+
+  if (parsed.linesOverride !== null && !allowsLines) {
+    throw createUsageError(
+      "Error: --lines is only supported for logs, tail, attach, or start/restart all with --attach."
+    );
+  }
+  if (parsed.untilMarker !== null && parsed.command !== "tail") {
+    throw createUsageError("Error: --until-marker is only supported for tail.");
+  }
+  if (parsed.untilTimeoutSeconds !== null && parsed.command !== "tail") {
+    throw createUsageError("Error: --until-timeout is only supported for tail.");
+  }
+}
+
+function renderError(error, fallbackUsageText) {
+  if (error.onlyUsage) {
+    process.stderr.write(`${fallbackUsageText}\n`);
+    process.exit(error.exitCode || 2);
+  }
+
+  if (error.isUsageError && error.usageText) {
+    process.stderr.write(`${error.message}\n\n${error.usageText}\n`);
+    process.exit(error.exitCode || 1);
+  }
+
+  if (error.isUsageError) {
+    die(error.message, error.exitCode || 1);
+  }
+
+  throw error;
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const baseUsageText = usage();
+  let parsed;
+
+  try {
+    parsed = parseArgs(argv);
+  } catch (error) {
+    renderError(error, baseUsageText);
+    return;
+  }
+
+  if (parsed.help) {
+    process.stdout.write(`${baseUsageText}\n`);
+    return;
+  }
+
+  if (!parsed.command) {
+    process.stderr.write(`${baseUsageText}\n`);
+    process.exit(1);
+  }
+
+  try {
+    validateParsedArgs(parsed, baseUsageText);
+
+    const cwd = process.cwd();
+    const configPath = findConfigPath(cwd);
+    const root = path.dirname(configPath);
+    const session = sessionName(root);
+    const { config } = await loadRuntimeConfig({ cwd, configPath, root, session });
+    const runtime = buildRuntime({ root, config, configPath });
+
+    switch (parsed.command) {
+      case "tool":
+        handleTool(parsed, runtime);
+        return;
+      case "cmd":
+        handleCmd(parsed, runtime);
+        return;
+      case "start":
+      case "restart":
+        handleStartOrRestart(parsed, runtime);
+        return;
+      case "stop":
+        handleStop(parsed, runtime);
+        return;
+      case "logs":
+        handleLogs(parsed, runtime);
+        return;
+      case "tail":
+        handleTail(parsed, runtime);
+        return;
+      case "attach":
+        handleAttach(parsed, runtime);
+        return;
+      default:
+        throw createUsageError(`Error: unknown command "${parsed.command}"`);
+    }
+  } catch (error) {
+    renderError(error, baseUsageText);
+  }
+}
+
+module.exports = {
+  buildRuntime,
+  main,
+  validateParsedArgs,
+};

package/src/internal/commands/attach.js

@@ -0,0 +1,43 @@
+const { createUsageError } = require("../config/normalize-config.js");
+const { ensureAppDefined, resolveLineCount } = require("./shared.js");
+
+function handleAttach(parsed, runtime) {
+  const { appNames, apps, root, tmux, tmuxSession, usageText } = runtime;
+
+  tmux.ensureInstalled();
+
+  if (!tmux.sessionExists(tmuxSession)) {
+    throw createUsageError(`Error: session "${tmuxSession}" does not exist.`);
+  }
+
+  tmux.enableMouse(tmuxSession);
+
+  if (parsed.app) {
+    if (parsed.linesOverride !== null) {
+      const error = new Error("Error: attach <app> does not support --lines.");
+      error.isUsageError = true;
+      error.usageText = usageText;
+      throw error;
+    }
+
+    ensureAppDefined({ appName: parsed.app, apps, usageText });
+    if (!tmux.windowExists(tmuxSession, parsed.app)) {
+      throw createUsageError(`Error: window "${parsed.app}" does not exist in session "${tmuxSession}".`);
+    }
+    tmux.selectWindow(tmuxSession, parsed.app);
+    tmux.attachSession(tmuxSession);
+    return;
+  }
+
+  tmux.openSplitAttachWindow({
+    root,
+    tmuxSession,
+    appNames,
+    lines: resolveLineCount(parsed.linesOverride),
+  });
+  tmux.attachSession(tmuxSession);
+}
+
+module.exports = {
+  handleAttach,
+};

package/src/internal/commands/cmd.js

@@ -0,0 +1,25 @@
+const { resolveStartCommand } = require("../config/normalize-config.js");
+const { shellQuote } = require("../runtime/shell.js");
+const { dieWithUsage } = require("./shared.js");
+
+function handleCmd(parsed, runtime) {
+  const { apps, root, usageText } = runtime;
+  if (!parsed.app) {
+    const error = new Error(usageText);
+    error.exitCode = 2;
+    error.onlyUsage = true;
+    throw error;
+  }
+
+  if (!Object.prototype.hasOwnProperty.call(apps, parsed.app)) {
+    dieWithUsage(`Error: unknown app "${parsed.app}"`, usageText);
+  }
+
+  const startCommand = resolveStartCommand(parsed.app, apps[parsed.app]);
+  const wrappedCommand = `cd ${shellQuote(root)} && ${startCommand}`;
+  process.stdout.write(`${wrappedCommand}\n`);
+}
+
+module.exports = {
+  handleCmd,
+};

package/src/internal/commands/logs.js

@@ -0,0 +1,22 @@
+const { ensureAppTarget, resolveLineCount } = require("./shared.js");
+
+function handleLogs(parsed, runtime) {
+  const { apps, tmux, tmuxSession, usageText } = runtime;
+  ensureAppTarget({
+    appName: parsed.app,
+    apps,
+    usageText,
+    tmuxSession,
+    tmux,
+  });
+
+  const lines = resolveLineCount(parsed.linesOverride);
+  const snapshot = tmux.captureWindowLogs(tmuxSession, parsed.app, lines);
+  if (snapshot) {
+    process.stdout.write(`${snapshot}\n`);
+  }
+}
+
+module.exports = {
+  handleLogs,
+};

package/src/internal/commands/shared.js

@@ -0,0 +1,64 @@
+const { createUsageError } = require("../config/normalize-config.js");
+
+function resolveLineCount(linesOverride) {
+  if (Number.isInteger(linesOverride) && linesOverride > 0) return linesOverride;
+  const fromEnv = Number.parseInt(String(process.env.TAIL_LINES || ""), 10);
+  if (Number.isInteger(fromEnv) && fromEnv > 0) return fromEnv;
+  return 120;
+}
+
+function dieWithUsage(message, usageText, code = 1) {
+  const error = createUsageError(message);
+  error.usageText = usageText;
+  error.exitCode = code;
+  throw error;
+}
+
+function ensureAppDefined({ appName, apps, usageText }) {
+  if (!appName) {
+    const error = new Error(usageText);
+    error.exitCode = 2;
+    error.onlyUsage = true;
+    throw error;
+  }
+
+  if (!Object.prototype.hasOwnProperty.call(apps, appName)) {
+    dieWithUsage(`Error: unknown app "${appName}"`, usageText);
+  }
+}
+
+function ensureAppTarget({ appName, apps, usageText, tmuxSession, tmux }) {
+  ensureAppDefined({ appName, apps, usageText });
+  tmux.ensureInstalled();
+
+  if (!tmux.sessionExists(tmuxSession)) {
+    throw createUsageError(`Error: session "${tmuxSession}" does not exist.`);
+  }
+
+  if (!tmux.windowExists(tmuxSession, appName)) {
+    throw createUsageError(`Error: window "${appName}" does not exist in session "${tmuxSession}".`);
+  }
+}
+
+function getOverlapCount(previousLines, nextLines) {
+  const maxOverlap = Math.min(previousLines.length, nextLines.length);
+  for (let overlap = maxOverlap; overlap >= 0; overlap--) {
+    let equal = true;
+    for (let index = 0; index < overlap; index++) {
+      if (previousLines[previousLines.length - overlap + index] !== nextLines[index]) {
+        equal = false;
+        break;
+      }
+    }
+    if (equal) return overlap;
+  }
+  return 0;
+}
+
+module.exports = {
+  dieWithUsage,
+  ensureAppDefined,
+  ensureAppTarget,
+  getOverlapCount,
+  resolveLineCount,
+};

package/src/internal/commands/start-restart.js

@@ -0,0 +1,119 @@
+const { resolveStartCommand } = require("../config/normalize-config.js");
+const { shellQuote } = require("../runtime/shell.js");
+const { createUsageError } = require("../config/normalize-config.js");
+const { dieWithUsage, resolveLineCount } = require("./shared.js");
+
+function buildWrappedCommand(root, command) {
+  return `cd ${shellQuote(root)} && ${command}`;
+}
+
+function handleStartOrRestart(parsed, runtime) {
+  const { apps, appNames, root, tmux, tmuxSession, usageText } = runtime;
+  const isRestart = parsed.command === "restart";
+
+  if (!parsed.app) {
+    const error = new Error(usageText);
+    error.exitCode = 2;
+    error.onlyUsage = true;
+    throw error;
+  }
+
+  tmux.ensureInstalled();
+  let sessionExists = tmux.sessionExists(tmuxSession);
+
+  if (parsed.app === "all") {
+    if (appNames.length === 0) {
+      throw createUsageError("Error: no apps are configured in the active dev config.");
+    }
+
+    if (!isRestart && sessionExists) {
+      const existingWindows = appNames.filter((name) => tmux.windowExists(tmuxSession, name));
+      if (existingWindows.length > 0) {
+        throw createUsageError(
+          `Error: cannot start all because these windows already exist in session "${tmuxSession}": ${existingWindows.join(", ")}.`
+        );
+      }
+    }
+
+    if (isRestart && sessionExists) {
+      for (const name of appNames) {
+        if (tmux.windowExists(tmuxSession, name)) {
+          tmux.killWindow(tmuxSession, name);
+        }
+      }
+      sessionExists = tmux.sessionExists(tmuxSession);
+    }
+
+    const startEntries = appNames.map((name) => ({
+      name,
+      wrappedCommand: buildWrappedCommand(root, resolveStartCommand(name, apps[name])),
+    }));
+
+    if (sessionExists) {
+      for (const entry of startEntries) {
+        tmux.newWindow(tmuxSession, entry.name, entry.wrappedCommand);
+      }
+    } else {
+      const [firstEntry, ...restEntries] = startEntries;
+      tmux.newSession(tmuxSession, firstEntry.name, firstEntry.wrappedCommand);
+      for (const entry of restEntries) {
+        tmux.newWindow(tmuxSession, entry.name, entry.wrappedCommand);
+      }
+    }
+
+    process.stdout.write(
+      `${isRestart ? "Restarted" : "Started"} apps ${appNames.join(", ")} in session "${tmuxSession}".\n`
+    );
+    for (const entry of startEntries) {
+      process.stdout.write(`- ${entry.name}: ${entry.wrappedCommand}\n`);
+    }
+  } else {
+    if (!Object.prototype.hasOwnProperty.call(apps, parsed.app)) {
+      dieWithUsage(`Error: unknown app "${parsed.app}"`, usageText);
+    }
+
+    const wrappedCommand = buildWrappedCommand(root, resolveStartCommand(parsed.app, apps[parsed.app]));
+
+    if (!isRestart && sessionExists && tmux.windowExists(tmuxSession, parsed.app)) {
+      throw createUsageError(`Error: window "${parsed.app}" already exists in session "${tmuxSession}".`);
+    }
+
+    if (isRestart && sessionExists && tmux.windowExists(tmuxSession, parsed.app)) {
+      tmux.killWindow(tmuxSession, parsed.app);
+      sessionExists = tmux.sessionExists(tmuxSession);
+    }
+
+    if (sessionExists) {
+      tmux.newWindow(tmuxSession, parsed.app, wrappedCommand);
+    } else {
+      tmux.newSession(tmuxSession, parsed.app, wrappedCommand);
+    }
+
+    process.stdout.write(
+      `${isRestart ? "Restarted" : "Started"} app "${parsed.app}" in session "${tmuxSession}" (window "${parsed.app}").\n`
+    );
+    process.stdout.write(`Command: ${wrappedCommand}\n`);
+  }
+
+  tmux.enableMouse(tmuxSession);
+
+  if (parsed.attachRequested) {
+    if (parsed.app === "all") {
+      const lines = resolveLineCount(parsed.linesOverride);
+      tmux.openSplitAttachWindow({
+        root,
+        tmuxSession,
+        appNames,
+        lines,
+      });
+    } else {
+      tmux.selectWindow(tmuxSession, parsed.app);
+    }
+    tmux.attachSession(tmuxSession);
+    return;
+  }
+}
+
+module.exports = {
+  handleStartOrRestart,
+};

package/src/internal/commands/stop.js

@@ -0,0 +1,40 @@
+const { createUsageError } = require("../config/normalize-config.js");
+const { dieWithUsage } = require("./shared.js");
+
+function handleStop(parsed, runtime) {
+  const { apps, tmux, tmuxSession, usageText } = runtime;
+
+  if (!parsed.app) {
+    const error = new Error(usageText);
+    error.exitCode = 2;
+    error.onlyUsage = true;
+    throw error;
+  }
+
+  tmux.ensureInstalled();
+
+  if (parsed.app !== "all" && !Object.prototype.hasOwnProperty.call(apps, parsed.app)) {
+    dieWithUsage(`Error: unknown app "${parsed.app}"`, usageText);
+  }
+
+  if (!tmux.sessionExists(tmuxSession)) {
+    throw createUsageError(`Error: session "${tmuxSession}" does not exist.`);
+  }
+
+  if (parsed.app === "all") {
+    tmux.killSession(tmuxSession);
+    process.stdout.write(`Stopped session "${tmuxSession}".\n`);
+    return;
+  }
+
+  if (!tmux.windowExists(tmuxSession, parsed.app)) {
+    throw createUsageError(`Error: window "${parsed.app}" does not exist in session "${tmuxSession}".`);
+  }
+
+  tmux.killWindow(tmuxSession, parsed.app);
+  process.stdout.write(`Stopped app "${parsed.app}" in session "${tmuxSession}".\n`);
+}
+
+module.exports = {
+  handleStop,
+};

package/src/internal/commands/tail.js

@@ -0,0 +1,81 @@
+const { ensureAppTarget, getOverlapCount, resolveLineCount } = require("./shared.js");
+
+function handleTail(parsed, runtime) {
+  const { apps, tmux, tmuxSession, usageText } = runtime;
+  ensureAppTarget({
+    appName: parsed.app,
+    apps,
+    usageText,
+    tmuxSession,
+    tmux,
+  });
+
+  const lines = resolveLineCount(parsed.linesOverride);
+  const untilMarker = parsed.untilMarker;
+  const untilTimeoutSeconds = parsed.untilTimeoutSeconds;
+  let previousLines = [];
+  let timer = null;
+  let timeoutTimer = null;
+  let tailStopped = false;
+
+  const stopTail = (code = 0, message = "") => {
+    if (tailStopped) return;
+    tailStopped = true;
+    if (timer) clearInterval(timer);
+    if (timeoutTimer) clearTimeout(timeoutTimer);
+    if (message) {
+      const out = code === 0 ? process.stdout : process.stderr;
+      out.write(`${message}\n`);
+    }
+    process.exit(code);
+  };
+
+  const initialSnapshot = tmux.captureWindowLogs(tmuxSession, parsed.app, lines);
+  if (initialSnapshot) {
+    process.stdout.write(`${initialSnapshot}\n`);
+    previousLines = initialSnapshot.split(/\r?\n/);
+  }
+  if (untilMarker && initialSnapshot.includes(untilMarker)) {
+    stopTail(0);
+    return;
+  }
+
+  if (untilTimeoutSeconds !== null) {
+    const timeoutMs = Math.max(1, Math.round(untilTimeoutSeconds * 1000));
+    timeoutTimer = setTimeout(() => {
+      if (untilMarker) {
+        stopTail(
+          124,
+          `Error: marker "${untilMarker}" was not found within ${untilTimeoutSeconds} seconds.`
+        );
+        return;
+      }
+      stopTail(0);
+    }, timeoutMs);
+  }
+
+  timer = setInterval(() => {
+    try {
+      const snapshot = tmux.captureWindowLogs(tmuxSession, parsed.app, lines);
+      const nextLines = snapshot ? snapshot.split(/\r?\n/) : [];
+      const overlap = getOverlapCount(previousLines, nextLines);
+      const appended = nextLines.slice(overlap);
+      if (appended.length > 0) {
+        process.stdout.write(`${appended.join("\n")}\n`);
+      }
+      previousLines = nextLines;
+      if (untilMarker && snapshot.includes(untilMarker)) {
+        stopTail(0);
+      }
+    } catch (error) {
+      stopTail(1, `Error: ${error.message}`);
+    }
+  }, 1000);
+
+  process.on("SIGINT", () => stopTail(0));
+  process.on("SIGTERM", () => stopTail(0));
+}
+
+module.exports = {
+  handleTail,
+};

package/src/internal/commands/tool.js

@@ -0,0 +1,32 @@
+const { withInheritedPath } = require("../runtime/shell.js");
+const { resolveToolCommand } = require("../config/normalize-config.js");
+const { run } = require("../runtime/process.js");
+
+function handleTool(parsed, runtime) {
+  const { usageText, root, tools } = runtime;
+  const toolName = parsed.app;
+  if (!toolName) {
+    const error = new Error(usageText);
+    error.exitCode = 2;
+    error.onlyUsage = true;
+    throw error;
+  }
+
+  if (!Object.prototype.hasOwnProperty.call(tools, toolName)) {
+    const error = new Error(`Error: unknown tool "${toolName}"`);
+    error.isUsageError = true;
+    error.usageText = usageText;
+    throw error;
+  }
+
+  const toolCommand = resolveToolCommand(toolName, tools[toolName], parsed.commandArgs);
+  const toolCommandWithPath = withInheritedPath(toolCommand);
+
+  process.stdout.write(`Running tool "${toolName}": ${toolCommand}\n`);
+  const shellPath = process.env.SHELL || "/bin/zsh";
+  run(shellPath, ["-lc", toolCommandWithPath], { cwd: root, stdio: "inherit" });
+}
+
+module.exports = {
+  handleTool,
+};

package/src/internal/config/load-config.js

@@ -0,0 +1,209 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const { createRequire, stripTypeScriptTypes } = require("node:module");
+const { pathToFileURL } = require("node:url");
+const { isDefinedConfig } = require("@hfossli/dev-sdk");
+const { sessionName } = require("@hfossli/dev-helpers/worktree");
+const { normalizeRuntimeConfig } = require("./normalize-config.js");
+const { createUsageError } = require("./normalize-config.js");
+
+const CONFIG_CANDIDATE_FILENAMES = [
+  "dev.config.js",
+  "dev.config.ts",
+  "_dev.config.js",
+  "_dev.config.ts",
+];
+const LEGACY_CONFIG_FILENAMES = new Set(["_dev.config.js", "_dev.config.ts"]);
+
+function stripConfigTypeScript(sourceCode) {
+  const originalEmitWarning = process.emitWarning;
+  process.emitWarning = function emitWarningPatched(warning, ...args) {
+    const type = typeof args[0] === "string" ? args[0] : warning && warning.name;
+    const message =
+      typeof warning === "string" ? warning : warning && warning.message ? warning.message : "";
+    if (type === "ExperimentalWarning" && message.includes("stripTypeScriptTypes")) {
+      return;
+    }
+    return originalEmitWarning.call(this, warning, ...args);
+  };
+
+  try {
+    return stripTypeScriptTypes(sourceCode);
+  } finally {
+    process.emitWarning = originalEmitWarning;
+  }
+}
+
+function transformImportsToRequire(sourceCode) {
+  return sourceCode
+    .replace(
+      /^\s*import\s+\{([^}]+)\}\s+from\s+["']([^"']+)["'];?\s*$/gm,
+      (_match, imports, moduleName) => `const {${imports.trim()}} = require(${JSON.stringify(moduleName)});`
+    )
+    .replace(
+      /^\s*import\s+\*\s+as\s+([A-Za-z_$][\w$]*)\s+from\s+["']([^"']+)["'];?\s*$/gm,
+      (_match, name, moduleName) => `const ${name} = require(${JSON.stringify(moduleName)});`
+    )
+    .replace(
+      /^\s*import\s+([A-Za-z_$][\w$]*)\s+from\s+["']([^"']+)["'];?\s*$/gm,
+      (_match, name, moduleName) =>
+        `const ${name} = (() => { const __imported = require(${JSON.stringify(moduleName)}); return __imported && __imported.default !== undefined ? __imported.default : __imported; })();`
+    );
+}
+
+function transformExportsToCommonJs(sourceCode) {
+  const transformed = sourceCode.replace(/\bexport\s+default\b/, "module.exports.default =");
+  if (transformed !== sourceCode) {
+    return transformed;
+  }
+  return sourceCode;
+}
+
+function loadConfigModuleFromTransformedSource(configPath, sourceCode) {
+  const stripped = configPath.endsWith(".ts") ? stripConfigTypeScript(sourceCode) : sourceCode;
+  const transformed = transformExportsToCommonJs(transformImportsToRequire(stripped));
+
+  const moduleObj = { exports: {} };
+  const localRequire = createRequire(configPath);
+  const dirname = path.dirname(configPath);
+  const runner = new Function(
+    "require",
+    "module",
+    "exports",
+    "__filename",
+    "__dirname",
+    transformed
+  );
+  runner(localRequire, moduleObj, moduleObj.exports, configPath, dirname);
+  return moduleObj.exports;
+}
+
+async function loadModule(configPath) {
+  let loaded;
+
+  try {
+    loaded = require(configPath);
+  } catch (requireError) {
+    try {
+      const imported = await import(pathToFileURL(configPath).href);
+      loaded = imported;
+    } catch (importError) {
+      try {
+        const sourceCode = fs.readFileSync(configPath, "utf8");
+        loaded = loadConfigModuleFromTransformedSource(configPath, sourceCode);
+      } catch (transpileError) {
+        const detail =
+          transpileError && transpileError.message
+            ? transpileError.message
+            : importError && importError.message
+              ? importError.message
+              : requireError.message;
+        throw createUsageError(`Error: failed to load ${configPath}: ${detail}`);
+      }
+    }
+  }
+
+  if (!loaded || (typeof loaded !== "object" && typeof loaded !== "function")) {
+    throw createUsageError(`Error: ${configPath} must export a config function or module object.`);
+  }
+
+  return loaded;
+}
+
+function findConfigPath(cwd = process.cwd()) {
+  let currentDir = path.resolve(cwd);
+
+  while (true) {
+    for (const filename of CONFIG_CANDIDATE_FILENAMES) {
+      const candidate = path.join(currentDir, filename);
+      if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+        return candidate;
+      }
+    }
+
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) break;
+    currentDir = parentDir;
+  }
+
+  throw createUsageError(
+    `Error: failed to load config from ${path.resolve(cwd)}: no ${CONFIG_CANDIDATE_FILENAMES.join(", ")} file was found in this directory or any parent directory.`
+  );
+}
+
+function getFactoryCandidate(loaded) {
+  const candidates = [
+    typeof loaded === "function" ? loaded : null,
+    loaded && loaded.config,
+    loaded && loaded.default,
+    loaded && loaded.default && loaded.default.config,
+  ];
+
+  return candidates.find((candidate) => typeof candidate === "function") || null;
+}
+
+function buildConfigContext({ root, cwd, session }) {
+  return {
+    root,
+    cwd,
+    session,
+    env: { ...process.env },
+    platform: process.platform,
+  };
+}
+
+function warnLegacyConfig(configPath) {
+  process.stderr.write(
+    `[deprecation] ${configPath} is using the legacy config(session) API. ` +
+      `Switch to defineConfig(({ root, cwd, session, env, platform }) => ({ ... })).\n`
+  );
+}
+
+function warnLegacyFilename(configPath) {
+  process.stderr.write(
+    `[deprecation] ${configPath} uses the legacy config filename. ` +
+      `Rename it to dev.config.js or dev.config.ts.\n`
+  );
+}
+
+async function loadRuntimeConfig({ configPath, root, cwd, session }) {
+  const resolvedConfigPath = configPath || findConfigPath(cwd);
+  const configRoot = root || path.dirname(resolvedConfigPath);
+  const resolvedSession = session || sessionName(configRoot);
+  const loaded = await loadModule(resolvedConfigPath);
+  const configFactory = getFactoryCandidate(loaded);
+
+  if (!configFactory) {
+    throw createUsageError(
+      `Error: ${resolvedConfigPath} must export defineConfig(...) or legacy config(session).`
+    );
+  }
+
+  const mode = isDefinedConfig(configFactory) ? "modern" : "legacy";
+  if (mode === "legacy") {
+    warnLegacyConfig(resolvedConfigPath);
+  }
+  if (LEGACY_CONFIG_FILENAMES.has(path.basename(resolvedConfigPath))) {
+    warnLegacyFilename(resolvedConfigPath);
+  }
+
+  const rawConfig =
+    mode === "modern"
+      ? configFactory(buildConfigContext({ root: configRoot, cwd, session: resolvedSession }))
+      : configFactory(resolvedSession);
+
+  return {
+    configPath: resolvedConfigPath,
+    root: configRoot,
+    session: resolvedSession,
+    mode,
+    config: normalizeRuntimeConfig(rawConfig, resolvedConfigPath),
+  };
+}
+
+module.exports = {
+  buildConfigContext,
+  findConfigPath,
+  loadRuntimeConfig,
+  loadConfigModuleFromTransformedSource,
+};

package/src/internal/config/normalize-config.js

@@ -0,0 +1,108 @@
+const { shellQuote } = require("../runtime/shell.js");
+
+function createUsageError(message) {
+  const error = new Error(message);
+  error.isUsageError = true;
+  return error;
+}
+
+function normalizeRuntimeConfig(cfg, configPath) {
+  if (!cfg || typeof cfg !== "object") {
+    throw createUsageError(`Error: config in ${configPath} must return an object.`);
+  }
+  if (!cfg.apps || typeof cfg.apps !== "object") {
+    throw createUsageError(`Error: config in ${configPath} must return an apps object.`);
+  }
+  if (cfg.tools !== undefined && (!cfg.tools || typeof cfg.tools !== "object")) {
+    throw createUsageError(`Error: config in ${configPath} must return tools as an object when provided.`);
+  }
+
+  for (const [appName, appDef] of Object.entries(cfg.apps)) {
+    if (typeof appDef === "string") continue;
+    if (!appDef || typeof appDef !== "object") {
+      throw createUsageError(`Error: app "${appName}" in ${configPath} must be a string or object.`);
+    }
+    if (appDef.description !== undefined && typeof appDef.description !== "string") {
+      throw createUsageError(`Error: app "${appName}" description in ${configPath} must be a string.`);
+    }
+    if (appDef.start !== undefined && typeof appDef.start !== "string" && typeof appDef.start !== "function") {
+      throw createUsageError(`Error: app "${appName}" start in ${configPath} must be a string or function.`);
+    }
+  }
+
+  if (cfg.tools) {
+    for (const [toolName, toolDef] of Object.entries(cfg.tools)) {
+      if (typeof toolDef === "string" || typeof toolDef === "function") continue;
+      if (!toolDef || typeof toolDef !== "object") {
+        throw createUsageError(`Error: tool "${toolName}" in ${configPath} must be a string, function, or object.`);
+      }
+      if (toolDef.description !== undefined && typeof toolDef.description !== "string") {
+        throw createUsageError(`Error: tool "${toolName}" description in ${configPath} must be a string.`);
+      }
+      if (toolDef.run !== undefined && typeof toolDef.run !== "string" && typeof toolDef.run !== "function") {
+        throw createUsageError(`Error: tool "${toolName}" run in ${configPath} must be a string or function.`);
+      }
+    }
+  }
+
+  return {
+    apps: cfg.apps,
+    tools: cfg.tools && typeof cfg.tools === "object" ? cfg.tools : {},
+  };
+}
+
+function getItemDescription(itemDef) {
+  if (!itemDef || typeof itemDef !== "object") return "";
+  if (typeof itemDef.description !== "string") return "";
+  return itemDef.description.trim();
+}
+
+function resolveStartCommand(appName, appDef) {
+  if (typeof appDef === "string") return appDef;
+  if (!appDef || typeof appDef !== "object") {
+    throw createUsageError(`Error: app "${appName}" must be a string command or an object with start.`);
+  }
+
+  const { start } = appDef;
+  if (typeof start === "string") return start;
+  if (typeof start === "function") {
+    const command = start();
+    if (typeof command !== "string" || !command.trim()) {
+      throw createUsageError(`Error: app "${appName}" start() must return a non-empty string.`);
+    }
+    return command;
+  }
+
+  throw createUsageError(`Error: app "${appName}" must define start as a string or function.`);
+}
+
+function resolveToolCommand(toolName, toolDef, toolArgs) {
+  let executableDef = toolDef;
+  if (
+    toolDef &&
+    typeof toolDef === "object" &&
+    (typeof toolDef.run === "function" || typeof toolDef.run === "string")
+  ) {
+    executableDef = toolDef.run;
+  }
+
+  if (typeof executableDef === "string") return executableDef;
+  if (typeof executableDef === "function") {
+    const quotedArgs = toolArgs.map((arg) => shellQuote(arg)).join(" ");
+    const plainArgs = toolArgs.join(" ");
+    const command = executableDef(quotedArgs, toolArgs, plainArgs);
+    if (typeof command !== "string" || !command.trim()) {
+      throw createUsageError(`Error: tool "${toolName}" must return a non-empty command string.`);
+    }
+    return command;
+  }
+  throw createUsageError(`Error: tool "${toolName}" must be a string/function or an object with run.`);
+}
+
+module.exports = {
+  createUsageError,
+  getItemDescription,
+  normalizeRuntimeConfig,
+  resolveStartCommand,
+  resolveToolCommand,
+};

package/src/internal/parse-args.js

@@ -0,0 +1,116 @@
+function fail(message) {
+  const error = new Error(message);
+  error.isUsageError = true;
+  throw error;
+}
+
+function parsePositiveInteger(value, flag) {
+  const parsed = Number.parseInt(value, 10);
+  if (!value || !Number.isInteger(parsed) || parsed <= 0) {
+    fail(`Error: ${flag} requires a positive integer value.`);
+  }
+  return parsed;
+}
+
+function parsePositiveNumber(value, flag) {
+  const parsed = Number(value);
+  if (!value || !Number.isFinite(parsed) || parsed <= 0) {
+    fail(`Error: ${flag} requires a positive number of seconds.`);
+  }
+  return parsed;
+}
+
+function parseArgs(argv) {
+  const positional = [];
+  let linesOverride = null;
+  let untilMarker = null;
+  let untilTimeoutSeconds = null;
+  let attachRequested = false;
+  let help = false;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const command = positional[0] || "";
+
+    if (command === "tool") {
+      positional.push(arg);
+      continue;
+    }
+
+    if (arg === "-h" || arg === "--help") {
+      help = true;
+      continue;
+    }
+    if (arg === "--attach" || arg === "-a") {
+      attachRequested = true;
+      continue;
+    }
+    if (arg === "--lines") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("-")) {
+        fail("Error: --lines requires a positive integer value.");
+      }
+      linesOverride = parsePositiveInteger(value, "--lines");
+      i++;
+      continue;
+    }
+    if (arg.startsWith("--lines=")) {
+      linesOverride = parsePositiveInteger(arg.slice("--lines=".length), "--lines");
+      continue;
+    }
+    if (arg === "--until-marker") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("-")) {
+        fail("Error: --until-marker requires a non-empty value.");
+      }
+      untilMarker = value;
+      i++;
+      continue;
+    }
+    if (arg.startsWith("--until-marker=")) {
+      untilMarker = arg.slice("--until-marker=".length);
+      if (!untilMarker) {
+        fail("Error: --until-marker requires a non-empty value.");
+      }
+      continue;
+    }
+    if (arg === "--until-timeout") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("-")) {
+        fail("Error: --until-timeout requires a positive number of seconds.");
+      }
+      untilTimeoutSeconds = parsePositiveNumber(value, "--until-timeout");
+      i++;
+      continue;
+    }
+    if (arg.startsWith("--until-timeout=")) {
+      untilTimeoutSeconds = parsePositiveNumber(
+        arg.slice("--until-timeout=".length),
+        "--until-timeout"
+      );
+      continue;
+    }
+    if (arg.startsWith("-")) fail(`Error: unknown option "${arg}"`);
+    positional.push(arg);
+  }
+
+  const command = positional[0] || "";
+  if (command !== "tool" && positional.length > 2) {
+    fail(`Error: unexpected argument "${positional[2]}"`);
+  }
+
+  return {
+    help,
+    command,
+    app: positional[1] || "",
+    commandArgs: command === "tool" ? positional.slice(2) : [],
+    linesOverride,
+    untilMarker,
+    untilTimeoutSeconds,
+    attachRequested,
+  };
+}
+
+module.exports = {
+  parseArgs,
+};

package/src/internal/runtime/process.js

@@ -0,0 +1,41 @@
+const { spawnSync } = require("node:child_process");
+
+function die(message, code = 1) {
+  const text = String(message);
+  process.stderr.write(text.endsWith("\n") ? text : `${text}\n`);
+  process.exit(code);
+}
+
+function run(cmd, args = [], options = {}) {
+  const result = spawnSync(cmd, args, {
+    cwd: options.cwd,
+    env: options.env,
+    encoding: "utf8",
+    stdio: options.stdio || "pipe",
+  });
+
+  const status = Number.isInteger(result.status) ? result.status : 1;
+  const stdout = typeof result.stdout === "string" ? result.stdout.trim() : "";
+  const stderr = typeof result.stderr === "string" ? result.stderr.trim() : "";
+
+  if (result.error && !options.allowFailure) {
+    throw result.error;
+  }
+
+  if (status !== 0 && !options.allowFailure) {
+    const detail = stderr || stdout || `exit code ${status}`;
+    throw new Error(`${cmd} ${args.join(" ")} failed: ${detail}`);
+  }
+
+  return {
+    status,
+    stdout,
+    stderr,
+    error: result.error || null,
+  };
+}
+
+module.exports = {
+  die,
+  run,
+};

package/src/internal/runtime/shell.js

@@ -0,0 +1,14 @@
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\"'\"'`)}'`;
+}
+
+function withInheritedPath(command) {
+  const inheritedPath = String(process.env.PATH || "");
+  if (!inheritedPath) return String(command || "");
+  return `export PATH=${shellQuote(inheritedPath)}; ${command}`;
+}
+
+module.exports = {
+  shellQuote,
+  withInheritedPath,
+};

package/src/internal/runtime/tmux.js

@@ -0,0 +1,170 @@
+const path = require("node:path");
+const { run } = require("./process.js");
+const { shellQuote } = require("./shell.js");
+
+function createTmuxController({ cliScriptPath, runCommand = run } = {}) {
+  function buildRemainOnExitArgs(target) {
+    return [";", "set-option", "-pt", target, "remain-on-exit", "failed"];
+  }
+
+  function ensureInstalled() {
+    const probe = runCommand("tmux", ["-V"], { allowFailure: true });
+    if (probe.status !== 0) {
+      const error = new Error("Error: tmux is required but was not found in PATH.");
+      error.isUsageError = true;
+      throw error;
+    }
+  }
+
+  function sessionExists(tmuxSession) {
+    return runCommand("tmux", ["has-session", "-t", tmuxSession], { allowFailure: true }).status === 0;
+  }
+
+  function listWindows(tmuxSession) {
+    const listed = runCommand("tmux", ["list-windows", "-t", tmuxSession, "-F", "#{window_name}"], {
+      allowFailure: true,
+    });
+    if (listed.status !== 0) return [];
+    return listed.stdout
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean);
+  }
+
+  function windowExists(tmuxSession, windowName) {
+    return listWindows(tmuxSession).includes(windowName);
+  }
+
+  function captureWindowLogs(tmuxSession, appName, lines) {
+    const captured = runCommand(
+      "tmux",
+      ["capture-pane", "-p", "-J", "-S", `-${lines}`, "-t", `${tmuxSession}:${appName}`],
+      { allowFailure: true }
+    );
+    if (captured.status !== 0) {
+      const detail = captured.stderr || captured.stdout || `exit code ${captured.status}`;
+      throw new Error(`failed to capture logs for "${appName}" in "${tmuxSession}": ${detail}`);
+    }
+    return captured.stdout;
+  }
+
+  function newWindow(tmuxSession, windowName, command) {
+    runCommand("tmux", [
+      "new-window",
+      "-d",
+      "-t",
+      tmuxSession,
+      "-n",
+      windowName,
+      command,
+      ...buildRemainOnExitArgs(`${tmuxSession}:${windowName}`),
+    ]);
+  }
+
+  function newSession(tmuxSession, windowName, command) {
+    runCommand("tmux", [
+      "new-session",
+      "-d",
+      "-s",
+      tmuxSession,
+      "-n",
+      windowName,
+      command,
+      ...buildRemainOnExitArgs(`${tmuxSession}:${windowName}`),
+    ]);
+  }
+
+  function killWindow(tmuxSession, windowName) {
+    runCommand("tmux", ["kill-window", "-t", `${tmuxSession}:${windowName}`], {
+      allowFailure: true,
+    });
+  }
+
+  function killSession(tmuxSession) {
+    runCommand("tmux", ["kill-session", "-t", tmuxSession]);
+  }
+
+  function selectWindow(tmuxSession, windowName) {
+    runCommand("tmux", ["select-window", "-t", `${tmuxSession}:${windowName}`], {
+      allowFailure: true,
+    });
+  }
+
+  function enableMouse(tmuxSession) {
+    runCommand("tmux", ["set-option", "-t", tmuxSession, "mouse", "on"]);
+  }
+
+  function getAttachEnv() {
+    const term = String(process.env.TERM || "").trim();
+    if (!term || term === "dumb") {
+      return { ...process.env, TERM: "xterm-256color" };
+    }
+    return process.env;
+  }
+
+  function attachSession(tmuxSession) {
+    runCommand("tmux", ["attach-session", "-t", tmuxSession], {
+      stdio: "inherit",
+      env: getAttachEnv(),
+    });
+  }
+
+  function buildTailPaneCommand({ root, appName, lines }) {
+    const scriptPath = cliScriptPath || path.resolve(process.argv[1] || "");
+    return (
+      `cd ${shellQuote(root)} && ` +
+      `node ${shellQuote(scriptPath)} tail ${shellQuote(appName)} --lines ${lines}`
+    );
+  }
+
+  function openSplitAttachWindow({ root, tmuxSession, appNames, lines }) {
+    const splitWindowName = "split-attach";
+    const activeApps = appNames.filter((appName) => windowExists(tmuxSession, appName));
+    if (activeApps.length === 0) {
+      const error = new Error(`Error: no active app windows found in session "${tmuxSession}".`);
+      error.isUsageError = true;
+      throw error;
+    }
+
+    if (windowExists(tmuxSession, splitWindowName)) {
+      killWindow(tmuxSession, splitWindowName);
+    }
+
+    const [firstApp, ...restApps] = activeApps;
+    newWindow(tmuxSession, splitWindowName, buildTailPaneCommand({ root, appName: firstApp, lines }));
+
+    for (const appName of restApps) {
+      runCommand("tmux", [
+        "split-window",
+        "-d",
+        "-t",
+        `${tmuxSession}:${splitWindowName}`,
+        "-v",
+        buildTailPaneCommand({ root, appName, lines }),
+      ]);
+      runCommand("tmux", ["select-layout", "-t", `${tmuxSession}:${splitWindowName}`, "tiled"]);
+    }
+
+    selectWindow(tmuxSession, splitWindowName);
+  }
+
+  return {
+    attachSession,
+    captureWindowLogs,
+    enableMouse,
+    ensureInstalled,
+    killSession,
+    killWindow,
+    listWindows,
+    newSession,
+    newWindow,
+    openSplitAttachWindow,
+    selectWindow,
+    sessionExists,
+    windowExists,
+  };
+}
+
+module.exports = {
+  createTmuxController,
+};

package/src/internal/usage.js

@@ -0,0 +1,44 @@
+function formatAvailableEntries(entries = []) {
+  if (!entries || entries.length === 0) return ["  (none)"];
+  return entries.map((entry) =>
+    entry.description ? `  ${entry.name}: ${entry.description}` : `  ${entry.name}`
+  );
+}
+
+function usage(appEntries = [], toolEntries = []) {
+  const appLines = formatAvailableEntries(appEntries);
+  const toolLines = formatAvailableEntries(toolEntries);
+  return [
+    "Usage:",
+    "  dev start <app|all> [-a|--attach] [--lines <n>]",
+    "  dev restart <app|all> [-a|--attach] [--lines <n>]",
+    "  dev stop <app|all>",
+    "  dev attach [app] [--lines <n>]",
+    "  dev logs <app> [--lines <n>]",
+    "  dev tail <app> [--lines <n>] [--until-marker <text>] [--until-timeout <seconds>]",
+    "  dev tool <tool-name> [tool args...]",
+    "",
+    "Available apps:",
+    ...appLines,
+    "",
+    "Available tools:",
+    ...toolLines,
+    "",
+    "Examples:",
+    "  npx dev start api",
+    "  npx dev start api -a",
+    "  npx dev start all --attach --lines 200",
+    "  npx dev attach",
+    "  npx dev attach web",
+    "  npx dev restart all -a",
+    "  npx dev stop all",
+    "  npx dev logs api --lines 250",
+    "  npx dev tail api --until-marker READY --until-timeout 30",
+    "  npx dev tool axe tap --label \"Continue\"",
+  ].join("\n");
+}
+
+module.exports = {
+  usage,
+  formatAvailableEntries,
+};