howtofixcli 0.7.24 → 0.7.26

package/dist/account-credential.js

@@ -0,0 +1,136 @@
+/**
+ * Signing in with the account itself, not with a key made for the occasion.
+ *
+ * ## The problem this replaces
+ *
+ * `/connect` ended in a browser flow whose approval minted a fresh `sk-` key
+ * every time. A user who reconnected a few times found a panel full of
+ * near-identical rows, could not tell which one the CLI was using, and had to
+ * revoke them one by one. The account was already the thing being proven; the
+ * key was only a side effect of proving it.
+ *
+ * ## What happens instead
+ *
+ * The credential — `email:password`, base64-encoded — is stored once in the agent
+ * directory, mode 600, and sent to `POST /api/auth/cli/credential`. The panel
+ * verifies it and answers with the CLI key this account already owns; only an
+ * account with no CLI key gets a new one. A headless install therefore needs no
+ * second device and no pasted key.
+ *
+ * ## Why base64
+ *
+ * It is what people paste: one opaque string, no shell quoting, no `@` or `:` to
+ * trip over. It is not encryption and is not presented as such — the file is
+ * protected by its permissions, and the value is never printed.
+ */
+import { chmodSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileAtomicSync } from "./fs-atomic.js";
+/** Where the stored credential lives. */
+export function accountCredentialPath(agentDir) {
+    return join(agentDir, "account-credential.json");
+}
+/** base64 of `username:password`. */
+export function encodeCredential(username, password) {
+    return Buffer.from(`${username}:${password}`, "utf8").toString("base64");
+}
+/**
+ * Read either a base64 blob or a plain `user:pass` line.
+ *
+ * A pasted credential is almost always one of the two, and refusing the plain
+ * form only makes the user encode it by hand to satisfy the parser.
+ */
+export function parseCredentialInput(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    const fromPlain = (value) => {
+        const at = value.indexOf(":");
+        if (at <= 0 || at === value.length - 1)
+            return null;
+        return { username: value.slice(0, at), password: value.slice(at + 1) };
+    };
+    const plain = fromPlain(trimmed);
+    if (plain)
+        return plain;
+    // Not `user:pass`, so try base64 and re-read the decoded text.
+    try {
+        const decoded = Buffer.from(trimmed, "base64").toString("utf8");
+        if (!decoded.includes(":"))
+            return null;
+        return fromPlain(decoded);
+    }
+    catch {
+        return null;
+    }
+}
+/** Store the credential so a later `/connect` needs nothing typed. */
+export function saveAccountCredential(agentDir, username, password) {
+    try {
+        const payload = {
+            credential: encodeCredential(username, password),
+            username,
+            savedAt: Math.floor(Date.now() / 1000),
+        };
+        const target = accountCredentialPath(agentDir);
+        writeFileAtomicSync(target, JSON.stringify(payload, null, 2));
+        chmodSync(target, 0o600);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The stored credential, if one was saved and is still readable. */
+export function loadAccountCredential(agentDir) {
+    try {
+        const target = accountCredentialPath(agentDir);
+        if (!existsSync(target))
+            return null;
+        const parsed = JSON.parse(readFileSync(target, "utf8"));
+        if (!parsed?.credential || !parsed?.username)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** A JSON POST against the panel. */
+async function panelPost(url, body) {
+    const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(20_000),
+    });
+    const text = await response.text();
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`the panel answered ${response.status} with something that is not JSON`);
+    }
+    const envelope = parsed;
+    if (!response.ok || envelope.success === false) {
+        throw new Error(envelope.message || `the panel answered ${response.status}`);
+    }
+    return envelope.data;
+}
+/**
+ * Exchange the account credential for the CLI key this account owns.
+ *
+ * The panel decides whether that key already existed; the CLI never creates a
+ * token of its own, so a reconnect cannot add a row to the panel.
+ */
+export async function loginWithCredential(panelUrl, username, password, clientInfo) {
+    const data = await panelPost(`${panelUrl}/api/auth/cli/credential`, {
+        credential: encodeCredential(username, password),
+        client_info: clientInfo,
+    });
+    if (!data?.token) {
+        throw new Error("the panel accepted the credential but returned no key");
+    }
+    return { token: data.token };
+}

