@effectstream/orchestrator 0.100.9

package/src/commands/silence.ts

@@ -0,0 +1,49 @@
+import type { ParsedArgs } from "../cli.ts";
+import { OrchestratorClient } from "../api-client.ts";
+import { logInfo, logError } from "../display.ts";
+
+type SilenceOptions = Pick<ParsedArgs, "positionals" | "flags"> & {
+  port?: number;
+};
+
+export async function runSilenceCommand(opts: SilenceOptions): Promise<void> {
+  const names = opts.positionals;
+  const unsilence = opts.flags["unsilence"] === true;
+
+  const client = new OrchestratorClient(opts.port);
+
+  if (!(await client.isRunning())) {
+    logError(
+      "Orchestrator daemon is not running. Start it with: orchestrator start",
+    );
+    process.exit(1);
+  }
+
+  if (names.length === 0) {
+    // Show currently silenced processes
+    const silenced = await client.getSilenced();
+    if (silenced.length === 0) {
+      logInfo("No processes are silenced.");
+    } else {
+      logInfo(`Silenced processes: ${silenced.join(", ")}`);
+    }
+    return;
+  }
+
+  const result = await client.silence(names, unsilence);
+
+  if (result.error) {
+    logError(result.error);
+    process.exit(1);
+  }
+
+  if (unsilence) {
+    logInfo(`Unsilenced: ${names.join(", ")}`);
+  } else {
+    logInfo(`Silenced: ${names.join(", ")}`);
+  }
+
+  if (result.silenced && result.silenced.length > 0) {
+    logInfo(`Currently silenced: ${result.silenced.join(", ")}`);
+  }
+}

package/src/commands/start.ts

