go-dev 0.1.0

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "go-dev",
+  "version": "0.1.0",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "Giuliano Collacchioni",
+  "license": "MIT",
+  "description": "",
+  "dependencies": {
+    "joi": "^17.13.3",
+    "js-yaml": "^4.1.0"
+  }
+}

package/src/config.js

@@ -0,0 +1,117 @@
+const Joi = require('joi');
+const yaml = require('js-yaml');
+const fs = require('fs');
+const path = require('path');
+
+const dependencyEntrySchema = Joi.alternatives().try(
+  Joi.string(),
+  Joi.object({
+    service: Joi.string().required(),
+    mode: Joi.string().required()
+  })
+);
+
+const commandSchema = Joi.array().items(Joi.string().min(1)).min(1);
+const commandConfigSchema = Joi.alternatives().try(
+    commandSchema,
+    Joi.object({
+        command: commandSchema,
+        directory: Joi.string().min(1),
+    })
+);
+
+const cmdServiceConfigSchema = Joi.object({
+  type: Joi.string().valid('cmd').required(),
+  preCommands: Joi.array().items(commandConfigSchema).default([]),
+  commands: Joi.object().pattern(
+    Joi.string(),
+    commandConfigSchema
+  ).min(1).required(),
+  defaultCommand: Joi.string().default('start'),
+  directory: Joi.string(),
+  dependencies: Joi.array().items(dependencyEntrySchema).default([]),
+  healthCheck: Joi.boolean().default(false)
+});
+
+const dockerServiceConfigSchema = Joi.object({
+  type: Joi.string().valid('docker').required(),
+  service: Joi.string().required(),
+  composeFile: Joi.string().default('docker-compose.yml'),
+  dependencies: Joi.array().items(dependencyEntrySchema).default([]),
+  healthCheck: Joi.boolean().default(true)
+});
+
+const serviceSchema = Joi.alternatives().try(
+  cmdServiceConfigSchema,
+  dockerServiceConfigSchema,
+  Joi.object({
+    type: Joi.string().valid('hybrid').required(),
+    defaultMode: Joi.string(),
+    modes: Joi.object().pattern(
+      Joi.string(),
+      Joi.alternatives().try(
+        cmdServiceConfigSchema,
+        dockerServiceConfigSchema
+      )
+    ).min(2).required()
+  })
+);
+
+const configSchema = Joi.object({
+  services: Joi.object().pattern(Joi.string(), serviceSchema).required(),
+  presets: Joi.object().pattern(
+    Joi.string(),
+    Joi.object({
+      services: Joi.array().items(Joi.string()).required(),
+      modes: Joi.object().pattern(Joi.string(), Joi.string()).default({})
+    })
+  ).default({})
+});
+
+function findConfigFile() {
+  const possibleNames = [
+    'dev-orchestrator',
+    '.dev-orchestrator'
+  ].flatMap(baseName => {
+    return [
+        baseName,
+        `${baseName}.config`
+    ];
+  }).flatMap(baseName => {
+    return [
+        `${baseName}.yml`,
+        `${baseName}.yaml`
+    ];
+  });
+
+  for (const name of possibleNames) {
+    if (fs.existsSync(name)) {
+      return name;
+    }
+  }
+
+  throw new Error(`No config file found. Expected one of: ${possibleNames.join(', ')}`);
+}
+
+function loadConfig(configPath) {
+  if (!configPath) {
+    configPath = findConfigFile();
+  }
+  
+  if (!fs.existsSync(configPath)) {
+    throw new Error(`Config file not found: ${configPath}`);
+  }
+  
+  const configContent = fs.readFileSync(configPath, 'utf8');
+  const config = yaml.load(configContent);
+  
+  const { error, value } = configSchema.validate(config);
+  
+  if (error) {
+    throw new Error(`Invalid config: ${error.message}`);
+  }
+  
+  return value;
+}
+
+module.exports = { loadConfig };

package/src/dependency-resolver.js

