howtofixcli 0.7.4 → 0.7.6

package/dist/brand.js

@@ -1,5 +1,5 @@
 export const APP_TITLE = "HowToFix";
-export const APP_VERSION = "0.7.4";
+export const APP_VERSION = "0.7.6";
 export const SYSTEM_APPEND = [
     // House style: RFC 2119 keywords in caps, one claim per line, the
     // highest-stakes rules at

package/dist/commands.js

@@ -2,6 +2,8 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, statSync, writeFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { AGENT_DIR } from "./paths.js";
+import { APP_TITLE } from "./brand.js";
+import { reportError } from "./errors.js";
 import { detectSandbox } from "./sandbox.js";
 const MIN_NODE = [22, 19];
 /** Everything the CLI needs from the machine, checked without a model call. */
@@ -89,12 +91,30 @@ export async function runDoctor() {
 /** Configured providers and their models, straight from models.json. */
 export function runModels(root = AGENT_DIR) {
     const path = join(root, "models.json");
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT") {
+            console.log(`  no models.json at ${path} — run \`howtofix /connect\` to pull the catalogue`);
+        }
+        else {
+            reportError(APP_TITLE, "models", error);
+        }
+        return 1;
+    }
     let parsed;
     try {
-        parsed = JSON.parse(readFileSync(path, "utf8"));
+        parsed = JSON.parse(raw);
     }
-    catch {
-        console.log(`  no models.json at ${path} — run \`howtofix /connect\` to pull the catalogue`);
+    catch (error) {
+        // A file that exists but does not parse is a different problem from a
+        // missing one: /connect will not fix it, and saying "no models.json" sends
+        // the user looking for a file that is already there.
+        console.error(`${APP_TITLE}: models: ${path} is not valid JSON (${error instanceof Error ? error.message : String(error)})`);
+        console.error("  fix the file, or delete it and run `howtofix /connect` to write a new one");
         return 1;
     }
     const providers = parsed.providers ?? {};

package/dist/errors.js

@@ -0,0 +1,63 @@
+/**
+ * One way to tell a user that something failed.
+ *
+ * Every command used to phrase its own failure, which meant a missing file, a
+ * refused connection and a typo in a flag could all arrive in the same shape:
+ * a sentence that says what broke but not what to do. This module answers both
+ * questions from the error itself, so the answer does not depend on which code
+ * path happened to throw.
+ */
+/** The action a user can take, inferred from the code Node attached. */
+function hintFor(code, message) {
+    const evidence = `${code ?? ""} ${message}`;
+    if (/EACCES|EPERM/.test(evidence))
+        return "the file or directory is not writable; check permissions and try again";
+    if (/ENOENT/.test(evidence))
+        return "a file or directory this command needs is missing";
+    if (/ENOSPC/.test(evidence))
+        return "the disk is full";
+    if (/ECONNREFUSED|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|UND_ERR|fetch failed/i.test(evidence)) {
+        return "the network request failed; check the connection and the gateway address";
+    }
+    if (/EADDRINUSE/.test(evidence))
+        return "another process is already using that port";
+    if (/MODULE_NOT_FOUND|ERR_MODULE_NOT_FOUND/.test(evidence)) {
+        return "a required file or package is missing; reinstall HowToFix";
+    }
+    if (/JSON/i.test(evidence) && /parse|unexpected token|end of input/i.test(evidence)) {
+        return "a configuration file is not valid JSON";
+    }
+    if (/not a git repository/i.test(evidence))
+        return "run the command inside a project, or pass --cwd";
+    return undefined;
+}
+/** The message, and the action that follows from it. */
+export function describeError(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    const message = raw.trim() || "unknown error";
+    const code = error?.code;
+    return { message, hint: hintFor(code, message) };
+}
+/**
+ * The line(s) a failure prints.
+ *
+ * `context` names the thing that failed ("doctor", "update"), because "not
+ * permitted" alone does not say what was not permitted. The stack is evidence,
+ * and evidence only appears when `HOWTOFIX_DEBUG` asks for it.
+ */
+export function formatError(appTitle, context, error, debug = false) {
+    const { message, hint } = describeError(error);
+    const head = context ? `${appTitle}: ${context}: ${message}` : `${appTitle}: ${message}`;
+    const lines = [head];
+    if (hint)
+        lines.push(`  ${hint}`);
+    if (debug && error instanceof Error && error.stack)
+        lines.push(error.stack);
+    return lines.join("\n");
+}
+/** Print a failure the same way everywhere. */
+export function reportError(appTitle, context, error, options) {
+    const debug = options?.debug ?? process.env.HOWTOFIX_DEBUG === "1";
+    const write = options?.write ?? ((text) => console.error(text));
+    write(formatError(appTitle, context, error, debug));
+}

package/dist/fatal.js

@@ -6,14 +6,14 @@
  * frames the user cannot act on. The message is what matters; the stack is
  * evidence, and evidence belongs behind a flag.
  */
+import { describeError } from "./errors.js";
 /** The single line a failure deserves, with the stack only when asked for. */
 export function describeFatal(error, debug = false) {
-    const message = error instanceof Error ? error.message : String(error);
-    const text = message.trim() || "unknown error";
+    const { message } = describeError(error);
     if (!debug)
-        return text;
+        return message;
     const stack = error instanceof Error ? error.stack : undefined;
-    return stack && stack.includes("\n") ? `${text}\n${stack}` : text;
+    return stack && stack.includes("\n") ? `${message}\n${stack}` : message;
 }
 /**
  * Catch what escapes `main()`.

package/dist/main.js

@@ -2,6 +2,7 @@
 import { helpText, parseArgs } from "./args.js";
 import { APP_TITLE, APP_VERSION } from "./brand.js";
 import { installCrashHandlers } from "./fatal.js";
+import { reportError } from "./errors.js";
 import { AGENT_DIR, pinAgentDir } from "./paths.js";
 import { jsonLine } from "./json-events.js";
 import { spendCapMessage, unpricedBudgetMessage } from "./spend-cap.js";
@@ -95,6 +96,28 @@ async function main() {
         }
         return;
     }
+    // Questions about the installation, answered without a session, a model, or
+    // any of the repairs below. They run first on purpose: `howtofix models` used
+    // to rewrite settings.json and print two notices about it before listing a
+    // single model, which reads like the command did something it did not.
+    const subArgv = process.argv.slice(2);
+    if (subArgv[0] === "doctor" || subArgv[0] === "models" || subArgv[0] === "sessions") {
+        const context = subArgv[0];
+        try {
+            const commands = await import("./commands.js");
+            if (context === "doctor")
+                process.exitCode = await commands.runDoctor();
+            else if (context === "models")
+                process.exitCode = commands.runModels();
+            else
+                process.exitCode = commands.runSessions(subArgv.slice(1));
+        }
+        catch (error) {
+            reportError(APP_TITLE, context, error);
+            process.exitCode = 1;
+        }
+        return;
+    }
     // Repair a howtofix gateway entry that predates `compat.supportsDeveloperRole`.
     // The gateway refuses the `developer` role that the SDK selects for every
     // reasoning model, so such an entry fails every prompt silently — the spinner
@@ -157,20 +180,6 @@ async function main() {
         // A start-time re-sync that fails costs the previous list, which still
         // works; `/sync` remains the manual way to try again.
     }
-    // Questions about the installation, answered without a session or a model.
-    // Dispatched before option parsing so their own flags (--limit) are not read
-    // as unknown options for the agent.
-    const subArgv = process.argv.slice(2);
-    if (subArgv[0] === "doctor" || subArgv[0] === "models" || subArgv[0] === "sessions") {
-        const commands = await import("./commands.js");
-        if (subArgv[0] === "doctor")
-            process.exitCode = await commands.runDoctor();
-        else if (subArgv[0] === "models")
-            process.exitCode = commands.runModels();
-        else
-            process.exitCode = commands.runSessions(subArgv.slice(1));
-        return;
-    }
     let args;
     try {
         args = parseArgs(process.argv.slice(2));
@@ -523,7 +532,6 @@ async function main() {
 }
 installCrashHandlers(APP_TITLE);
 main().catch((error) => {
-    const message = error instanceof Error ? error.message : String(error);
-    console.error(`${APP_TITLE}: ${message}`);
+    reportError(APP_TITLE, undefined, error);
     process.exitCode = 1;
 });

package/dist/update.js

@@ -418,6 +418,43 @@ export async function checkForUpdate(current, options) {
         message: `HowToFix ${latest} is available (you have ${current})`,
     };
 }
+/**
+ * The line that explains an npm failure.
+ *
+ * npm prints deprecation warnings on stderr and a real failure after them, so
+ * taking the last line reported `npm warn deprecated node-domexception@1.0.0`
+ * as the reason an install failed. Warnings are dropped, error lines win, and
+ * the code that is left is mapped to the action a user can actually take.
+ */
+export function npmFailureDetail(stdout, stderr, errorCode) {
+    const lines = `${stderr}\n${stdout}`
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .filter((line) => !/^npm warn\b/i.test(line));
+    const errors = lines.filter((line) => /^npm error\b/i.test(line) || /\bERR!/i.test(line));
+    const codeLine = errors.find((line) => /^npm error code\b/i.test(line));
+    const detail = (codeLine ?? errors.at(-1) ?? lines.at(-1) ?? errorCode ?? "")
+        .replace(/^npm error\s*/i, "")
+        .trim();
+    // The hint reads the whole output: the code that names the cause is often on
+    // an earlier line than the path or syscall that failed last.
+    const evidence = `${lines.join(" ")} ${errorCode ?? ""}`;
+    let hint = "";
+    if (/EACCES|EPERM|permission denied/i.test(evidence)) {
+        hint = " — npm could not replace its files; close other HowToFix windows and run the terminal as Administrator";
+    }
+    else if (/EBUSY|EEXIST|ENOTEMPTY|resource busy|being used by another process/i.test(evidence)) {
+        hint = " — a file is in use; close other HowToFix windows and try again";
+    }
+    else if (/ENOSPC/i.test(evidence)) {
+        hint = " — the disk is full";
+    }
+    else if (/ETIMEDOUT|ENOTFOUND|EAI_AGAIN|ECONNREFUSED/i.test(evidence)) {
+        hint = " — npm could not reach the registry";
+    }
+    return { detail, hint };
+}
 /**
  * Install the newest release globally.
  *
@@ -442,9 +479,7 @@ export async function installUpdate(options) {
             timeoutMs: options?.timeoutMs ?? INSTALL_TIMEOUT_MS,
         });
         if (result.code !== 0) {
-            const detail = (result.stderr || result.stdout).trim().split("\n").filter(Boolean).pop() ?? result.errorCode ?? "";
-            // Permissions are the common failure and the one a user can act on.
-            const hint = /EACCES|EPERM|permission/i.test(detail) ? " — npm could not write to its global directory" : "";
+            const { detail, hint } = npmFailureDetail(result.stdout, result.stderr, result.errorCode);
             return { ok: false, message: `the update did not install${hint}${detail ? `: ${detail}` : ""}` };
         }
         return { ok: true, version: options?.version, message: "updated; it takes effect the next time HowToFix starts" };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "howtofixcli",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "description": "HowToFix coding agent. Workbench TUI, sessions, background agents.",
   "type": "module",
   "bin": {