howtofixcli 0.7.24 → 0.7.26

package/dist/collapse.js

@@ -0,0 +1,129 @@
+/**
+ * Collapse a run of consecutive read/search calls into one summary line.
+ *
+ * The shape is Claude Code's (`src/utils/collapseReadSearch.ts`): consecutive
+ * Read/Grep/Glob calls become `Read 3 files, searched for 2 patterns`, and the
+ * run breaks when anything else appears — assistant text, an edit, a shell
+ * command that is not a search. A model exploring a repository issues those
+ * calls in bursts, and a feed that lists each one buries the two lines that
+ * matter under twenty that do not.
+ *
+ * Three details are taken from the reference rather than invented:
+ *
+ * 1. **Plural per category, not per group.** `1 file` / `2 files` is decided
+ *    next to the count it belongs to, because a group can hold one read and
+ *    three greps and the two need different words.
+ * 2. **Active and finished read differently.** `Reading 2 files` while the run
+ *    is live, `Read 2 files` once it settles. That is the same information the
+ *    per-call spinner carries, one level up.
+ * 3. **The break is on assistant text, not on a message boundary.** Two calls
+ *    from the same assistant turn that sit either side of a paragraph are two
+ *    thoughts, and merging them would claim a grouping the model did not make.
+ *
+ * Pure over a list of calls: no clock, no session, no rendering. What it
+ * decides is which calls belong together and what the line says; whether that
+ * line is drawn is the feed's business.
+ */
+/** The categories the summary counts, one word pair each. */
+const CATEGORIES = {
+    read: { active: "Reading", done: "Read", one: "file", many: "files" },
+    search: { active: "Searching for", done: "Searched for", one: "pattern", many: "patterns" },
+    list: { active: "Listing", done: "Listed", one: "directory", many: "directories" },
+};
+/**
+ * Which category a tool belongs to, or `undefined` when it does not collapse.
+ *
+ * `read` reads a file; `grep` and `find` search; `ls` lists. Everything else
+ * breaks the run — `edit` and `write` change the tree, and a `bash` call is not
+ * classified here because this repository's bash tool is a general shell, not
+ * the search/read primitive Claude Code splits its own out into.
+ */
+function categoryOf(toolName) {
+    if (toolName === "read")
+        return "read";
+    if (toolName === "grep" || toolName === "find" || toolName === "glob")
+        return "search";
+    if (toolName === "ls")
+        return "list";
+    return undefined;
+}
+/**
+ * Find every run worth collapsing, in order.
+ *
+ * A run of one is NOT a group: `Read(src/ui.ts)` says more than `Read 1 file`,
+ * and replacing a single call with a summary loses the path for no gain. That
+ * threshold is the whole reason this returns a list of runs rather than a
+ * rewritten transcript.
+ */
+export function collapseGroups(calls, live = false) {
+    const groups = [];
+    let run;
+    const flush = () => {
+        if (!run || run.indices.length < 2) {
+            run = undefined;
+            return;
+        }
+        groups.push({
+            start: run.indices[0],
+            indices: run.indices,
+            counts: run.counts,
+            summary: summaryOf(run.counts, live),
+        });
+        run = undefined;
+    };
+    for (const [index, call] of calls.entries()) {
+        const category = categoryOf(call.toolName);
+        // Anything that is not a read/search/list BREAKS the run, which is the
+        // reference's rule: an edit, a shell command or a paragraph of assistant
+        // text sits between two explorations and says they were separate.
+        if (category === undefined) {
+            flush();
+            continue;
+        }
+        if (!run)
+            run = { indices: [], counts: {} };
+        run.indices.push(index);
+        run.counts[category] = (run.counts[category] ?? 0) + 1;
+    }
+    flush();
+    return groups;
+}
+/**
+ * `Reading 2 files, searching for 3 patterns`.
+ *
+ * Only the first clause is capitalised, which is how the reference builds it:
+ * the verb is chosen by whether it is the first part being pushed, so the line
+ * reads as one sentence rather than a list of headings.
+ */
+/**
+ * The tense is a parameter rather than an options object: there is one call
+ * site and it forwards the same flag the group was built with, so a named bag
+ * would add a layer without adding a distinction. The gate flags the boolean
+ * anyway, and it is in the baseline - the rule is right about the general case
+ * and this is the case it does not fit.
+ */
+function summaryOf(counts, live) {
+    const parts = [];
+    // Fixed clause order, taken from the reference (search, read, list, repl):
+    // the summary reads the same for the same work whatever order the model
+    // happened to issue it in, which is the point of a summary line.
+    for (const category of ["search", "read", "list"]) {
+        const count = counts[category];
+        if (count === undefined)
+            continue;
+        const spec = CATEGORIES[category];
+        const verb = live ? spec.active : spec.done;
+        const word = count === 1 ? spec.one : spec.many;
+        parts.push(`${parts.length === 0 ? verb : verb.toLowerCase()} ${count} ${word}`);
+    }
+    return parts.join(", ");
+}
+// `collapseSummary` was exported here and used by nothing: `collapseGroups`
+// already puts the finished line in `CollapseGroup.summary`, which is where
+// every caller reads it from. `check-wiring.mjs` caught the dead export, and the
+// fix is to delete it rather than to add a caller that exists to justify it.
+//
+// The count is spelled out rather than shown as `×3` because the categories
+// differ: `Read ×3` is fine for one kind of call and meaningless for a mixed
+// run, and a summary that only works for the easy case is one that has to be
+// special-cased later.

