howtofixcli 0.7.24 → 0.7.26

package/dist/web.js

@@ -0,0 +1,265 @@
+import { promises as dns } from "node:dns";
+const PRIVATE_V4 = /^(127\.|10\.|192\.168\.|169\.254\.|0\.|221\.|222\.|223\.)/;
+// 172.16.0.0/12 is the remaining RFC1918 block.
+function isRfc1918(host) {
+    if (PRIVATE_V4.test(host))
+        return true;
+    const m = /^172\.(\d+)\./.exec(host);
+    if (!m)
+        return false;
+    const second = Number(m[1]);
+    return second >= 16 && second <= 31;
+}
+/**
+ * Carrier-grade NAT (100.64.0.0/10) and the benchmarking block (198.18.0.0/15)
+ * are special-use like RFC1918: not routable on the public internet, and both
+ * have shown up in SSRF bypass lists.
+ */
+function isSpecialUseIpv4(host) {
+    const m = /^100\.(\d+)\.(\d+)\.(\d+)$/.exec(host);
+    if (m) {
+        const second = Number(m[1]);
+        return second >= 64 && second <= 127;
+    }
+    const b = /^198\.(\d+)\./.exec(host);
+    return b !== null && (Number(b[1]) === 18 || Number(b[1]) === 19);
+}
+/**
+ * Every address form that must never be fetched: RFC1918 plus special-use
+ * IPv4, and the IPv6 equivalents — loopback, unspecified, ULA (fc00::/7),
+ * link-local (fe80::/10), and IPv4-mapped (::ffff:a.b.c.d), which otherwise
+ * smuggles a private v4 address past a v6-shaped check. Used for both URL
+ * hostnames and resolved DNS answers, so the two layers cannot disagree.
+ */
+export function isPrivateAddress(raw) {
+    const host = raw
+        .toLowerCase()
+        .replace(/^\[|\]$/g, "")
+        .split("%")[0];
+    if (host === "localhost" || host.endsWith(".localhost"))
+        return true;
+    const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(host);
+    if (mapped) {
+        const v4 = mapped[1];
+        return isRfc1918(v4) || isSpecialUseIpv4(v4) || v4 === "0.0.0.0";
+    }
+    // The URL parser canonises ::ffff:a.b.c.d to the hex-pair form
+    // (::ffff:7f00:1); both forms carry a v4 address in the last 32 bits.
+    const mappedHex = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(host);
+    if (mappedHex) {
+        const hi = Number.parseInt(mappedHex[1], 16);
+        const lo = Number.parseInt(mappedHex[2], 16);
+        const v4 = `${(hi >> 8) & 255}.${hi & 255}.${(lo >> 8) & 255}.${lo & 255}`;
+        return isRfc1918(v4) || isSpecialUseIpv4(v4) || v4 === "0.0.0.0";
+    }
+    if (host.includes(":")) {
+        if (host === "::1" || host === "::")
+            return true;
+        if (/^f[cd][0-9a-f]{2}:/.test(host))
+            return true; // fc00::/7 ULA
+        if (/^fe[89ab][0-9a-f]:/.test(host))
+            return true; // fe80::/10 link-local
+        return false;
+    }
+    if (host === "0.0.0.0")
+        return true;
+    return isRfc1918(host) || isSpecialUseIpv4(host);
+}
+export const MAX_FETCH_CHARS = 80_000;
+export const SEARCH_LIMIT = 8;
+export function isPublicHttpUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return { ok: false, reason: "not a URL" };
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        return { ok: false, reason: `refused protocol ${url.protocol}` };
+    }
+    const host = url.hostname.toLowerCase();
+    if (host === "localhost" || host.endsWith(".localhost") || host === "::1" || host === "[::1]") {
+        return { ok: false, reason: "refused loopback host" };
+    }
+    if (isPrivateAddress(host))
+        return { ok: false, reason: "refused private address" };
+    return { ok: true, url };
+}
+export function htmlToText(html) {
+    const without = html
+        .replace(/<script[\s\S]*?<\/script>/gi, " ")
+        .replace(/<style[\s\S]*?<\/style>/gi, " ")
+        .replace(/<noscript[\s\S]*?<\/noscript>/gi, " ")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/&nbsp;/g, " ")
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/\s+/g, " ")
+        .trim();
+    return without.length > MAX_FETCH_CHARS ? without.slice(0, MAX_FETCH_CHARS) : without;
+}
+export function parseDuckDuckGo(html) {
+    const hits = [];
+    const re = /class="result__a"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/gi;
+    let match;
+    while ((match = re.exec(html)) && hits.length < SEARCH_LIMIT) {
+        const href = match[1] ?? "";
+        const title = htmlToText(match[2] ?? "");
+        let url = href;
+        const uddg = /[?&]uddg=([^&]+)/.exec(href);
+        if (uddg) {
+            try {
+                url = decodeURIComponent(uddg[1]);
+            }
+            catch {
+                url = href;
+            }
+        }
+        else if (href.startsWith("//")) {
+            url = `https:${href}`;
+        }
+        const allowed = isPublicHttpUrl(url);
+        if (!allowed.ok || !title)
+            continue;
+        hits.push({ title, url: allowed.url.toString(), snippet: "" });
+    }
+    return hits;
+}
+const DEFAULT_UA = "HowToFix (https://howtofix.id)";
+export async function searchWeb(query, options = {}) {
+    const q = query.trim();
+    if (!q)
+        return { ok: false, error: "empty query" };
+    const fetchFn = options.fetchFn ?? fetch;
+    const timeout = options.timeoutMs ?? 15_000;
+    const headers = { "user-agent": options.userAgent ?? DEFAULT_UA, accept: "text/html, application/json" };
+    try {
+        if (options.braveKey) {
+            const url = `https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(q)}&count=${SEARCH_LIMIT}`;
+            const response = await fetchFn(url, {
+                headers: { ...headers, accept: "application/json", "x-subscription-token": options.braveKey },
+                signal: AbortSignal.timeout(timeout),
+            });
+            if (!response.ok)
+                return { ok: false, error: `brave ${response.status}` };
+            const hits = parseBrave(await response.json());
+            return { ok: true, hits, provider: "brave" };
+        }
+        const url = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(q)}`;
+        const response = await fetchFn(url, { headers, signal: AbortSignal.timeout(timeout) });
+        if (!response.ok)
+            return { ok: false, error: `search ${response.status}` };
+        const hits = parseDuckDuckGo(await response.text());
+        return { ok: true, hits, provider: "ddg" };
+    }
+    catch (cause) {
+        return { ok: false, error: cause instanceof Error ? cause.message : String(cause) };
+    }
+}
+export function parseBrave(payload) {
+    let rows = [];
+    if (payload && typeof payload === "object" && "web" in payload) {
+        const web = payload.web;
+        if (web && typeof web === "object" && "results" in web && Array.isArray(web.results)) {
+            rows = web.results;
+        }
+    }
+    const hits = [];
+    for (const row of rows) {
+        if (!row || typeof row !== "object" || !("url" in row) || !("title" in row))
+            continue;
+        const url = row.url;
+        const title = row.title;
+        if (typeof url !== "string" || typeof title !== "string")
+            continue;
+        const allowed = isPublicHttpUrl(url);
+        if (!allowed.ok)
+            continue;
+        const description = "description" in row ? row.description : undefined;
+        hits.push({
+            title,
+            url: allowed.url.toString(),
+            snippet: typeof description === "string" ? description : "",
+        });
+        if (hits.length >= SEARCH_LIMIT)
+            break;
+    }
+    return hits;
+}
+const MAX_REDIRECTS = 5;
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/**
+ * The hostname half of the SSRF check: `isPublicHttpUrl` only sees the name,
+ * and a public name can resolve anywhere. Every answer must be public — one
+ * private record poisons the fetch, because the connection goes wherever DNS
+ * says. IP literals are skipped here: they were already judged directly.
+ */
+async function resolvePublicHost(hostname, lookup) {
+    const bare = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    if (bare.includes(":") || /^[\d.]+$/.test(bare))
+        return { ok: true };
+    let addresses;
+    try {
+        addresses = await lookup(bare);
+    }
+    catch (cause) {
+        return { ok: false, error: `could not resolve ${hostname}: ${cause instanceof Error ? cause.message : String(cause)}` };
+    }
+    if (addresses.length === 0)
+        return { ok: false, error: `could not resolve ${hostname}` };
+    const bad = addresses.find((address) => isPrivateAddress(address));
+    if (bad !== undefined)
+        return { ok: false, error: `refused ${hostname}: resolves to private address ${bad}` };
+    return { ok: true };
+}
+export async function fetchUrl(raw, options = {}) {
+    const allowed = isPublicHttpUrl(raw);
+    if (!allowed.ok)
+        return { ok: false, error: allowed.reason };
+    const fetchFn = options.fetchFn ?? fetch;
+    const lookup = options.lookup ?? ((hostname) => dns.lookup(hostname, { all: true }).then((rows) => rows.map((row) => row.address)));
+    const signal = AbortSignal.timeout(options.timeoutMs ?? 20_000);
+    const headers = { "user-agent": options.userAgent ?? DEFAULT_UA, accept: "text/html, text/plain, application/json" };
+    try {
+        // Redirects are followed by hand, not by fetch: every hop passes the same
+        // URL and DNS checks as the first URL. `redirect: "follow"` would take the
+        // connection wherever a 302 pointed — the classic SSRF bypass of a
+        // one-time check.
+        let current = allowed.url;
+        for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+            const hopCheck = isPublicHttpUrl(current.toString());
+            if (!hopCheck.ok)
+                return { ok: false, error: `redirect refused: ${hopCheck.reason}` };
+            const resolved = await resolvePublicHost(hopCheck.url.hostname, lookup);
+            if (!resolved.ok)
+                return { ok: false, error: resolved.error };
+            const response = await fetchFn(hopCheck.url, { headers, signal, redirect: "manual" });
+            if (REDIRECT_STATUSES.has(response.status)) {
+                const location = response.headers.get("location");
+                if (!location)
+                    return { ok: false, error: `HTTP ${response.status} without a location` };
+                try {
+                    current = new URL(location, hopCheck.url);
+                }
+                catch {
+                    return { ok: false, error: "redirect location is not a URL" };
+                }
+                continue;
+            }
+            if (!response.ok)
+                return { ok: false, error: `HTTP ${response.status}` };
+            const contentType = response.headers.get("content-type") ?? "";
+            const body = await response.text();
+            const text = /html/i.test(contentType) ? htmlToText(body) : body.slice(0, MAX_FETCH_CHARS);
+            return { ok: true, url: current.toString(), contentType, text };
+        }
+        return { ok: false, error: `too many redirects (max ${MAX_REDIRECTS})` };
+    }
+    catch (cause) {
+        return { ok: false, error: cause instanceof Error ? cause.message : String(cause) };
+    }
+}

package/dist/welcome.js

@@ -0,0 +1,179 @@
+/**
+ * The screen a first-time user meets.
+ *
+ * Every other CLI in this space prints a line and drops you at an empty prompt,
+ * which tells a new user nothing about what the tool is or what to do next. This
+ * is the deliberate alternative: on the very first interactive start, before the
+ * editor takes over, welcome the user, show the handful of commands that actually
+ * matter, and offer to sign in right there.
+ *
+ * Three rules shape everything below.
+ *
+ *  1. It runs ONCE. Marking the greeting as seen is the first thing that happens,
+ *     before the user answers anything, so no exit — picking an option, pressing
+ *     Escape, or the terminal going away — can leave it to appear again. It is a
+ *     greeting, not a gate.
+ *  2. It never invents a second sign-in path. "Sign in" runs the same `/connect`
+ *     slash command the user would type, so there is one flow to maintain: when
+ *     `connect` changes, this screen changes with it.
+ *  3. It is interactive only. `--print` never reaches here, so piping the CLI into
+ *     a script cannot stall on a question nobody is there to answer.
+ */
+import { AGENT_DIR } from "./paths.js";
+import { APP_TITLE, APP_VERSION } from "./brand.js";
+import { readWorkbenchSettings, markWelcomeSeen } from "./settings.js";
+/**
+ * What the greeting teaches, in the order a new user needs it.
+ *
+ * One list, filtered per state, rather than a branch per state: the signed-out
+ * screen drops nothing and the signed-in screen drops `/connect`, so the two can
+ * never drift into disagreeing about what `/help` means.
+ */
+const CHEAT_SHEET = [
+    ["/connect", "sign in with your howtofix.id email:password — no browser needed"],
+    ["/model", "choose which model answers"],
+    ["/help", "list every command"],
+    ["/quit", "leave"],
+];
+/**
+ * The wordmark, in two alphabets.
+ *
+ * The block version is the one to prefer: solid and box-drawing characters read as a
+ * logo rather than as text. But every character in it is East Asian *Ambiguous* —
+ * measured, all seven of them — so a terminal in a CJK locale or with "wide" set
+ * gives each glyph two columns instead of one. The rows then wrap, and a logo becomes
+ * a smear of half-drawn boxes.
+ *
+ * The ASCII version is 23 columns of pure printable ASCII, so it is one column per
+ * character everywhere: any locale, any code page, including terminals that are not
+ * UTF-8 at all (a `cmd.exe` on cp936 or a shell with `LANG=C` turns the block version
+ * into mojibake, because every character is above U+007F).
+ *
+ * Picked per render, not per build, because the terminal that runs an npm-installed
+ * CLI is whatever the user happens to have — see `terminalTakesWideBox()`. A real
+ * console on Windows is excluded deliberately: it is the one environment where Per's
+ * size check holds, and the block dial's Unicode rendering is also a defect there.
+ */
+const WORDMARK_BLOCKS = [
+    "  ██╗  ██╗██╗  ██╗███████╗",
+    "  ██║  ██║╚██╗██╔╝██╔════╝",
+    "  ███████║ ╚███╔╝ █████╗  ",
+    "  ██╔══██║ ██╔██╗ ██╔══╝  ",
+    "  ██║  ██║██╔╝ ██╗██║     ",
+    "  ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝     ",
+];
+const WORDMARK_ASCII = [
+    " _   _           _____ ",
+    "| | | | __  __  |  ___|",
+    "| |_| | \\ \\/ /  | |_   ",
+    "|  _  |  >  <   |  _|  ",
+    "|_| |_| /_/\\_\\  |_|    ",
+];
+/**
+ * Whether this terminal gives a box-drawing or block character one column.
+ *
+ * Two independent things have to hold, and each is checked where it can be known:
+ *
+ *  - **Unicode is usable.** The block set is all above U+007F, so a non-UTF-8 locale
+ *    renders it as mojibake. `LANG`/`LC_ALL`/`LC_CTYPE` say so directly and are the
+ *    only reliable signal — Windows keeps its console code page in a syscall rather
+ *    than an environment variable, so a console there answers "no" by default.
+ *  - **The width is one column.** Every glyph in the set is East Asian *Ambiguous*,
+ *    and an ambiguous character is two columns in a CJK locale or under the "wide"
+ *    setting; `LC_ALL=ja_JP.UTF-8` is the case a real user hits.
+ */
+function terminalTakesWideBox() {
+    // A native console is the case where Per's rule holds — an ambiguous character is
+    // one column — but it also mangles the block dial this CLI draws, so on Windows the
+    // logo gets a safe shape and the HUD is left to guard itself.
+    if (process.platform === "win32")
+        return false;
+    const locale = (process.env.LC_ALL || process.env.LC_CTYPE || process.env.LANG || "").toLowerCase();
+    // No locale at all: the byte-oriented default. Assume the narrow ASCII alphabet.
+    if (locale === "" || locale === "c" || locale === "posix")
+        return false;
+    if (!locale.includes("utf-8") && !locale.includes("utf8"))
+        return false;
+    // An "ambiguous is wide" locale: the block set would double in width.
+    const cjk = /ja|ko|zh|_kr|_jp|_cn|_tw|_hk/.test(locale);
+    return !cjk;
+}
+/** The wordmark this terminal can draw. */
+function wordmark() {
+    if (!terminalTakesWideBox())
+        return WORDMARK_ASCII;
+    return WORDMARK_BLOCKS;
+}
+/** Where the "what's new" option sends a reader. */
+const RELEASE_NOTES_URL = "https://howtofix.id/cli";
+/**
+ * Shrink a path for display: home becomes `~`, and anything before the last two
+ * segments is elided.
+ *
+ * The greeting has one row to say where the user is, and a deep worktree path
+ * would push everything else off it. The tail identifies the directory, so the
+ * front is what gets dropped.
+ */
+function shortenPath(cwd) {
+    const home = process.env.HOME ?? "";
+    const display = home !== "" && cwd.startsWith(home) ? `~${cwd.slice(home.length)}` : cwd;
+    const parts = display.split("/").filter(Boolean);
+    return parts.length > 3 ? `…/${parts.slice(-2).join("/")}` : display;
+}
+/** The body of the greeting, as one block of text the feed already knows how to draw. */
+function welcomeBody(options) {
+    const cheat = options.signedIn ? CHEAT_SHEET.filter(([command]) => command !== "/connect") : CHEAT_SHEET;
+    return [
+        ...wordmark(),
+        "",
+        `${APP_TITLE} ${APP_VERSION} — a terminal coding agent. Describe the change you want and it reads, edits and runs the code in front of you.`,
+        "",
+        `  working in  ${shortenPath(options.cwd)}`,
+        ...(options.note ? [`  session     ${options.note}`] : []),
+        "",
+        ...(options.signedIn ? ["  already signed in to howtofix.id", ""] : []),
+        ...cheat.map(([command, summary]) => `  ${command.padEnd(11)}${summary}`),
+        "",
+        '  Or just start typing. Every message goes to the model; anything beginning with "/" stays local.',
+    ].join("\n");
+}
+/** The choices offered when the user has no credential yet. */
+function firstRunChoices() {
+    return [
+        { value: "connect", label: "Sign in to howtofix.id", description: "opens the browser, or paste a key from the panel" },
+        { value: "ready", label: "I have a key — just give me the prompt", description: "drops you at the prompt; run /connect whenever you like" },
+        { value: "release", label: "What's in this release", description: `opens the ${APP_VERSION} notes in your browser` },
+    ];
+}
+/**
+ * Show the welcome screen when — and only when — this is the user's first
+ * interactive run.
+ *
+ * Resolves once the screen is out of the way, so the caller can await it before
+ * doing anything that writes to the same rows. Resolves immediately when the
+ * screen has already been shown, which keeps the call site free of a branch.
+ */
+export async function maybeShowWelcome(options, choose, note) {
+    // A settings file that cannot be read falls back to the defaults, and
+    // `welcomeSeen` defaults to false — so a broken file shows the greeting again
+    // rather than silently swallowing it. That is the harmless direction to fail.
+    if (readWorkbenchSettings(AGENT_DIR).welcomeSeen)
+        return;
+    // Claimed before the user is asked anything, so every exit from here — an
+    // answer, an Escape, or a terminal that closes — leaves the flag written.
+    markWelcomeSeen(AGENT_DIR);
+    note(`welcome to ${APP_TITLE}`, welcomeBody(options));
+    // Already signed in: nothing to decide, so stop at the greeting rather than
+    // asking a question whose answer is already on disk.
+    if (options.signedIn)
+        return;
+    await new Promise((settle) => {
+        choose("First run — how do you want to begin?", firstRunChoices(), (value) => {
+            if (value === "connect")
+                options.runSlash("/connect");
+            if (value === "release")
+                options.openExternal(RELEASE_NOTES_URL);
+            settle();
+        }, () => settle());
+    });
+}