go-dev 0.5.0 → 0.6.0

package/README.md

@@ -14,7 +14,7 @@ In complex monorepos, starting your development environment can be a chore. You
 
 *   **Unified Configuration:** Define all your services, their modes (e.g., `dev`, `docker`, `serve`), and dependencies in a single `go-dev.yml` file.
 *   **Service Types:**
-    *   **`cmd` services:** Run any command-line process (e.g., `npm run dev`, `rollup -w`, `python app.py`). Supports `preCommands` for setup tasks like builds. Commands can be defined in multiple flexible ways to run single or multiple processes in parallel for a service.
+    *   **`cmd` services:** Run any command-line process (e.g., `npm run dev`, `rollup -w`, `python app.py`). Supports `preCommands` for setup tasks like builds, and `readyWhen` to hold back dependents until the service is actually usable (log match, file, or open port). Commands can be defined in multiple flexible ways to run single or multiple processes in parallel for a service.
     *   **`docker` services:** Manage Docker containers via `docker compose`. Automatically checks container status and performs health checks.
 *   **Mode-Aware Dependencies:** Services can depend on other services running in specific modes (e.g., your `api` dev mode might depend on `frontend` in `serve` mode).
 *   **Preset-Driven Startup:** Define different "presets" (e.g., `api`, `frontend`, `all`) to easily spin up specific combinations of services tailored to your current development focus.
@@ -174,6 +174,17 @@ services:
         commands:
           command: [npx, rollup, -c, -w]
           directory: ./frontend
