docs(dev-runner): add explanatory comments to basic multi-service dev script

Author: BhaskarKulshrestha

scripts/dev-basic.cjs

@@ -1,74 +1,120 @@
 #!/usr/bin/env node
-// Simple multi-service dev runner (no turborepo / nx)
-// Starts each workspace's dev script concurrently.
-// Basic, no restart on file change; rely on each service's own dev behavior.
-// CommonJS to ensure compatibility regardless of root type/module settings.
+// ---------------------------------------------------------------------------
+// Basic Multi-Service Dev Runner
+// ---------------------------------------------------------------------------
+// Purpose:
+//   Lightweight script to start each service's "dev" script in parallel when
+//   you are NOT using an advanced orchestrator (like Turborepo or Nx).
+//   Intended for the scaffold's "basic" preset.
+//
+// High-Level Flow:
+//   1. Identify the root directory and the conventional services/ folder.
+//   2. Detect which JavaScript package manager to use (npm / pnpm / yarn / bun).
+//   3. Enumerate each subfolder in services/.
+//   4. For every folder containing a package.json with a dev script, spawn it.
+//   5. Stream each child process' output with a readable prefix.
+//
+// Design Constraints:
+//   - Zero external dependencies (Node built‑ins only) to stay portable.
+//   - Does NOT attempt file-change restarts (leave that to each service's own
+//     tooling, e.g. nodemon, ts-node-dev, next dev, etc.).
+//   - Ignores non-Node services (e.g., Go, Python, Java) since they don't have
+//     a package.json dev script; those are expected to run via their own tools.
+//   - CommonJS for maximum compatibility regardless of root "type: module".
+//
+// Extending Tips:
+//   - To include non-Node services, add detection logic (e.g., main.go, pom.xml)
+//     and spawn the appropriate commands.
+//   - To implement auto-restart, consider integrating chokidar to watch files
+//     and restart specific child processes.
+//   - To add coloring per service, map service names to a color palette and
+//     wrap the prefix() output (keep it optional for plain CI logs).
+// ---------------------------------------------------------------------------
 
 const { spawn } = require('node:child_process');
 const fs = require('fs');
 const path = require('path');
 
+// Root of the repo (assumes script is run from project root via npm script)
 const root = process.cwd();
-// Updated to new structure: services directory replaces apps
+
+// Convention: all services generated by the scaffold live under services/
+// (Older versions used apps/; that was replaced to avoid confusion with Next.js)
 const servicesDir = path.join(root, 'services');
 if (!fs.existsSync(servicesDir)) {
   console.error('No services directory found.');
   process.exit(1);
 }
 
+// Snapshot the list of entries inside services/ (folders assumed to be services)
 const services = fs.readdirSync(servicesDir);
 
 // Determine the root package manager heuristically
 function detectPM() {
+  // Heuristic: look for lock files in order of preference.
+  // If multiple exist (rare / misconfigured), first match wins.
   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';
+  // Fallback to npm when no known lockfile is detected.
   return 'npm';
 }
 const pm = detectPM();
 
 if (services.length === 0) {
+  // Nothing inside services/; we exit early (not an error condition).
   console.log('No Node-based services with package.json to run.');
   process.exit(0);
 }
 
 console.log(`Using package manager: ${pm}`);
 console.log(`Discovered services: ${services.join(', ')}`);
 
+// Keep references to spawned child processes so we can forward signals.
 const procs = [];
 
 function prefix(name, data) {
+  // Prepend the service name to each line of output for readability.
+  // NOTE: data may contain multiple lines; we leave as‑is to avoid splitting.
   process.stdout.write(`[${name}] ${data}`);
 }
 
 services.forEach(svc => {
   const svcPath = path.join(servicesDir, svc);
   const pkgPath = path.join(svcPath, 'package.json');
   if (!fs.existsSync(pkgPath)) {
+    // Non-Node service (e.g., python, go, java). Skip silently with context.
     console.log(`Skipping ${svc} (no package.json; likely non-Node service)`);
     return;
   }
   try {
     const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
     if (!pkg.scripts || !pkg.scripts.dev) {
+      // Node project present but without a dev script; user may add later.
       console.log(`Skipping ${svc} (no dev script)`);
       return;
     }
-    const cmd = pm === 'bun' ? 'bun' : pm;
+    // Determine spawn command + arguments.
+    // For yarn classic, `yarn dev` would also work, but keeping uniform form.
+    const cmd = pm === 'bun' ? 'bun' : pm; // direct binary (npm, pnpm, yarn, bun)
     const args = pm === 'yarn' ? ['run', 'dev'] : pm === 'bun' ? ['run', 'dev'] : ['run', 'dev'];
+    // Could special-case: if (pm==='yarn') args=['dev'] but current pattern is fine.
     const child = spawn(cmd, args, { cwd: svcPath, shell: true, env: process.env });
     procs.push(child);
     child.stdout.on('data', d => prefix(svc, d));
     child.stderr.on('data', d => prefix(svc, d));
     child.on('exit', code => {
+      // Log exit so the developer sees early failures.
       console.log(`[${svc}] exited with code ${code}`);
     });
   } catch (e) {
+    // JSON parse errors or spawn failures bubble here.
     console.log(`Failed to start ${svc}:`, e.message);
   }
 });
 
 process.on('SIGINT', () => {
+  // Graceful shutdown: forward Ctrl+C to each child, then exit.
   procs.forEach(p => p.kill('SIGINT'));
   process.exit(0);
 });