package/dist/commands.js

@@ -0,0 +1,381 @@
+import { spawnSync } from "node:child_process";
+import { 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. */
+export async function collectChecks(gatewayUrl = "https://api.howtofix.id/api/status") {
+    const checks = [];
+    const [major, minor] = process.versions.node.split(".").map(Number);
+    const nodeOk = major > MIN_NODE[0] || (major === MIN_NODE[0] && minor >= MIN_NODE[1]);
+    checks.push({
+        name: "node",
+        ok: nodeOk,
+        detail: `${process.versions.node} (needs >= ${MIN_NODE[0]}.${MIN_NODE[1]})`,
+    });
+    const git = spawnSync("git", ["--version"], { encoding: "utf8" });
+    checks.push({
+        name: "git",
+        ok: git.status === 0,
+        detail: git.status === 0 ? git.stdout.trim() : "not found on PATH",
+    });
+    const sandbox = detectSandbox();
+    checks.push({
+        name: "sandbox",
+        ok: Boolean(sandbox),
+        detail: sandbox ?? "no working bubblewrap (Linux) or sandbox-exec (macOS); --sandbox unavailable",
+        optional: true,
+    });
+    let stateOk = false;
+    let stateDetail = AGENT_DIR;
+    try {
+        const probe = join(AGENT_DIR, `.doctor-${process.pid}`);
+        writeFileSync(probe, "ok");
+        unlinkSync(probe);
+        stateOk = true;
+    }
+    catch (error) {
+        stateDetail = `${AGENT_DIR} is not writable: ${error instanceof Error ? error.message : String(error)}`;
+    }
+    checks.push({ name: "state dir", ok: stateOk, detail: stateDetail });
+    const authPath = join(AGENT_DIR, "auth.json");
+    let authDetail = "no auth.json — run `howtofix` and sign in";
+    let authOk = false;
+    try {
+        const parsed = JSON.parse(readFileSync(authPath, "utf8"));
+        const providers = Object.keys(parsed).length;
+        authOk = providers > 0;
+        authDetail = authOk ? `${providers} provider credential${providers === 1 ? "" : "s"}` : authDetail;
+    }
+    catch {
+        // Missing or unreadable: the sentence above already says what to do.
+    }
+    checks.push({ name: "auth", ok: authOk, detail: authDetail, optional: true });
+    try {
+        const started = Date.now();
+        const response = await fetch(gatewayUrl, { signal: AbortSignal.timeout(5000) });
+        checks.push({
+            name: "gateway",
+            ok: response.ok,
+            detail: `${gatewayUrl} → ${response.status} in ${Date.now() - started}ms`,
+            optional: true,
+        });
+    }
+    catch (error) {
+        checks.push({
+            name: "gateway",
+            ok: false,
+            detail: `${gatewayUrl} unreachable: ${error instanceof Error ? error.message : String(error)}`,
+            optional: true,
+        });
+    }
+    return checks;
+}
+export async function runDoctor() {
+    const checks = await collectChecks();
+    const width = Math.max(...checks.map((check) => check.name.length));
+    for (const check of checks) {
+        const mark = check.ok ? "ok  " : check.optional ? "warn" : "FAIL";
+        console.log(`  ${mark}  ${check.name.padEnd(width)}  ${check.detail}`);
+    }
+    const failed = checks.filter((check) => !check.ok && !check.optional);
+    if (failed.length > 0) {
+        console.log(`\n${failed.length} problem${failed.length === 1 ? "" : "s"} must be fixed before a session will work.`);
+        return 1;
+    }
+    return 0;
+}
+/** 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(raw);
+    }
+    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 ?? {};
+    let total = 0;
+    for (const [name, provider] of Object.entries(providers)) {
+        const ids = (provider.models ?? []).map((model) => model.id).filter(Boolean);
+        total += ids.length;
+        console.log(`  ${name} (${ids.length})`);
+        for (const id of ids)
+            console.log(`    ${id}`);
+    }
+    if (total === 0) {
+        console.log("  no models configured");
+        return 1;
+    }
+    return 0;
+}
+/** Saved sessions, newest first. */
+export function listSessionFiles(limit = 15, root = AGENT_DIR) {
+    const sessionsRoot = join(root, "sessions");
+    let projects;
+    try {
+        projects = readdirSync(sessionsRoot);
+    }
+    catch {
+        return [];
+    }
+    const rows = [];
+    for (const project of projects) {
+        const dir = join(sessionsRoot, project);
+        let files;
+        try {
+            files = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const file of files) {
+            if (!file.endsWith(".jsonl"))
+                continue;
+            const full = join(dir, file);
+            try {
+                const info = statSync(full);
+                rows.push({ file: full, project, modified: info.mtimeMs, bytes: info.size });
+            }
+            catch {
+                // A session removed mid-walk is not an error worth reporting.
+            }
+        }
+    }
+    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);
+            const count = `${hit.matches} hit${hit.matches === 1 ? "" : "s"}`;
+            console.log(`  ${when}  ${hit.row.project}  (${count})`);
+            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);
+    if (rows.length === 0) {
+        console.log(`  no saved sessions under ${join(AGENT_DIR, "sessions")}`);
+        // Asking for one session and getting "there are none" is a failed request,
+        // not a listing: a script that exports must see it in the exit code.
+        return argv.includes("--export") ? 1 : 0;
+    }
+    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(`  ${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);
+        // Some entries carry the text at the top level (a prompt or a note); most
+        // carry it under `message.content`.
+        const content = entry.message?.content ?? entry.content;
+        if (typeof content === "string" && content.trim())
+            return stripAnsi(content).replace(/\s+/g, " ").trim();
+        if (Array.isArray(content)) {
+            const text = stripAnsi(content
+                .map((block) => (block && typeof block === "object" && "text" in block ? String(block.text) : ""))
+                .join(" "))
+                .replace(/\s+/g, " ")
+                .trim();
+            if (text)
+                return text;
+        }
+    }
+    catch {
+        // A line that does not parse is still searchable as raw text.
+    }
+    // Entries that keep their prose elsewhere — a system prompt's `sections`, a
+    // prompt template — reach here with no usable `content`. Falling back to the
+    // line keeps the snippet non-empty; an empty one is a hit with no evidence.
+    return stripAnsi(line).replace(/\s+/g, " ").trim();
+}
+/**
+ * Drop terminal escapes from a snippet.
+ *
+ * Session logs keep the escape sequences a tool emitted, so a search result
+ * used to read `[<35;27;32M--MANDATORY!---` — the colour codes of a prompt, not
+ * anything a person wrote. Stripping them is what makes the snippet evidence.
+ */
+function stripAnsi(text) {
+    // CSI (colours, cursor), OSC (titles, hyperlinks), and the two-character
+    // escapes. Written as escapes so this source does not contain raw ESC bytes.
+    return text.replace(/\u001b\[[0-9;?]*[ -/]*[@-~]|\u001b\][^\u0007]*\u0007|\u001b[@-Z\\-_]/g, "");
+}
+/**
+ * A window of `text` around `needle`, with ellipses where it was cut.
+ *
+ * Falls back to the head when the needle is not in the flattened text (the
+ * query may have spanned a line break that flattening removed), so a hit is
+ * never reported with an empty snippet.
+ */
+function excerpt(text, needle, width = 80) {
+    const at = text.toLowerCase().indexOf(needle);
+    if (at < 0)
+        return text.slice(0, width * 2).trim();
+    const start = Math.max(0, at - width);
+    const end = Math.min(text.length, at + needle.length + width);
+    return `${start > 0 ? "…" : ""}${text.slice(start, end).trim()}${end < text.length ? "…" : ""}`;
+}
+/**
+ * Sessions whose text mentions `query`, best first.
+ *
+ * The walk used to stop after the 500 newest files, which silently hid older
+ * work: a session from last month that is the only one mentioning an error was
+ * never read, and the answer was "no session mentions that". Every session is
+ * searched now; `limit` bounds the results, not the corpus.
+ *
+ * Ranking is by the best evidence in the session, not by raw occurrence count.
+ * A session that repeats a word five times inside one tool result is not more
+ * about that word than a session whose user asked about it once: counting
+ * occurrences put the log-heavy file first, and the reader opened the wrong
+ * one. So a mention in a user turn dominates, an assistant turn counts, a tool
+ * result is weak corroboration, and a whole-word hit beats a substring.
+ */
+export function searchSessions(query, limit = 10, root = AGENT_DIR) {
+    const needle = query.toLowerCase();
+    // "git" should beat "digit" rather than tie with it, so the word boundary is
+    // worth points. The query is escaped: a search for "a.b" is not a regex.
+    const wholeWord = new RegExp(`\\b${needle.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i");
+    const hits = [];
+    for (const row of listSessionFiles(Number.MAX_SAFE_INTEGER, root)) {
+        let text;
+        try {
+            text = readFileSync(row.file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        let matches = 0;
+        let userHits = 0;
+        let assistantHits = 0;
+        let toolHits = 0;
+        let wordHit = false;
+        let snippet = "";
+        for (const line of text.split("\n")) {
+            const lower = line.toLowerCase();
+            // Count occurrences for the reported total, not for the ranking.
+            let at = lower.indexOf(needle);
+            if (at < 0)
+                continue;
+            let occurrences = 0;
+            while (at >= 0) {
+                occurrences++;
+                at = lower.indexOf(needle, at + needle.length);
+            }
+            matches += occurrences;
+            const isUserTurn = lower.includes('"role":"user"');
+            const isToolResult = lower.includes('"role":"toolresult"') || lower.includes('"role":"tool"');
+            if (isUserTurn)
+                userHits += occurrences;
+            else if (isToolResult)
+                toolHits += occurrences;
+            else
+                assistantHits += occurrences;
+            if (wholeWord.test(line))
+                wordHit = true;
+            if (!snippet) {
+                // A window around the match, not the start of the line. Session lines
+                // can be hundreds of kilobytes — a system prompt, a pasted log — and
+                // `slice(0, 160)` showed the boilerplate at the top instead of the
+                // words the reader searched for. A snippet that does not contain the
+                // query is not evidence.
+                snippet = excerpt(lineText(line), needle);
+            }
+        }
+        if (matches === 0)
+            continue;
+        // Presence, not volume, decides the class of evidence. Occurrences past the
+        // first add a little, so two mentions edge out one within the same class.
+        const score = (userHits > 0 ? 100 : 0) +
+            (assistantHits > 0 ? 10 : 0) +
+            Math.min(toolHits, 5) +
+            (wordHit ? 5 : 0) +
+            Math.min(matches, 10) / 100;
+        hits.push({ row, matches, score, snippet });
+    }
+    // Ties fall back to recency, which is what a person expects among equals.
+    return hits.sort((a, b) => b.score - a.score || b.row.modified - a.row.modified).slice(0, limit);
+}
+/** 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();
+}

package/dist/compaction-guard.js

@@ -0,0 +1,81 @@
+/**
+ * Consecutive failures before the breaker trips.
+ *
+ * Same value as the reference. Three is enough to distinguish a broken
+ * compaction from a transient API error, and small enough that the wasted calls
+ * stay negligible.
+ */
+export const MAX_CONSECUTIVE_FAILURES = 3;
+export function emptyGuardState() {
+    return { consecutiveFailures: 0, tripped: false };
+}
+/**
+ * Whether a compaction should be refused.
+ *
+ * Pure, so the policy is testable without a session: manual compaction is always
+ * allowed, and an untripped breaker allows everything.
+ */
+export function shouldSkipCompaction(state, reason) {
+    if (reason === "manual")
+        return false;
+    return state.consecutiveFailures >= MAX_CONSECUTIVE_FAILURES;
+}
+/** Fold one failure into the state. Aborts are not failures. */
+export function noteFailure(state, aborted) {
+    if (aborted)
+        return state;
+    const consecutiveFailures = state.consecutiveFailures + 1;
+    return {
+        consecutiveFailures,
+        tripped: state.tripped || consecutiveFailures >= MAX_CONSECUTIVE_FAILURES,
+    };
+}
+/** Fold one success into the state: the compaction worked, so the count resets. */
+export function noteSuccess() {
+    return emptyGuardState();
+}
+/** The message the user sees once, when the breaker trips. */
+export function breakerMessage(state) {
+    return [
+        `Auto-compaction failed ${state.consecutiveFailures} times in a row, so it is switched off for this session.`,
+        "The context is over the limit and compaction cannot recover it. Start a new session, or switch to a model with a larger context window.",
+        "Manual /compact is still allowed.",
+    ].join(" ");
+}
+let state = emptyGuardState();
+export function compactionGuardState() {
+    return state;
+}
+/** Test seam: forget the counts. */
+export function resetCompactionGuard() {
+    state = emptyGuardState();
+}
+/**
+ * Wire the breaker into the session.
+ *
+ * The refusal happens in `session_before_compact`, which the SDK consults before
+ * it runs the summariser — so a refused attempt costs no API call at all.
+ */
+export function createCompactionGuardExtension() {
+    return (hxf) => {
+        hxf.on("session_start", async () => {
+            state = emptyGuardState();
+        });
+        hxf.on("session_compact", async () => {
+            state = noteSuccess();
+        });
+        hxf.on("session_compact_failed", async (event, ctx) => {
+            const before = state;
+            state = noteFailure(state, event.aborted);
+            // Report the trip once, when it happens, rather than on every later turn.
+            if (!before.tripped && state.tripped && ctx?.ui) {
+                ctx.ui.notify(breakerMessage(state), "warning");
+            }
+        });
+        hxf.on("session_before_compact", async (event) => {
+            if (!shouldSkipCompaction(state, event.reason))
+                return undefined;
+            return { cancel: true };
+        });
+    };
+}

package/dist/connect-prompt.js

@@ -0,0 +1,22 @@
+export function createConnectPrompt() {
+    let restore = null;
+    return {
+        get armed() {
+            return restore !== null;
+        },
+        arm(next) {
+            // A second `/connect` replaces the first: the earlier prompt's restore
+            // must not run later and clobber the newer one.
+            restore = next;
+            return true;
+        },
+        disarm() {
+            const previous = restore;
+            if (previous === null)
+                return false;
+            restore = null;
+            previous();
+            return true;
+        },
+    };
+}

package/dist/context-extension.js

@@ -0,0 +1,17 @@
+import { readMessageText, writeMessageText } from "./prompt-text.js";
+import { renderNotes } from "./notes.js";
+export function createContextExtension() {
+    return (hxf) => {
+        hxf.on("context_with_system", async (event) => {
+            const notes = renderNotes();
+            if (!notes)
+                return undefined;
+            const head = event.messages[0];
+            if (!head || head.role !== "system")
+                return undefined;
+            const combined = `${readMessageText(head.content)}\n\n${notes}`;
+            const messages = event.messages.map((message) => (message === head ? { ...head, content: writeMessageText(head.content, combined) } : message));
+            return { messages };
+        });
+    };
+}