@@ -0,0 +1,102 @@
+function resolveServiceExecutionGraph(config, presetName) {
+  const preset = config.presets[presetName];
+  if (!preset) {
+    throw new Error(`Preset '${presetName}' not found in configuration.`);
+  }
+
+  const services = [];
+  const dependencies = [];
+
+  for (const serviceName of preset.services) {
+    addService(
+      serviceName,
+      preset.modes[serviceName],
+      null,
+    );
+  }
+
+  return { dependencies, services };
+
+  function addService(serviceName, mode, dependentService) {
+    const service = config.services[serviceName];
+    if (service == null) {
+      throw new Error(`Service named '${serviceName}' not found in configuration.`);
+    }
+
+    if (dependentService != null) {
+      const existingService = services.find(({ name }) => {
+        return name === serviceName;
+      });
+      if (existingService != null) {
+        console.warn(
+          `Ignoring dependency '${serviceName}' for '${dependentService}' because it is flagged to be run as service in mode '${existingService.mode}'.`
+        );
+        return;
+      }
+    } else {
+      const existingDependencyIndex = dependencies.findIndex(({ name }) => {
+        return name === serviceName;
+      });
+      if (existingDependencyIndex >= 0) {
+        console.warn(
+          `Removing service '${serviceName}' from dependencies because it is flagged to be run as service in mode '${dependencies[existingDependencyIndex].mode}'.`
+        );
+        dependencies.splice(existingDependencyIndex, 1);
+      }
+    }
+
+    mode = (service.type === 'hybrid' ?
+      mode ?? service.defaultMode ?? 'dev' :
+      mode ?? 'dev'
+    );
+    const serviceConfig = (service.type === 'hybrid' ?
+      service.modes[mode] :
+      (mode === 'dev' ? service : undefined)
+    );
+
+    if (serviceConfig == null) {
+      throw new Error(`Mode named '${mode}' not found in service '${serviceName}'.`);
+    }
+
+    if (dependentService == null) {
+      services.push({
+        name: serviceName,
+        mode,
+        config: serviceConfig,
+      });
+    } else {
+      dependencies.unshift({
+        name: serviceName,
+        mode,
+        config: serviceConfig,
+      });
+    }
+
+    for (let index = serviceConfig.dependencies.length - 1; index >= 0; index--) {
+      const dependency = serviceConfig.dependencies[index];
+      const {
+        service: dependencyName,
+        mode: dependencyMode,
+      } = (typeof dependency === 'string' ?
+        { service: dependency, mode: 'dev' } :
+        dependency
+      );
+
+      const existingDependencyIndex = dependencies.find(({ name }) => {
+        return name === dependencyName;
+      });
+      if (existingDependencyIndex != null) {
+        console.warn(`Skipping dependency '${dependencyName}' for '${serviceName}' because it's already present in dependencies list.`);
+        continue;
+      }
+
+      addService(
+        dependencyName,
+        dependencyMode,
+        serviceName,
+      );
+    }
+  }
+}
+
+module.exports = { resolveServiceExecutionGraph };

package/src/index.js

@@ -0,0 +1,4 @@
+const Orchestrator = require('./orchestrator');
+
+const orchestrator = new Orchestrator();
+orchestrator.start(process.argv[2]);

package/src/orchestrator.js

