@auroraflow/code 0.0.19 → 0.0.21

package/README.md

@@ -37,6 +37,10 @@ aurora update-clients
 aurora install codex
 aurora install claude
 aurora install all
+aurora repair codex
+aurora repair claude
+aurora doctor
+aurora doctor --json
 ```
 
 ## Commands
@@ -50,6 +54,9 @@ node bin/aurora.js claude
 node bin/aurora.js codex
 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
@@ -59,6 +66,10 @@ Running `aurora` without a subcommand opens an interactive client selector. Use
 Up/Down (or `j`/`k`) and Enter to launch Claude or Codex through Aurora.
 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.19",
+  "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, 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";
 
@@ -28,9 +28,15 @@ export async function runAuroraCLI(argv = process.argv.slice(2)) {
         officialClients: officialClientStatuses()
       }, null, 2));
       return;
+    case "doctor":
+      await doctorCommand(rest);
+      return;
     case "install":
       await installCommand(rest);
       return;
+    case "repair":
+      await repairCommand(rest);
+      return;
     case "install-clients":
     case "install-official-clients":
     case "update-clients":
@@ -93,6 +99,58 @@ async function installCommand(args) {
   }
 }
 
+async function repairCommand(args) {
+  const target = args[0] ?? "";
+  switch (target) {
+    case "codex":
+    case "claude":
+      await repairOfficialClient(target);
+      console.log(JSON.stringify({ officialClients: officialClientStatuses() }, null, 2));
+      return;
+    case "all":
+    case "clients":
+    case "official-clients":
+      await repairOfficialClient("claude");
+      await repairOfficialClient("codex");
+      console.log(JSON.stringify({ officialClients: officialClientStatuses() }, null, 2));
+      return;
+    default:
+      console.error("Usage: aurora repair [codex|claude|all]");
+      process.exit(1);
+  }
+}
+
+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.log(`  fix: aurora repair ${status.id}`);
+      if (process.platform === "win32") {
+        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)) {
   await ensureLayout();
   await runClient("claude", argv);
@@ -116,12 +174,22 @@ async function startInteractive(args) {
 async function ensureOfficialClientForInteractive(client) {
   const status = officialClientStatus(client);
   if (status?.installed) return;
-  const action = await promptChoice(`${status?.name ?? client} is not installed`, [
-    { label: `Install ${status?.name ?? client} now`, value: "install" },
+  const broken = status?.state === "broken";
+  const action = await promptChoice(`${status?.name ?? client} ${broken ? "is installed but not usable" : "is not installed"}`, [
+    { label: `${broken ? "Repair" : "Install"} ${status?.name ?? client} now`, value: broken ? "repair" : "install" },
+    { label: "Show fix command", value: "manual" },
     { label: "Exit", value: "exit" }
   ]);
+  if (action === "manual") {
+    const command = broken ? `aurora repair ${client}` : `aurora install ${client}`;
+    throw new Error(`${status?.name ?? client} is required. Run: ${command}`);
+  }
+  if (action === "repair") {
+    await repairOfficialClient(client);
+    return;
+  }
   if (action !== "install") {
-    throw new Error(`${status?.name ?? client} is required. Run: aurora install ${client}`);
+    throw new Error(`${status?.name ?? client} is required. Run: aurora ${broken ? "repair" : "install"} ${client}`);
   }
   await installOfficialClient(client);
 }
@@ -204,6 +272,10 @@ function usage(exitCode) {
   aurora install codex
   aurora install claude
   aurora install all
+  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

@@ -67,14 +67,20 @@ export function officialClientStatuses() {
   return Object.entries(OFFICIAL_CLIENTS).map(([id, client]) => {
     const bin = resolveOfficialClientBin(client.binName);
     const packagePath = officialClientPackageJSONPath(client.packageName);
-    const version = readOfficialClientVersion(bin) ?? (packagePath ? JSON.parse(readFileSync(packagePath, "utf8")).version : null);
+    const binVersion = readOfficialClientVersion(bin);
+    const packageVersion = packagePath ? JSON.parse(readFileSync(packagePath, "utf8")).version : null;
+    const state = bin && binVersion ? "installed" : packagePath ? "broken" : "missing";
     return {
       id,
       name: client.name,
       packageName: client.packageName,
       bin,
-      installed: Boolean(bin),
-      version
+      packagePath,
+      installed: state === "installed",
+      packagePresent: Boolean(packagePath),
+      state,
+      version: binVersion ?? packageVersion,
+      problem: officialClientProblem(state, bin, packagePath)
     };
   });
 }
@@ -88,13 +94,25 @@ export async function installOfficialClients() {
   await installOfficialClient("codex");
 }
 
-export async function installOfficialClient(client) {
+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", `${spec.packageName}@latest`];
-  console.error(`[aurora] installing ${spec.name}: ${npm.command} ${[...npm.args, ...args].join(" ")}`);
-  await spawnAndWait(npm.command, [...npm.args, ...args], { ...process.env });
+  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(" ")}`);
+  try {
+    await spawnAndWait(npm.command, [...npm.args, ...args], { ...process.env });
+  } catch (error) {
+    throw new Error(formatOfficialClientInstallError(spec, client, error));
+  }
+}
+
+export async function repairOfficialClient(client) {
+  await installOfficialClient(client, { repair: true });
 }
 
 export function isGlobalNpmLifecycle() {
@@ -105,14 +123,27 @@ 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}`);
-  const bin = resolveOfficialClientBin(spec.binName);
-  if (!bin) {
+  const status = officialClientStatus(client);
+  if (!status?.installed) {
+    if (status?.state === "broken") {
+      throw new Error(`${spec.name} is installed but not usable. Run: aurora doctor, then aurora repair ${client}`);
+    }
     throw new Error(`${spec.name} is not installed. Run: aurora install ${client}`);
   }
-  return bin;
+  return status.bin;
 }
 
 function resolveOfficialClientBin(binName) {
@@ -139,8 +170,136 @@ function findPathCommand(binName) {
 
 function officialClientPackageJSONPath(packageName) {
   const parts = packageName.startsWith("@") ? packageName.split("/") : [packageName];
-  const packagePath = join(packageRoot, "node_modules", ...parts, "package.json");
-  return existsSync(packagePath) ? packagePath : null;
+  for (const root of officialClientPackageRoots()) {
+    const packagePath = join(root, ...parts, "package.json");
+    if (existsSync(packagePath)) return packagePath;
+  }
+  return null;
+}
+
+function officialClientPackageRoots() {
+  const roots = [join(packageRoot, "node_modules")];
+  const npmBin = findPathCommand("npm");
+  if (npmBin) roots.push(join(dirname(npmBin), "node_modules"));
+  if (process.platform === "win32" && process.env.APPDATA) {
+    roots.push(join(process.env.APPDATA, "npm", "node_modules"));
+  }
+  return [...new Set(roots)];
+}
+
+function officialClientProblem(state, bin, packagePath) {
+  if (state === "installed") return null;
+  if (state === "missing") return "package_not_found";
+  if (!bin) return "package_present_but_command_not_found";
+  if (packagePath) return "command_found_but_version_check_failed";
+  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) {