@@ -0,0 +1,304 @@
+import * as fs from "fs";
+import * as path from "path";
+import type { ParsedArgs } from "../cli.ts";
+import { OrchestratorClient } from "../api-client.ts";
+import { ProcessManager } from "../process-manager.ts";
+import { runProcesses } from "../task-runner.ts";
+import { startApiServer } from "../api-server.ts";
+import {
+  writeState,
+  readStateConfigPath,
+  clearStatePort,
+  freePort,
+  DEFAULT_API_PORT,
+} from "../port-check.ts";
+import {
+  logTaskStart,
+  logTaskRunning,
+  logTaskDone,
+  logTaskFailed,
+  logInfo,
+  logWarn,
+  logError,
+} from "../display.ts";
+import { loadConfig, findDefaultConfig, findPackageJsonConfig } from "../load-config.ts";
+
+type StartOptions = Pick<ParsedArgs, "positionals" | "flags"> & {
+  port?: number;
+};
+
+/** Resolve and load the orchestrator config file. */
+async function resolveConfig(opts: StartOptions) {
+  // Only use positional[0] as config path if it looks like a file path
+  const positionalConfig = opts.positionals[0]?.includes(".") || opts.positionals[0]?.includes("/")
+    ? opts.positionals[0]
+    : undefined;
+
+  const configPath =
+    (opts.flags["config"] as string | undefined) ??
+    positionalConfig ??
+    readStateConfigPath() ??
+    (await findPackageJsonConfig()) ??
+    (await findDefaultConfig()) ??
+    (() => {
+      throw new Error(
+        "(1) No config file found. Pass one as an argument or create orchestrator.config.ts.",
+      );
+    })();
+
+  logInfo(`Loading config: ${configPath}`);
+  return { configPath, config: await loadConfig(configPath) };
+}
+
+/** Parse --only and --except flags into arrays. */
+function parseFilters(flags: Record<string, string | boolean>) {
+  const only =
+    typeof flags["only"] === "string"
+      ? flags["only"].split(",").map((s) => s.trim()).filter(Boolean)
+      : undefined;
+
+  const except =
+    typeof flags["except"] === "string"
+      ? flags["except"].split(",").map((s) => s.trim()).filter(Boolean)
+      : undefined;
+
+  return { only, except };
+}
+
+export async function runStartCommand(opts: StartOptions): Promise<void> {
+  // ── Background mode ────────────────────────────────────────────────────────
+  if (opts.flags["background"] === true) {
+    await spawnBackground(opts);
+    return;
+  }
+
+  // ── Resolve config ─────────────────────────────────────────────────────────
+  const { configPath, config } = await resolveConfig(opts);
+  let { only, except } = parseFilters(opts.flags);
+
+  // Treat positional args as process names (shorthand for --only)
+  // e.g. `start hardhat` is the same as `start --only=hardhat`
+  if (!only && opts.positionals.length > 0) {
+    const processNames = new Set(config.processes.map((p) => p.name));
+    const names = opts.positionals.filter((p) => processNames.has(p));
+    if (names.length > 0) {
+      only = names;
+    }
+  }
+
+  // ── API port ───────────────────────────────────────────────────────────────
+  const apiPort =
+    opts.port ??
+    (typeof opts.flags["port"] === "string" ? Number(opts.flags["port"]) : undefined) ??
+    config.apiPort ??
+    DEFAULT_API_PORT;
+
+  const noApi = opts.flags["no-api"] === true;
+  const serial = opts.flags["serial"] === true;
+  const noDeps = opts.flags["no-deps"] === true;
+  const silenceFlag =
+    typeof opts.flags["silence"] === "string"
+      ? opts.flags["silence"].split(",").map((s) => s.trim()).filter(Boolean)
+      : undefined;
+
+  // ── Check for existing daemon ──────────────────────────────────────────────
+  // If an orchestrator daemon is already running, delegate to it via API.
+  if (!noApi) {
+    const client = new OrchestratorClient(apiPort);
+    if (await client.isRunning()) {
+      logInfo(`Orchestrator daemon already running on port ${apiPort} — delegating via API`);
+
+      if (only)   logInfo(`Running only: ${only.join(", ")}`);
+      if (except)  logInfo(`Skipping: ${except.join(", ")}`);
+
+      const result = await client.start(config.processes, { only, except, serial, noDeps });
+      if (result.success) {
+        logInfo(`Queued processes: ${result.queued?.join(", ") ?? "none"}`);
+      } else {
+        logError(`Failed to start via API: ${result.error}`);
+      }
+      return;
+    }
+  }
+
+  // ── Foreground mode hint ───────────────────────────────────────────────────
+  // Skip when this is a re-spawned child from --background (has --log-dir)
+  if (!opts.flags["log-dir"]) {
+    const col = { reset: "\x1b[0m", dim: "\x1b[2m", cyan: "\x1b[36m" };
+    console.log(
+      `\n${col.dim}Tip: Run with ${col.cyan}--background${col.dim} to daemonize and view status/logs separately.${col.reset}\n`
+    );
+    await Bun.sleep(250);
+  }
+
+  // ── Per-process log directory (set by --background re-spawn) ──────────────
+  const logDirFlag = opts.flags["log-dir"] as string | undefined;
+  if (logDirFlag) fs.mkdirSync(logDirFlag, { recursive: true });
+
+  // ── Process manager ────────────────────────────────────────────────────────
+  const manager = new ProcessManager();
+  if (logDirFlag) manager.logDir = logDirFlag;
+  if (silenceFlag) {
+    for (const name of silenceFlag) manager.silence(name);
+  }
+
+  // ── Task event callbacks (shared between local runs and API-triggered runs)
+  const runCallbacks = {
+    onTaskStart: (name: string, logFile: string | null) => logTaskStart(name, logFile ?? undefined),
+    onTaskRunning: logTaskRunning,
+    onTaskDone: logTaskDone,
+    onTaskFailed: logTaskFailed,
+    onShutdown: undefined as ((reason: string) => void) | undefined,
+  };
+
+  // ── Graceful shutdown ──────────────────────────────────────────────────────
+  let shuttingDown = false;
+  let apiServer: ReturnType<typeof startApiServer> | undefined;
+
+  const shutdown = async (reason?: string) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    if (reason) logWarn(`Shutting down: ${reason}`);
+    else logInfo("Shutting down…");
+    apiServer?.stop(true);
+    await manager.stopAll();
+
+    // Kill any orphan processes still occupying configured ports
+    for (const proc of config.processes) {
+      for (const port of proc.stopProcessAtPort ?? []) {
+        await freePort(port);
+      }
+    }
+
+    clearStatePort();
+    process.exit(reason ? 1 : 0);
+  };
+
+  runCallbacks.onShutdown = shutdown;
+
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+
+  // ── API server ─────────────────────────────────────────────────────────────
+  if (!noApi) {
+    try {
+      apiServer = startApiServer({
+        port: apiPort,
+        manager,
+        onShutdown: () => shutdown("shutdown API request"),
+        runCallbacks,
+      });
+      writeState(apiPort, path.resolve(configPath));
+      logInfo(`API server listening on http://localhost:${apiPort}`);
+    } catch (err: any) {
+      logWarn(`Could not start API server on port ${apiPort}: ${err.message}`);
+    }
+  }
+
+  // ── Launch ─────────────────────────────────────────────────────────────────
+  if (only)   logInfo(`Running only: ${only.join(", ")}`);
+  if (except) logInfo(`Skipping: ${except.join(", ")}`);
+  if (serial) logInfo("Serial mode: launching processes one at a time");
+  if (noDeps) logInfo("No-deps mode: skipping dependency resolution");
+
+  try {
+    await runProcesses(config.processes, manager, {
+      only,
+      except,
+      serial,
+      noDeps,
+      ...runCallbacks,
+    });
+  } catch (err: any) {
+    logError(err.message);
+    await shutdown(err.message);
+    return;
+  }
+
+  // If no background processes remain (all were waitToExit) and no API server,
+  // exit cleanly instead of hanging forever.
+  const hasBackground = manager.getAll().some(p => p.status === "running");
+  if (!hasBackground && noApi) {
+    logInfo("All processes completed. Exiting.");
+    process.exit(0);
+  }
+
+  logInfo("All processes launched. Orchestrator is running. Press Ctrl+C to stop.");
+}
+
+// ── Background helper ─────────────────────────────────────────────────────────
+
+async function spawnBackground(opts: StartOptions): Promise<void> {
+  const apiPort =
+    opts.port ??
+    (typeof opts.flags["port"] === "string" ? Number(opts.flags["port"]) : undefined) ??
+    DEFAULT_API_PORT;
+
+  const client = new OrchestratorClient(apiPort);
+  if (await client.isRunning()) {
+    const col = { reset: "\x1b[0m", bold: "\x1b[1m", red: "\x1b[31m", dim: "\x1b[2m", cyan: "\x1b[36m" };
+    const relCliPath = path.relative(process.cwd(), path.resolve(import.meta.dir, "../cli.ts")) || ".";
+    console.error(`\n${col.red}${col.bold}An orchestrator daemon is already running on port ${apiPort}.${col.reset}\n`);
+    console.error(`${col.dim}Check status:${col.reset}    bun ${relCliPath} status`);
+    console.error(`${col.dim}View logs:${col.reset}       bun ${relCliPath} logs`);
+    console.error(`${col.dim}Stop it:${col.reset}         bun ${relCliPath} stop`);
+    console.error();
+    process.exit(1);
+  }
+
+  const configPath =
+    (opts.flags["config"] as string | undefined) ??
+    opts.positionals[0] ??
+    readStateConfigPath() ??
+    (await findPackageJsonConfig()) ??
+    (await findDefaultConfig()) ??
+    (() => {
+      throw new Error(
+        "(2) No config file found. Pass one as an argument or create orchestrator.config.ts.",
+      );
+    })();
+
+  // Default log dir: <cwd>/.orchestrator-logs
+  const logDir = path.resolve(
+    (opts.flags["log-dir"] as string | undefined) ??
+      path.join(process.cwd(), ".orchestrator-logs"),
+  );
+  fs.mkdirSync(logDir, { recursive: true });
+
+  const orchLogPath = path.join(logDir, "orchestrator.log");
+
+  // Build daemon args: same start command without --background, plus --log-dir
+  const daemonArgs: string[] = ["start", configPath, `--log-dir=${logDir}`];
+  if (opts.flags["only"])   daemonArgs.push(`--only=${opts.flags["only"]}`);
+  if (opts.flags["except"]) daemonArgs.push(`--except=${opts.flags["except"]}`);
+  if (opts.flags["port"])   daemonArgs.push(`--port=${opts.flags["port"]}`);
+  if (opts.flags["no-api"]) daemonArgs.push("--no-api");
+  if (opts.flags["serial"]) daemonArgs.push("--serial");
+  if (opts.flags["no-deps"]) daemonArgs.push("--no-deps");
+
+  // Open orchestrator log in write mode (fresh on each background start)
+  const orchFd = fs.openSync(orchLogPath, "w");
+
+  const cliPath = path.resolve(import.meta.dir, "../cli.ts");
+  const daemon = Bun.spawn(["bun", cliPath, ...daemonArgs], {
+    stdout: orchFd,
+    stderr: orchFd,
+    stdin: "ignore",
+    detached: true,
+  });
+  fs.closeSync(orchFd);
+  daemon.unref();
+
+  // Print summary with relative paths for easy copy-paste
+  const col = { reset: "\x1b[0m", bold: "\x1b[1m", cyan: "\x1b[36m", green: "\x1b[32m", dim: "\x1b[2m" };
+  const relLogDir = path.relative(process.cwd(), logDir) || ".";
+  const relOrchLog = path.relative(process.cwd(), orchLogPath) || ".";
+  const relCliPath = path.relative(process.cwd(), cliPath) || ".";
+  console.log(`\n${col.bold}Orchestrator started in background${col.reset}  (PID ${daemon.pid})\n`);
+  console.log(`${col.bold}Log directory:${col.reset}  ${col.cyan}${relLogDir}${col.reset}`);
+  console.log(`  ${col.dim}orchestrator:${col.reset}  ${relOrchLog}`);
+  console.log(`  ${col.dim}processes:${col.reset}     ${relLogDir}/<process-name>.log\n`);
+  console.log(`${col.dim}Tail all logs:${col.reset}   tail -f ${relLogDir}/*.log`);
+  console.log(`${col.dim}Check status:${col.reset}    bun ${relCliPath} status`);
+  console.log(`${col.dim}Stop all:${col.reset}        bun ${relCliPath} stop\n`);
+}

