ccgauge 1.1.0 → 1.1.2

package/bin/cli.mjs

@@ -13,11 +13,6 @@ const __dirname = dirname(__filename);
 const packageRoot = resolve(__dirname, '..');
 const pkg = require(join(packageRoot, 'package.json'));
 
-// commander is needed before we even parse argv to know which subcommand
-// the user asked for, so we load it eagerly. `get-port` (only used by
-// start / restart) and `open` (only by start / open) are deferred so
-// short-lived commands like `mcp`, `status`, `logs`, `report`, `--version`
-// don't pay their import cost (~20-30 ms cold-start each).
 const { Command } = await import('commander');
 async function loadGetPort() {
   const mod = await import('get-port');
@@ -38,13 +33,7 @@ const COMMAND_NAMES = new Set([
   'start', 'stop', 'restart', 'status', 'open', 'logs', 'mcp',
   'report', 'doctor',
 ]);
-// `start` subcommand's own option set (incl. short aliases). The value
-// indicates whether the option consumes the following positional as a
-// value. Used by `normalizeArgv` to decide whether `ccgauge -p 3000`
-// should be treated as the bare-`start` shortcut. Anything outside this
-// set (e.g. `-r` / `--range` from `report`) makes us bail out and let
-// commander surface its own "unknown option" against the root program
-// — which lists subcommands. Keep in sync with `addStartOptions`.
+
 const START_OPTIONS = new Map([
   ['-p', true], ['--port', true],
   ['-H', true], ['--host', true],
@@ -65,18 +54,6 @@ function buildUrl(host, port) {
   return `http://${browserHost(host)}:${port}`;
 }
 
-/** Decide whether to emit ANSI colour. Precedence (high → low):
- *  1. `forceOff` (commander's `--no-color`) → off.
- *  2. `NO_COLOR` env var (NO_COLOR.org convention) → off.
- *  3. `FORCE_COLOR` env var → on (covers tee / pipes / CI).
- *  4. stdout TTY check → on.
- *  5. else → off.
- *
- *  We take `forceOff` as an explicit boolean rather than reading
- *  `opts.color` directly because commander gives `.option('--no-color')`
- *  a default of `true` — there's no in-band way to distinguish "user
- *  didn't say anything" from "user passed --color". Callers translate
- *  their own option to `forceOff: opts.color === false`. */
 function shouldUseColor({ forceOff = false } = {}) {
   if (forceOff) return false;
   if (process.env.NO_COLOR) return false;
@@ -107,26 +84,16 @@ function addStartOptions(cmd) {
     .option('--log <path>', 'background log file', DEFAULT_LOG_FILE);
 }
 
-// Browser-open policy:
-//   - foreground: open by default; --no-open disables.
-//   - background: never auto-open. Use `ccgauge open` after start.
 function shouldOpenBrowser(opts) {
   if (opts.background) return false;
   return opts.open !== false;
 }
 
-// For `restart`: when the user did not explicitly pass an option, fall back
-// to whatever the previous background run was using.
 async function inheritFromState(opts, cmd) {
   const prev = await readState();
   if (!prev) return { ...opts };
   const isDefault = (key) => cmd.getOptionValueSource(key) === 'default';
-  // `--dir` has no default value (see addStartOptions), so commander
-  // reports its source as `undefined` when unset and `'cli'` when the
-  // user typed it — including `--dir ""` which means "clear override".
-  // Using truthy-on-opts.dir would conflate "unset" and "explicit empty"
-  // and re-inherit the old dataDir, defeating the whole point of
-  // letting users switch back to the default Claude path on restart.
+
   const isProvided = (key) => cmd.getOptionValueSource(key) === 'cli';
   const merged = { ...opts };
   if (isDefault('port') && prev.port) merged.port = String(prev.port);
@@ -229,40 +196,27 @@ addReportOptions(program.command('report').description('print a formatted usage
 
 await program.parseAsync(normalizeArgv(process.argv));
 
-/** Implements `ccgauge` (no subcommand) as a shortcut for `ccgauge start`,
- *  but only when every flag we see belongs to `start`. If the user typed
- *  something that looks like a `report` / `mcp` flag without the
- *  subcommand (e.g. `ccgauge -r 7d`), we leave argv alone so commander
- *  surfaces "unknown option" against the root program — which lists the
- *  available subcommands. Without this discrimination commander would
- *  complain about `start: unknown option -r`, which is the wrong hint. */
 function normalizeArgv(argv) {
   const args = argv.slice(2);
-  // `ccgauge` (no args) is documented as a shortcut for `ccgauge start` —
-  // we deliberately do NOT early-return on `args.length === 0`. The flag
-  // walk below is a no-op for an empty argv, so we fall through to the
-  // final `[argv[0], argv[1], 'start']` injection.
+
   if (args.includes('--help') || args.includes('-h') || args.includes('-V') || args.includes('--version')) {
     return argv;
   }
-  // First token is a known subcommand → caller knows what they're doing.
+
   if (args.length > 0 && COMMAND_NAMES.has(args[0])) return argv;
-  // Walk flags; bail if we see anything `start` doesn't accept.
+
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
     if (arg === '--') break;
     if (!arg.startsWith('-')) {
-      // Stray positional with no subcommand prefix → let commander error
-      // out at the root rather than after silently picking `start`.
+
       return argv;
     }
-    // Support `--port=3737` style: only the part before `=` is the flag.
+
     const eqIdx = arg.indexOf('=');
     const flag = eqIdx >= 0 ? arg.slice(0, eqIdx) : arg;
     if (!START_OPTIONS.has(flag)) return argv;
-    // If the option takes a value and the user didn't inline it with `=`,
-    // the next token is the value — skip it so we don't re-check it as a
-    // flag.
+
     if (START_OPTIONS.get(flag) === true && eqIdx < 0) i += 1;
   }
   return [argv[0], argv[1], 'start', ...args];
@@ -281,13 +235,7 @@ async function start(opts) {
 async function startForeground(standaloneEntry, opts) {
   const port = await resolvePort(opts);
   const env = makeServerEnv(opts, port);
-  // `spawn` (not `fork`) because Next's standalone server is a plain
-  // node script — it doesn't use the IPC channel. `fork` would open one
-  // anyway, and since Next never calls `process.disconnect()`, the
-  // parent could never exit cleanly without `process.exit()` racing the
-  // child's shutdown. `spawn` matches the background path and lets us
-  // hand the child our stdio directly. `--quiet` muffles both streams
-  // (Next's warnings go to stderr, so muting only stdout misses them).
+
   const stdio = opts.quiet
     ? ['ignore', 'ignore', 'ignore']
     : 'inherit';
@@ -309,15 +257,10 @@ async function startForeground(standaloneEntry, opts) {
       process.exit(1);
     });
 
-  // Forward our signals to the child, then wait for it to exit so its
-  // teardown is observable rather than racing `process.exit()`. The
-  // child propagates the exit code back via the `exit` event below.
   function forward(signal) {
     return () => {
       if (!child.killed) child.kill(signal);
-      // Don't process.exit() here; let `child.on('exit')` decide. If the
-      // child ignores the signal for some reason, a second Ctrl+C will
-      // re-enter and the OS eventually escalates.
+
     };
   }
   process.on('SIGINT', forward('SIGINT'));
@@ -327,9 +270,7 @@ async function startForeground(standaloneEntry, opts) {
   });
 
   child.on('exit', (code, signal) => {
-    // Convention: signal-terminated child → 128 + signal number (bash
-    // standard). Plain numeric exit → forward as-is. `code === null`
-    // happens when only `signal` is set.
+
     if (typeof code === 'number') process.exit(code);
     else process.exit(signal ? 128 : 0);
   });
@@ -355,14 +296,13 @@ async function startBackground(standaloneEntry, opts) {
     env,
     detached: true,
     stdio: ['ignore', out, err],
-    // Suppress the fleeting console window that Windows pops up for a
-    // detached background child. No-op on macOS/Linux.
+
     windowsHide: true,
   });
   child.unref();
-  // Once spawn() has dup'd these fds into the child, the parent can release them.
-  try { closeSync(out); } catch { /* ignore */ }
-  try { closeSync(err); } catch { /* ignore */ }
+
+  try { closeSync(out); } catch {  }
+  try { closeSync(err); } catch {  }
 
   const url = buildUrl(opts.host, port);
   try {
@@ -373,10 +313,7 @@ async function startBackground(standaloneEntry, opts) {
       const exited = await waitForProcessExit(child.pid, 2_000);
       if (!exited) safeKill(child.pid, 'SIGKILL');
     }
-    // The actual reason (EADDRINUSE, bad CCGAUGE_CONFIG_DIR, port taken
-    // by a sibling that survived getPort's check, etc.) is in the log
-    // file that the spawned child writes to. Surface the tail so users
-    // don't have to discover `ccgauge logs` themselves.
+
     const tail = await tailLog(logFile, 5);
     const tailNote = tail ? `\nLast log lines (${logFile}):\n${tail}\n` : '';
     throw new Error(`failed to start background service: ${startErr.message}${tailNote}`);
@@ -390,11 +327,7 @@ async function startBackground(standaloneEntry, opts) {
     logFile,
     startedAt: new Date().toISOString(),
     bootId: bootId(),
-    // The Next.js standalone bundle renames the process via
-    // `process.title = 'next-server (vX.Y.Z)'` on boot, so `ps` will
-    // show "next-server" in the command column. Pinning that as the
-    // identity marker means a recycled PID belonging to some other
-    // node process won't pass the identity check in isProcessRunning.
+
     cmdMarker: 'next-server',
     packageRoot,
     dataDir: opts.dir ? String(opts.dir) : null,
@@ -433,15 +366,7 @@ async function status(opts) {
   const payload = state
     ? { running, ...state }
     : { running: false };
-  // Exit-code convention split between the two output modes:
-  // - Plain text → systemd-style 3 when not running, so
-  //   `if ccgauge status; then …` works in shell.
-  // - `--json`   → always 0; the consumer is a script that should read
-  //   `payload.running` from the JSON. Non-zero here would break
-  //   pipelines like `ccgauge status --json | jq` under `set -e`.
-  // Number inlined (no const) because this function sits below the
-  // file's top-level `await program.parseAsync(...)` — a const there
-  // would be in the TDZ when commander invokes the action handler.
+
   if (opts.json) {
     console.log(JSON.stringify(payload, null, 2));
     return;
@@ -485,16 +410,6 @@ async function logs(opts) {
   await followLog(logFile, content.length);
 }
 
-/** Shared "build artifact missing" template. Used by start / report /
- *  mcp so all three give the same diagnostic shape and so future
- *  artifacts only need a one-line registration here. Three install
- *  sources mean three different remediation hints:
- *
- *  - `npm`: the tarball should already contain this — reinstall is the
- *    move. We also print `node -v` / `ccgauge -v` so issue reports
- *    don't lose those.
- *  - `source`: a `pnpm build` (or the per-artifact target) is missing.
- *  - `dev`: there's no built artifact in dev mode — point at `pnpm dev`. */
 function missingArtifactError({ artifactName, expectedPath, buildCmd, devCmd }) {
   const lines = [
     '',
@@ -567,11 +482,7 @@ async function report(opts) {
     console.error(`[ccgauge] error: report failed: ${(err && err.message) || err}`);
     process.exit(1);
   }
-  // The indexer keeps fs watchers alive, which would block process exit.
-  // For a one-shot report we explicitly exit once stdout is drained.
-  // Use the write() return value rather than chaining a `drain` listener
-  // after the fact: if drain fires between the write and the listener
-  // attach, we'd hang forever waiting for an event that already happened.
+
   const flushed = process.stdout.write(payload);
   if (flushed) {
     process.exit(0);
@@ -590,9 +501,6 @@ async function startMcp(opts = {}) {
     });
   }
 
-  // --check: don't actually run the JSON-RPC server — load the bundle,
-  // boot the indexer, print one line per provider, and exit. Lets users
-  // verify their install without wiring up an MCP client.
   if (opts.check) {
     const mod = await import(pathToFileURL(bundle).href);
     if (typeof mod.printCheck !== 'function') {
@@ -603,21 +511,6 @@ async function startMcp(opts = {}) {
     process.exit(typeof code === 'number' ? code : 0);
   }
 
-  // Run the bundled MCP server **in this process** — the bundle exposes a
-  // top-level `runStdioServer()` so we just import + invoke it. Spawning a
-  // second Node process here is wasted memory/latency (LLM clients already
-  // spawn `ccgauge mcp` per conversation), and forwarding signals across
-  // processes is brittle (e.g. SIGHUP isn't covered by the old shim).
-  //
-  // CRITICAL: `runStdioServer()` resolves as soon as
-  // `server.connect(transport)` finishes the JSON-RPC handshake setup —
-  // the long-running stdio listener is what holds the process alive
-  // afterwards. We must NOT call `process.exit(0)` after the await
-  // returns, or we'd kill the process before any client `initialize`
-  // can land. The dist/mcp/server.mjs direct-entry path gets this right
-  // (entry.ts uses `.catch()` only); the CLI in-process wrapper used to
-  // exit here too — a regression introduced when we moved off the
-  // spawn-a-child design. Don't reintroduce.
   try {
     const mod = await import(pathToFileURL(bundle).href);
     if (typeof mod.runStdioServer !== 'function') {
@@ -625,25 +518,13 @@ async function startMcp(opts = {}) {
       process.exit(1);
     }
     await mod.runStdioServer();
-    // Function returned but didn't process.exit — stdin listener still
-    // alive. Just let the event loop run; the transport calls
-    // process.exit(0) when stdin closes (see `shutdown` in
-    // lib/mcp/server.ts), which is the LLM client disconnecting.
+
   } catch (err) {
     console.error('[ccgauge-mcp] error: failed to start:', err?.message ?? err);
     process.exit(1);
   }
 }
 
-/** `ccgauge doctor` — print everything we'd ask the user to gather when
- *  debugging a "why doesn't it work" report, in one place:
- *  - version / platform
- *  - env vars that influence ccgauge behaviour
- *  - on-disk build artifacts (each can be rebuilt independently)
- *  - background service state (if any)
- *  - delegated MCP `--check` for indexer + per-provider scan stats
- *  Output is plain text (no colour) so it's easy to paste into a GitHub
- *  issue. */
 async function doctor() {
   const lines = [];
   lines.push(`ccgauge:  v${pkg.version ?? '?'}`);
@@ -697,12 +578,8 @@ async function doctor() {
   }
   lines.push('');
 
-  // Print everything we've accumulated so the indexer probe's output
-  // appears below it (printCheck writes to stdout synchronously).
   for (const l of lines) console.log(l);
 
-  // Delegate to the MCP bundle's printCheck() for indexer / providers
-  // detail — same info `ccgauge mcp --check` shows, in the same format.
   const mcpBundle = join(packageRoot, 'dist', 'mcp', 'server.mjs');
   if (!existsSync(mcpBundle)) {
     console.log('indexer:  (MCP bundle missing; rebuild to run the indexer probe)');
@@ -712,9 +589,7 @@ async function doctor() {
     const mod = await import(pathToFileURL(mcpBundle).href);
     if (typeof mod.printCheck === 'function') {
       const code = await mod.printCheck();
-      // Doctor exit code mirrors the indexer probe: 0 on success, non-0
-      // otherwise. Anything that printCheck couldn't decide we treat as
-      // success — doctor is a diagnostic tool, not a gate.
+
       process.exit(typeof code === 'number' ? code : 0);
     }
     process.exit(0);
@@ -729,11 +604,7 @@ async function resolvePort(opts) {
   if (!Number.isInteger(preferred) || preferred <= 0 || preferred > 65535) {
     throw new Error(`invalid port: ${opts.port}`);
   }
-  // Try the preferred port first, then up to 19 ports above it (capped at
-  // 65535), then 0 (let the OS pick an ephemeral port). For unusually high
-  // preferred values (e.g. 65530) the +N candidates are clamped by the
-  // filter, leaving just the preferred + ephemeral fallback — that's still
-  // correct, just narrower.
+
   const candidates = opts.strictPort
     ? preferred
     : [preferred, ...Array.from({ length: 19 }, (_, i) => preferred + i + 1).filter((p) => p <= 65535), 0];
@@ -758,10 +629,6 @@ function makeServerEnv(opts, port) {
   return env;
 }
 
-/** Read the last `lines` non-empty lines of a log file. Used as a hint
- *  in error messages when the spawned background server fails to come
- *  up — the actual root cause (port conflict, parse error, etc.) is in
- *  the log file and we'd rather not make the user go fishing for it. */
 async function tailLog(logFile, lines = 5) {
   try {
     const content = await readFile(logFile, 'utf8');
@@ -795,13 +662,10 @@ async function tryOpen(url) {
     const openBrowser = await loadOpenBrowser();
     await openBrowser(url);
   } catch {
-    // ignore — user may be on remote without a browser
+
   }
 }
 
-/** Build a small palette of ANSI escapes that collapse to '' when colour
- *  is off, so the same template literal works for both modes without an
- *  if/else per line. */
 function ansiPalette(useColor) {
   const seq = (...codes) => (useColor ? `\x1b[${codes.join(';')}m` : '');
   return {
@@ -852,12 +716,9 @@ async function readState() {
     const raw = await readFile(STATE_FILE, 'utf8');
     const parsed = JSON.parse(raw);
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
-    // Treat unknown / future versions as stale (auto-clean on next stop/start).
+
     if (parsed.version !== STATE_VERSION) return null;
-    // Type-guard the fields callers actually use — `stop`, `status`, and
-    // `restart` all assume these have the right shape. A hand-edited
-    // state.json with the right `version` but garbage in `pid` could
-    // otherwise crash `safeKill()` or `isProcessRunning()`.
+
     if (typeof parsed.pid !== 'number' || !Number.isInteger(parsed.pid) || parsed.pid <= 0) {
       return null;
     }
@@ -879,22 +740,10 @@ async function removeState() {
   await rm(STATE_FILE, { force: true });
 }
 
-/** Best-effort approximation of system boot time, in ms since the epoch.
- *  Used as a `bootId` on persisted state so we can reject stale PIDs
- *  after a reboot (PID space gets recycled and would otherwise let us
- *  SIGTERM an unrelated process that happens to inherit the old PID). */
 function bootId() {
   return Math.floor(Date.now() - os.uptime() * 1000);
 }
 
-/** Optional identity check on top of the existing `process.kill(pid, 0)`.
- *  Pass `state` to additionally verify:
- *  1. We're still on the same boot (uptime hasn't reset).
- *  2. `ps -p <pid> -o command=` mentions `state.cmdMarker` — i.e. that
- *     pid actually points at *our* dashboard child and not some other
- *     process that re-inherited the PID.
- *  Failures of (2) are tolerated (`ps` missing, sandboxed exec, etc.)
- *  so we don't false-negative on minimal containers. */
 function isProcessRunning(pid, state) {
   if (!pid) return false;
   try {
@@ -903,8 +752,7 @@ function isProcessRunning(pid, state) {
     return false;
   }
   if (!state) return true;
-  // Reboot detection: bootId drifts by tens of ms across reads on the
-  // same boot (os.uptime() has float jitter), so use a generous window.
+
   if (typeof state.bootId === 'number') {
     if (Math.abs(bootId() - state.bootId) > 60_000) return false;
   }
@@ -917,12 +765,7 @@ function isProcessRunning(pid, state) {
       });
       if (!out.includes(state.cmdMarker)) return false;
     } catch {
-      // `ps` not available or PID gone between kill(0) and exec — fall
-      // back to the kill(0) result we already have. We deliberately do
-      // NOT fail closed here: a missing `ps` is more common than a PID
-      // collision (PID reuse requires a reboot or wraparound), so the
-      // false-negative cost of "treat as not-running" outweighs the
-      // false-positive of "treat as running".
+
     }
   }
   return true;
@@ -954,12 +797,9 @@ async function followLog(logFile, offset) {
       busy = true;
       try {
         const s = await stat(logFile);
-        if (s.size < cursor) cursor = 0; // log was truncated / rotated
+        if (s.size < cursor) cursor = 0;
         if (s.size === cursor) return;
-        // Pin the upper bound to the size we saw in stat() — otherwise a
-        // chunk written *after* stat returns would slip into this read,
-        // and the next tick (which starts at `s.size`) would replay it.
-        // `end` is inclusive, hence the -1.
+
         const endAt = s.size - 1;
         await new Promise((res, rej) => {
           const stream = createReadStream(logFile, {
@@ -975,7 +815,7 @@ async function followLog(logFile, offset) {
           stream.on('error', rej);
         });
       } catch {
-        // keep following unless interrupted
+
       } finally {
         busy = false;
       }