howtofixcli 0.7.5 → 0.7.7

package/dist/args.js

@@ -149,6 +149,8 @@ usage:
   howtofix -p "explain this repo"
   howtofix preset new|check|pack     author a preset
   howtofix doctor|models|sessions    inspect the installation
+  howtofix sessions --search <text> find a session by what was said in it
+  howtofix sessions --export <n>    print session n from the list as markdown
 
 options:
   -p, --print          run one prompt and print the answer

package/dist/brand.js

@@ -1,5 +1,5 @@
 export const APP_TITLE = "HowToFix";
-export const APP_VERSION = "0.7.5";
+export const APP_VERSION = "0.7.7";
 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 ?? {};
@@ -148,6 +168,26 @@ export function listSessionFiles(limit = 15, root = AGENT_DIR) {
     return rows.sort((a, b) => b.modified - a.modified).slice(0, limit);
 }
 export function runSessions(argv) {
+    const searchIndex = argv.indexOf("--search");
+    if (searchIndex >= 0) {
+        const query = argv[searchIndex + 1]?.trim();
+        if (!query) {
+            console.error(`${APP_TITLE}: sessions: --search needs a word or phrase`);
+            return 2;
+        }
+        const hits = searchSessions(query);
+        if (hits.length === 0) {
+            console.log(`  no session mentions "${query}"`);
+            return 0;
+        }
+        for (const hit of hits) {
+            const when = new Date(hit.row.modified).toISOString().replace("T", " ").slice(0, 16);
+            console.log(`  ${when}  ${hit.row.project}  (${hit.matches} hit${hit.matches === 1 ? "" : "s"})`);
+            console.log(`                     ${hit.row.file}`);
+            console.log(`                     ${hit.snippet}`);
+        }
+        return 0;
+    }
     const limitIndex = argv.indexOf("--limit");
     const limit = limitIndex >= 0 ? Number(argv[limitIndex + 1]) || 15 : 15;
     const rows = listSessionFiles(limit);
@@ -155,14 +195,101 @@ export function runSessions(argv) {
         console.log(`  no saved sessions under ${join(AGENT_DIR, "sessions")}`);
         return 0;
     }
-    for (const row of rows) {
+    const exportIndex = argv.indexOf("--export");
+    if (exportIndex >= 0) {
+        const which = Number(argv[exportIndex + 1]);
+        if (!Number.isInteger(which) || which < 1 || which > rows.length) {
+            console.error(`${APP_TITLE}: sessions: --export needs a number from the list (1-${rows.length})`);
+            return 2;
+        }
+        const row = rows[which - 1];
+        try {
+            console.log(exportSessionMarkdown(row.file));
+        }
+        catch (error) {
+            reportError(APP_TITLE, "sessions", error);
+            return 1;
+        }
+        return 0;
+    }
+    rows.forEach((row, index) => {
         const when = new Date(row.modified).toISOString().replace("T", " ").slice(0, 16);
         const kb = Math.round(row.bytes / 1024);
-        console.log(`  ${when}  ${String(kb).padStart(6)}k  ${row.project}`);
+        console.log(`  ${String(index + 1).padStart(2)}  ${when}  ${String(kb).padStart(6)}k  ${row.project}`);
         console.log(`                     ${row.file}`);
-    }
+    });
     return 0;
 }
+/** Text of one JSONL line, whether its content is a string or content blocks. */
+function lineText(line) {
+    try {
+        const entry = JSON.parse(line);
+        const content = entry.message?.content;
+        if (typeof content === "string")
+            return content.replace(/\s+/g, " ").trim();
+        if (Array.isArray(content)) {
+            return content
+                .map((block) => (block && typeof block === "object" && "text" in block ? String(block.text) : ""))
+                .join(" ")
+                .replace(/\s+/g, " ")
+                .trim();
+        }
+    }
+    catch {
+        // A line that does not parse is still searchable as raw text.
+    }
+    return line.replace(/\s+/g, " ").trim();
+}
+/** Sessions whose text mentions `query`, with the first matching line as evidence. */
+export function searchSessions(query, limit = 10, root = AGENT_DIR) {
+    const needle = query.toLowerCase();
+    const hits = [];
+    for (const row of listSessionFiles(500, root)) {
+        let text;
+        try {
+            text = readFileSync(row.file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        let matches = 0;
+        let snippet = "";
+        for (const line of text.split("\n")) {
+            if (!line.toLowerCase().includes(needle))
+                continue;
+            matches++;
+            if (!snippet)
+                snippet = lineText(line).slice(0, 160);
+        }
+        if (matches > 0)
+            hits.push({ row, matches, snippet });
+        if (hits.length >= limit)
+            break;
+    }
+    return hits;
+}
+/** A session as markdown, for pasting into an issue or a chat. */
+export function exportSessionMarkdown(file) {
+    const out = [`# Session ${file.split(/[\\/]/).pop() ?? file}`, ""];
+    for (const line of readFileSync(file, "utf8").split("\n")) {
+        if (!line.trim())
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (entry.type !== "message")
+            continue;
+        const text = lineText(line);
+        if (!text)
+            continue;
+        out.push(`## ${entry.message?.role ?? "unknown"}`, "", text, "");
+    }
+    return out.join("\n").trimEnd();
+}
 /** True when the file exists and is a directory — used by doctor's callers. */
 export function stateDirExists() {
     try {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "howtofixcli",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "description": "HowToFix coding agent. Workbench TUI, sessions, background agents.",
   "type": "module",
   "bin": {
@@ -44,10 +44,10 @@
     "node": ">=22.19"
   },
   "dependencies": {
-    "@netrodev/hxf-agent-core": "^1.0.19",
-    "@netrodev/hxf-ai": "^1.0.19",
-    "@netrodev/hxf-coding-agent": "^1.0.19",
-    "@netrodev/hxf-tui": "^1.0.19",
+    "@netrodev/hxf-agent-core": "^1.0.22",
+    "@netrodev/hxf-ai": "^1.0.22",
+    "@netrodev/hxf-coding-agent": "^1.0.22",
+    "@netrodev/hxf-tui": "^1.0.22",
     "typebox": "1.3.27",
     "typescript": "7.0.2",
     "undici": "^8.10.2"