package/src/commands/status.ts

@@ -0,0 +1,111 @@
+import type { ParsedArgs } from "../cli.ts";
+import { OrchestratorClient, type RemoteProcess } from "../api-client.ts";
+import { printStatusTable, type StatusRow, logError, logWarn } from "../display.ts";
+import { findDefaultConfig, findPackageJsonConfig, loadConfig } from "../load-config.ts";
+import { isPortInUse, pidsByPort, readStateConfigPath } from "../port-check.ts";
+import type { ProcessConfig } from "../config.ts";
+
+type StatusOptions = Pick<ParsedArgs, "positionals" | "flags"> & {
+  port?: number;
+};
+
+async function fetchStatus(
+  opts: StatusOptions,
+  configs: ProcessConfig[],
+): Promise<{ rows: StatusRow[]; daemonRunning: boolean }> {
+  const client = new OrchestratorClient(opts.port);
+  const daemonRunning = await client.isRunning();
+  const daemonProcesses = daemonRunning ? await client.getProcesses() : [];
+  const daemonMap = new Map(daemonProcesses.map((p) => [p.name, p]));
+
+  const untracked = configs.filter((c) => !daemonMap.has(c.name));
+  const portResults = await Promise.all(
+    untracked.map(async (c) => {
+      const ports = c.stopProcessAtPort ?? [];
+      if (ports.length === 0) return { name: c.name, portStatus: "no-ports" as const, pid: undefined };
+      const results = await Promise.all(ports.map((p) => isPortInUse(p)));
+      const allUp = results.every(Boolean);
+      const someUp = results.some(Boolean);
+      const portStatus = allUp ? "up" : someUp ? "partial" : ("down" as const);
+      const firstUpIdx = results.findIndex(Boolean);
+      const pid = firstUpIdx >= 0 ? (pidsByPort(ports[firstUpIdx])[0] ?? undefined) : undefined;
+      return { name: c.name, portStatus, pid };
+    }),
+  );
+  const portMap = new Map(portResults.map((r) => [r.name, r]));
+
+  const daemonPidMap = new Map<string, number | undefined>();
+  await Promise.all(
+    daemonProcesses.map(async (p) => {
+      const cfg = configs.find((c) => c.name === p.name);
+      const ports = cfg?.stopProcessAtPort ?? [];
+      if (ports.length === 0) { daemonPidMap.set(p.name, undefined); return; }
+      const up = await Promise.all(ports.map((port) => isPortInUse(port)));
+      const firstUpIdx = up.findIndex(Boolean);
+      const actualPid = firstUpIdx >= 0 ? (pidsByPort(ports[firstUpIdx])[0] ?? undefined) : undefined;
+      daemonPidMap.set(p.name, actualPid);
+    }),
+  );
+
+  const rows: StatusRow[] = configs.map((c) => {
+    const daemon = daemonMap.get(c.name);
+    if (daemon) return { source: "daemon" as const, config: c, daemon, actualPid: daemonPidMap.get(c.name) };
+    const { portStatus, pid } = portMap.get(c.name)!;
+    return { source: "port" as const, config: c, portStatus, pid };
+  });
+
+  return { rows, daemonRunning };
+}
+
+export async function runStatusCommand(opts: StatusOptions): Promise<void> {
+  const configPath =
+    (opts.flags["config"] as string | undefined) ??
+    opts.positionals[0] ??
+    readStateConfigPath() ??
+    (await findPackageJsonConfig()) ??
+    (await findDefaultConfig());
+
+  if (!configPath) {
+    logError(
+      "No config file found. Pass one with --config or create orchestrator.config.ts",
+    );
+    process.exit(1);
+  }
+
+  let configs: ProcessConfig[];
+  try {
+    const config = await loadConfig(configPath);
+    configs = config.processes;
+  } catch (err: any) {
+    logError(err.message);
+    process.exit(1);
+  }
+
+  const follow = opts.flags["follow"] === true;
+
+  if (!follow) {
+    const { rows, daemonRunning } = await fetchStatus(opts, configs);
+    if (!daemonRunning) {
+      logWarn("No orchestrator daemon detected — showing port-based status.");
+    }
+    printStatusTable(rows, daemonRunning);
+    return;
+  }
+
+  // Follow mode: refresh every second
+  process.on("SIGINT", () => process.exit(0));
+  process.on("SIGTERM", () => process.exit(0));
+
+  let firstRender = true;
+  while (true) {
+    process.stdout.write("\x1b[H");
+    const { rows, daemonRunning } = await fetchStatus(opts, configs);
+    if (!daemonRunning && firstRender) {
+      logWarn("No orchestrator daemon detected — showing port-based status.");
+    }
+    printStatusTable(rows, daemonRunning);
+    process.stdout.write("\x1b[J");
+    firstRender = false;
+    await Bun.sleep(1000);
+  }
+}

