@effectstream/orchestrator 0.100.9

package/src/display.ts

@@ -0,0 +1,190 @@
+import * as path from "path";
+import type { RemoteProcess } from "./api-client.ts";
+import type { ProcessConfig } from "./config.ts";
+
+// ANSI colour helpers
+const c = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  blue: "\x1b[34m",
+  cyan: "\x1b[36m",
+  gray: "\x1b[90m",
+};
+
+function pad(s: string, width: number, align: "left" | "right" = "left"): string {
+  const len = stripAnsi(s).length;
+  const pad = Math.max(0, width - len);
+  return align === "left" ? s + " ".repeat(pad) : " ".repeat(pad) + s;
+}
+
+function stripAnsi(s: string): string {
+  // eslint-disable-next-line no-control-regex
+  return s.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+function colorStatus(status: string, waitToExit?: boolean): string {
+  switch (status) {
+    case "running":
+      // Distinguish background services from tasks that will exit
+      if (waitToExit) return `${c.yellow}running…${c.reset}`;
+      return `${c.green}${status}${c.reset}`;
+    case "done":
+      return `${c.blue}${status}${c.reset}`;
+    case "failed":
+      return `${c.red}${status}${c.reset}`;
+    case "stopped":
+      return `${c.yellow}${status}${c.reset}`;
+    case "pending":
+      return `${c.gray}${status}${c.reset}`;
+    default:
+      return status;
+  }
+}
+
+function relativeTime(iso: string | null): string {
+  if (!iso) return c.gray + "—" + c.reset;
+  const ms = Date.now() - new Date(iso).getTime();
+  if (ms < 60_000) return `${Math.floor(ms / 1000)}s ago`;
+  if (ms < 3_600_000) return `${Math.floor(ms / 60_000)}m ago`;
+  return `${Math.floor(ms / 3_600_000)}h ago`;
+}
+
+export type StatusRow =
+  | { source: "daemon"; config: ProcessConfig; daemon: RemoteProcess; actualPid?: number }
+  | { source: "port"; config: ProcessConfig; portStatus: "up" | "partial" | "down" | "no-ports"; pid?: number };
+
+/**
+ * Unified status table. Shows every process from the config in order.
+ * Processes tracked by the daemon show live data; others show port-based status.
+ */
+export function printStatusTable(rows: StatusRow[], daemonRunning: boolean): void {
+  const hasLogFiles = rows.some(
+    (r) => r.source === "daemon" && r.daemon.logFile,
+  );
+
+  const cols = { name: 28, status: 10, pid: 8, ports: 18, started: 12 };
+  const tailLabel = hasLogFiles ? "LOG" : "LINK";
+
+  const header =
+    c.bold +
+    pad("NAME", cols.name) +
+    "  " +
+    pad("STATUS", cols.status) +
+    "  " +
+    pad("PID", cols.pid, "right") +
+    "  " +
+    pad("PORTS", cols.ports) +
+    "  " +
+    pad("STARTED", cols.started) +
+    "  " +
+    tailLabel +
+    c.reset;
+
+  const sep = c.dim + "─".repeat(110) + c.reset;
+
+  console.log(header);
+  console.log(sep);
+
+  for (const row of rows) {
+    const portList = (row.config.stopProcessAtPort ?? []).join(", ");
+    const ports = portList || c.gray + "—" + c.reset;
+    const nameLabel = row.config.name + (row.config.autoStart === false ? ` ${c.dim}*${c.reset}` : "");
+
+    if (row.source === "daemon") {
+      const { daemon: d } = row;
+      const pidVal = row.actualPid ?? d.pid;
+      const pid = pidVal != null ? String(pidVal) : c.gray + "—" + c.reset;
+      const relLog = d.logFile ? path.relative(process.cwd(), d.logFile) || "." : null;
+      const tail = hasLogFiles
+        ? relLog ? `${c.dim}${relLog}${c.reset}` : ""
+        : d.link ? `${c.cyan}${d.link}${c.reset}` : "";
+
+      console.log(
+        pad(nameLabel, cols.name) +
+          "  " +
+          pad(colorStatus(d.status, row.config.waitToExit), cols.status) +
+          "  " +
+          pad(pid, cols.pid, "right") +
+          "  " +
+          pad(ports, cols.ports) +
+          "  " +
+          pad(relativeTime(d.startedAt), cols.started) +
+          "  " +
+          tail,
+      );
+    } else {
+      const dash = c.gray + "—" + c.reset;
+      const status = colorPortStatus(row.portStatus);
+      const pid = row.pid != null ? String(row.pid) : dash;
+      console.log(
+        pad(nameLabel, cols.name) +
+          "  " +
+          pad(status, cols.status) +
+          "  " +
+          pad(pid, cols.pid, "right") +
+          "  " +
+          pad(ports, cols.ports) +
+          "  " +
+          pad(dash, cols.started) +
+          "  " +
+          (row.config.link ? `${c.cyan}${row.config.link}${c.reset}` : ""),
+      );
+    }
+  }
+
+  const hasManual = rows.some((r) => r.config.autoStart === false);
+  if (hasManual) {
+    console.log(`\n${c.dim}* manual — only runs via --only, not during default start${c.reset}`);
+  }
+
+  if (!daemonRunning) {
+    console.log(
+      `\n${c.dim}(no daemon — port-based status only; start with: orchestrator start)${c.reset}`,
+    );
+  }
+}
+
+function colorPortStatus(s: "up" | "partial" | "down" | "no-ports"): string {
+  switch (s) {
+    case "up":      return `${c.green}up${c.reset}`;
+    case "partial": return `${c.yellow}partial${c.reset}`;
+    case "down":    return `${c.red}down${c.reset}`;
+    case "no-ports": return `${c.gray}—${c.reset}`;
+  }
+}
+
+/**
+ * Prints a start event line to the terminal.
+ */
+export function logTaskStart(name: string, logFile?: string): void {
+  const suffix = logFile ? `  ${c.dim}→ ${logFile}${c.reset}` : "";
+  console.log(`${c.green}▶${c.reset} ${c.bold}${name}${c.reset}${suffix}`);
+}
+
+export function logTaskRunning(name: string): void {
+  console.log(`${c.blue}●${c.reset} ${c.bold}${name}${c.reset} ${c.dim}running in background${c.reset}`);
+}
+
+export function logTaskDone(name: string): void {
+  console.log(`${c.blue}✓${c.reset} ${c.bold}${name}${c.reset} ${c.dim}exited successfully${c.reset}`);
+}
+
+export function logTaskFailed(name: string, code: number): void {
+  console.error(`${c.red}✗${c.reset} ${c.bold}${name}${c.reset} ${c.red}exited with code ${code}${c.reset}`);
+}
+
+export function logInfo(msg: string): void {
+  console.log(`${c.cyan}ℹ${c.reset} ${msg}`);
+}
+
+export function logError(msg: string): void {
+  console.error(`${c.red}✗${c.reset} ${msg}`);
+}
+
+export function logWarn(msg: string): void {
+  console.warn(`${c.yellow}⚠${c.reset} ${msg}`);
+}

package/src/load-config.ts

@@ -0,0 +1,64 @@
+import * as path from "path";
+import type { OrchestratorConfig } from "./config.ts";
+import { logWarn } from "./display.ts";
+
+/**
+ * Loads an OrchestratorConfig from a TypeScript or JSON file.
+ * Handles both absolute paths and paths relative to process.cwd().
+ */
+export async function loadConfig(filePath: string): Promise<OrchestratorConfig> {
+  // Ensure the path is absolute so `import()` works reliably
+  const abs = path.isAbsolute(filePath)
+    ? filePath
+    : path.resolve(process.cwd(), filePath);
+
+  const mod = await import(abs);
+  const cfg: OrchestratorConfig = mod.default ?? mod;
+
+  if (!Array.isArray(cfg.processes)) {
+    throw new Error(
+      `Config file "${filePath}" must export an OrchestratorConfig with a "processes" array.`,
+    );
+  }
+
+  // The "sync" process is the main Effectstream sync engine. Warn if missing.
+  const hasSync = cfg.processes.some((p) => p.name === "sync");
+  if (!hasSync) {
+    logWarn(
+      `No "sync" process defined in config. ` +
+      `Add a process named "sync" (e.g. args: ["run", "node:start"]) to start the Effectstream sync engine.`,
+    );
+  }
+
+  return cfg;
+}
+
+/** Returns the path to the first default config file found, or null. */
+export async function findDefaultConfig(): Promise<string | null> {
+  const candidates = [
+    "orchestrator.config.ts",
+    "orchestrator.config.js",
+    "orchestrator.config.json",
+  ];
+  for (const name of candidates) {
+    const abs = path.resolve(process.cwd(), name);
+    if (await Bun.file(abs).exists()) return abs;
+  }
+  return null;
+}
+
+/** Checks package.json in cwd for an `effectstream.default` config path. */
+export async function findPackageJsonConfig(): Promise<string | null> {
+  try {
+    const pkgPath = path.join(process.cwd(), "package.json");
+    const content = await Bun.file(pkgPath).text();
+    const pkg = JSON.parse(content);
+    const configRel = pkg?.effectstream?.default;
+    if (typeof configRel === "string") {
+      return path.resolve(process.cwd(), configRel);
+    }
+  } catch {
+    // no package.json or invalid JSON
+  }
+  return null;
+}

package/src/port-check.ts

@@ -0,0 +1,126 @@
+import * as net from "net";
+import * as os from "os";
+import * as path from "path";
+import * as fs from "fs";
+
+/** Returns true if something is accepting connections on `port`. */
+export function isPortInUse(port: number, host = "127.0.0.1"): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = net.createConnection({ port, host });
+    socket.setTimeout(500);
+    socket.once("connect", () => { socket.destroy(); resolve(true); });
+    socket.once("timeout", () => { socket.destroy(); resolve(false); });
+    socket.once("error", () => resolve(false));
+  });
+}
+
+/** Polls until the port is in use or the timeout elapses. Returns true if port came up. */
+export async function waitForPort(port: number, timeoutMs = 60_000): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await isPortInUse(port)) return true;
+    await Bun.sleep(500);
+  }
+  return false;
+}
+
+/**
+ * Returns the PID(s) of processes listening on `port`, or an empty array if none.
+ * Uses `lsof -ti tcp:<port>` (macOS / Linux).
+ */
+export function pidsByPort(port: number): number[] {
+  const result = Bun.spawnSync(["lsof", "-ti", `tcp:${port}`], {
+    stderr: "pipe",
+  });
+  if (result.exitCode !== 0) return [];
+  return result.stdout
+    .toString()
+    .trim()
+    .split("\n")
+    .map((s) => parseInt(s.trim(), 10))
+    .filter((n) => !isNaN(n));
+}
+
+/**
+ * Kills any process occupying `port` via SIGTERM, then waits for the port to free.
+ * Uses `lsof` (macOS / Linux).
+ */
+export async function freePort(port: number): Promise<void> {
+  if (!(await isPortInUse(port))) return;
+
+  const result = Bun.spawnSync(["lsof", "-ti", `tcp:${port}`], {
+    stderr: "pipe",
+  });
+
+  if (result.exitCode === 0) {
+    const pids = result.stdout
+      .toString()
+      .trim()
+      .split("\n")
+      .filter(Boolean);
+
+    for (const pid of pids) {
+      Bun.spawnSync(["kill", "-TERM", pid.trim()]);
+    }
+
+    // Wait up to 5 seconds for the port to free
+    let tries = 20;
+    while (tries-- > 0) {
+      if (!(await isPortInUse(port))) return;
+      await Bun.sleep(250);
+    }
+
+    // Fall back to SIGKILL
+    for (const pid of pids) {
+      Bun.spawnSync(["kill", "-KILL", pid.trim()]);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// State file: records the API port of the running daemon so CLI commands can
+// discover it without requiring the user to pass --port every time.
+// ---------------------------------------------------------------------------
+
+const STATE_FILE = path.join(os.tmpdir(), ".orchestrator.port");
+
+export const DEFAULT_API_PORT = 4747;
+
+export function writeState(port: number, configPath: string): void {
+  fs.writeFileSync(STATE_FILE, JSON.stringify({ port, configPath }), "utf8");
+}
+
+export function readStatePort(): number | null {
+  try {
+    const text = fs.readFileSync(STATE_FILE, "utf8").trim();
+    if (text.startsWith("{")) {
+      const data = JSON.parse(text);
+      return typeof data.port === "number" ? data.port : null;
+    }
+    const n = parseInt(text, 10);
+    return isNaN(n) ? null : n;
+  } catch {
+    return null;
+  }
+}
+
+export function readStateConfigPath(): string | null {
+  try {
+    const text = fs.readFileSync(STATE_FILE, "utf8").trim();
+    if (text.startsWith("{")) {
+      const data = JSON.parse(text);
+      return typeof data.configPath === "string" ? data.configPath : null;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export function clearStatePort(): void {
+  try {
+    fs.unlinkSync(STATE_FILE);
+  } catch {
+    // ignore
+  }
+}

package/src/process-manager.ts

@@ -0,0 +1,266 @@
+import * as fs from "fs";
+import * as path from "path";
+import type { ProcessConfig } from "./config.ts";
+import { freePort } from "./port-check.ts";
+
+export type ProcessStatus = "pending" | "running" | "done" | "failed" | "stopped";
+
+export type ManagedProcess = {
+  name: string;
+  pid: number | null;
+  /** Ports this process is expected to occupy (from config.stopProcessAtPort). */
+  ports: number[];
+  status: ProcessStatus;
+  config: ProcessConfig;
+  startedAt: Date | null;
+  endedAt: Date | null;
+  exitCode: number | null;
+  /** Absolute path to the log file, or null if logging to terminal. */
+  logFile: string | null;
+};
+
+type BunProc = ReturnType<typeof Bun.spawn>;
+type StreamReader = ReadableStreamDefaultReader<Uint8Array>;
+
+export type ChangeListener = (p: ManagedProcess) => void;
+
+export class ProcessManager {
+  private processes = new Map<string, ManagedProcess>();
+  private procs = new Map<string, BunProc>();
+  /** Active stream readers per process — cancelled on stop to release file descriptors. */
+  private readers = new Map<string, StreamReader[]>();
+  private listeners: ChangeListener[] = [];
+  /** Processes currently being intentionally stopped/restarted — suppress exit handlers. */
+  private stopping = new Set<string>();
+  /** Processes whose terminal output is suppressed. */
+  private silenced = new Set<string>();
+  /**
+   * When set, each process's stdout+stderr are appended to
+   * `<logDir>/<process-name>.log` instead of inheriting the terminal.
+   */
+  logDir: string | undefined;
+
+  onProcessChange(fn: ChangeListener): () => void {
+    this.listeners.push(fn);
+    return () => {
+      const i = this.listeners.indexOf(fn);
+      if (i !== -1) this.listeners.splice(i, 1);
+    };
+  }
+
+  private emit(p: ManagedProcess) {
+    for (const fn of this.listeners) fn(p);
+  }
+
+  getAll(): ManagedProcess[] {
+    return Array.from(this.processes.values());
+  }
+
+  get(name: string): ManagedProcess | undefined {
+    return this.processes.get(name);
+  }
+
+  /**
+   * Spawns the process described by `config`.
+   * Returns a `waitForExit` promise that resolves with the exit code.
+   * When `this.logDir` is set, stdout+stderr are appended to
+   * `<logDir>/<name>.log` instead of the terminal.
+   */
+  async launch(config: ProcessConfig): Promise<{ waitForExit: Promise<number>; logFile: string | null }> {
+    // Free any ports this process needs
+    for (const port of config.stopProcessAtPort ?? []) {
+      await freePort(port);
+    }
+
+    const command = config.command ?? "bun";
+
+    // Resolve log file destination
+    let logFile: string | null = null;
+    let outFd: number | "inherit" = "inherit";
+    if (this.logDir) {
+      logFile = path.join(this.logDir, `${config.name}.log`);
+      // Open in append mode so restarts accumulate in the same file
+      outFd = fs.openSync(logFile, "a");
+    }
+
+    // When logging to a file, write directly to the fd.
+    // Otherwise, pipe output so we can suppress silenced processes.
+    const usesPipe = typeof outFd !== "number";
+
+    const proc = Bun.spawn([command, ...config.args], {
+      env: {
+        ...process.env,
+        ...config.env,
+        FORCE_COLOR: "true",
+      },
+      cwd: config.cwd ?? process.cwd(),
+      stdout: usesPipe ? "pipe" : outFd,
+      stderr: usesPipe ? "pipe" : outFd,
+      stdin: "ignore",
+    });
+
+    // The child has inherited the fd — safe to close the parent's copy
+    if (typeof outFd === "number") fs.closeSync(outFd);
+
+    // Forward piped output to the terminal unless silenced, prefixed with [name]
+    if (usesPipe) {
+      const prefix = `\x1b[36m[${config.name}]\x1b[0m `;
+      const prefixBytes = new TextEncoder().encode(prefix);
+      const newline = 0x0a; // '\n'
+      const activeReaders: StreamReader[] = [];
+
+      const forward = (stream: ReadableStream<Uint8Array> | null, dest: typeof process.stdout) => {
+        if (!stream) return;
+        const reader = stream.getReader();
+        activeReaders.push(reader);
+        let atLineStart = true;
+
+        const pump = (): void => {
+          reader.read().then(({ done, value }) => {
+            if (done) {
+              reader.releaseLock();
+              return;
+            }
+            if (this.silenced.has(config.name)) {
+              pump();
+              return;
+            }
+
+            // Prefix each line with [processName]
+            const chunks: Uint8Array[] = [];
+            let start = 0;
+            for (let i = 0; i < value.length; i++) {
+              if (atLineStart) {
+                chunks.push(prefixBytes);
+                atLineStart = false;
+              }
+              if (value[i] === newline) {
+                chunks.push(value.subarray(start, i + 1));
+                start = i + 1;
+                atLineStart = true;
+              }
+            }
+            // Remaining bytes after last newline
+            if (start < value.length) {
+              chunks.push(value.subarray(start));
+            }
+
+            for (const chunk of chunks) {
+              dest.write(chunk);
+            }
+            pump();
+          }).catch(() => {});
+        };
+        pump();
+      };
+      forward(proc.stdout as ReadableStream<Uint8Array>, process.stdout);
+      forward(proc.stderr as ReadableStream<Uint8Array>, process.stderr);
+      this.readers.set(config.name, activeReaders);
+    }
+
+    const managed: ManagedProcess = {
+      name: config.name,
+      pid: proc.pid,
+      ports: config.stopProcessAtPort ?? [],
+      status: "running",
+      config,
+      startedAt: new Date(),
+      endedAt: null,
+      exitCode: null,
+      logFile,
+    };
+
+    this.processes.set(config.name, managed);
+    this.procs.set(config.name, proc);
+    this.emit(managed);
+
+    const waitForExit = proc.exited.then((code) => {
+      managed.status = code === 0 ? "done" : "failed";
+      managed.exitCode = code;
+      managed.endedAt = new Date();
+      this.procs.delete(config.name);
+      this.emit(managed);
+      return code;
+    });
+
+    return { waitForExit, logFile };
+  }
+
+  /**
+   * Sends SIGTERM to the named process; waits for it to exit.
+   * Falls back to SIGKILL after 5 seconds.
+   */
+  async stop(name: string): Promise<boolean> {
+    const proc = this.procs.get(name);
+    const managed = this.processes.get(name);
+    if (!proc || !managed) return false;
+
+    this.stopping.add(name);
+
+    // Cancel active stream readers to release file descriptors
+    const readers = this.readers.get(name);
+    if (readers) {
+      for (const reader of readers) {
+        reader.cancel().catch(() => {});
+      }
+      this.readers.delete(name);
+    }
+
+    proc.kill("SIGTERM");
+
+    // Wait up to 5 s for graceful exit, then SIGKILL
+    const graceful = await Promise.race([
+      proc.exited.then(() => true),
+      Bun.sleep(5000).then(() => false),
+    ]);
+
+    if (!graceful) {
+      proc.kill("SIGKILL");
+      await proc.exited.catch(() => {});
+    }
+
+    managed.status = "stopped";
+    managed.endedAt = new Date();
+    this.procs.delete(name);
+    this.stopping.delete(name);
+    this.emit(managed);
+    return true;
+  }
+
+  /** Stops and re-launches a process. Returns null if the process was never started. */
+  async restart(name: string): Promise<{ waitForExit: Promise<number> } | null> {
+    const managed = this.processes.get(name);
+    if (!managed) return null;
+    await this.stop(name);
+    return this.launch(managed.config);
+  }
+
+  /** Stops all running processes in parallel. */
+  async stopAll(): Promise<void> {
+    await Promise.all(Array.from(this.procs.keys()).map((n) => this.stop(n)));
+  }
+
+  isRunning(name: string): boolean {
+    return this.procs.has(name);
+  }
+
+  /** Returns true if the process is being intentionally stopped (via stop/restart). */
+  isStopping(name: string): boolean {
+    return this.stopping.has(name);
+  }
+
+  /** Suppress terminal output for the named process. */
+  silence(name: string): void {
+    this.silenced.add(name);
+  }
+
+  /** Resume terminal output for the named process. */
+  unsilence(name: string): void {
+    this.silenced.delete(name);
+  }
+
+  /** Returns the set of currently silenced process names. */
+  getSilenced(): string[] {
+    return [...this.silenced];
+  }
+}