@bli-cockpit/cli 0.2.37 → 0.2.39

package/dist/tower-client.js

@@ -0,0 +1,150 @@
+/**
+ * The one shared "call the dashboard as me" client (BLI-3457).
+ *
+ * Every command that speaks to Tower on the paired person's behalf — `jarvis`
+ * today, the rest of the CLI-parity surface next — needs the same three
+ * things: the paired device session, a request that carries its device token,
+ * and a failure that names itself instead of throwing a transport stack trace
+ * at a person. Before this module each command grew its own copy; the copies
+ * drifted (one normalised the dashboard URL, one did not) and only one of them
+ * ever named a reason.
+ *
+ * Contract:
+ * - Nothing here throws for a transport error. `towerRequest` returns
+ *   `{ ok: false, reason }` for every network-shaped failure, and the reason
+ *   label is the thing that travels to the operator.
+ * - `loadPairedSession` still throws, because "this machine is not paired" is
+ *   not a transport failure — it is a precondition the caller cannot proceed
+ *   past, and the command's top level turns it into one plain sentence.
+ * - The device token is attached to the request and never returned, logged, or
+ *   put in a reason. Log lines here carry metadata only.
+ *
+ * The HTTP vocabulary (`normalizeDashboardUrl`, `readResponseJson`,
+ * `responseErrorMessage`) is reused from `upload-http.ts` rather than copied —
+ * the upload path and the conversation path answer to the same rules.
+ */
+import { errorMessage } from "./commands/cli-io.js";
+import { getCollectorRuntimePaths, readLocalCollectorSessionFile, } from "./local-state.js";
+import { normalizeDashboardUrl, readResponseJson, responseErrorMessage, } from "./upload-http.js";
+const defaultLog = (line) => {
+    console.error(line);
+};
+/**
+ * Loads the paired device session, or explains in one sentence why it cannot.
+ *
+ * `commandName` names the caller so the sentence reads as the command a person
+ * actually typed ("`cockpit jarvis` needs a valid paired Tower session"),
+ * rather than the JARVIS-specific wording this used to be hard-coded to.
+ */
+export async function loadPairedSession(commandName, homeDir) {
+    const paths = getCollectorRuntimePaths(homeDir);
+    try {
+        const session = await readLocalCollectorSessionFile(paths);
+        if (session.session_state !== "valid") {
+            throw new Error(`session_${session.session_state}`);
+        }
+        return session;
+    }
+    catch (error) {
+        throw new Error(`\`cockpit ${commandName}\` needs a valid paired Tower session. ` +
+            `Run \`cockpit login\`, then try again (${errorMessage(error)}).`);
+    }
+}
+/**
+ * Makes one authenticated request to the dashboard. Never throws.
+ *
+ * A 4xx/5xx still comes back as `{ ok: true, response }` — the status is the
+ * caller's to interpret, because several routes put a readable refusal in a
+ * non-2xx body. Only a request that produced no response at all is a failure
+ * here, and it always carries a reason label.
+ */
+export async function towerRequest(options) {
+    const log = options.log ?? defaultLog;
+    const startedAt = Date.now();
+    const url = `${normalizeDashboardUrl(options.dashboardUrl)}${options.path}`;
+    const isForm = typeof FormData !== "undefined" && options.body instanceof FormData;
+    const headers = {
+        ...(options.headers ?? {}),
+        authorization: `Bearer ${options.deviceToken}`,
+    };
+    // fetch derives the multipart boundary from a FormData body; declaring the
+    // content-type by hand would strip it and the server would parse nothing.
+    if (options.body !== undefined && !isForm)
+        headers["content-type"] = "application/json";
+    const init = {
+        method: options.method ?? "POST",
+        headers,
+        ...(options.body === undefined
+            ? {}
+            : { body: (isForm ? options.body : JSON.stringify(options.body)) }),
+        ...(timeoutSignal(options.timeoutMs) ?? {}),
+    };
+    try {
+        const response = await options.fetch(url, init);
+        log(`[tower client] responded ${JSON.stringify({
+            request: options.label,
+            http_status: response.status,
+            content_type: response.headers.get("content-type") ?? "none",
+            streamed: (response.headers.get("content-type") ?? "").includes("application/x-ndjson"),
+            elapsed_ms: Date.now() - startedAt,
+        })}`);
+        return { ok: true, response };
+    }
+    catch (error) {
+        const reason = isAbortError(error)
+            ? "turn_timed_out"
+            : "gateway_unreachable";
+        log(`[tower client] request failed ${JSON.stringify({
+            request: options.label,
+            reason,
+            elapsed_ms: Date.now() - startedAt,
+        })}`);
+        return { ok: false, reason, detail: towerFailureDetail(reason, errorMessage(error)) };
+    }
+}
+/**
+ * `towerRequest` plus reading the body as JSON and turning a non-2xx into a
+ * named failure carrying the server's own words when it supplied any.
+ */
+export async function towerJsonRequest(options) {
+    const result = await towerRequest(options);
+    if (!result.ok)
+        return result;
+    const body = await readResponseJson(result.response);
+    if (!result.response.ok) {
+        return {
+            ok: false,
+            reason: "http_error",
+            httpStatus: result.response.status,
+            detail: responseErrorMessage(body, `http_${result.response.status}`),
+        };
+    }
+    return { ok: true, httpStatus: result.response.status, body };
+}
+/** One plain sentence per reason, so no caller has to invent its own wording. */
+export function towerFailureDetail(reason, detail) {
+    switch (reason) {
+        case "gateway_unreachable":
+            return `Tower could not be reached (${detail}).`;
+        case "turn_timed_out":
+            return "Tower did not finish in time, so the answer is incomplete. Ask again.";
+        case "http_error":
+            return detail;
+    }
+}
+export function isAbortError(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const name = error.name;
+    return name === "AbortError" || name === "TimeoutError";
+}
+/**
+ * A deadline when the runtime has one. `AbortSignal.timeout` exists on Node 18+
+ * on both supported host families; the guard is here so a stripped runtime
+ * loses the ceiling rather than the whole request.
+ */
+function timeoutSignal(timeoutMs) {
+    if (!timeoutMs || typeof AbortSignal?.timeout !== "function")
+        return null;
+    return { signal: AbortSignal.timeout(timeoutMs) };
+}

