@auroraflow/code 0.0.20 → 0.0.21

package/README.md

@@ -40,6 +40,7 @@ aurora install all
 aurora repair codex
 aurora repair claude
 aurora doctor
+aurora doctor --json
 ```
 
 ## Commands
@@ -55,6 +56,7 @@ node bin/aurora.js install codex
 node bin/aurora.js install claude
 node bin/aurora.js repair codex
 node bin/aurora.js doctor
+node bin/aurora.js doctor --json
 node bin/aurora.js install-clients
 node bin/aurora.js update-clients
 node bin/aurora.js status
@@ -66,6 +68,8 @@ If the selected official client is missing, Aurora prompts to install that
 specific client before launch.
 If the package exists but its command is not usable, Aurora reports a broken
 client state and prompts to repair instead of calling it "not installed".
+`aurora doctor` prints a human-readable health summary, including npm, disk
+space on Windows, and repair commands for missing or broken clients.
 
 The launcher stores shared local state under `~/.aurora` and starts a local
 sidecar at `127.0.0.1:17878`. Official clients talk to the sidecar; the sidecar

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auroraflow/code",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "type": "module",
   "description": "Aurora launcher and sidecar for official Codex and Claude Code clients.",
   "repository": {

package/packages/cli/src/index.js

@@ -1,5 +1,5 @@
 import { ensureLayout, readAccount, readState, writeAccount, writeState } from "../../state/src/index.js";
-import { installOfficialClient, officialClientStatus, officialClientStatuses, repairOfficialClient, runClient, updateOfficialClients } from "../../clients/src/index.js";
+import { installOfficialClient, officialClientStatus, officialClientStatuses, officialClientsDoctor, repairOfficialClient, runClient, updateOfficialClients } from "../../clients/src/index.js";
 import { ensureSidecarRunning, installSidecarService, sidecarServiceStatus, uninstallSidecarService } from "../../service/src/index.js";
 import { chooseClient, promptChoice, promptFields } from "../../../lib/prompt.js";
 
@@ -29,7 +29,7 @@ export async function runAuroraCLI(argv = process.argv.slice(2)) {
       }, null, 2));
       return;
     case "doctor":
-      await doctorCommand();
+      await doctorCommand(rest);
       return;
     case "install":
       await installCommand(rest);
@@ -120,18 +120,35 @@ async function repairCommand(args) {
   }
 }
 
-async function doctorCommand() {
-  const statuses = officialClientStatuses();
-  console.log(JSON.stringify({ officialClients: statuses }, null, 2));
-  for (const status of statuses) {
+async function doctorCommand(args = []) {
+  const report = officialClientsDoctor();
+  if (args.includes("--json")) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  console.log("Aurora doctor\n");
+  console.log(`Platform: ${report.platform}`);
+  console.log(`npm: ${report.npm.ok ? `ok (${report.npm.version})` : `problem (${report.npm.error || "unknown"})`}`);
+  if (report.disk.checked) {
+    console.log(`Disk ${report.disk.drive}: ${report.disk.availableMB ?? "unknown"} MB free`);
+  }
+  console.log("");
+  for (const status of report.officialClients) {
+    console.log(`${status.name}: ${status.state}${status.version ? ` (${status.version})` : ""}`);
+    if (status.bin) console.log(`  command: ${status.bin}`);
+    if (status.packagePath) console.log(`  package: ${status.packagePath}`);
+    if (status.problem) console.log(`  problem: ${status.problem}`);
+    if (status.state === "missing") console.log(`  fix: aurora install ${status.id}`);
     if (status.state === "broken") {
-      console.error(`\n${status.name} exists but is not usable (${status.problem}).`);
-      console.error(`Repair: aurora repair ${status.id}`);
+      console.log(`  fix: aurora repair ${status.id}`);
       if (process.platform === "win32") {
-        console.error(`If repair reports EBUSY, close ${status.name} and run: taskkill /F /IM ${status.id === "claude" ? "claude.exe" : "codex.exe"}`);
+        console.log(`  if locked: taskkill /F /IM ${status.id === "claude" ? "claude.exe" : "codex.exe"}`);
       }
     }
   }
+  if (report.disk.checked && report.disk.availableBytes != null && report.disk.availableBytes < 512 * 1024 * 1024) {
+    console.log("\nWarning: low disk space can break npm install/repair. Free space and run: npm cache clean --force");
+  }
 }
 
 export async function runAuroraClaude(argv = process.argv.slice(2)) {
@@ -258,6 +275,7 @@ function usage(exitCode) {
   aurora repair codex
   aurora repair claude
   aurora doctor
+  aurora doctor --json
   aurora install-clients
   aurora update-clients
   aurora status

package/packages/clients/src/index.js

@@ -97,12 +97,18 @@ export async function installOfficialClients() {
 export async function installOfficialClient(client, options = {}) {
   const spec = OFFICIAL_CLIENTS[client];
   if (!spec) throw new Error(`unknown official client: ${client}`);
+  const preflight = officialClientPreflight(client);
+  if (!preflight.ok) throw new Error(formatOfficialClientPreflightError(spec, preflight));
   const npm = npmCommandSpec();
   const args = ["install", "-g"];
   if (options.repair) args.push("--force");
   args.push(`${spec.packageName}@latest`);
   console.error(`[aurora] ${options.repair ? "repairing" : "installing"} ${spec.name}: ${npm.command} ${[...npm.args, ...args].join(" ")}`);
-  await spawnAndWait(npm.command, [...npm.args, ...args], { ...process.env });
+  try {
+    await spawnAndWait(npm.command, [...npm.args, ...args], { ...process.env });
+  } catch (error) {
+    throw new Error(formatOfficialClientInstallError(spec, client, error));
+  }
 }
 
 export async function repairOfficialClient(client) {
@@ -117,6 +123,16 @@ export function officialClientStatus(client) {
   return officialClientStatuses().find(status => status.id === client) ?? null;
 }
 
+export function officialClientsDoctor() {
+  return {
+    platform: process.platform,
+    npm: npmDoctor(),
+    disk: diskDoctor(),
+    processHints: processHints(),
+    officialClients: officialClientStatuses()
+  };
+}
+
 function officialClientBin(client) {
   const spec = OFFICIAL_CLIENTS[client];
   if (!spec) throw new Error(`unknown official client: ${client}`);
@@ -179,6 +195,113 @@ function officialClientProblem(state, bin, packagePath) {
   return "unknown";
 }
 
+function officialClientPreflight(client) {
+  const disk = diskDoctor();
+  if (disk.availableBytes != null && disk.availableBytes < 512 * 1024 * 1024) {
+    return { ok: false, reason: "low_disk_space", disk };
+  }
+  const processes = processHints();
+  const locked = processes.find(item => item.client === client && item.running);
+  if (locked) return { ok: false, reason: "client_process_running", process: locked };
+  return { ok: true, disk, processes };
+}
+
+function npmDoctor() {
+  try {
+    const npm = npmCommandSpec();
+    const result = spawnSyncCompat(npm.command, [...npm.args, "--version"]);
+    return {
+      command: npm.command,
+      args: npm.args,
+      ok: result.status === 0,
+      version: String(result.stdout || result.stderr || "").trim() || null
+    };
+  } catch (error) {
+    return { ok: false, error: error?.message || String(error) };
+  }
+}
+
+function diskDoctor() {
+  if (process.platform !== "win32") return { checked: false, reason: "not_windows" };
+  try {
+    const drive = (process.env.APPDATA || process.cwd()).slice(0, 2);
+    const result = spawnSync("powershell.exe", [
+      "-NoProfile",
+      "-Command",
+      `(Get-PSDrive -Name ${JSON.stringify(drive.charAt(0))}).Free`
+    ], { encoding: "utf8" });
+    const availableBytes = Number(String(result.stdout || "").trim());
+    return {
+      checked: true,
+      drive,
+      availableBytes: Number.isFinite(availableBytes) ? availableBytes : null,
+      availableMB: Number.isFinite(availableBytes) ? Math.floor(availableBytes / 1024 / 1024) : null
+    };
+  } catch (error) {
+    return { checked: false, error: error?.message || String(error) };
+  }
+}
+
+function processHints() {
+  if (process.platform !== "win32") return [];
+  return [
+    { client: "claude", image: "claude.exe", running: isWindowsProcessRunning("claude.exe") },
+    { client: "codex", image: "codex.exe", running: isWindowsProcessRunning("codex.exe") },
+    { client: "codex", image: "node.exe", running: false, note: "Codex may run through node.exe depending on npm package version." }
+  ];
+}
+
+function isWindowsProcessRunning(image) {
+  try {
+    const result = spawnSync("tasklist", ["/FI", `IMAGENAME eq ${image}`], { encoding: "utf8" });
+    return String(result.stdout || "").toLowerCase().includes(image.toLowerCase());
+  } catch {
+    return false;
+  }
+}
+
+function formatOfficialClientPreflightError(spec, preflight) {
+  if (preflight.reason === "low_disk_space") {
+    return `${spec.name} repair/install blocked: low disk space on ${preflight.disk.drive} (${preflight.disk.availableMB} MB free). Free at least 512 MB, run npm cache clean --force, then retry.`;
+  }
+  if (preflight.reason === "client_process_running") {
+    return `${spec.name} repair/install blocked: ${preflight.process.image} is running. Close ${spec.name} or run: taskkill /F /IM ${preflight.process.image}`;
+  }
+  return `${spec.name} repair/install preflight failed: ${preflight.reason}`;
+}
+
+function formatOfficialClientInstallError(spec, client, error) {
+  const message = error?.message || String(error);
+  const suggestions = officialClientFailureSuggestions(client, message);
+  return [`${spec.name} install/repair failed: ${message}`, ...suggestions].join("\n");
+}
+
+function officialClientFailureSuggestions(client, message) {
+  const text = String(message);
+  const image = client === "claude" ? "claude.exe" : "codex.exe";
+  if (/ENOSPC|no space left/i.test(text)) {
+    return [
+      "Detected cause: disk is full.",
+      "Fix: free disk space, then run: npm cache clean --force",
+      `Retry: aurora repair ${client}`
+    ];
+  }
+  if (/EBUSY|EPERM|resource busy|operation not permitted/i.test(text)) {
+    return [
+      "Detected cause: files are locked by a running process or antivirus.",
+      process.platform === "win32" ? `Fix: close the client, then run: taskkill /F /IM ${image}` : "Fix: close the running client process.",
+      `Retry: aurora repair ${client}`
+    ];
+  }
+  if (/ENOENT|not found/i.test(text)) {
+    return [
+      "Detected cause: npm or a required command was not found.",
+      "Fix: reinstall Node.js/npm or add npm to PATH, then retry."
+    ];
+  }
+  return [`Run diagnostics: aurora doctor`, `Retry after fixing the reported issue: aurora repair ${client}`];
+}
+
 function readOfficialClientVersion(bin) {
   if (!bin) return null;
   try {