go-dev 0.1.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Giuliano Collacchioni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# `go-dev`
+
+A simple and robust orchestrator for streamlining local development environments in monorepos.
+
+**`npx go-dev <preset>` – Go develop!**
+
+## 🚀 Introduction
+
+In complex monorepos, starting your development environment can be a chore. You might need to spin up Docker containers, run multiple Node.js (or other language) development servers, handle pre-builds, and manage inter-service dependencies. `go-dev` simplifies this by allowing you to define your entire local development stack in a single YAML configuration file.
+
+`go-dev` acts as a central command to bring up your `api`, `frontend`, `database`, and any other microservices, ensuring they start in the correct order, with the right modes, and provide clear, prefixed logs.
+
+## ✨ Features
+
+*   **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.
+    *   **`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.
+*   **Automatic Dependency Resolution:** `go-dev` builds an intelligent execution graph, starting services in the correct topological order.
+*   **Centralized Logging:** Prefixes logs from each service, making it easy to follow activity from multiple concurrent processes.
+*   **Robust Cleanup:** Handles graceful shutdown of all started processes and Docker services on exit (e.g., via `Ctrl+C`).
+
+## 🤔 Why `go-dev`?
+
+While tools like `concurrently` manage parallel processes and `docker compose` handles containers, `go-dev` fills a crucial gap by:
+
+*   **Integrating `cmd` and `docker` services seamlessly:** It bridges the world of host-based processes and containerized applications under one roof.
+*   **Providing intelligent mode-aware dependency resolution:** It understands that "frontend" might mean a different set of commands (and dependencies) when you're actively developing the frontend vs. when it's just a dependency for API development.
+*   **Offering a single, declarative interface for your entire dev stack:** No more remembering multiple `npm` scripts or `docker compose` commands.
+
+## 📦 Installation
+
+`go-dev` is distributed via npm and designed to be used with `npx`.
+
+```bash
+# Install it as a devDependency in your monorepo's root
+npm install --save-dev go-dev
+# or
+yarn add --dev go-dev
+```
+
+## 🚀 Usage
+
+Once installed, simply run `go-dev` with the name of the preset you want to start:
+
+```bash
+npx go-dev <preset_name> [config_path]
+```
+
+*   `<preset_name>`: The name of the preset defined in your `go-dev.yml` (e.g., `api`, `frontend`, `all`).
+*   `[config_path]`: (Optional) Path to your `go-dev.yml` file. Defaults to looking for `go-dev.yml`, `.go-dev.yml`, `go-dev.yaml`, or `.go-dev.yaml` in the current directory.
+
+**Example:**
+
+```bash
+npx go-dev api       # Start the environment for API development
+npx go-dev frontend  # Start the environment for Frontend development
+npx go-dev all       # Start the full development environment
+```
+
+Press `Ctrl+C` at any time to gracefully shut down all running services.
+
+## ⚙️ Configuration (`go-dev.yml`)
+
+Create a configuration file in your project's root.
+
+By default, `go-dev` automatically detects its configuration file. It looks for files named `go-dev` (or `.go-dev` for a hidden file), optionally including `.config` before the `.yml` or `.yaml` extension. It will search for these files in the directory where you run `npx go-dev`.
+
+Common examples include: `go-dev.yml`, `.go-dev.yml`, and `go-dev.config.yaml`.
+
+```yaml
+# go-dev.yml
+
+# Define your individual services here
+services:
+  # Example: A Docker-based PostgreSQL database
+  postgres:
+    type: docker         # This service runs inside Docker
+    service: postgres    # Name of the service in your docker-compose.yml
+    composeFile: infrastructure/docker-compose.yml # Path to the docker-compose file
+    healthCheck: true    # Enable health checks for this Docker service
+
+  # Example: Your API service, which can run in 'dev' (cmd) or 'docker' mode
+  api:
+    type: hybrid         # This service has multiple modes
+    defaultMode: dev     # Default mode if not specified by a preset or dependency
+    # Note: The name of the modes is totally arbirtary
+    modes:
+      # API in active development mode (runs directly on host)
+      dev:
+        type: cmd             # This mode runs a command-line process
+        commands:
+          start:
+            command: [npx, rollup, -c, -w] # The primary command for development
+            directory: ./api      # Directory to run the command from
+        dependencies:         # What this mode depends on
+          - postgres          # API dev needs PostgreSQL (will use postgres's default docker mode)
+          - { service: frontend, mode: serve } # API dev needs frontend running in its 'serve' mode
+
+      # API running as a Docker container (e.g., for frontend-only dev)
+      docker:
+        type: docker
+        service: api
+        composeFile: infrastructure/docker-compose.yml
+        healthCheck: true
+        dependencies:
+          - postgres # Docker API also needs PostgreSQL
+
+  # Example: Your Frontend service, which can run in 'dev' (cmd) or 'serve' (cmd) mode
+  frontend:
+    type: hybrid
+    defaultMode: dev
+    modes:
+      # Frontend in active development (watch mode)
+      dev:
+        type: cmd
+        commands:
+          start:
+            command: [npx, rollup, -c, -w]
+            directory: ./frontend
+        dependencies:
+          # Frontend dev needs API (will use api's default docker mode for this preset)
+          # Note: No direct circular dependency between dev modes.
+          # Dev modes often assume peers will eventually be ready.
+          - { service: api, mode: docker } 
+
+      # Frontend serving its built assets (e.g., when API depends on it)
+      serve:
+        type: cmd
+        preCommands: # Commands to run and await completion BEFORE the main 'start' command
+          - [npm, --prefix, frontend, run, build] # Build frontend assets first
+        commands:
+          start:
+            command: [node, ./localserver.mjs] # Then start the local server
+            directory: ./frontend
+        dependencies:
+          - api # Frontend serve needs API (will use api's default dev mode for this preset)
+
+
+# Define different development presets (combinations of services and their modes)
+presets:
+  # Preset: "api" development focus
+  # Starts API in dev mode, pulling in its dependencies (postgres, frontend:serve)
+  api:
+    services: [api] # Only explicitly list top-level services you want to run
+    modes:
+      # no explicit modes needed here, as defaultMode and dependency requests handle it
+      # api: dev # (already default)
+      # frontend: serve # (requested by api:dev)
+      # postgres: dev # (pulled by dependencies)
+
+  # Preset: "frontend" development focus
+  # Starts Frontend in dev mode, pulling in its dependencies (api:docker, postgres)
+  frontend:
+    services: [frontend]
+    modes:
+      # frontend: dev # (already default)
+      # api: docker # (requested by frontend:dev)
+      # postgres: dev # (pulled by dependencies)
+
+  # Preset: "all" development (both API and Frontend in dev mode concurrently)
+  all:
+    services: [api, frontend] # Explicitly list both as top-level focus
+    modes:
+      # api: dev # (already default)
+      # frontend: dev # (already default)
+      # No need to specify modes if they match the defaultMode
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Feel free to open issues or submit pull requests.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "go-dev",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "main": "src/index.js",
   "bin": {
-    "dev-orchestrator": "bin/dev-orchestrator"
+    "go-dev": "bin/go-dev"
   },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"