package/dist/tower-stream.js

@@ -0,0 +1,252 @@
+/**
+ * Reading a Tower turn as it happens (BLI-3457).
+ *
+ * The dashboard's conversation routes speak one JSON object per line
+ * (`application/x-ndjson`): `activity` events as tools start and settle, then
+ * exactly one `final` event carrying what the plain JSON response used to be.
+ * That is the same wire format the browser already reads
+ * (`apps/dashboard/src/lib/webchat/tool-trace.ts`); this is the terminal's
+ * reader for it.
+ *
+ * Three things it refuses to do:
+ * - Throw. A stream that dies mid-turn comes back as a named reason, never an
+ *   exception in the middle of a person's answer.
+ * - Present a truncated turn as a complete one. No `final` event means the
+ *   turn failed, and it says which way it failed
+ *   (`turn_timed_out` when the dashboard's own 120s ceiling is the likely
+ *   cause, `stream_ended_without_final` otherwise).
+ * - Require the stream. A dashboard that has not shipped streaming yet answers
+ *   `application/json`; that single object is read as the final event and the
+ *   fallback is named `stream_not_available` rather than passed off as a
+ *   stream that happened to be quiet.
+ *
+ * A malformed line is skipped, named `ndjson_line_unparseable`, and the lines
+ * after it still count — one bad byte cannot swallow an answer.
+ */
+import { errorMessage } from "./commands/cli-io.js";
+import { isAbortError } from "./tower-client.js";
+/**
+ * The dashboard caps a turn at 120s (`maxDuration = 120`). A stream that stops
+ * without a final event anywhere near that mark was almost certainly cut off by
+ * the platform, and saying `turn_timed_out` is the honest label; earlier than
+ * that, the stream broke for some other reason and gets its own.
+ */
+const CEILING_HINT_MS = 110_000;
+/**
+ * Yields every event on the response, then stops at the first `final`.
+ *
+ * Handles both wire shapes: real NDJSON, and a plain `application/json` body
+ * from a dashboard that does not stream yet (yielded as the final event, after
+ * a `stream_not_available` note).
+ */
+export async function* readTowerStream(response) {
+    const contentType = response.headers.get("content-type") ?? "";
+    if (!contentType.includes("application/x-ndjson")) {
+        yield* readPlainJsonBody(response);
+        return;
+    }
+    let buffer = "";
+    try {
+        for await (const chunk of iterateBody(response)) {
+            buffer += chunk;
+            const lines = buffer.split("\n");
+            buffer = lines.pop() ?? "";
+            for (const line of lines) {
+                const item = parseLine(line);
+                if (!item)
+                    continue;
+                yield item;
+                if (item.kind === "event" && item.event.type === "final")
+                    return;
+            }
+        }
+    }
+    catch (error) {
+        yield {
+            kind: "note",
+            reason: isAbortError(error) ? "turn_timed_out" : "stream_read_failed",
+            detail: errorMessage(error),
+        };
+        return;
+    }
+    // Whatever was still in flight when the body ended.
+    const tail = parseLine(buffer);
+    if (tail)
+        yield tail;
+}
+/**
+ * The whole turn in one call: renders activity as it arrives, buffers the
+ * final, and names any way the turn failed to produce one.
+ *
+ * `onActivity` is where a caller draws its live trace. `onNote` sees every
+ * named oddity (a skipped line, a non-streaming dashboard) so nothing is
+ * silently absorbed — the caller decides whether that is a log line or a
+ * sentence.
+ */
+export async function readTowerTurn(response, options = {}) {
+    const startedAt = options.startedAt ?? Date.now();
+    const activity = [];
+    const notes = [];
+    let streamed = true;
+    let final = null;
+    for await (const item of readTowerStream(response)) {
+        if (item.kind === "note") {
+            if (item.reason === "stream_not_available")
+                streamed = false;
+            notes.push({ reason: item.reason, detail: item.detail });
+            options.onNote?.(item.reason, item.detail);
+            continue;
+        }
+        if (item.event.type === "final") {
+            final = item.event;
+            break;
+        }
+        activity.push(item.event);
+        options.onActivity?.(item.event);
+    }
+    const elapsedMs = Date.now() - startedAt;
+    if (!final) {
+        // The last named note is the truest reason we have; absent one, a stream
+        // that simply stopped near the dashboard's ceiling is a timeout.
+        const terminal = notes.at(-1);
+        const reason = terminal && terminal.reason !== "stream_not_available"
+            ? terminal.reason
+            : elapsedMs >= CEILING_HINT_MS
+                ? "turn_timed_out"
+                : "stream_ended_without_final";
+        options.log?.(`[tower stream] turn incomplete ${JSON.stringify({
+            reason,
+            activity_events: activity.length,
+            notes: notes.length,
+            elapsed_ms: elapsedMs,
+        })}`);
+        return { ok: false, reason, detail: streamFailureDetail(reason, terminal?.detail) };
+    }
+    options.log?.(`[tower stream] turn complete ${JSON.stringify({
+        streamed,
+        activity_events: activity.length,
+        notes: notes.length,
+        elapsed_ms: elapsedMs,
+    })}`);
+    return { ok: true, final, activity, streamed };
+}
+/** One plain sentence per way a turn can end without an answer. */
+export function streamFailureDetail(reason, detail) {
+    switch (reason) {
+        case "turn_timed_out":
+            return "Tower ran out of time before finishing that turn, so the answer is incomplete. Ask again.";
+        case "stream_ended_without_final":
+            return "Tower stopped sending mid-answer, so the answer is incomplete. Ask again.";
+        case "stream_read_failed":
+            return `The connection to Tower broke mid-answer${detail ? ` (${detail})` : ""}. Ask again.`;
+        case "response_body_not_json":
+            return "Tower answered with something that was not JSON.";
+        case "response_body_empty":
+            return "Tower answered with an empty body.";
+        default:
+            return detail ?? reason;
+    }
+}
+/**
+ * A dashboard that does not stream yet. The whole body is one JSON object; it
+ * becomes the final event so every caller has exactly one code path.
+ */
+async function* readPlainJsonBody(response) {
+    yield {
+        kind: "note",
+        reason: "stream_not_available",
+        detail: response.headers.get("content-type") ?? "none",
+    };
+    let text;
+    try {
+        text = await response.text();
+    }
+    catch (error) {
+        yield {
+            kind: "note",
+            reason: isAbortError(error) ? "turn_timed_out" : "stream_read_failed",
+            detail: errorMessage(error),
+        };
+        return;
+    }
+    if (!text.trim()) {
+        yield { kind: "note", reason: "response_body_empty" };
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        yield { kind: "note", reason: "response_body_not_json" };
+        return;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        yield { kind: "note", reason: "response_body_not_json" };
+        return;
+    }
+    yield {
+        kind: "event",
+        event: { ...parsed, type: "final" },
+    };
+}
+/** One NDJSON line: an event, a named skip, or nothing at all for blank lines. */
+function parseLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        // The line text is never logged: it is conversation content.
+        return { kind: "note", reason: "ndjson_line_unparseable" };
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { kind: "note", reason: "unexpected_event_type" };
+    }
+    const type = parsed.type;
+    if (type !== "activity" && type !== "final") {
+        return { kind: "note", reason: "unexpected_event_type" };
+    }
+    return { kind: "event", event: parsed };
+}
+/**
+ * Decoded text chunks from a response body.
+ *
+ * Node's web `ReadableStream` is async-iterable on both supported host
+ * families (macOS and Windows, Node 20+), and that is the fast path. The
+ * `getReader()` fallback is there because a test double or a polyfilled fetch
+ * may hand back a stream without the iterator, and losing the answer over an
+ * iteration protocol would be absurd.
+ */
+async function* iterateBody(response) {
+    const body = response.body;
+    if (!body) {
+        const text = await response.text();
+        if (text)
+            yield text;
+        return;
+    }
+    const decoder = new TextDecoder();
+    const asyncIterable = body;
+    if (typeof asyncIterable[Symbol.asyncIterator] === "function") {
+        for await (const chunk of asyncIterable) {
+            yield decoder.decode(chunk, { stream: true });
+        }
+    }
+    else {
+        const reader = body.getReader();
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value)
+                yield decoder.decode(value, { stream: true });
+        }
+    }
+    const rest = decoder.decode();
+    if (rest)
+        yield rest;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.37",
+  "version": "0.2.39",
   "private": false,
   "type": "module",
   "bin": {
@@ -24,7 +24,7 @@
     "pretypecheck": "npm run build",
     "typecheck": "node -e \"await import('./dist/commands/public-root.js')\"",
     "pretest": "npm run build",
-    "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
+    "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-cli-runtime-files.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
   },
   "dependencies": {
     "@bli-cockpit/telemetry-core": "0.1.25"