package/dist/acp.js

@@ -0,0 +1,234 @@
+/**
+ * `howtofix acp`: the Agent Client Protocol over stdio.
+ *
+ * ACP is how an editor (Zed and others) or any other host drives a coding agent:
+ * JSON-RPC 2.0, one message per line, the host as client and this process as the
+ * agent. Speaking it means the CLI plugs into those hosts without each one
+ * needing its own adapter — and it is also the seam the hosted Roblox workspace
+ * uses to steer a local session.
+ *
+ * What is implemented is the part a host needs to hold a conversation:
+ * `initialize`, `session/new`, `session/prompt` (with streamed `session/update`
+ * notifications for text, thinking and tool calls) and `session/cancel`. Anything
+ * else is answered `-32601` rather than ignored, so a host finds out a capability
+ * is missing instead of waiting on a reply that never comes.
+ *
+ * ## Per-turn context
+ *
+ * A host can attach `_meta.howtofix.context` to a prompt: the Studio place, the
+ * selection, what is connected. It is rendered into a `<session_context>` block
+ * ahead of the user's words *each turn*, not once at session start, because the
+ * selection the user had when they typed is the one that matters, and a context
+ * frozen at `session/new` would describe a place that has since changed.
+ *
+ * The agent is reached through `AcpAgent` so this file does not import the SDK:
+ * the protocol layer is testable with a fake, and `main.ts` supplies the real one.
+ */
+import { createInterface } from "node:readline";
+export const ACP_PROTOCOL_VERSION = 1;
+/**
+ * Render per-turn context as text the model reads before the prompt.
+ *
+ * Returns an empty string for no context, so a plain prompt is passed through
+ * untouched. Values are JSON-encoded rather than interpolated: a place named
+ * `</session_context>` must not be able to close the block and speak as the user.
+ */
+export function renderSessionContext(context) {
+    if (!context || Object.keys(context).length === 0)
+        return "";
+    // JSON quoting alone does not stop `</session_context>` inside a string from
+    // reading as the closing tag, so `<` is escaped too. `\u003c` is still valid
+    // JSON and decodes to the same text; it just cannot be mistaken for markup.
+    const encode = (value) => JSON.stringify(value).replace(/</g, "\\u003c");
+    const lines = [];
+    if (context.place)
+        lines.push(`place: ${encode(context.place)}`);
+    if (context.selection && context.selection.length > 0)
+        lines.push(`selection: ${encode(context.selection)}`);
+    if (context.connected)
+        lines.push(`connected: ${encode(context.connected)}`);
+    for (const [key, value] of Object.entries(context)) {
+        if (key === "place" || key === "selection" || key === "connected")
+            continue;
+        lines.push(`${key.replace(/[^\w.-]/g, "_")}: ${encode(value)}`);
+    }
+    return `<session_context>\n${lines.join("\n")}\n</session_context>\n\n`;
+}
+/** A tool's kind for the host's icon, from its name. */
+function toolKind(name) {
+    if (/^(get_|list_|read_|snapshot|diff_|audit|datastore_get|datastore_list|roblox_status)/.test(name))
+        return "read";
+    if (/^(search|grep|find)/.test(name))
+        return "search";
+    if (/(execute|run_|luau)/.test(name))
+        return "execute";
+    if (/^(set_|create_|delete_|clone_|reparent_|edit_|insert_|send_|publish_|upload_|generate_|datastore_set|datastore_delete)/.test(name))
+        return "edit";
+    return "other";
+}
+function resultText(result) {
+    if (typeof result === "string")
+        return result;
+    const content = result?.content;
+    if (Array.isArray(content))
+        return content.map((block) => (block.type === "text" ? (block.text ?? "") : `[${block.type ?? "?"}]`)).join("\n");
+    return JSON.stringify(result ?? null);
+}
+/** Run the protocol until the input closes. Resolves when it has. */
+export function runAcp(options) {
+    const sessions = new Map();
+    const running = new Map();
+    let counter = 0;
+    const write = (message) => {
+        options.output.write(`${JSON.stringify({ jsonrpc: "2.0", ...message })}\n`);
+    };
+    const reply = (id, result) => write({ id, result });
+    const fail = (id, code, message) => write({ id, error: { code, message } });
+    const update = (sessionId, body) => write({ method: "session/update", params: { sessionId, update: body } });
+    async function handle(request) {
+        const params = request.params ?? {};
+        const isNotification = request.id === undefined;
+        switch (request.method) {
+            case "initialize":
+                return reply(request.id, {
+                    protocolVersion: ACP_PROTOCOL_VERSION,
+                    agentCapabilities: { loadSession: false, promptCapabilities: { image: false, audio: false, embeddedContext: true } },
+                    authMethods: [],
+                    agentInfo: { name: options.name ?? "howtofix", title: "HowToFix", version: options.version },
+                });
+            case "session/new": {
+                const cwd = typeof params.cwd === "string" ? params.cwd : process.cwd();
+                try {
+                    const agent = await options.createAgent(cwd);
+                    counter += 1;
+                    const sessionId = `sess_${Date.now().toString(36)}_${counter}`;
+                    sessions.set(sessionId, agent);
+                    return reply(request.id, { sessionId });
+                }
+                catch (error) {
+                    return fail(request.id, -32000, error instanceof Error ? error.message : String(error));
+                }
+            }
+            case "session/prompt": {
+                const sessionId = String(params.sessionId ?? "");
+                const agent = sessions.get(sessionId);
+                if (!agent)
+                    return fail(request.id, -32602, `unknown session ${sessionId}`);
+                if (running.has(sessionId))
+                    return fail(request.id, -32000, "a prompt is already running in this session");
+                const blocks = Array.isArray(params.prompt) ? params.prompt : [];
+                const text = blocks
+                    .map((block) => {
+                    if (block.type === "text")
+                        return block.text ?? "";
+                    if (block.type === "resource" && block.resource?.text !== undefined)
+                        return `<file uri=${JSON.stringify(block.resource.uri ?? "")}>\n${block.resource.text}\n</file>`;
+                    return "";
+                })
+                    .filter((part) => part !== "")
+                    .join("\n\n");
+                if (text === "")
+                    return fail(request.id, -32602, "the prompt has no text");
+                const meta = params._meta;
+                const full = renderSessionContext(meta?.howtofix?.context) + text;
+                let cancelled = false;
+                const unsubscribe = agent.subscribe((event) => {
+                    if (event.type === "message_update") {
+                        const inner = event.assistantMessageEvent;
+                        if (inner?.type === "text_delta" && inner.delta) {
+                            update(sessionId, { sessionUpdate: "agent_message_chunk", content: { type: "text", text: inner.delta } });
+                        }
+                        else if (inner?.type === "thinking_delta" && inner.delta) {
+                            update(sessionId, { sessionUpdate: "agent_thought_chunk", content: { type: "text", text: inner.delta } });
+                        }
+                    }
+                    else if (event.type === "tool_execution_start") {
+                        const e = event;
+                        update(sessionId, {
+                            sessionUpdate: "tool_call",
+                            toolCallId: e.toolCallId,
+                            title: e.toolName,
+                            kind: toolKind(e.toolName),
+                            status: "in_progress",
+                            rawInput: e.args ?? {},
+                        });
+                    }
+                    else if (event.type === "tool_execution_end") {
+                        const e = event;
+                        update(sessionId, {
+                            sessionUpdate: "tool_call_update",
+                            toolCallId: e.toolCallId,
+                            status: e.isError ? "failed" : "completed",
+                            content: [{ type: "content", content: { type: "text", text: resultText(e.result) } }],
+                        });
+                    }
+                });
+                const turn = agent
+                    .prompt(full)
+                    .then(() => {
+                    const stop = agent.lastStopReason?.();
+                    const stopReason = cancelled || stop === "aborted" ? "cancelled" : stop === "length" ? "max_tokens" : "end_turn";
+                    reply(request.id, { stopReason });
+                })
+                    .catch((error) => {
+                    if (cancelled)
+                        reply(request.id, { stopReason: "cancelled" });
+                    else
+                        fail(request.id, -32000, error instanceof Error ? error.message : String(error));
+                })
+                    .finally(() => {
+                    unsubscribe();
+                    running.delete(sessionId);
+                });
+                running.set(sessionId, turn);
+                // `cancel` needs to reach this turn's flag, so it is looked up by session.
+                cancels.set(sessionId, () => {
+                    cancelled = true;
+                });
+                return;
+            }
+            case "session/cancel": {
+                const sessionId = String(params.sessionId ?? "");
+                cancels.get(sessionId)?.();
+                await sessions.get(sessionId)?.abort();
+                return;
+            }
+            default:
+                // A notification has no reply to carry an error, so it is dropped.
+                if (!isNotification)
+                    fail(request.id, -32601, `method not found: ${request.method}`);
+        }
+    }
+    const cancels = new Map();
+    return new Promise((resolve) => {
+        const lines = createInterface({ input: options.input });
+        const pending = new Set();
+        lines.on("line", (line) => {
+            if (line.trim() === "")
+                return;
+            let request;
+            try {
+                request = JSON.parse(line);
+            }
+            catch {
+                fail(null, -32700, "parse error");
+                return;
+            }
+            const task = handle(request)
+                .catch((error) => {
+                if (request.id !== undefined)
+                    fail(request.id, -32603, error instanceof Error ? error.message : String(error));
+            })
+                .finally(() => pending.delete(task));
+            pending.add(task);
+        });
+        lines.on("close", () => {
+            // Let in-flight turns finish writing before sessions are torn down: closing
+            // stdin after sending a prompt is how a one-shot host says "and then stop".
+            void Promise.allSettled([...pending, ...running.values()]).then(async () => {
+                await Promise.allSettled([...sessions.values()].map((agent) => agent.dispose()));
+                resolve();
+            });
+        });
+    });
+}