@@ -0,0 +1,106 @@
+const { loadConfig } = require('./config');
+const { resolveServiceExecutionGraph } = require('./dependency-resolver');
+const ProcessManager = require('./process-manager');
+const { BaseService } = require('./services/base');
+const { CmdService } = require('./services/cmd');
+const { DockerService } = require('./services/docker');
+
+const serviceTypeMap = {
+  cmd: CmdService,
+  docker: DockerService,
+};
+
+class Orchestrator {
+  constructor(configPath) {
+    this.config = loadConfig(configPath);
+
+    this.processManager = new ProcessManager();
+    this.activeServiceInstances = new Map();
+
+    BaseService.initialize(this.processManager);
+  }
+
+  async start(presetName) {
+    try {
+      const { dependencies, services: primaryServices } = resolveServiceExecutionGraph(
+        this.config,
+        presetName,
+      );
+
+      console.log(`Starting development environment for preset: ${presetName}`);
+      console.log('--- Resolved Dependencies to Start First ---');
+      dependencies.forEach(s => console.log(` - ${s.name} (mode: ${s.mode})`));
+      console.log('--- Resolved Primary Services to Run ---');
+      primaryServices.forEach(s => console.log(` - ${s.name} (mode: ${s.mode})`));
+
+      console.log('\n--- Starting Dependencies ---');
+      for (const { name, mode, config } of dependencies) {
+        if (this.activeServiceInstances.has(name)) {
+          console.log(`[${name}:${mode}] Already active, skipping start.`);
+          continue;
+        }
+        const ServiceClass = serviceTypeMap[config.type];
+        if (!ServiceClass) {
+          throw new Error(`Unknown service type '${config.type}' for service '${name}'.`);
+        }
+        const serviceInstance = new ServiceClass(name, mode, config);
+        this.activeServiceInstances.set(name, serviceInstance);
+        await serviceInstance.start();
+      }
+
+      console.log('\n--- Starting Primary Services ---');
+      const primaryServicePromises = [];
+      for (const { name, mode, config } of primaryServices) {
+        if (this.activeServiceInstances.has(name)) {
+          console.log(`[${name}:${mode}] Already active, skipping start.`);
+          continue;
+        }
+        const ServiceClass = serviceTypeMap[config.type];
+        if (!ServiceClass) {
+          throw new Error(`Unknown service type '${config.type}' for service '${name}'.`);
+        }
+        const serviceInstance = new ServiceClass(name, mode, config);
+        this.activeServiceInstances.set(name, serviceInstance);
+        primaryServicePromises.push(serviceInstance.start());
+      }
+      await Promise.all(primaryServicePromises);
+
+      console.log('\n--- All services initiated. Press Ctrl+C to stop. ---');
+
+      process.once('SIGINT', this.cleanup.bind(this));
+      process.once('SIGTERM', this.cleanup.bind(this));
+      process.stdin.resume();
+
+    } catch (error) {
+      console.error('\n❌ Orchestrator failed to start:', error.message);
+      await this.cleanup(true);
+      process.exit(1);
+    }
+  }
+
+  async cleanup() {
+    if (this.processManager.cleanupInProgress) {
+      console.log('[Orchestrator] Cleanup already in progress.');
+      return;
+    }
+
+    console.log('\n[Orchestrator] Initiating graceful cleanup...');
+
+    for (const [name, instance] of this.activeServiceInstances.entries()) {
+      try {
+        console.log(`[Orchestrator] Requesting instance stop for ${name}:${instance.mode}`);
+        await instance.stop();
+      } catch (error) {
+        console.error(`[Orchestrator] Error stopping instance ${name}:${instance.mode}: ${error.message}`);
+      }
+    }
+
+    await DockerService.cleanup();
+    await this.processManager.cleanupManagedProcesses();
+
+    console.log('[Orchestrator] Cleanup complete.');
+    process.exit(0);
+  }
+}
+
+module.exports = Orchestrator;

package/src/process-manager.js