+        # 'readyWhen' holds back dependents until this (long-running) service is
+        # actually usable, instead of resolving as soon as the process spawns.
+        # This is the watch-mode counterpart of docker's 'healthCheck': prefer it
+        # over building shared artifacts again as a preCommand of every consumer.
+        # Provide at least one condition (multiple are combined with AND):
+        #   logMatch: "<regex>"   — ready when a line on stdout/stderr matches
+        #   file: ./dist/index.js — ready when the path exists on disk
+        #   port: 5173            — ready when a TCP connection succeeds
+        # Optional: host (default 127.0.0.1), timeoutMs (60000), pollIntervalMs (500).
+        readyWhen:
+          logMatch: "created .* in"   # rollup's "created dist/... in 1.2s"
         dependencies:
           # Frontend dev needs API (will use api's default docker mode for this preset)
           # Note: No direct circular dependency between dev modes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "go-dev",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "main": "src/index.js",
   "bin": {
     "go-dev": "bin/go-dev"

package/src/config.js

@@ -31,6 +31,15 @@ const preCommandConfigSchema = Joi.alternatives().try(
     serviceRefSchema,
 );
 
+const readyWhenSchema = Joi.object({
+  logMatch: Joi.string().min(1),
+  file: Joi.string().min(1),
+  port: Joi.number().integer().min(1).max(65535),
+  host: Joi.string().min(1).default('127.0.0.1'),
+  timeoutMs: Joi.number().integer().min(0).default(60000),
+  pollIntervalMs: Joi.number().integer().min(50).default(500),
+}).or('logMatch', 'file', 'port');
+
 const cmdServiceConfigSchema = Joi.object({
   type: Joi.string().valid('cmd').required(),
   preCommands: Joi.array().items(preCommandConfigSchema).default([]),
@@ -41,6 +50,7 @@ const cmdServiceConfigSchema = Joi.object({
   defaultCommand: Joi.string().default('start'),
   directory: Joi.string(),
   dependencies: Joi.array().items(dependencyEntrySchema).default([]),
+  readyWhen: readyWhenSchema.optional(),
   healthCheck: Joi.boolean().default(false)
 });
 

package/src/process-manager.js

@@ -88,6 +88,56 @@ class ProcessManager {
     });
   }
 
+  /**
+   * Runs a command asynchronously, prefixing its output like a managed process.
+   * Used for pre-commands (literal or service-as-preCommand) so their output is
+   * attributed to the owning service instead of leaking raw to the terminal.
+   * @param {string} command - The command to execute.
+   * @param {string[]} args - Arguments for the command.
+   * @param {object} [options={}] - Options for spawn (e.g., cwd).
+   * @param {string} prefix - Prefix for stdout/stderr lines.
+   * @returns {Promise<void>} Resolves when the process exits successfully.
+   */
+  runInheritedPrefixed(command, args = [], options = {}, prefix) {
+    return new Promise((resolve, reject) => {
+      if (this.cleanupInProgress) {
+        log.warn(`[ProcessManager] Skipping inherited command '${command}' during cleanup.`);
+        return resolve();
+      }
+      log.debug(`[ProcessManager] Running inherited (prefixed): ${command} ${args.join(' ')}`);
+      const proc = spawn(command, args, {
+        shell: true,
+        stdio: 'pipe',
+        ...options,
+        env: { FORCE_COLOR: '1', ...process.env, ...(options.env ?? {}) },
+      });
+
+      let lastFormatting = '';
+      const writePrefixed = (data, target) => {
+        const result = prefixLines(data.toString(), prefix, lastFormatting);
+        lastFormatting = result.lastFormatting;
+        target.write(result.prefixedText);
+      };
+      proc.stdout.on('data', (data) => writePrefixed(data, process.stdout));
+      proc.stderr.on('data', (data) => writePrefixed(data, process.stderr));
+
+      proc.on('error', (err) => {
+        log.error(`[ProcessManager] Failed to start inherited command '${command}':`, err);
+        reject(err);
+      });
+
+      proc.on('exit', (code) => {
+        if (code !== 0) {
+          reject(
+            new Error(`Inherited command '${command}' exited with code ${code}`),
+          );
+        } else {
+          resolve();
+        }
+      });
+    });
+  }
+
   /**
    * Starts a long-running, managed process (like 'npx rollup -w').
    * Its output is prefixed, and it can be configured to restart on exit.

package/src/services/cmd.js

@@ -1,6 +1,7 @@
 const log = require('../logger');
 const { BaseService } = require('./base');
 const { buildColoredPrefix, buildColoredTag } = require('../service-colors');
+const { waitForReady } = require('./ready-check');
 
 class CmdService extends BaseService {
   /**
@@ -70,9 +71,11 @@ class CmdService extends BaseService {
       }
 
       const normalized = CmdService._normalizeCommands(config.commands);
-      await Promise.all(normalized.map(({ command, directory }) => {
+      const useIndex = normalized.length > 1;
+      await Promise.all(normalized.map(({ command, directory }, index) => {
         const [cmd, ...args] = command;
-        return CmdService._processManager.runInherited(cmd, args, { cwd: directory });
+        const prefix = buildColoredPrefix(serviceName, mode, useIndex ? index : null);
+        return CmdService._processManager.runInheritedPrefixed(cmd, args, { cwd: directory }, prefix);
       }));
 
       log.info(`[${ctx}] preCommand service completed.`);
@@ -98,10 +101,12 @@ class CmdService extends BaseService {
       ? { cmdArgs: pre }
       : { cmdArgs: pre.command, directory: pre.directory });
     try {
-      CmdService._processManager.runSync(cmdArgs[0], cmdArgs.slice(1), {
-        cwd: directory,
-        stdio: 'inherit',
-      });
+      await CmdService._processManager.runInheritedPrefixed(
+        cmdArgs[0],
+        cmdArgs.slice(1),
+        { cwd: directory },
+        fromContext,
+      );
     } catch (error) {
       log.debug({ cmdArgs });
       throw new Error(
@@ -222,6 +227,14 @@ class CmdService extends BaseService {
         `[${this.coloredId}] Process started (PID: ${process.process.pid}).`,
       );
     }
+
+    if (this.config.readyWhen) {
+      await waitForReady(
+        this.processes.map(({ process }) => process),
+        this.config.readyWhen,
+        this.coloredId,
+      );
+    }
   }
 
   async stop() {

package/src/services/ready-check.js

@@ -0,0 +1,134 @@
+const net = require('net');
+const fs = require('fs');
+const path = require('path');
+const log = require('../logger');
+
+const MAX_BUFFER = 16 * 1024;
+
+/**
+ * Resolves when one of the managed processes prints a line matching `pattern`.
+ * Attaches an extra listener on top of the existing prefixing one, so it does
+ * not interfere with normal output.
+ */
+function logMatchCheck(processes, pattern, timeoutMs) {
+  const regex = new RegExp(pattern);
+  let cleanup = () => {};
+  const promise = new Promise((resolve, reject) => {
+    let buffer = '';
+    const listeners = [];
+    const onData = (data) => {
+      buffer = (buffer + data.toString()).slice(-MAX_BUFFER);
+      if (regex.test(buffer)) {
+        resolve();
+      }
+    };
+    for (const proc of processes) {
+      for (const stream of [proc.stdout, proc.stderr]) {
+        if (!stream) {
+          continue;
+        }
+        stream.on('data', onData);
+        listeners.push(stream);
+      }
+    }
+    const timer = setTimeout(() => {
+      reject(new Error(`Timed out after ${timeoutMs}ms waiting for log /${pattern}/`));
+    }, timeoutMs);
+    cleanup = () => {
+      clearTimeout(timer);
+      for (const stream of listeners) {
+        stream.off('data', onData);
+      }
+    };
+  });
+  return { promise: promise.finally(() => cleanup()), cancel: () => cleanup() };
+}
+
+/** Resolves once `filePath` exists on disk, polling until the timeout. */
+function fileCheck(filePath, timeoutMs, pollIntervalMs) {
+  const resolved = path.resolve(filePath);
+  let cancelled = false;
+  const promise = (async () => {
+    const deadline = Date.now() + timeoutMs;
+    while (!cancelled) {
+      if (fs.existsSync(resolved)) {
+        return;
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(`Timed out after ${timeoutMs}ms waiting for file '${resolved}'`);
+      }
+      await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+    }
+  })();
+  return { promise, cancel: () => { cancelled = true; } };
+}
+
+function tryConnect(host, port) {
+  return new Promise((resolve) => {
+    const socket = net.connect({ host, port });
+    const done = (ok) => {
+      socket.destroy();
+      resolve(ok);
+    };
+    socket.once('connect', () => done(true));
+    socket.once('error', () => done(false));
+    socket.setTimeout(1000, () => done(false));
+  });
+}
+
+/** Resolves once a TCP connection to `host:port` succeeds, polling until the timeout. */
+function portCheck(host, port, timeoutMs, pollIntervalMs) {
+  let cancelled = false;
+  const promise = (async () => {
+    const deadline = Date.now() + timeoutMs;
+    while (!cancelled) {
+      if (await tryConnect(host, port)) {
+        return;
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(`Timed out after ${timeoutMs}ms waiting for ${host}:${port}`);
+      }
+      await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+    }
+  })();
+  return { promise, cancel: () => { cancelled = true; } };
+}
+
+/**
+ * Blocks until the given `readyWhen` conditions are all satisfied for the
+ * provided managed processes. Multiple conditions are combined with AND.
+ * @param {import('child_process').ChildProcess[]} processes
+ * @param {object} readyWhen - Validated `readyWhen` config (with defaults applied).
+ * @param {string} coloredId - The service's colored tag, for logging.
+ */
+async function waitForReady(processes, readyWhen, coloredId) {
+  const { logMatch, file, port, host, timeoutMs, pollIntervalMs } = readyWhen;
+
+  const checks = [];
+  const labels = [];
+  if (logMatch != null) {
+    checks.push(logMatchCheck(processes, logMatch, timeoutMs));
+    labels.push(`log /${logMatch}/`);
+  }
+  if (file != null) {
+    checks.push(fileCheck(file, timeoutMs, pollIntervalMs));
+    labels.push(`file '${file}'`);
+  }
+  if (port != null) {
+    checks.push(portCheck(host, port, timeoutMs, pollIntervalMs));
+    labels.push(`${host}:${port}`);
+  }
+
+  log.info(`[${coloredId}] Waiting until ready (${labels.join(' AND ')})...`);
+  try {
+    await Promise.all(checks.map(check => check.promise));
+    log.info(`[${coloredId}] Service is ready.`);
+  } finally {
+    // Stop any still-pending checks so they don't reject after we're done.
+    for (const check of checks) {
+      check.cancel();
+    }
+  }
+}
+
+module.exports = { waitForReady };