package/dist/activity.js

@@ -0,0 +1,124 @@
+/**
+ * The one line under the input box, made consistent.
+ *
+ * That line used to be a single `hud.activity` string written from twenty-three
+ * places, each with its own idea of what it looked like:
+ *
+ *   `⠋ thinking 12s`          — spinner and a word
+ *   `✓ Read ×1 | Workflow ×1` — a tool tally
+ *   `* shell 4096 bytes`      — a bullet
+ *   `API key for nrimo. Paste it, then press enter.` — a sentence
+ *   `""`                      — blank, from eight different places
+ *
+ * The result flickered between shapes and erased itself whenever an unrelated
+ * event landed, which is what "the text keeps changing and is not consistent"
+ * describes. The cause is not the number of writers; it is that each writer
+ * owned the *whole* line.
+ *
+ * So writers now own a **layer**, and the line renders the highest-priority
+ * non-empty one:
+ *
+ *   prompt > retry > note > run > tally
+ *
+ * A prompt waiting for you outranks a transient note, a note outranks the live
+ * run, and the tool tally is a floor that survives the run ending. Clearing a
+ * layer only clears that layer: a finished run no longer wipes a message that
+ * was waiting for the user.
+ *
+ * The retry sits above the note because the two describe the same silence — a
+ * provider that did not answer — and the retry is the one that says what is
+ * being done about it. A note that is still pinned while a retry counts down is
+ * the older, vaguer half of the same story.
+ *
+ * Time-varying text is produced here, not stored, so the label stays put while
+ * only the elapsed seconds tick.
+ */
+export function emptyActivity() {
+    return {};
+}
+/** Set or clear one layer. Returns a new state; the caller assigns it. */
+export function withLayer(state, layer, text, now = Date.now()) {
+    const next = { ...state };
+    if (layer === "run") {
+        if (text === undefined || text === "")
+            delete next.run;
+        // Keep the original start when only the label changes, so a run that moves
+        // from "thinking" to "running agents" does not reset its own clock.
+        else
+            next.run = { label: text, since: state.run?.since ?? now };
+        return next;
+    }
+    if (text === undefined || text === "")
+        delete next[layer];
+    else
+        next[layer] = text;
+    return next;
+}
+/**
+ * Set or clear the retry layer.
+ *
+ * Separate from `withLayer` because the value is a deadline rather than a
+ * string: the caller hands over when the next attempt fires and what went
+ * wrong, and the text is derived from the clock on every draw.
+ */
+export function withRetry(state, retry) {
+    const next = { ...state };
+    if (retry === undefined)
+        delete next.retry;
+    else
+        next.retry = retry;
+    return next;
+}
+/** `42s` / `1m 05s`, the same shape the rest of the UI uses. */
+function formatElapsed(ms) {
+    const seconds = Math.max(0, Math.round(ms / 1000));
+    const minutes = Math.floor(seconds / 60);
+    return minutes > 0 ? `${minutes}m ${String(seconds % 60).padStart(2, "0")}s` : `${seconds}s`;
+}
+/**
+ * The provider's message, cut to what one line can hold.
+ *
+ * A failed request reports itself in a paragraph, sometimes several — a status
+ * line, a JSON body, a stack. The activity line is one row wide, so the first
+ * non-empty line is the part that says what happened.
+ */
+export function firstLine(text, limit = 72) {
+    const line = text.split("\n").map((part) => part.trim()).find((part) => part !== "") ?? "";
+    return line.length > limit ? `${line.slice(0, limit - 1)}…` : line;
+}
+/**
+ * `retry 1/3 in 2s · upstream 502` — the wait counts down as the clock moves.
+ *
+ * The countdown is the point: a bare `retry 1/3` says something is happening
+ * but not whether to wait or to reach for ctrl+c, and a retry that has already
+ * fired must not keep reading like a countdown. Past the deadline the text says
+ * so and stays there until the attempt reports back.
+ */
+function retryText(retry, now) {
+    const left = Math.max(0, Math.ceil((retry.until - now) / 1000));
+    const when = left > 0 ? `in ${left}s` : "now";
+    const head = `retry ${retry.attempt}/${retry.maxAttempts} ${when}`;
+    const reason = firstLine(retry.error);
+    return reason === "" ? head : `${head} · ${reason}`;
+}
+/**
+ * The line to draw, or `""` when nothing is happening.
+ *
+ * One marker per layer, one separator (` · `), and the text never carries its
+ * own prefix — so two different states can never look like two different tools.
+ */
+export function activityText(state, spinner, now = Date.now()) {
+    if (state.prompt)
+        return `? ${state.prompt}`;
+    if (state.retry)
+        return `* ${retryText(state.retry, now)}`;
+    if (state.note)
+        return `* ${state.note}`;
+    if (state.run)
+        return `${spinner} ${state.run.label} · ${formatElapsed(now - state.run.since)}`;
+    // No marker of its own: the tally is already a list of per-tool markers
+    // (`✓ Read ×1 | ! Workflow ×1`), so prefixing it drew `✓ ✓ Read ×1`.
+    if (state.tally)
+        return state.tally;
+    return "";
+}