feat: add 'dev' command to run services locally or via Docker Compose with health checks

Signed-off-by: kaifcoder <kaifmohd2014@gmail.com>

Author: kaifcoder

README.md

@@ -31,13 +31,24 @@ Add a plugin scaffold:
 create-polyglot add plugin postgres
 ```
 
+Run all services in dev mode (Node & frontend locally; others manual unless using docker):
+```bash
+create-polyglot dev
+```
+
+Run everything via Docker Compose:
+```bash
+create-polyglot dev --docker
+```
+
 ## Commands
 
 | Command | Description |
 |---------|-------------|
 | `create-polyglot init <name>` | Scaffold a new workspace (root invocation without `init` is deprecated). |
 | `create-polyglot add service <name>` | Add a service after init (`--type`, `--port`, `--yes`). |
 | `create-polyglot add plugin <name>` | Create plugin skeleton under `plugins/<name>`. |
+| `create-polyglot dev [--docker]` | Run Node & frontend services locally or all via compose. |
 
 ## Init Options
 
@@ -92,6 +103,11 @@ Non-Node services start manually or via compose:
 cd services/python && uvicorn app.main:app --reload
 ```
 
+### polyglot dev Command
+`create-polyglot dev` reads `polyglot.json`, launches Node & frontend services that expose a `dev` script, assigns each a colorized log prefix, and probes `http://localhost:<port>/health` until ready (15s timeout). Pass `--docker` to instead delegate to `docker compose up --build` for all services.
+
+If a service lacks a `dev` script it is skipped with no error. Non-Node services (python/go/java) are not auto-started yet unless you choose `--docker`.
+
 ### Docker & Compose
 For each selected service a Dockerfile is generated. A `compose.yaml` includes:
 - Service definitions with build contexts

bin/index.js

@@ -2,6 +2,7 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
 import { scaffoldMonorepo, addService, scaffoldPlugin } from './lib/scaffold.js';
+import { runDev } from './lib/dev.js';
 
 const program = new Command();
 
@@ -94,5 +95,13 @@ program
     }
   });
 
+program
+  .command('dev')
+  .description('Run services locally (Node & frontend) or use --docker for compose')
+  .option('--docker', 'Use docker compose up --build to start all services')
+  .action(async (opts) => {
+    await runDev({ docker: !!opts.docker });
+  });
+
 program.parse();
 

bin/lib/dev.js