package/src/config.js

@@ -12,12 +12,13 @@ const dependencyEntrySchema = Joi.alternatives().try(
 );
 
 const commandSchema = Joi.array().items(Joi.string().min(1)).min(1);
+const commandObjectSchema = Joi.object({
+    command: commandSchema,
+    directory: Joi.string().min(1).optional(),
+})
 const commandConfigSchema = Joi.alternatives().try(
     commandSchema,
-    Joi.object({
-        command: commandSchema,
-        directory: Joi.string().min(1),
-    })
+    commandObjectSchema
 );
 
 const cmdServiceConfigSchema = Joi.object({
@@ -25,7 +26,10 @@ const cmdServiceConfigSchema = Joi.object({
   preCommands: Joi.array().items(commandConfigSchema).default([]),
   commands: Joi.object().pattern(
     Joi.string(),
-    commandConfigSchema
+    Joi.alternatives().try(
+      commandConfigSchema,
+      Joi.array().items(commandObjectSchema).min(1)
+    )
   ).min(1).required(),
   defaultCommand: Joi.string().default('start'),
   directory: Joi.string(),
@@ -68,22 +72,26 @@ const configSchema = Joi.object({
   ).default({})
 });
 
-function findConfigFile() {
-  const possibleNames = [
-    'dev-orchestrator',
-    '.dev-orchestrator'
-  ].flatMap(baseName => {
-    return [
-        baseName,
-        `${baseName}.config`
-    ];
-  }).flatMap(baseName => {
-    return [
-        `${baseName}.yml`,
-        `${baseName}.yaml`
-    ];
-  });
+const possibleNames = [
+  'go-dev'
+].flatMap(baseName => {
+  return [
+    baseName,
+    `.${baseName}`
+  ];
+}).flatMap(baseName => {
+  return [
+      baseName,
+      `${baseName}.config`
+  ];
+}).flatMap(baseName => {
+  return [
+      `${baseName}.yml`,
+      `${baseName}.yaml`
+  ];
+});
 
+function findConfigFile() {
   for (const name of possibleNames) {
     if (fs.existsSync(name)) {
       return name;

package/src/process-manager.js

@@ -1,5 +1,6 @@
-// src/process-manager.js
 const { spawn, spawnSync } = require('child_process');
+const { appendFileSync } = require('fs');
+
 
 class ProcessManager {
   constructor() {
@@ -120,7 +121,9 @@ class ProcessManager {
       if (!prefixedData.endsWith('\n')) {
           prefixedData = prefixedData + '\n';
       }
+      prefixedData = prefixedData.replace(/\x1b\[(?:2J|3J|H)/gi, '');
       process.stdout.write(prefixedData);
+      appendFileSync('./banana.log', prefixedData);
     });
     proc.stderr.on('data', (data) => {
       let prefixedData = data.toString().split('\n').map(line => `${prefix} ${line}`).join('\n');
@@ -130,7 +133,9 @@ class ProcessManager {
       if (!prefixedData.endsWith('\n')) {
           prefixedData = prefixedData + '\n';
       }
+      prefixedData = prefixedData.replace(/\x1b\[(?:2J|H)/gi, '');
       process.stderr.write(prefixedData);
+      appendFileSync('./banana.log', prefixedData);
     });
 
     this.managedProcesses.add(proc);
@@ -143,6 +148,10 @@ class ProcessManager {
     });
 
     proc.on('exit', (code, signal) => {
+      if (!this.managedProcesses.has(proc)) {
+        return;
+      }
+
       this.managedProcesses.delete(proc);
       if (this.cleanupInProgress) {
         console.log(
@@ -171,6 +180,47 @@ class ProcessManager {
     return proc;
   }
 
+  killProcess(process) {
+    this.managedProcesses.delete(process);
+
+    return new Promise((resolve, reject) => {
+      let exited = false;
+      const onExit = () => {
+        exited = true;
+        resolve();
+      };
+      process.on('exit', onExit);
+
+      setTimeout(() => {
+        if (exited) {
+          return;
+        }
+
+        console.error(`[ProcessManager] Timeout reached for process interruption ${process.pid}`);
+        try {
+          process.kill('SIGKILL');
+        } catch (e) {
+          console.error(`[ProcessManager] Error force killing process ${process.pid}: ${e.message}`);
+          reject(e);
+        }
+      }, 500);
+
+      try {
+        process.kill('SIGTERM');
+        return;
+      } catch (e) {
+        console.error(`[ProcessManager] Error signaling process ${process.pid}: ${e.message}`);
+      }
+
+      try {
+        process.kill('SIGKILL');
+      } catch (e) {
+        console.error(`[ProcessManager] Error force killing process ${process.pid}: ${e.message}`);
+        reject(e);
+      }
+    });
+  }
+
   /**
    * Kills all currently managed child processes.
    */
@@ -179,11 +229,22 @@ class ProcessManager {
       console.log('[ProcessManager] Cleanup of managed processes already in progress, skipping.');
       return;
     }
+    for (let index = this.managedProcesses.length - 1; index >= 0; index--) {
+      const process = this.managedProcesses[index];
+      if (process.killed) {
+        this.managedProcesses.splice(index, 1);
+      }
+    }
+
     this.cleanupInProgress = true;
 
     console.log('\n[ProcessManager] Initiating cleanup of managed processes...');
 
     for (const proc of [...this.managedProcesses]) {
+      if (proc.killed) {
+        continue;
+      }
+
       console.log(`[ProcessManager] Killing managed process PID: ${proc.pid}`);
       try {
         proc.kill('SIGTERM');

package/src/services/cmd.js

@@ -4,7 +4,7 @@ class CmdService extends BaseService {
   constructor(name, mode, config) {
     super(name, mode, config);
     this.prefix = `${name}:${mode}:`;
-    this.process = null;
+    this.processes = [];
   }
 
   async start() {
@@ -17,7 +17,7 @@ class CmdService extends BaseService {
       for (const command of preCommands) {
         const { cmdArgs, directory } = (Array.isArray(command) ?
           { cmdArgs: command } :
-          { cmdArgs: command.command, cmdArgs: command.directory }
+          { cmdArgs: command.command, directory: command.directory }
         );
         try {
           CmdService._processManager.runSync(cmdArgs[0], cmdArgs.slice(1), {
@@ -25,6 +25,7 @@ class CmdService extends BaseService {
             stdio: 'inherit',
           });
         } catch (error) {
+          console.log({ cmdArgs });
           throw new Error(
             `[${this.name}:${this.mode}] Pre-command failed: ${cmdArgs.join(
               ' ',
@@ -42,39 +43,54 @@ class CmdService extends BaseService {
       );
     }
 
-    const { cmdArgs, directory } = (Array.isArray(mainCommand) ?
-      { cmdArgs: mainCommand } :
-      { cmdArgs: mainCommand.command, directory: mainCommand.directory }
+    const { cmdArgs, directory } = (Array.isArray(mainCommand) && typeof mainCommand[0] === 'string' ?
+      { cmdArgs: [mainCommand], directory: [undefined] } :
+      (Array.isArray(mainCommand) ?
+        {
+          cmdArgs: mainCommand.map(({ command }) => command),
+          directory: mainCommand.map(({ directory }) => directory),
+        } :
+        { cmdArgs: [mainCommand.command], directory: [mainCommand.directory] }
+      )
     );
 
-    this.process = CmdService._processManager.startManagedProcess(
-      cmdArgs[0],
-      cmdArgs.slice(1),
-      { cwd: directory },
-      this.prefix,
-      true,
-    );
+    const useProcessIndex = cmdArgs.length > 1;
+    for (let index = 0; index < cmdArgs.length; index++) {
+      const command = cmdArgs[index];
+      const cwd = directory[index];
 
-    if (!this.process) {
-      throw new Error(
-        `[${this.name}:${this.mode}] Failed to spawn main process: ${cmdArgs.join(' ')}`,
+      const process = CmdService._processManager.startManagedProcess(
+        command[0],
+        command.slice(1),
+        { cwd },
+        (useProcessIndex ?
+          `${this.prefix}${index}:` :
+          this.prefix
+        ),
+        true,
+      );
+  
+      if (!process) {
+        throw new Error(
+          `[${this.name}:${this.mode}] Failed to spawn process: ${command.join(' ')}`,
+        );
+      }
+
+      this.processes.push(process);
+      console.log(
+        `[${this.name}:${this.mode}] Process started (PID: ${process.pid}).`,
       );
     }
-    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;
-    }
+    const promises = this.processes.map(process => {
+      console.log(`[${this.name}:${this.mode}] Stopping process (PID: ${process.pid}).`);
+      return CmdService._processManager.killProcess(process);
+    });
+    this.processes.splice(0, this.processes.length);
+
+    await Promise.all(promises);
   }
 }
 

package/src/services/docker.js

@@ -80,7 +80,6 @@ class DockerService extends BaseService {
   }
 
   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;
   }
@@ -94,7 +93,6 @@ class DockerService extends BaseService {
       return this.containerName;
     }
     try {
-      // Access processManager statically
       const name = DockerService._processManager.runSync(
         'docker',
         ['compose', '-f', this.dockerComposeFile, 'ps', '-a', '-q', this.dockerServiceName],
@@ -115,7 +113,6 @@ class DockerService extends BaseService {
       return null;
     }
     try {
-      // Access processManager statically
       return DockerService._processManager.runSync(
         'docker',
         ['container', 'inspect', '-f', '{{.State.Status}}', containerName],
@@ -132,15 +129,13 @@ class DockerService extends BaseService {
       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}'`);
+    console.log(`[${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],
@@ -148,7 +143,7 @@ class DockerService extends BaseService {
         );
 
         if (healthStatus === 'healthy' || healthStatus === 'none') {
-          process.stdout.write(" Healthy!\n");
+          console.log(`[${this.name}:${this.mode}] Container '${containerName}' healty!\n`);
           return true;
         }
 
@@ -156,15 +151,12 @@ class DockerService extends BaseService {
           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.`);
   }
 }