package/src/commands/stop.ts

@@ -0,0 +1,100 @@
+import type { ParsedArgs } from "../cli.ts";
+import type { ProcessConfig } from "../config.ts";
+import { OrchestratorClient } from "../api-client.ts";
+import { loadConfig, findDefaultConfig, findPackageJsonConfig } from "../load-config.ts";
+import { pidsByPort, freePort, readStateConfigPath } from "../port-check.ts";
+import { logInfo, logError, logWarn } from "../display.ts";
+
+type StopOptions = Pick<ParsedArgs, "positionals" | "flags"> & {
+  port?: number;
+};
+
+export async function runStopCommand(opts: StopOptions): Promise<void> {
+  const name = opts.positionals[0]; // optional
+
+  const client = new OrchestratorClient(opts.port);
+
+  // If the daemon is running, delegate to it
+  if (await client.isRunning()) {
+    if (name) {
+      logInfo(`Stopping "${name}"…`);
+      const result = await client.stop(name);
+      if (result.error) {
+        logError(result.error);
+        process.exit(1);
+      }
+      logInfo(`"${name}" stopped.`);
+    } else {
+      logWarn("Stopping all processes and shutting down the orchestrator…");
+      await client.shutdown();
+      logInfo("Shutdown signal sent.");
+    }
+    return;
+  }
+
+  // No daemon — fall back to port-based kill
+  logWarn("No orchestrator daemon detected — killing processes by port.");
+
+  const configPath =
+    (opts.flags["config"] as string | undefined) ??
+    opts.positionals[1] ??
+    readStateConfigPath() ??
+    (await findPackageJsonConfig()) ??
+    (await findDefaultConfig());
+
+  if (!configPath) {
+    logError("No config file found. Cannot determine which ports to free.");
+    process.exit(1);
+  }
+
+  let configs: ProcessConfig[];
+  try {
+    const config = await loadConfig(configPath);
+    configs = config.processes;
+  } catch (err: any) {
+    logError(err.message);
+    process.exit(1);
+  }
+
+  // If a name is given, only kill that process's ports
+  if (name) {
+    const proc = configs.find((c) => c.name === name);
+    if (!proc) {
+      logError(`Process "${name}" not found in config.`);
+      process.exit(1);
+    }
+    const ports = proc.stopProcessAtPort ?? [];
+    if (ports.length === 0) {
+      logWarn(`Process "${name}" has no ports defined — nothing to kill.`);
+      return;
+    }
+    for (const port of ports) {
+      const pids = pidsByPort(port);
+      if (pids.length > 0) {
+        logInfo(`Killing PID ${pids.join(", ")} on port ${port} (${name})`);
+        await freePort(port);
+      }
+    }
+    logInfo(`"${name}" stopped.`);
+    return;
+  }
+
+  // Kill all processes that have ports defined
+  let killed = 0;
+  for (const proc of configs) {
+    for (const port of proc.stopProcessAtPort ?? []) {
+      const pids = pidsByPort(port);
+      if (pids.length > 0) {
+        logInfo(`Killing PID ${pids.join(", ")} on port ${port} (${proc.name})`);
+        await freePort(port);
+        killed++;
+      }
+    }
+  }
+
+  if (killed === 0) {
+    logInfo("No processes found on any configured ports.");
+  } else {
+    logInfo(`Stopped ${killed} process(es).`);
+  }
+}

