howtofixcli 0.7.24 → 0.7.26

package/dist/dcp/prune.js

@@ -0,0 +1,418 @@
+/**
+ * The prune transform: replaces stale context with fixed placeholders in the
+ * copy of the transcript that is sent to the LLM. The session itself is never
+ * touched — every function here is pure over a message array and returns new
+ * messages.
+ *
+ * Placeholder constants are verbatim from Opencode-DCP `lib/messages/prune.ts`,
+ * and the three appliers (`pruneToolOutputs` / `pruneToolInputs` /
+ * `pruneToolErrors`) plus `filterCompressedRanges` port DCP's mechanics to the harness's
+ * message shape: outputs live on `toolResult` messages, inputs on the
+ * `toolCall` parts inside assistant messages. On top of that sits `planPrune`,
+ * this repo's keep-set-aware planner (spec §3.4): three rules, each op carrying
+ * the reason it was planned.
+ *
+ * Hard exceptions, never planned or applied onto:
+ * - the `todo` / `goal` / `context` / `task` tools (HARD_EXCEPTION_TOOLS)
+ * - the plan file's results
+ * - user messages, assistant text/thinking (appliers only touch toolCall args)
+ * - the message at array index 0, whatever it says
+ *
+ * Safety rule: when the keep-set is empty, rule 3 (big unrelated output) is
+ * OFF — structural pruning (rules 1 and 2, dedup, compressed ranges) still
+ * runs, but nothing is dropped for being unrelated to a goal that does not
+ * exist.
+ *
+ * Pipeline order (spec §3.4): filterCompressedRanges → pruneToolOutputs →
+ * pruneToolInputs → pruneToolErrors.
+ */
+import { refIndicesOf } from "./ids.js";
+import { HARD_EXCEPTION_TOOLS, getFilePathsFromParameters, normalizePath } from "./protected.js";
+import { createToolSignature } from "./dedup.js";
+export const PRUNED_TOOL_OUTPUT_REPLACEMENT = "[Output removed to save context - information superseded or no longer needed]";
+export const PRUNED_TOOL_ERROR_INPUT_REPLACEMENT = "[input removed due to failed tool call]";
+export const PRUNED_QUESTION_INPUT_REPLACEMENT = "[questions removed - see output for user's answers]";
+/** Rule 3 threshold: outputs longer than this may be pruned when unrelated. */
+export const BIG_OUTPUT_CHARS = 2000;
+/** Tools that ask the user questions: their output holds the answers, so only
+ * their input is ever pruned (with PRUNED_QUESTION_INPUT_REPLACEMENT). */
+export const QUESTION_TOOLS = ["ask", "question"];
+/** Tools whose results feed rule 1 (superseded file reads). */
+const READ_TOOLS = ["read", "grep", "ls"];
+/** Tools whose success supersedes an earlier read of the same path (rule 1). */
+const MUTATING_TOOLS = ["edit", "write", "multiedit", "apply_patch", "patch"];
+function textOfResult(content) {
+    return content
+        .filter((part) => part.type === "text")
+        .map((part) => part.text)
+        .join("");
+}
+function stringArgTotal(args) {
+    if (!args)
+        return { total: 0, count: 0 };
+    let total = 0;
+    let count = 0;
+    for (const value of Object.values(args)) {
+        if (typeof value === "string") {
+            total += value.length;
+            count++;
+        }
+    }
+    return { total, count };
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Plan the prune: returns which tool calls to replace and why, without
+ * touching anything. Apply the result with `applyPrune`.
+ */
+export function planPrune(messages, keep, options) {
+    const bigOutputChars = options?.bigOutputChars ?? BIG_OUTPUT_CHARS;
+    const calls = new Map();
+    const results = [];
+    for (let index = 0; index < messages.length; index++) {
+        const message = messages[index];
+        if (message.role === "assistant") {
+            for (const part of message.content) {
+                if (part.type === "toolCall") {
+                    calls.set(part.id, { name: part.name, args: part.arguments, callIndex: index });
+                }
+            }
+        }
+        else if (message.role === "toolResult") {
+            const call = calls.get(message.toolCallId);
+            const tool = message.toolName;
+            results.push({
+                index,
+                callId: message.toolCallId,
+                tool,
+                isError: message.isError,
+                text: textOfResult(message.content),
+                paths: call ? getFilePathsFromParameters(tool, call.args) : [],
+                signature: createToolSignature(tool, call?.args),
+                callIndex: call?.callIndex ?? -1,
+            });
+        }
+    }
+    const planFile = keep.planFile ? normalizePath(keep.planFile) : undefined;
+    const isOutputExempt = (r) => r.index === 0 || HARD_EXCEPTION_TOOLS.includes(r.tool) || (planFile !== undefined && r.paths.some((p) => normalizePath(p) === planFile));
+    const isInputExempt = (r) => r.callIndex < 0 || r.callIndex === 0 || HARD_EXCEPTION_TOOLS.includes(r.tool) || (planFile !== undefined && r.paths.some((p) => normalizePath(p) === planFile));
+    const ops = [];
+    const emitted = new Set();
+    const emit = (op) => {
+        const key = `${op.kind}:${op.callId}`;
+        if (emitted.has(key))
+            return;
+        emitted.add(key);
+        ops.push(op);
+    };
+    // Rule 1 — a read/grep/ls result whose file was later edited or re-read.
+    // The newest result for the path stays; every older read is superseded.
+    const latestByPath = new Map();
+    for (const r of results) {
+        if (r.isError || (!READ_TOOLS.includes(r.tool) && !MUTATING_TOOLS.includes(r.tool)))
+            continue;
+        for (const path of r.paths) {
+            const key = normalizePath(path);
+            const previous = latestByPath.get(key);
+            if (previous === undefined || r.index > previous)
+                latestByPath.set(key, r.index);
+        }
+    }
+    for (const r of results) {
+        if (r.isError || !READ_TOOLS.includes(r.tool) || isOutputExempt(r))
+            continue;
+        // Already pruned: the paths are still attached, so without this the read
+        // looks superseded on every pass and the plan is never empty. Skipping it
+        // is what makes a second pass over a pruned transcript a no-op.
+        if (r.text === PRUNED_TOOL_OUTPUT_REPLACEMENT)
+            continue;
+        const superseded = r.paths.some((path) => (latestByPath.get(normalizePath(path)) ?? -1) > r.index);
+        if (superseded) {
+            emit({
+                kind: "output",
+                reason: "superseded-read",
+                callId: r.callId,
+                messageIndex: r.index,
+                savedChars: Math.max(0, r.text.length - PRUNED_TOOL_OUTPUT_REPLACEMENT.length),
+            });
+        }
+    }
+    // Rule 2 — an error result followed by an identical successful call: the
+    // error output is superseded, and the failed call's arguments (the most
+    // expensive part — a rejected patch) are useless now that the retry worked.
+    const latestSuccessBySignature = new Map();
+    for (const r of results) {
+        if (r.isError)
+            continue;
+        const previous = latestSuccessBySignature.get(r.signature);
+        if (previous === undefined || r.index > previous)
+            latestSuccessBySignature.set(r.signature, r.index);
+    }
+    for (const r of results) {
+        if (!r.isError || isOutputExempt(r))
+            continue;
+        const success = latestSuccessBySignature.get(r.signature);
+        if (success === undefined || success <= r.index)
+            continue;
+        emit({
+            kind: "output",
+            reason: "error-then-success",
+            callId: r.callId,
+            messageIndex: r.index,
+            savedChars: Math.max(0, r.text.length - PRUNED_TOOL_OUTPUT_REPLACEMENT.length),
+        });
+        if (!isInputExempt(r)) {
+            const args = calls.get(r.callId)?.args;
+            const { total, count } = stringArgTotal(args);
+            if (count > 0) {
+                emit({
+                    kind: "failed-input",
+                    reason: "error-then-success",
+                    callId: r.callId,
+                    messageIndex: r.callIndex,
+                    savedChars: Math.max(0, total - count * PRUNED_TOOL_ERROR_INPUT_REPLACEMENT.length),
+                });
+            }
+        }
+    }
+    // Rule 3 — an output over the threshold that does not touch the keep-set.
+    // OFF when the keep-set is empty: nothing is dropped for being unrelated to
+    // a goal that does not exist.
+    if (keep.files.length > 0 || keep.identifiers.length > 0) {
+        const touchFiles = [...keep.files.map(normalizePath), ...(planFile ? [planFile] : [])];
+        const basenames = touchFiles.map((file) => file.split("/").pop() ?? "").filter((name) => name.length > 0);
+        const identifierPatterns = keep.identifiers.map((identifier) => new RegExp(`(?<![\\w.-])${escapeRegExp(identifier)}(?![\\w.-])`));
+        const touchesKeep = (text) => {
+            const normalized = normalizePath(text);
+            if (touchFiles.some((file) => normalized.includes(file)))
+                return true;
+            if (basenames.some((name) => text.includes(name)))
+                return true;
+            return identifierPatterns.some((pattern) => pattern.test(text));
+        };
+        for (const r of results) {
+            if (isOutputExempt(r) || QUESTION_TOOLS.includes(r.tool))
+                continue;
+            if (r.text.length <= bigOutputChars)
+                continue;
+            if (touchesKeep(r.text))
+                continue;
+            emit({
+                kind: "output",
+                reason: "unrelated-big-output",
+                callId: r.callId,
+                messageIndex: r.index,
+                savedChars: Math.max(0, r.text.length - PRUNED_TOOL_OUTPUT_REPLACEMENT.length),
+            });
+        }
+    }
+    let savedChars = 0;
+    for (const op of ops)
+        savedChars += op.savedChars;
+    return { ops, savedChars };
+}
+/** Apply planned ops to a copy of the transcript, in DCP's order:
+ * outputs → question inputs → failed inputs. Pure; input is never mutated. */
+export function applyPrune(messages, ops) {
+    const outputs = new Set();
+    const questions = new Set();
+    const failures = new Set();
+    for (const op of ops) {
+        if (op.kind === "output")
+            outputs.add(op.callId);
+        else if (op.kind === "question-input")
+            questions.add(op.callId);
+        else
+            failures.add(op.callId);
+    }
+    return pruneToolErrors(pruneToolInputs(pruneToolOutputs(messages, outputs), questions), failures);
+}
+/** Replace the toolResult content of every marked call with the output
+   placeholder. Question tools are skipped — their answers live in the output
+   and their input is pruned instead. Never touches array index 0. */
+export function pruneToolOutputs(messages, marks) {
+    if (marks.size === 0)
+        return [...messages];
+    return messages.map((message, index) => {
+        if (index === 0 || message.role !== "toolResult" || !marks.has(message.toolCallId))
+            return message;
+        if (QUESTION_TOOLS.includes(message.toolName))
+            return message;
+        return { ...message, content: [{ type: "text", text: PRUNED_TOOL_OUTPUT_REPLACEMENT }] };
+    });
+}
+/** For marked, successfully answered question tools (ask/question), replace
+   the question-bearing input fields — the answers are in the output. */
+export function pruneToolInputs(messages, marks) {
+    if (marks.size === 0)
+        return [...messages];
+    const answered = new Set();
+    for (const message of messages) {
+        if (message.role === "toolResult" && !message.isError && marks.has(message.toolCallId)) {
+            answered.add(message.toolCallId);
+        }
+    }
+    if (answered.size === 0)
+        return [...messages];
+    return messages.map((message, index) => {
+        if (index === 0 || message.role !== "assistant")
+            return message;
+        let changed = false;
+        const content = message.content.map((part) => {
+            if (part.type !== "toolCall" || !answered.has(part.id) || !QUESTION_TOOLS.includes(part.name))
+                return part;
+            const args = { ...part.arguments };
+            let touched = false;
+            for (const field of ["question", "questions", "options"]) {
+                if (field in args) {
+                    args[field] = PRUNED_QUESTION_INPUT_REPLACEMENT;
+                    touched = true;
+                }
+            }
+            if (!touched)
+                return part;
+            changed = true;
+            return { ...part, arguments: args };
+        });
+        return changed ? { ...message, content } : message;
+    });
+}
+/** For marked calls whose tool result is an error, replace every string
+   argument with the failed-call placeholder — a rejected patch's arguments are
+   the most expensive dead weight in the transcript. */
+export function pruneToolErrors(messages, marks) {
+    if (marks.size === 0)
+        return [...messages];
+    const failed = new Set();
+    for (const message of messages) {
+        if (message.role === "toolResult" && message.isError && marks.has(message.toolCallId)) {
+            failed.add(message.toolCallId);
+        }
+    }
+    if (failed.size === 0)
+        return [...messages];
+    return messages.map((message, index) => {
+        if (index === 0 || message.role !== "assistant")
+            return message;
+        let changed = false;
+        const content = message.content.map((part) => {
+            if (part.type !== "toolCall" || !failed.has(part.id))
+                return part;
+            const args = {};
+            let hasString = false;
+            for (const [key, value] of Object.entries(part.arguments)) {
+                if (typeof value === "string") {
+                    args[key] = PRUNED_TOOL_ERROR_INPUT_REPLACEMENT;
+                    hasString = true;
+                }
+                else {
+                    args[key] = value;
+                }
+            }
+            if (!hasString)
+                return part;
+            changed = true;
+            return { ...part, arguments: args };
+        });
+        return changed ? { ...message, content } : message;
+    });
+}
+/** Drop every message covered by an active compressed range and insert the
+   block's summary (a synthetic user message) at the anchor position. Unref'd
+   positions — the system message above all — can never be covered. */
+export function filterCompressedRanges(messages, ranges, state) {
+    if (ranges.length === 0)
+        return [...messages];
+    const refs = refIndicesOf(state, messages);
+    const posByRef = new Map();
+    for (let pos = 0; pos < refs.length; pos++) {
+        const ref = refs[pos];
+        if (ref !== null)
+            posByRef.set(ref, pos);
+    }
+    const covered = new Set();
+    const summaries = new Map();
+    for (const range of ranges) {
+        const positions = [];
+        for (const coveredIndex of range.coveredIndices) {
+            const pos = posByRef.get(coveredIndex);
+            if (pos !== undefined) {
+                covered.add(pos);
+                positions.push(pos);
+            }
+        }
+        const anchorPos = posByRef.get(range.anchorIndex) ?? (positions.length > 0 ? Math.min(...positions) : undefined);
+        if (range.summary && anchorPos !== undefined) {
+            const existing = summaries.get(anchorPos);
+            if (existing)
+                existing.push(range.summary);
+            else
+                summaries.set(anchorPos, [range.summary]);
+        }
+    }
+    // A tool call and its result are one exchange, and a provider rejects a
+    // transcript where they are separated: an assistant message calling a tool
+    // whose result is absent is an invalid request, and that is what the 400 from
+    // the provider was. So the covered set is closed over exchanges first - if
+    // either half is covered, both are - before anything is dropped.
+    //
+    // Nothing before this noticed because every fixture compressed whole
+    // exchanges; a range boundary landing between a call and its result is what
+    // a real model produces.
+    const callIdByPosition = new Map();
+    const resultPositionByCallId = new Map();
+    for (let position = 0; position < messages.length; position++) {
+        const message = messages[position];
+        if (!message)
+            continue;
+        if (message.role === "assistant" && Array.isArray(message.content)) {
+            for (const part of message.content) {
+                if (part.type === "toolCall")
+                    callIdByPosition.set(position, part.id);
+            }
+        }
+        else if (message.role === "toolResult") {
+            resultPositionByCallId.set(message.toolCallId, position);
+        }
+    }
+    // One pass over a worklist rather than nested scans: a position pulled in can
+    // pull in another exchange behind it.
+    const queue = [...covered];
+    while (queue.length > 0) {
+        const position = queue.pop();
+        const callId = callIdByPosition.get(position);
+        if (callId !== undefined) {
+            const resultPosition = resultPositionByCallId.get(callId);
+            if (resultPosition !== undefined && !covered.has(resultPosition)) {
+                covered.add(resultPosition);
+                queue.push(resultPosition);
+            }
+        }
+        const message = messages[position];
+        if (message?.role === "toolResult") {
+            for (const [callPosition, id] of callIdByPosition) {
+                if (id === message.toolCallId && !covered.has(callPosition)) {
+                    covered.add(callPosition);
+                    queue.push(callPosition);
+                }
+            }
+        }
+    }
+    const out = [];
+    for (let index = 0; index < messages.length; index++) {
+        const pending = summaries.get(index);
+        if (pending) {
+            const anchor = messages[index];
+            for (const summary of pending) {
+                const synthetic = { role: "user", content: summary, timestamp: anchor.timestamp };
+                out.push(synthetic);
+            }
+        }
+        if (covered.has(index))
+            continue;
+        out.push(messages[index]);
+    }
+    return out;
+}

package/dist/dcp/state.js

@@ -0,0 +1,176 @@
+/**
+ * DCP session state: what has been pruned, what has been compressed, and the
+ * three-layer switch that decides whether any of it runs.
+ *
+ * Two responsibilities live here deliberately:
+ *
+ * 1. **The on/off switch** (spec §2). `HOWTOFIX_DCP` (env, strongest) →
+ *    `enabled` in `<cwd>/.howtofix/dcp.json` (config) → the session's own
+ *    `/dcp on|off` override (weakest) → default on. Every resolution reports
+ *    WHICH layer decided, so `/dcp` can say "off (config)" instead of a bare
+ *    value the user cannot attribute — the pattern `antislopEnabled` in
+ *    `paths.ts` uses for the skill suite. The config layer is read once when
+ *    the extension is created (spec §2), so `resolveDcpEnabled` takes the
+ *    layers as plain values and stays pure; `readConfigEnabled` is the file
+ *    read the factory and the `/dcp` command each perform for themselves.
+ *
+ * 2. **The per-session state file** (spec §3.6): prune marks, compressed
+ *    blocks with their anchors, the block/run id counters, and the savings
+ *    stats. Plain JSON under `AGENT_DIR/dcp/<session>.json` — machine state,
+ *    not a project document, so it is never git-backed — written atomically
+ *    like every other persisted state file in this codebase. Loaded into a
+ *    per-session cache so the request handler and the slash commands mutate
+ *    one object instead of racing load-modify-save cycles.
+ */
+import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { writeFileAtomicSync } from "../fs-atomic.js";
+import { AGENT_DIR } from "../paths.js";
+import { createMessageIdState } from "./ids.js";
+/**
+ * Read `enabled` from `<cwd>/.howtofix/dcp.json`.
+ *
+ * Returns `undefined` when the file is missing, unparseable, or holds no
+ * boolean there: a broken config is "no decision", not an error, because the
+ * next layer down must still get its say — same rule as `configuredAntislop`.
+ */
+export function readConfigEnabled(cwd) {
+    try {
+        const file = join(cwd, ".howtofix", "dcp.json");
+        if (!existsSync(file))
+            return undefined;
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (typeof parsed !== "object" || parsed === null)
+            return undefined;
+        const enabled = parsed.enabled;
+        return typeof enabled === "boolean" ? enabled : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The three-layer switch, strongest layer first (spec §2):
+ *
+ * 1. `HOWTOFIX_DCP` — `0`/`false` off, any other value on. Wins both ways,
+ *    because it is how one person disables pruning across every project at
+ *    once while chasing a suspected pruning bug.
+ * 2. `enabled` in `.howtofix/dcp.json` — the per-project say.
+ * 3. The session's `/dcp on|off` override — consulted only when neither
+ *    layer above decided, so it persists across a resume of the same session
+ *    without out-ranking the project's own config.
+ * 4. Default: on.
+ */
+export function resolveDcpEnabled(layers) {
+    if (layers.env !== undefined) {
+        const value = layers.env.trim().toLowerCase();
+        return { enabled: value !== "0" && value !== "false", source: "env" };
+    }
+    if (layers.config !== undefined)
+        return { enabled: layers.config, source: "config" };
+    if (layers.runtime !== undefined)
+        return { enabled: layers.runtime, source: "session" };
+    return { enabled: true, source: "default" };
+}
+/** A fresh state: no marks, no blocks, counters start where validation expects them. */
+export function createDcpState() {
+    return {
+        messageIds: createMessageIdState(),
+        prune: { tools: {}, messages: { blocks: [], nextBlockId: 1, nextRunId: 1 } },
+        stats: { totalPruneTokens: 0, totalCompressTokens: 0 },
+    };
+}
+/**
+ * Where a session's state is stored. Session ids are already file-safe, but
+ * normalise anyway: this value builds a path, and a stray separator here would
+ * write outside the dcp directory.
+ */
+export function dcpStatePath(sessionId) {
+    const safe = sessionId.replace(/[^A-Za-z0-9._-]/g, "_") || "session";
+    return join(AGENT_DIR, "dcp", `${safe}.json`);
+}
+function isDcpState(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const state = value;
+    const messages = state.prune?.messages;
+    const ids = state.messageIds;
+    return (typeof state.prune === "object" &&
+        state.prune !== null &&
+        typeof state.prune.tools === "object" &&
+        state.prune.tools !== null &&
+        typeof messages === "object" &&
+        messages !== null &&
+        Array.isArray(messages.blocks) &&
+        Number.isInteger(messages.nextBlockId) &&
+        Number.isInteger(messages.nextRunId) &&
+        typeof ids === "object" &&
+        ids !== null &&
+        Number.isInteger(ids.nextRef) &&
+        typeof ids.keyToRef === "object" &&
+        ids.keyToRef !== null &&
+        typeof ids.refToKey === "object" &&
+        ids.refToKey !== null &&
+        typeof state.stats === "object" &&
+        state.stats !== null &&
+        Number.isFinite(state.stats.totalPruneTokens) &&
+        Number.isFinite(state.stats.totalCompressTokens));
+}
+/**
+ * Per-session cache. The handler runs before every LLM call and the slash
+ * commands mutate between them; one live object per session keeps them from
+ * overwriting each other's load-modify-save cycles.
+ */
+const states = new Map();
+/** The session's state, loaded from disk on first touch. */
+export function getDcpState(sessionId) {
+    const cached = states.get(sessionId);
+    if (cached)
+        return cached;
+    let loaded;
+    try {
+        const file = dcpStatePath(sessionId);
+        if (existsSync(file)) {
+            const parsed = JSON.parse(readFileSync(file, "utf8"));
+            if (isDcpState(parsed))
+                loaded = parsed;
+        }
+    }
+    catch {
+        // An unreadable or hand-mangled state file starts fresh rather than
+        // killing every request with a parse error.
+        loaded = undefined;
+    }
+    const state = loaded ?? createDcpState();
+    states.set(sessionId, state);
+    return state;
+}
+/** Persist the cached state for this session. No-op before first touch. */
+export function saveDcpState(sessionId) {
+    const state = states.get(sessionId);
+    if (!state)
+        return;
+    const file = dcpStatePath(sessionId);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileAtomicSync(file, JSON.stringify(state));
+}
+/**
+ * Drop a session's state, in memory and on disk.
+ *
+ * The cache is process-wide and keyed by session, and the file under
+ * `AGENT_DIR/dcp/` is one per session. Neither had a delete: `/new` and
+ * `/resume` replace the session, but the previous one's ref maps and its file
+ * stayed for good. The design spec says the state is deleted when the session
+ * is discarded. A later resume of the same session finds no file and starts
+ * fresh, which is the correct state for a session that was thrown away — the
+ * refs it stored pointed at a transcript that no longer exists.
+ */
+export function dropDcpState(sessionId) {
+    states.delete(sessionId);
+    try {
+        unlinkSync(dcpStatePath(sessionId));
+    }
+    catch {
+        // Already gone is the state we wanted.
+    }
+}

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));
+}