Merge pull request #32 from BhaskarKulshrestha/docs/dev-basic-comments

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

Author: BhaskarKulshrestha

scripts/dev-basic.cjs

@@ -1,37 +1,82 @@
+#!/usr/bin/env node
+// ---------------------------------------------------------------------------
+// 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();
+
+// 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.warn('⚠️  services/ directory not found. No local services will be started.');
   process.exit(0);
 }
 
+// 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) {
-  console.warn('⚠️  No services found inside services/.');
+  // 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}`);
 }
 
@@ -40,45 +85,39 @@ services.forEach((svc) => {
   const pkgPath = path.join(svcPath, 'package.json');
 
   if (!fs.existsSync(pkgPath)) {
-    console.warn(`⚠️  Skipping ${svc} (no package.json; likely non-Node service)`);
+    // 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'));
-    const script = pkg.scripts?.dev || pkg.scripts?.start;
-
-    if (!script) {
-      console.warn(`⚠️  Skipping ${svc} (no "dev" or "start" script in package.json)`);
+    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;
-    const args =
-      pm === 'yarn'
-        ? ['run', script === pkg.scripts.dev ? 'dev' : 'start']
-        : pm === 'bun'
-        ? ['run', script === pkg.scripts.dev ? 'dev' : 'start']
-        : ['run', script === pkg.scripts.dev ? 'dev' : 'start'];
-
-    const child = spawn(cmd, args, {
-      cwd: svcPath,
-      shell: true,
-      env: process.env,
-    });
-
+    // 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) => {
+    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) {
-    console.error(`❌ Failed to start ${svc}:`, e.message);
+    // JSON parse errors or spawn failures bubble here.
+    console.log(`Failed to start ${svc}:`, e.message);
   }
 });
 
 process.on('SIGINT', () => {
-  procs.forEach((p) => p.kill('SIGINT'));
+  // Graceful shutdown: forward Ctrl+C to each child, then exit.
+  procs.forEach(p => p.kill('SIGINT'));
   process.exit(0);
 });