howtofixcli 0.7.24 → 0.7.26

package/dist/repo-map.js

@@ -0,0 +1,292 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { extname, join, relative, resolve, sep } from "node:path";
+import { Type } from "@netrodev/hxf-ai";
+import { defineTool } from "@netrodev/hxf-coding-agent";
+/**
+ * A ranked outline of the repository, built without a parser dependency.
+ *
+ * The model cannot read a large tree, and listing every file is worse than
+ * useless: it spends the budget evenly on files that matter and files that do
+ * not. This walks the tree, pulls the declarations out of each file, follows the
+ * relative imports between them, and ranks by how much of the code depends on a
+ * file — the same idea as a tree-sitter repo map, done with regexes so it works
+ * on any machine without native builds.
+ *
+ * The ranking is the point. A file that ten others import is more likely to be
+ * the one worth reading than a file nobody mentions, and a symbol outline says
+ * what is in it before a single line is opened.
+ */
+const SKIP_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    "out",
+    "coverage",
+    "vendor",
+    "target",
+    "__pycache__",
+    ".venv",
+    "venv",
+    ".next",
+    ".turbo",
+    ".cache",
+]);
+const LANGUAGES = {
+    ".ts": {
+        kind: "ts",
+        patterns: [
+            /^\s*export\s+(?:default\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/gm,
+            /^\s*export\s+(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)/gm,
+            /^\s*export\s+(?:interface|type)\s+([A-Za-z_$][\w$]*)/gm,
+            /^\s*export\s+const\s+([A-Za-z_$][\w$]*)/gm,
+            /^\s*(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/gm,
+            /^\s*(?:export\s+)?class\s+([A-Za-z_$][\w$]*)/gm,
+        ],
+    },
+    ".tsx": { kind: "tsx", patterns: [] },
+    ".js": { kind: "js", patterns: [] },
+    ".mjs": { kind: "js", patterns: [] },
+    ".go": {
+        kind: "go",
+        patterns: [
+            /^func\s+(?:\([^)]*\)\s*)?([A-Za-z_]\w*)/gm,
+            /^type\s+([A-Za-z_]\w*)\s+(?:struct|interface)/gm,
+        ],
+    },
+    ".py": {
+        kind: "py",
+        patterns: [/^(?:async\s+)?def\s+([A-Za-z_]\w*)/gm, /^class\s+([A-Za-z_]\w*)/gm],
+    },
+    ".rs": {
+        kind: "rs",
+        patterns: [
+            /^\s*(?:pub\s+)?(?:async\s+)?fn\s+([A-Za-z_]\w*)/gm,
+            /^\s*(?:pub\s+)?(?:struct|enum|trait)\s+([A-Za-z_]\w*)/gm,
+        ],
+    },
+};
+// TSX/JS share the TypeScript patterns; declared separately so the table reads
+// as "which extensions are walked", not "which extensions have a parser".
+LANGUAGES[".tsx"].patterns = LANGUAGES[".ts"].patterns;
+LANGUAGES[".js"].patterns = LANGUAGES[".ts"].patterns;
+LANGUAGES[".mjs"].patterns = LANGUAGES[".ts"].patterns;
+const MAX_FILE_BYTES = 512 * 1024;
+const MAX_DEPTH = 12;
+/** Declarations in one file, deduplicated and in source order. */
+export function extractSymbols(text, ext) {
+    const language = LANGUAGES[ext];
+    if (!language)
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const pattern of language.patterns) {
+        pattern.lastIndex = 0;
+        for (const match of text.matchAll(pattern)) {
+            const name = match[1];
+            if (name && !seen.has(name)) {
+                seen.add(name);
+                out.push(name);
+            }
+        }
+    }
+    return out;
+}
+/** Relative import specifiers, as written in the file. */
+export function extractImports(text, ext) {
+    const found = new Set();
+    const add = (spec) => {
+        if (spec && (spec.startsWith("./") || spec.startsWith("../")))
+            found.add(spec);
+    };
+    if (ext === ".ts" || ext === ".tsx" || ext === ".js" || ext === ".mjs") {
+        for (const match of text.matchAll(/(?:from|require\()\s*["']([^"']+)["']/g))
+            add(match[1]);
+        for (const match of text.matchAll(/^\s*import\s+["']([^"']+)["']/gm))
+            add(match[1]);
+    }
+    else if (ext === ".go") {
+        for (const match of text.matchAll(/^\s*(?:[\w.]+\s+)?"([^"]+)"/gm))
+            add(match[1]);
+    }
+    else if (ext === ".py") {
+        for (const match of text.matchAll(/^\s*from\s+(\.+[\w.]*)\s+import/gm)) {
+            const spec = match[1].replace(/\./g, "/");
+            add(spec.startsWith("/") ? `.${spec}` : `./${spec}`);
+        }
+    }
+    else if (ext === ".rs") {
+        for (const match of text.matchAll(/^\s*use\s+(?:crate|super|self)::([\w:]+)/gm)) {
+            add(`./${match[1].split("::").join("/")}`);
+        }
+    }
+    return [...found];
+}
+/** Resolve an import specifier to a file that is in the walked set. */
+function resolveImport(fromPath, spec, known) {
+    const base = fromPath.split("/").slice(0, -1).join("/");
+    const target = join(base, spec).split(sep).join("/").replace(/^\.\//, "");
+    const candidates = [
+        target,
+        `${target}.ts`,
+        `${target}.tsx`,
+        `${target}.js`,
+        `${target}.mjs`,
+        `${target}.go`,
+        `${target}.py`,
+        `${target}.rs`,
+        `${target}/index.ts`,
+        `${target}/index.tsx`,
+        `${target}/index.js`,
+        `${target}/mod.rs`,
+        `${target}.py`,
+    ];
+    return candidates.find((candidate) => known.has(candidate));
+}
+/** Walk the tree, skipping the directories nobody wants in a map. */
+export function collectFiles(root, subdir = ".") {
+    const files = [];
+    const walk = (dir, depth) => {
+        if (depth > MAX_DEPTH)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (SKIP_DIRS.has(entry.name) || entry.name.startsWith("."))
+                    continue;
+                walk(full, depth + 1);
+                continue;
+            }
+            const ext = extname(entry.name);
+            if (!LANGUAGES[ext])
+                continue;
+            try {
+                if (statSync(full).size > MAX_FILE_BYTES)
+                    continue;
+                const text = readFileSync(full, "utf8");
+                const rel = relative(root, full).split(sep).join("/");
+                files.push({ path: rel, symbols: extractSymbols(text, ext), imports: extractImports(text, ext) });
+            }
+            catch {
+                // An unreadable file is not a reason to fail the map.
+            }
+        }
+    };
+    walk(resolve(root, subdir), 0);
+    return files;
+}
+/**
+ * Rank files by how much of the tree depends on them.
+ *
+ * PageRank over the import graph, with a small personalisation toward files
+ * that mention the query. Twenty iterations is far past convergence for a
+ * repository of this size and keeps the call cheap.
+ */
+export function rankFiles(files, query) {
+    if (files.length === 0)
+        return [];
+    const known = new Set(files.map((file) => file.path));
+    const index = new Map(files.map((file, i) => [file.path, i]));
+    const out = files.map(() => []);
+    const incoming = files.map(() => []);
+    files.forEach((file, i) => {
+        for (const spec of file.imports) {
+            const target = resolveImport(file.path, spec, known);
+            if (!target || target === file.path)
+                continue;
+            const j = index.get(target);
+            if (j === undefined)
+                continue;
+            out[i].push(j);
+            incoming[j].push(i);
+        }
+    });
+    const n = files.length;
+    const needle = query?.trim().toLowerCase();
+    const personal = files.map((file) => {
+        if (!needle)
+            return 1 / n;
+        const haystack = `${file.path} ${file.symbols.join(" ")}`.toLowerCase();
+        return haystack.includes(needle) ? 4 / n : 1 / n;
+    });
+    const personalTotal = personal.reduce((sum, value) => sum + value, 0);
+    let rank = files.map((_, i) => personal[i] / personalTotal);
+    for (let iteration = 0; iteration < 20; iteration++) {
+        const next = files.map((_, i) => 0.15 * (personal[i] / personalTotal));
+        for (let i = 0; i < n; i++) {
+            if (out[i].length === 0) {
+                // A file that imports nothing spreads its weight over the whole tree,
+                // which is what keeps a leaf-only repository from collapsing to zero.
+                for (let j = 0; j < n; j++)
+                    next[j] += (0.85 * rank[i]) / n;
+                continue;
+            }
+            for (const j of out[i])
+                next[j] += (0.85 * rank[i]) / out[i].length;
+        }
+        rank = next;
+    }
+    return files
+        .map((file, i) => ({
+        file,
+        score: rank[i],
+        // A query is a statement about what the caller is looking for, so a file
+        // that names it is worth more than any amount of graph weight: the ranking
+        // still orders the matches among themselves.
+        match: needle ? `${file.path} ${file.symbols.join(" ")}`.toLowerCase().includes(needle) : false,
+    }))
+        .sort((a, b) => Number(b.match) - Number(a.match) || b.score - a.score || a.file.path.localeCompare(b.file.path))
+        .map((entry) => entry.file);
+}
+/** Render a ranked map inside a character budget (roughly 4 chars per token). */
+export function renderRepoMap(files, options = {}) {
+    const budget = Math.max(200, Math.min(8000, options.budget ?? 1200));
+    const chars = budget * 4;
+    const ranked = rankFiles(files, options.query);
+    const lines = [];
+    let used = 0;
+    for (const file of ranked) {
+        const symbols = file.symbols.slice(0, 8).join(", ");
+        const line = symbols ? `${file.path}: ${symbols}` : `${file.path}`;
+        if (used + line.length + 1 > chars)
+            break;
+        lines.push(line);
+        used += line.length + 1;
+    }
+    if (lines.length === 0)
+        return "(no source files found)";
+    const omitted = ranked.length - lines.length;
+    if (omitted > 0)
+        lines.push(`… ${omitted} more file${omitted === 1 ? "" : "s"} not shown`);
+    return lines.join("\n");
+}
+let projectRoot;
+/** The session's project directory, supplied by the caller for the same reason
+ * claims take one: a tool cannot know which project the process is in. */
+export function setRepoRoot(next) {
+    projectRoot = next;
+}
+export const repoMapTool = defineTool({
+    name: "repo_map",
+    label: "repo_map",
+    description: "A ranked outline of the repository: files by importance with their top declarations. Use it to find where something lives before reading files, instead of listing directories.",
+    promptSnippet: "repo_map: ranked file outline of the project",
+    parameters: Type.Object({
+        path: Type.Optional(Type.String({ description: "Subdirectory to map, relative to the project root" })),
+        query: Type.Optional(Type.String({ description: "Keyword to bias the ranking, e.g. 'billing'" })),
+        budget: Type.Optional(Type.Number({ description: "Token budget, default 1200" })),
+    }),
+    async execute(_toolCallId, params) {
+        const root = projectRoot?.() ?? process.cwd();
+        const files = collectFiles(root, params.path ?? ".");
+        const text = renderRepoMap(files, { budget: params.budget, query: params.query });
+        return { content: [{ type: "text", text }], details: { files: files.length } };
+    },
+});