package/src/config.ts

@@ -0,0 +1,65 @@
+/**
+ * Configuration types for orchestrator.
+ *
+ * ProcessConfig is intentionally compatible with the v1 ProcessLaunch schema
+ * so existing launch-*.ts scripts can be reused with minor changes.
+ */
+export type ProcessConfig = {
+  /** Unique name for this process. */
+  name: string;
+  /** Human-readable description (shown in status output). */
+  description?: string;
+  /**
+   * Executable to run. Defaults to "bun".
+   * Use "deno" for legacy deno-task-based processes.
+   */
+  command?: string;
+  /** Arguments passed to the command. */
+  args: string[];
+  /** Names of processes that must complete/start before this one. */
+  dependsOn?: string[];
+  /**
+   * If set, these ports are freed (kill any occupying process) before launch.
+   * Also used by the `status` command for port-based liveness detection.
+   */
+  stopProcessAtPort?: number[];
+  /**
+   * If true, dependents wait for this process to EXIT before starting.
+   * If false (default), dependents start as soon as this process is launched.
+   */
+  waitToExit?: boolean;
+  /**
+   * system-dependency: a core service (e.g. a chain node); failure triggers shutdown.
+   * secondary: optional service; failure is logged but orchestrator keeps running.
+   * Defaults to "system-dependency".
+   */
+  type?: "system-dependency" | "secondary";
+  /** Extra environment variables for the process. */
+  env?: Record<string, string>;
+  /** Working directory for the process. Defaults to process.cwd(). */
+  cwd?: string;
+  /**
+   * If true (default), a non-zero exit code triggers a full shutdown.
+   * If false, the failure is reported but the orchestrator keeps running.
+   */
+  critical?: boolean;
+  /** Optional URL shown in status output (e.g. a UI endpoint). */
+  link?: string;
+  /**
+   * If false, this process is skipped during a normal `start` and only runs
+   * when explicitly requested via `--only`. Useful for one-off tasks like
+   * contract compilation that aren't part of the default startup flow.
+   * Defaults to true.
+   */
+  autoStart?: boolean;
+};
+
+export type OrchestratorConfig = {
+  /** Ordered list of processes to manage. */
+  processes: ProcessConfig[];
+  /**
+   * Port for the orchestrator HTTP API used by status/restart/stop commands.
+   * Defaults to 4747. Overrideable with --port CLI flag.
+   */
+  apiPort?: number;
+};