@@ -0,0 +1,213 @@
+// src/process-manager.js
+const { spawn, spawnSync } = require('child_process');
+
+class ProcessManager {
+  constructor() {
+    this.managedProcesses = new Set();
+    this.cleanupInProgress = false;
+  }
+
+  /**
+   * Runs a command synchronously (blocking).
+   * Used for pre-commands, status checks, getting container names.
+   * @param {string} command - The command to execute.
+   * @param {string[]} args - Arguments for the command.
+   * @param {object} [options={}] - Options for spawnSync (e.g., cwd, stdio).
+   * @returns {string} The stdout of the command, trimmed.
+   * @throws {Error} If the command fails.
+   */
+  runSync(command, args = [], options = {}) {
+    if (this.cleanupInProgress) {
+      console.warn(`[ProcessManager] Skipping synchronous command '${command}' during cleanup.`);
+      return '';
+    }
+    console.log(`[ProcessManager] Running sync: ${command} ${args.join(' ')}`);
+    try {
+      const result = spawnSync(command, args, {
+        shell: true,
+        encoding: 'utf8',
+        ...options,
+      });
+
+      if (result.error) {
+        throw result.error;
+      }
+      if (result.status !== 0) {
+        const stderrOutput = result.stderr ? result.stderr.trim() : 'No stderr output.';
+        throw new Error(
+          `Command failed with code ${result.status}: ${command} ${args.join(
+            ' ',
+          )}\n${stderrOutput}`,
+        );
+      }
+      return result.stdout?.trim() ?? '';
+    } catch (error) {
+      throw new Error(`Failed to run sync command '${command}': ${error.message}`);
+    }
+  }
+
+  /**
+   * Runs a command asynchronously, inheriting stdio.
+   * Used for initial 'docker compose up -d' where we want to see immediate output
+   * and the process is not meant to be continually managed/restarted by the orchestrator.
+   * @param {string} command - The command to execute.
+   * @param {string[]} args - Arguments for the command.
+   * @param {object} [options={}] - Options for spawn.
+   * @returns {Promise<void>} A promise that resolves when the process exits successfully.
+   */
+  runInherited(command, args = [], options = {}) {
+    return new Promise((resolve, reject) => {
+      if (this.cleanupInProgress) {
+        console.warn(`[ProcessManager] Skipping inherited command '${command}' during cleanup.`);
+        return resolve();
+      }
+      console.log(`[ProcessManager] Running inherited: ${command} ${args.join(' ')}`);
+      const proc = spawn(command, args, {
+        shell: true,
+        stdio: 'inherit',
+        ...options,
+      });
+
+      proc.on('error', (err) => {
+        console.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.
+   * @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 (e.g., 'frontend:').
+   * @param {boolean} restartOnExit - Whether to restart the process if it exits with non-zero code.
+   * @returns {ChildProcess} The spawned child process instance.
+   */
+  startManagedProcess(command, args, options, prefix, restartOnExit) {
+    if (this.cleanupInProgress) {
+      console.warn(`[ProcessManager] Skipping managed process '${command}' during cleanup.`);
+      return null;
+    }
+    console.log(
+      `[ProcessManager] Starting managed process: ${command} ${args.join(
+        ' ',
+      )} (prefix: ${prefix})`,
+    );
+
+    const proc = spawn(command, args, {
+      shell: true,
+      stdio: 'pipe',
+      ...options,
+    });
+
+    proc.stdout.on('data', (data) => {
+      let prefixedData = data.toString().split('\n').map(line => `${prefix} ${line}`).join('\n');
+      if (prefixedData.endsWith(`${prefix} `)) {
+          prefixedData = prefixedData.slice(0, -(`${prefix} `).length);
+      }
+      if (!prefixedData.endsWith('\n')) {
+          prefixedData = prefixedData + '\n';
+      }
+      process.stdout.write(prefixedData);
+    });
+    proc.stderr.on('data', (data) => {
+      let prefixedData = data.toString().split('\n').map(line => `${prefix} ${line}`).join('\n');
+      if (prefixedData.endsWith(`${prefix} `)) {
+          prefixedData = prefixedData.slice(0, -(`${prefix} `).length);
+      }
+      if (!prefixedData.endsWith('\n')) {
+          prefixedData = prefixedData + '\n';
+      }
+      process.stderr.write(prefixedData);
+    });
+
+    this.managedProcesses.add(proc);
+
+    proc.on('error', (err) => {
+      console.error(
+        `[ProcessManager] Error starting managed process '${command}': ${err.message}`,
+      );
+      this.managedProcesses.delete(proc);
+    });
+
+    proc.on('exit', (code, signal) => {
+      this.managedProcesses.delete(proc);
+      if (this.cleanupInProgress) {
+        console.log(
+          `[ProcessManager] Managed process '${command}' (PID: ${proc.pid}) exited due to cleanup.`,
+        );
+        return;
+      }
+
+      if (code !== 0) {
+        console.error(
+          `[ProcessManager] Managed process '${command}' (PID: ${proc.pid}) exited with code ${code}.`,
+        );
+        if (restartOnExit) {
+          console.warn(
+            `[ProcessManager] Restarting managed process '${command}'...`,
+          );
+          this.startManagedProcess(command, args, options, prefix, restartOnExit);
+        }
+      } else {
+        console.log(
+          `[ProcessManager] Managed process '${command}' (PID: ${proc.pid}) exited cleanly.`,
+        );
+      }
+    });
+
+    return proc;
+  }
+
+  /**
+   * Kills all currently managed child processes.
+   */
+  async cleanupManagedProcesses() {
+    if (this.cleanupInProgress) {
+      console.log('[ProcessManager] Cleanup of managed processes already in progress, skipping.');
+      return;
+    }
+    this.cleanupInProgress = true;
+
+    console.log('\n[ProcessManager] Initiating cleanup of managed processes...');
+
+    for (const proc of [...this.managedProcesses]) {
+      console.log(`[ProcessManager] Killing managed process PID: ${proc.pid}`);
+      try {
+        proc.kill('SIGTERM');
+      } catch (e) {
+        console.error(`[ProcessManager] Error killing process ${proc.pid}: ${e.message}`);
+      }
+    }
+    await new Promise(resolve => setTimeout(resolve, 500));
+
+    for (const proc of [...this.managedProcesses]) {
+      if (proc.killed) {
+        continue;
+      }
+
+      console.warn(`[ProcessManager] Process ${proc.pid} did not exit gracefully, forcing kill.`);
+      try {
+        proc.kill('SIGKILL');
+      } catch (e) {
+        console.error(`[ProcessManager] Error forcing kill for process ${proc.pid}: ${e.message}`);
+      }
+    }
+
+    console.log('[ProcessManager] Managed process cleanup complete.');
+  }
+}
+
+module.exports = ProcessManager;

package/src/services/base.js

@@ -0,0 +1,50 @@
+class BaseService {
+  /** @type {import("../process-manager")} */
+  static _processManager = null;
+
+  /**
+   * Initializes the shared ProcessManager for all service types.
+   * This should be called once at application startup.
+   * @param {import("../process-manager")} processManagerInstance
+   */
+  static initialize(processManagerInstance) {
+    if (BaseService._processManager) {
+      console.warn('BaseService.initialize called multiple times. Skipping.');
+      return;
+    }
+    BaseService._processManager = processManagerInstance;
+  }
+
+  /**
+   * Static method for type-specific cleanup. To be overridden by subclasses.
+   * @returns {Promise<void>}
+   */
+  static async cleanup() {
+    console.log(`[${this.name}] No specific static cleanup defined.`);
+  }
+
+  /**
+   * @param {string} name - The logical name of the service (e.g., 'api', 'frontend').
+   * @param {string} mode - The resolved mode for this service (e.g., 'dev', 'docker', 'serve').
+   * @param {object} config - The concrete configuration object for this service and mode.
+   */
+  constructor(name, mode, config) {
+    this.name = name;
+    this.mode = mode;
+    this.config = config;
+  }
+
+  async start() {
+    throw new Error(`Service type for '${this.name}' in mode '${this.mode}' must implement start()`);
+  }
+
+  async stop() {
+    return;
+  }
+
+  async checkHealth() {
+    return true;
+  }
+}
+
+module.exports = { BaseService };

package/src/services/cmd.js

@@ -0,0 +1,81 @@
+const { BaseService } = require('./base');
+
+class CmdService extends BaseService {
+  constructor(name, mode, config) {
+    super(name, mode, config);
+    this.prefix = `${name}:${mode}:`;
+    this.process = null;
+  }
+
+  async start() {
+    console.log(`[${this.name}:${this.mode}] Starting cmd service...`);
+
+    const { preCommands, commands, defaultCommand } = this.config;
+
+    if (preCommands && preCommands.length > 0) {
+      console.log(`[${this.name}:${this.mode}] Running pre-commands...`);
+      for (const command of preCommands) {
+        const { cmdArgs, directory } = (Array.isArray(command) ?
+          { cmdArgs: command } :
+          { cmdArgs: command.command, cmdArgs: command.directory }
+        );
+        try {
+          CmdService._processManager.runSync(cmdArgs[0], cmdArgs.slice(1), {
+            cwd: directory,
+            stdio: 'inherit',
+          });
+        } catch (error) {
+          throw new Error(
+            `[${this.name}:${this.mode}] Pre-command failed: ${cmdArgs.join(
+              ' ',
+            )}: ${error.message}`,
+          );
+        }
+      }
+      console.log(`[${this.name}:${this.mode}] Pre-commands completed.`);
+    }
+
+    const mainCommand = commands[defaultCommand];
+    if (!mainCommand) {
+      throw new Error(
+        `[${this.name}:${this.mode}] Default command '${defaultCommand}' not found for service.`,
+      );
+    }
+
+    const { cmdArgs, directory } = (Array.isArray(mainCommand) ?
+      { cmdArgs: mainCommand } :
+      { cmdArgs: mainCommand.command, directory: mainCommand.directory }
+    );
+
+    this.process = CmdService._processManager.startManagedProcess(
+      cmdArgs[0],
+      cmdArgs.slice(1),
+      { cwd: directory },
+      this.prefix,
+      true,
+    );
+
+    if (!this.process) {
+      throw new Error(
+        `[${this.name}:${this.mode}] Failed to spawn main process: ${cmdArgs.join(' ')}`,
+      );
+    }
+    console.log(
+      `[${this.name}:${this.mode}] Main process started (PID: ${this.process.pid}).`,
+    );
+  }
+
+  async stop() {
+    if (this.process) {
+      console.log(`[${this.name}:${this.mode}] Stopping main process (PID: ${this.process.pid}).`);
+      try {
+        this.process.kill('SIGTERM');
+      } catch (e) {
+        console.error(`[${this.name}:${this.mode}] Error signaling process ${this.process.pid}: ${e.message}`);
+      }
+      this.process = null;
+    }
+  }
+}
+
+module.exports = { CmdService };

package/src/services/docker.js

@@ -0,0 +1,172 @@
+const { BaseService } = require('./base');
+
+class DockerService extends BaseService {
+  /** @type {Set<string>} */
+  static _composeFilesToStop = new Set();
+
+  static async cleanup() {
+    if (!DockerService._processManager) {
+      console.warn('[DockerService] ProcessManager not initialized, skipping static cleanup.');
+      return;
+    }
+
+    if (DockerService._composeFilesToStop.size > 0) {
+      console.log('[DockerService] Stopping all docker services from used compose files...');
+      for (const composeFile of DockerService._composeFilesToStop) {
+        try {
+          console.log(`[DockerService] Running 'docker compose -f ${composeFile} stop'`);
+          DockerService._processManager.runSync(
+            'docker',
+            ['compose', '-f', composeFile, 'stop'],
+            { stdio: 'inherit' },
+          );
+        } catch (error) {
+          console.error(
+            `[DockerService] Failed to execute 'docker compose -f ${composeFile} stop': ${error.message}`,
+          );
+        }
+      }
+      DockerService._composeFilesToStop.clear();
+    } else {
+      console.log('[DockerService] No docker services were started by orchestrator, skipping global stop.');
+    }
+  }
+
+  constructor(name, mode, config) {
+    super(name, mode, config);
+    this.dockerServiceName = config.service;
+    this.dockerComposeFile = config.composeFile;
+    this.containerName = null;
+  }
+
+  async start() {
+    console.log(`[${this.name}:${this.mode}] Starting docker service '${this.dockerServiceName}' (using ${this.dockerComposeFile})...`);
+
+    let status = this._getContainerStatus();
+    if (status === 'running') {
+      console.log(
+        `[${this.name}:${this.mode}] Docker container for '${this.dockerServiceName}' is already running.`,
+      );
+      DockerService._composeFilesToStop.add(this.dockerComposeFile);
+    } else {
+      console.log(`[${this.name}:${this.mode}] Bringing up docker service '${this.dockerServiceName}'...`);
+      try {
+        await DockerService._processManager.runInherited(
+          'docker',
+          ['compose', '-f', this.dockerComposeFile, 'up', this.dockerServiceName, '-d'],
+        );
+        DockerService._composeFilesToStop.add(this.dockerComposeFile);
+        console.log(`[${this.name}:${this.mode}] Docker service '${this.dockerServiceName}' brought up.`);
+      } catch (error) {
+        throw new Error(
+          `[${this.name}:${this.mode}] Failed to bring up docker service '${this.dockerServiceName}': ${error.message}`,
+        );
+      }
+    }
+
+    if (this.config.healthCheck) {
+      console.log(`[${this.name}:${this.mode}] Checking healthiness for '${this.dockerServiceName}'...`);
+      try {
+        await this._checkServiceHealthiness();
+        console.log(`[${this.name}:${this.mode}] Docker service '${this.dockerServiceName}' is healthy.`);
+      } catch (error) {
+        throw new Error(
+          `[${this.name}:${this.mode}] Health check failed for '${this.dockerServiceName}': ${error.message}`,
+        );
+      }
+    } else {
+      console.log(`[${this.name}:${this.mode}] Skipping health check for '${this.dockerServiceName}'.`);
+    }
+  }
+
+  async stop() {
+    // The static cleanup method will handle the actual docker compose stop.
+    console.log(`[${this.name}:${this.mode}] Relying on orchestrator's static docker compose stop for '${this.dockerServiceName}'.`);
+    this.containerName = null;
+  }
+
+  async checkHealth() {
+    return await this._checkServiceHealthiness();
+  }
+
+  _getContainerName() {
+    if (this.containerName) {
+      return this.containerName;
+    }
+    try {
+      // Access processManager statically
+      const name = DockerService._processManager.runSync(
+        'docker',
+        ['compose', '-f', this.dockerComposeFile, 'ps', '-a', '-q', this.dockerServiceName],
+      );
+      if (name) {
+        this.containerName = name;
+        return name;
+      }
+    } catch (error) {
+      // console.warn(...);
+    }
+    return null;
+  }
+
+  _getContainerStatus() {
+    const containerName = this._getContainerName();
+    if (!containerName) {
+      return null;
+    }
+    try {
+      // Access processManager statically
+      return DockerService._processManager.runSync(
+        'docker',
+        ['container', 'inspect', '-f', '{{.State.Status}}', containerName],
+      );
+    } catch (error) {
+      // console.warn(...);
+      return null;
+    }
+  }
+
+  async _checkServiceHealthiness(maxAttempts = 30, delayMs = 1000) {
+    const containerName = this._getContainerName();
+    if (!containerName) {
+      throw new Error(`[${this.name}:${this.mode}] Cannot check health: Container for '${this.dockerServiceName}' not found.`);
+    }
+
+    process.stdout.write(`[${this.name}:${this.mode}] Checking healthiness for '${containerName}'`);
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      if (attempt > 1) {
+        process.stdout.write(".");
+        await new Promise(resolve => setTimeout(resolve, delayMs));
+      }
+
+      try {
+        // Access processManager statically
+        const healthStatus = DockerService._processManager.runSync(
+          'docker',
+          ['container', 'inspect', '-f', '{{.State.Health.Status}}', containerName],
+          { stdio: 'pipe' }
+        );
+
+        if (healthStatus === 'healthy' || healthStatus === 'none') {
+          process.stdout.write(" Healthy!\n");
+          return true;
+        }
+
+        if (healthStatus === 'starting' || healthStatus === 'unhealthy') {
+          continue;
+        }
+
+        process.stdout.write(` Status: ${healthStatus}\n`);
+        throw new Error(`[${this.name}:${this.mode}] Container '${containerName}' is in unexpected health state: ${healthStatus}`);
+      } catch (error) {
+        process.stdout.write(` Error: ${error.message}\n`);
+        throw new Error(`[${this.name}:${this.mode}] Failed to check health for '${containerName}': ${error.message}`);
+      }
+    }
+
+    process.stdout.write("\n");
+    throw new Error(`[${this.name}:${this.mode}] Service '${this.dockerServiceName}' wasn't healthy in time after ${maxAttempts} attempts.`);
+  }
+}
+
+module.exports = { DockerService };

package/test.js

@@ -0,0 +1,136 @@
+const { loadConfig } = require('./src/config');
+const { resolveServiceExecutionGraph } = require('./src/dependency-resolver');
+const fs = require('fs');
+
+const testConfigContent = `
+composeFile: infrastructure/docker-compose.yml
+
+services:
+  postgres:
+    type: docker
+    service: postgres
+    healthCheck: true
+
+  api:
+    type: hybrid
+    defaultMode: dev
+    modes:
+      dev:
+        type: cmd
+        commands:
+          start: [npx, rollup, -c, -w]
+        directory: ./api
+        dependencies:
+          - postgres
+          - { service: frontend, mode: serve }
+
+      docker:
+        type: docker
+        service: api
+        healthCheck: true
+        dependencies:
+          - postgres
+
+  frontend:
+    type: hybrid
+    defaultMode: dev
+    modes:
+      dev:
+        type: cmd
+        commands:
+          start: [npx, rollup, -c, -w]
+        directory: ./frontend
+        dependencies:
+          - { service: api, mode: docker }
+
+      serve:
+        type: cmd
+        preCommands:
+          - [npm, --prefix, frontend, run, build]
+        commands:
+          start: [node, ./localserver.mjs]
+        directory: ./frontend
+        dependencies:
+          - api
+
+presets:
+  api:
+    services: [api]
+
+  frontend:
+    services: [frontend]
+
+  all:
+    services: [api, frontend]
+
+  # Example of a preset that would cause a cycle if dependencies were set up naively
+  # (and without the \`dev\` modes being peers)
+  # cycle-test:
+  #   services: [api, frontend]
+  #   modes:
+  #     api: dev
+  #     frontend: cycle-dev # Imagine 'cycle-dev' depends on 'api:dev'
+  #     # To trigger a cycle, you'd need api:dev -> frontend:dev and frontend:dev -> api:dev
+
+`;
+
+const testConfigPath = 'temp-dev-orchestrator.yml';
+fs.writeFileSync(testConfigPath, testConfigContent);
+
+console.log('--- Testing Dependency Resolver ---');
+
+try {
+  const config = loadConfig(testConfigPath);
+  console.log('✅ Config loaded successfully');
+
+  console.log('\n--- Resolving "api" preset ---');
+  const apiExecutionGraph = resolveServiceExecutionGraph(config, 'api');
+  console.log('✅ "api" preset resolved successfully.');
+  console.log('Dependencies:');
+  apiExecutionGraph.dependencies.forEach((node) => {
+    console.log(`  - ${node.name} (mode: ${node.mode})`);
+  });
+  console.log('Services:');
+  apiExecutionGraph.services.forEach((node) => {
+    console.log(`  - ${node.name} (mode: ${node.mode})`);
+  });
+  
+  console.log('\n--- Resolving "frontend" preset ---');
+  const frontendExecutionGraph = resolveServiceExecutionGraph(config, 'frontend');
+  console.log('✅ "frontend" preset resolved successfully.');
+  console.log('Dependencies:');
+  frontendExecutionGraph.dependencies.forEach((node) => {
+    console.log(`  - ${node.name} (mode: ${node.mode})`);
+  });
+  console.log('Services:');
+  frontendExecutionGraph.services.forEach((node) => {
+    console.log(`  - ${node.name} (mode: ${node.mode})`);
+  });
+
+  console.log('\n--- Resolving "all" preset ---');
+  const allExecutionGraph = resolveServiceExecutionGraph(config, 'all');
+  console.log('✅ "all" preset resolved successfully.');
+  console.log('Dependencies:');
+  allExecutionGraph.dependencies.forEach((node) => {
+    console.log(`  - ${node.name} (mode: ${node.mode})`);
+  });
+  console.log('Services:');
+  allExecutionGraph.services.forEach((node) => {
+    console.log(`  - ${node.name} (mode: ${node.mode})`);
+  });
+
+  console.log('\n--- Testing non-existent preset ---');
+  try {
+    resolveServiceExecutionGraph(config, 'non-existent');
+  } catch (error) {
+    console.log(`✅ Caught expected error: ${error.message}`);
+  }
+} catch (error) {
+  console.error('❌ An unexpected error occurred during testing:', error);
+} finally {
+  // Clean up the temporary config file
+  if (fs.existsSync(testConfigPath)) {
+    fs.unlinkSync(testConfigPath);
+    console.log(`\nCleaned up temporary config file: ${testConfigPath}`);
+  }
+}