package/dist/roblox-connect.js

@@ -0,0 +1,125 @@
+/**
+ * `/roblox login | logout | status | tunnel` — the CLI's side of the Roblox
+ * connection.
+ *
+ * The bridge (`@netrodev/howtofix-roblox-bridge`) runs beside the agent and owns
+ * the Roblox sign-in, the virtual place and the tunnel. This module is a thin
+ * client for its loopback REST surface: it finds the bridge through the state file
+ * the bridge writes, asks it to do the thing, and reports what happened. Nothing
+ * Roblox-specific lives here, so the CLI stays small and the logic stays where the
+ * tests are.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { openInBrowser } from "./browser.js";
+/** Where the bridge recorded its port and token, or undefined when none runs. */
+export function readBridgeEndpoint(stateDir) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(stateDir, "roblox-bridge.json"), "utf8"));
+        if (typeof parsed.port === "number" && typeof parsed.token === "string")
+            return { port: parsed.port, token: parsed.token };
+    }
+    catch {
+        /* no bridge has started here */
+    }
+    return undefined;
+}
+const NO_BRIDGE = "the Roblox bridge is not running. Install RoToolbox with /preset, restart, and it starts with the agent.";
+export class RobloxConnect {
+    endpoint;
+    fetcher;
+    open;
+    constructor(endpoint, fetcher = fetch, open = (url) => openInBrowser(url)) {
+        this.endpoint = endpoint;
+        this.fetcher = fetcher;
+        this.open = open;
+    }
+    base() {
+        if (!this.endpoint)
+            throw new Error(NO_BRIDGE);
+        return `http://127.0.0.1:${this.endpoint.port}`;
+    }
+    async get(path) {
+        const response = await this.fetcher(`${this.base()}${path}`);
+        const body = (await response.json().catch(() => ({})));
+        if (!response.ok)
+            throw new Error(body.error ?? `the bridge answered ${response.status}`);
+        return body;
+    }
+    async status() {
+        return this.get("/roblox/status");
+    }
+    /**
+     * Open Roblox's consent page and wait until the bridge reports a sign-in.
+     *
+     * The URL is always returned too: a machine with no browser (SSH, a container)
+     * cannot open it, and the person has to be able to paste it somewhere that can.
+     */
+    async login(options = {}) {
+        const status = await this.status();
+        if (!status.oauth.configured) {
+            throw new Error("no Roblox OAuth app is configured. Set HOWTOFIX_ROBLOX_CLIENT_ID (or use ROBLOX_API_KEY for an API key).");
+        }
+        const { url } = await this.get("/oauth/start");
+        options.onUrl?.(url);
+        const opened = await this.open(url);
+        const deadline = Date.now() + (options.timeoutMs ?? 5 * 60_000);
+        while (Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, options.pollMs ?? 1000));
+            const now = await this.status();
+            if (now.oauth.signedIn) {
+                return { ok: true, message: `signed in${now.oauth.userName ? ` as ${now.oauth.userName}` : ""}`, url };
+            }
+        }
+        return {
+            ok: false,
+            message: opened ? "timed out waiting for the Roblox consent screen" : "could not open a browser; open the URL yourself, then run /roblox status",
+            url,
+        };
+    }
+    async logout() {
+        if (!this.endpoint)
+            throw new Error(NO_BRIDGE);
+        await this.get(`/oauth/logout?token=${encodeURIComponent(this.endpoint.token)}`);
+    }
+    async tunnel(action) {
+        if (!this.endpoint)
+            throw new Error(NO_BRIDGE);
+        const response = await this.fetcher(`${this.base()}/tunnel`, {
+            method: "POST",
+            headers: { "content-type": "application/json", "x-howtofix-token": this.endpoint.token },
+            body: JSON.stringify({ action }),
+        });
+        const body = (await response.json().catch(() => ({})));
+        if (!response.ok)
+            throw new Error(body.error ?? `the bridge answered ${response.status}`);
+        return body;
+    }
+}
+/** The sentence(s) `/roblox status` shows. */
+export function describeStatus(status, tunnel) {
+    const lines = [];
+    if (status.oauth.signedIn) {
+        lines.push(`Roblox: signed in${status.oauth.userName ? ` as ${status.oauth.userName}` : ""}`);
+        lines.push(status.oauth.universeIds.length > 0
+            ? `experiences: ${status.oauth.universeIds.join(", ")}`
+            : "experiences: none granted yet (sign in again and tick one)");
+    }
+    else if (status.openCloud) {
+        lines.push("Roblox: using an API key (ROBLOX_API_KEY)");
+    }
+    else {
+        lines.push(`Roblox: not signed in${status.oauth.configured ? " — run /roblox login" : " — set HOWTOFIX_ROBLOX_CLIENT_ID to enable sign-in"}`);
+    }
+    lines.push(`virtual places: ${status.places.join(", ") || "none"} (answer tools when Studio is closed)`);
+    if (tunnel)
+        lines.push(`workspace tunnel: ${tunnel.open ? "connected" : tunnel.running ? "connecting" : "off"}`);
+    return lines.join("\n");
+}
+/** Parse `/roblox <sub> [args]`; undefined means the legacy RoToolbox status. */
+export function parseRobloxSubcommand(arg) {
+    const [first = "", ...rest] = arg.trim().split(/\s+/);
+    if (first === "login" || first === "logout" || first === "status" || first === "tunnel")
+        return { sub: first, rest: rest.join(" ") };
+    return undefined;
+}