@@ -0,0 +1,98 @@
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { spawn } from 'node:child_process';
+import http from 'http';
+
+function colorFor(name) {
+  const colors = [chalk.cyan, chalk.magenta, chalk.green, chalk.blue, chalk.yellow, chalk.redBright];
+  let sum = 0; for (let i=0;i<name.length;i++) sum += name.charCodeAt(i);
+  return colors[sum % colors.length];
+}
+
+async function waitForHealth(url, timeoutMs=15000, interval=500) {
+  const start = Date.now();
+  return new Promise(resolve => {
+    const check = () => {
+      const req = http.get(url, res => {
+        if (res.statusCode && res.statusCode < 500) {
+          resolve(true); req.destroy(); return;
+        }
+        res.resume();
+        if (Date.now() - start > timeoutMs) return resolve(false);
+        setTimeout(check, interval);
+      });
+      req.on('error', () => {
+        if (Date.now() - start > timeoutMs) return resolve(false);
+        setTimeout(check, interval);
+      });
+    };
+    check();
+  });
+}
+
+export async function runDev({ docker=false } = {}) {
+  const cwd = process.cwd();
+  const configPath = path.join(cwd, 'polyglot.json');
+  if (!fs.existsSync(configPath)) {
+    console.error(chalk.red('polyglot.json not found. Run inside a generated workspace.'));
+    process.exit(1);
+  }
+  const cfg = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  const servicesDir = path.join(cwd, 'services');
+  if (!fs.existsSync(servicesDir)) {
+    console.error(chalk.red('services/ directory not found.'));
+    process.exit(1);
+  }
+  if (docker) {
+    console.log(chalk.cyan('🛳  Starting via docker compose...'));
+    const compose = spawn('docker', ['compose', 'up', '--build'], { stdio: 'inherit' });
+    compose.on('exit', code => process.exit(code || 0));
+    return;
+  }
+  console.log(chalk.cyan('🚀 Starting services locally (best effort)...'));
+  const procs = [];
+  const healthPromises = [];
+  for (const svc of cfg.services) {
+    const svcPath = path.join(cwd, svc.path);
+    if (!fs.existsSync(svcPath)) continue;
+    // Only auto-run node & frontend services (others require language runtime dev tasks)
+    if (!['node','frontend'].includes(svc.type)) continue;
+    const pkgPath = path.join(svcPath, 'package.json');
+    if (!fs.existsSync(pkgPath)) continue;
+    let pkg;
+    try { pkg = JSON.parse(fs.readFileSync(pkgPath,'utf-8')); } catch { continue; }
+    if (!pkg.scripts || !pkg.scripts.dev) continue;
+    const color = colorFor(svc.name);
+    const pm = detectPM(cwd);
+    const cmd = pm === 'yarn' ? 'yarn' : pm === 'pnpm' ? 'pnpm' : pm === 'bun' ? 'bun' : 'npm';
+    const args = pm === 'yarn' ? ['run','dev'] : ['run','dev'];
+    const child = spawn(cmd, args, { cwd: svcPath, env: { ...process.env, PORT: String(svc.port) }, shell: true });
+    procs.push(child);
+    child.stdout.on('data', d => process.stdout.write(color(`[${svc.name}] `) + d.toString()));
+    child.stderr.on('data', d => process.stderr.write(color(`[${svc.name}] `) + d.toString()));
+    child.on('exit', code => {
+      process.stdout.write(color(`[${svc.name}] exited with code ${code}\n`));
+    });
+    // health check
+    const healthUrl = `http://localhost:${svc.port}/health`;
+    const hp = waitForHealth(healthUrl).then(ok => {
+      const msg = ok ? chalk.green(`✔ health OK ${svc.name} ${healthUrl}`) : chalk.yellow(`⚠ health timeout ${svc.name} ${healthUrl}`);
+      console.log(msg);
+    });
+    healthPromises.push(hp);
+  }
+  if (!procs.length) {
+    console.log(chalk.yellow('No auto-runnable Node/Frontend services found. Use --docker to start all via compose.'));
+  }
+  await Promise.all(healthPromises);
+  console.log(chalk.blue('Watching services. Press Ctrl+C to exit.'));
+  process.on('SIGINT', () => { procs.forEach(p => p.kill('SIGINT')); process.exit(0); });
+}
+
+function detectPM(root) {
+  if (fs.existsSync(path.join(root,'pnpm-lock.yaml'))) return 'pnpm';
+  if (fs.existsSync(path.join(root,'yarn.lock'))) return 'yarn';
+  if (fs.existsSync(path.join(root,'bun.lockb'))) return 'bun';
+  return 'npm';
+}

docs/cli/index.md

@@ -15,3 +15,15 @@ Add a plugin:
 ```bash
 create-polyglot add plugin kafka
 ```
+
+Run dev (local processes):
+```bash
+create-polyglot dev
+```
+
+Run dev via Docker Compose:
+```bash
+create-polyglot dev --docker
+```
+
+Health endpoints are polled at `/health` on each service port with a 15s timeout.

tests/dev-command.test.js

@@ -0,0 +1,32 @@
+import { execa } from 'execa';
+import { describe, it, expect, afterAll } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+describe('polyglot dev command (non-docker)', () => {
+  const tmpParent = fs.mkdtempSync(path.join(os.tmpdir(), 'polyglot-dev-'));
+  const tmpDir = path.join(tmpParent, 'workspace');
+  fs.mkdirSync(tmpDir);
+  const projName = 'dev-proj';
+
+  afterAll(() => { try { fs.rmSync(tmpParent, { recursive: true, force: true }); } catch {} });
+
+  it('starts node service and performs health check', async () => {
+    const repoRoot = process.cwd();
+    const cliPath = path.join(repoRoot, 'bin/index.js');
+    await execa('node', [cliPath, 'init', projName, '--services', 'node', '--no-install', '--yes'], { cwd: tmpDir, env: { ...process.env, CI: 'true' } });
+    const projectPath = path.join(tmpDir, projName);
+    // Write a minimal dev script to the node service if missing
+    const nodePkgPath = path.join(projectPath, 'services/node/package.json');
+    const nodePkg = JSON.parse(fs.readFileSync(nodePkgPath,'utf-8'));
+    nodePkg.scripts = nodePkg.scripts || {}; nodePkg.scripts.dev = 'node src/index.js';
+    fs.writeFileSync(nodePkgPath, JSON.stringify(nodePkg, null, 2));
+    const proc = execa('node', [cliPath, 'dev'], { cwd: projectPath, env: { ...process.env, CI: 'true' } });
+    // wait briefly then kill
+    await new Promise(r => setTimeout(r, 3500));
+    proc.kill('SIGINT');
+    await proc.catch(()=>{}); // ignore exit errors due to SIGINT
+    expect(fs.existsSync(path.join(projectPath,'polyglot.json'))).toBe(true);
+  }, 20000);
+});