package/dist/rpc.js

@@ -0,0 +1,91 @@
+/**
+ * `howtofix --mode rpc`: drive a session from another process, one JSON object
+ * per line.
+ *
+ * The same contract the harness's own RPC mode speaks for the commands that make
+ * a session useful from outside — `prompt`, `abort`, `get_state`,
+ * `get_last_assistant_text` — with every session event streamed on stdout in the
+ * `--output-format stream-json` shape. A host that already parses that stream
+ * needs nothing new, and a host that wants a conversation gets one without a
+ * terminal.
+ *
+ * The CLI opens sessions through `createAgentSession`, which the harness's
+ * `runRpcMode` does not accept (it wants a full runtime host with session
+ * switching and forking). Rather than rebuild the CLI around a different
+ * constructor, this drives the session the CLI already has, so every extension it
+ * loads — MCP, code mode, the Roblox bridge — is present in RPC mode too.
+ *
+ * stdout carries only protocol lines. Anything a person should read goes to
+ * stderr, because one stray line would corrupt the stream for the host.
+ */
+import { createInterface } from "node:readline";
+/** Run until the input closes. Resolves when in-flight work has finished. */
+export function runRpc(options) {
+    const { agent } = options;
+    const write = (message) => options.output.write(`${JSON.stringify(message)}\n`);
+    const respond = (id, command, success, extra = {}) => write({ ...(id !== undefined ? { id } : {}), type: "response", command, success, ...extra });
+    const unsubscribe = agent.subscribe((event) => {
+        const encoded = options.encodeEvent ? options.encodeEvent(event) : `${JSON.stringify(event)}\n`;
+        if (encoded !== undefined)
+            options.output.write(encoded);
+    });
+    let running = null;
+    return new Promise((resolve) => {
+        const lines = createInterface({ input: options.input });
+        lines.on("line", (line) => {
+            if (line.trim() === "")
+                return;
+            let command;
+            try {
+                command = JSON.parse(line);
+            }
+            catch {
+                respond(undefined, "parse", false, { error: "a command must be one JSON object per line" });
+                return;
+            }
+            const { id, type } = command;
+            if (type === "prompt") {
+                if (typeof command.message !== "string" || command.message.trim() === "") {
+                    respond(id, "prompt", false, { error: "prompt needs a message" });
+                    return;
+                }
+                if (running) {
+                    respond(id, "prompt", false, { error: "a prompt is already running; abort it or wait" });
+                    return;
+                }
+                // Acknowledged before it runs: the host learns the command was accepted
+                // immediately and follows the work through the event stream.
+                respond(id, "prompt", true);
+                running = agent
+                    .prompt(command.message)
+                    .catch((error) => {
+                    write({ type: "error", message: error instanceof Error ? error.message : String(error) });
+                })
+                    .finally(() => {
+                    running = null;
+                });
+                return;
+            }
+            if (type === "abort") {
+                void agent.abort().then(() => respond(id, "abort", true));
+                return;
+            }
+            if (type === "get_state") {
+                respond(id, "get_state", true, { data: { running: running !== null, ...(options.state?.() ?? {}) } });
+                return;
+            }
+            if (type === "get_last_assistant_text") {
+                respond(id, "get_last_assistant_text", true, { data: { text: agent.getLastAssistantText() ?? null } });
+                return;
+            }
+            respond(id, String(type ?? "unknown"), false, { error: `unknown command ${String(type)}` });
+        });
+        lines.on("close", () => {
+            void (running ?? Promise.resolve()).then(async () => {
+                unsubscribe();
+                await agent.dispose();
+                resolve();
+            });
+        });
+    });
+}