@bli-cockpit/cli 0.2.37 → 0.2.39

package/dist/commands/local-help.js

@@ -22,6 +22,14 @@ export const rootCommandNames = new Set([
     "sync",
     "analyze",
     "jarvis",
+    "model",
+    "scout",
+    "settings",
+    "team",
+    "workbook",
+    "brief",
+    "correct",
+    "notes",
     "backfill",
     "status",
     "sessions",
@@ -42,11 +50,19 @@ export function localCommandHelp(command) {
         "  cockpit install [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--json]",
         "  cockpit login [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--no-auth] [--json]",
         "  cockpit pair [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--no-auth] [--json]",
-        "  cockpit logout",
+        "  cockpit logout [--revoke] [--yes] [--dashboard-url <url>] [--json]",
         "  cockpit start [--ticket <id>|--clear-ticket] [--topic <label>] [--intent <intent>] [--phase <phase>] [--workspace <path>] [--branch <name>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit sync [--workspace <path>] [--dashboard-url <url>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit analyze [--workspace <path>] [--dashboard-url <url>] [--max-depth <n>] [--max-repos <n>] [--json]",
-        "  cockpit jarvis [question] [--prompt <question>] [--as <person>] [--thread <name>] [--model <key>] [--image <path>|--file <path>] [--dashboard-url <url>] [--json]",
+        "  cockpit jarvis [question] [--prompt <question>] [--as <person>] [--thread <name>] [--model <key>] [--image <path>|--file <path>] [--no-stream] [--threads|--history [--limit <n>]] [--dashboard-url <url>] [--json]",
+        "  cockpit model [show|set <provider:model>] [--json]",
+        "  cockpit scout [start|dismiss|undo <experiment-id>] [--days <n>] [--dashboard-url <url>] [--json]",
+        "  cockpit settings [personal [--chat-model <key>] [--brief-model <key>] | switches [set <key> <value>] | models [set --chat <key>] [--memory <id>] | env list|set --project <p> --file <f> --content-stdin|delete --id <uuid> [--yes]] [--json]",
+        "  cockpit team [members | invite <email> --role <role> [--team-id <uuid>] | role <userId> --role <role> [--yes]] [--json]",
+        "  cockpit workbook [<project> [<doc>]] [--section <id>] [--markdown] [--width <n>] [--dashboard-url <url>] [--json]",
+        "  cockpit brief [--for <person>] [--version <pageId>] [--tldr|--full] [--versions] [--claims] [--dashboard-url <url>] [--json]",
+        "  cockpit correct --claim <claimId> --text \"<what is wrong>\" [--for <person>] [--version <pageId>] [--supersedes <id>] [--dashboard-url <url>] [--json]",
+        "  cockpit notes [list|show <id>|shelf|shelves|upload <paths...>|paste|share <id>|unshare <id>|move <id>] [--series <shelf>] [--kind <kind>] [--since <YYYY-MM-DD>] [--until <YYYY-MM-DD>] [--limit <n>] [--file <path>] [--name <n>] [--exclude \"<sentence>\"] [--to \"<shelf>\"|--clear-shelf] [--yes] [--dashboard-url <url>] [--json]",
         "  cockpit backfill (--since-days <n>|--all) [--source codex|claude] [--dry-run] [--max-files <n>] [--max-depth <n>] [--max-repos <n>] [--yes] [--workspace <path>] [--json]",
         "  cockpit status [--workspace <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit sessions [--source codex|claude] [--since-days <n>|--all] [--workspace <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
@@ -140,7 +156,70 @@ function localSubcommandHelp(command) {
                 "Alias for `cockpit login`.",
             ],
         ],
-        ["logout", ["Usage: cockpit logout [--json]", "", "Removes the local device session."]],
+        [
+            "logout",
+            [
+                "Usage: cockpit logout [--revoke] [--yes] [--dashboard-url <url>] [--json]",
+                "",
+                "Removes the local device session.",
+                "--revoke also asks Tower to end this device's token, which is what you want",
+                "when the machine is being handed back: without it this laptop stops collecting",
+                "but the token it held is still one the server would honour.",
+                "A device can only revoke ITSELF; revoking someone else's machine stays in the browser.",
+                "The local session is removed either way, and the two outcomes are reported separately.",
+            ],
+        ],
+        [
+            "model",
+            [
+                "Usage: cockpit model [show|set <provider:model>] [--json]",
+                "",
+                "Shows or changes YOUR chat model — the short way to say",
+                "`cockpit settings personal --chat-model`. Affects your account, not the org.",
+                "An unrecognised key is refused by the dashboard, not by this command.",
+            ],
+        ],
+        [
+            "settings",
+            [
+                "Usage: cockpit settings [section] [verb] [flags] [--json]",
+                "",
+                "With no section it shows everything you can see; a section you cannot see reads",
+                "`admin only` rather than failing, because that is the system working.",
+                "",
+                "  cockpit settings personal [--chat-model <key>] [--brief-model <key>]",
+                "      Your teams and your two model choices. No flags = show.",
+                "  cockpit settings switches [set <key> <value>]",
+                "      Access and feature switches. Everyone may look; only an admin may set.",
+                "  cockpit settings models [set --chat <key>] [--memory <id>]",
+                "      The ORG-WIDE model map. Admin only, in both directions.",
+                "  cockpit settings env list",
+                "      Stored env files: project, name, when, id. Never a value — the server",
+                "      cannot return one and this command has no flag that prints one.",
+                "  cockpit settings env set --project <project> --file <name> --content-stdin",
+                "      Pipe the file in; there is no --content flag, because a secret on a",
+                "      command line lands in shell history and in every process listing.",
+                "      macOS:      cat <path> | cockpit settings env set --project <project> --file <name> --content-stdin",
+                "      PowerShell: Get-Content <path> -Raw | cockpit settings env set --project <project> --file <name> --content-stdin",
+                "      Run `cockpit settings env list` to see which file names this project accepts.",
+                "  cockpit settings env delete --id <uuid> [--yes]",
+                "      Asks first unless --yes; a headless run without --yes is refused, not assumed.",
+            ],
+        ],
+        [
+            "team",
+            [
+                "Usage: cockpit team [members | invite <email> --role <role> | role <userId> --role <role>] [--json]",
+                "",
+                "  cockpit team [members]",
+                "      Everyone on your team — roster and accounts together, with each person's id.",
+                "      Open to every role; it says so when the view is read-only for you.",
+                "  cockpit team invite <email> --role <role> [--team-id <uuid>]",
+                "      Admin only. Defaults to your own team; Tower emails them a sign-in link.",
+                "  cockpit team role <userId> --role <role> [--yes]",
+                "      Admin only. Asks first unless --yes. You cannot change your own role.",
+            ],
+        ],
         [
             "start",
             [
@@ -190,7 +269,7 @@ function localSubcommandHelp(command) {
         [
             "jarvis",
             [
-                "Usage: cockpit jarvis [question] [--prompt <question>] [--as <person>] [--thread <name>] [--model <key>] [--image <path>|--file <path>] [--dashboard-url <url>] [--json]",
+                "Usage: cockpit jarvis [question] [--prompt <question>] [--as <person>] [--thread <name>] [--model <key>] [--image <path>|--file <path>] [--no-stream] [--threads|--history [--limit <n>]] [--dashboard-url <url>] [--json]",
                 "",
                 "Chats with the same JARVIS used by Tower web chat and the BLI Slack DM.",
                 "--as selects the existing website person space; it changes who the chat is about, never who is authenticated.",
@@ -199,11 +278,99 @@ function localSubcommandHelp(command) {
                 "Run with no question for an interactive terminal conversation.",
                 "Agents can pass --prompt, positional text, or pipe one question on stdin.",
                 "Each answer prints a per-tool trace line and, only on a fallback or model mismatch, one model receipt line.",
-                "--json writes one machine-readable response (including trace and model) to stdout; operational metadata stays on stderr.",
+                "Trace lines arrive live while JARVIS works; pass --no-stream to wait for the whole answer in one piece instead.",
+                "--json writes one machine-readable response (including trace and model) to stdout; operational metadata stays on stderr. A --json run never streams fragments, whichever mode it is in.",
+                "A turn that outlives the dashboard's own ceiling is reported as turn_timed_out — an incomplete answer is never printed as a finished one.",
                 "The command uses the existing paired device identity. It cannot override the caller, team, role, or person scope.",
+                "--threads lists the terminal conversations on this account; --thread <name> --history replays one (the newest --limit <n> messages). Neither takes a question, and neither can reach anybody else's conversations.",
+                "Run `cockpit login` first if this machine is not paired.",
+            ],
+        ],
+        [
+            "scout",
+            [
+                "Usage: cockpit scout [start|dismiss|undo <experiment-id>] [--days <n>] [--dashboard-url <url>] [--json]",
+                "",
+                "Prints the same Scout board the Tower page shows, in the same words: the standing",
+                "watch line, the cards waiting on a decision, and the raw signal watch underneath.",
+                "This is the board itself. To ask a QUESTION about it — what it means, whether it is",
+                "worth doing here — use `cockpit jarvis`, whose readScout tool reads the same rows.",
+                "--days <n> widens or narrows the window (1 to 90; the board defaults to 14).",
+                "Reading follows the Scout page audience setting, so whoever can open /scout can run this.",
+                "start, dismiss, and undo move one card and are super_admin actions on every surface;",
+                "a refusal is printed as Tower worded it and the board stays readable underneath.",
+                "The id can be the first 6 or more characters printed beside each card; an ambiguous",
+                "prefix is refused with the candidates rather than acting on the first match.",
+                "--json writes one object to stdout; operational lines stay on stderr.",
+                "Run `cockpit login` first if this machine is not paired.",
+            ],
+        ],
+        [
+            "workbook",
+            [
+                "Usage: cockpit workbook [<project> [<doc>]] [--section <id>] [--markdown] [--width <n>] [--dashboard-url <url>] [--json]",
+                "",
+                "Reads the Tower workbook library: written project documents — workbooks, runbooks —",
+                "each with an author and a date. With no arguments it lists every compartment and the",
+                "command that opens each document.",
+                "`cockpit workbook tower` lists one project's shelf; `cockpit workbook tower workbook`",
+                "prints that document as wrapped plain text.",
+                "--section <id> prints one section, named by the anchors listed with the document.",
+                "--markdown prints the server's Markdown unchanged, for piping into anything else.",
+                "--width <n> sets the wrap column; otherwise the terminal's width is used, held between 60 and 100.",
+                "There is no pager: pipe it into one if you want paging.",
+                "Sign-in is the only gate, exactly as on the website page.",
                 "Run `cockpit login` first if this machine is not paired.",
             ],
         ],
+        [
+            "brief",
+            [
+                "Usage: cockpit brief [--for <person>] [--version <pageId>] [--tldr|--full] [--versions] [--claims] [--dashboard-url <url>] [--json]",
+                "",
+                "Prints the TODAY page — the same page the Tower website shows, rendered for a terminal.",
+                "--for opens somebody else's page; the website's own rule decides whether you may, and it refuses in plain words when you may not.",
+                "--tldr prints the ten-second version; the whole page is the default.",
+                "--version <pageId> steps back to one exact earlier version; --versions lists them with their ids.",
+                "--claims prints the [claimId] beside every line, which is what `cockpit correct --claim` takes.",
+                "Reading it here counts as opening it, exactly as opening it in a browser does.",
+                "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
+            ],
+        ],
+        [
+            "notes",
+            [
+                "Usage: cockpit notes [list|show <id>|shelf|shelves|upload <paths...>|paste|share <id>|unshare <id>|move <id>] [flags]",
+                "",
+                "The /meeting-notes surface, typed. Bare `cockpit notes` lists the library.",
+                "list [--series <shelf>] [--kind <kind>] [--since <YYYY-MM-DD>] [--until <YYYY-MM-DD>] [--limit <n>] — every note you may open, grouped by shelf, newest meeting first. Never a word of a note.",
+                "show <id> — one note with its text, its shelf, and why you are allowed to see it.",
+                "shelf [--limit <n>] — the notes YOU have put in, and what became of each.",
+                "shelves — the shelves in use, with how many notes are on each.",
+                "upload <paths...> [--exclude \"<sentence>\"] — put one or more local files in. Explicit paths only; your shell does any globbing, and a file that does not exist is named rather than skipped.",
+                "paste [--file <path>] [--name <n>] [--exclude \"<sentence>\"] — put text in with no file. Defaults to stdin: `pbpaste | cockpit notes paste` on macOS, `Get-Clipboard | cockpit notes paste` on Windows.",
+                "--exclude carries your own sentence about what to leave out, exactly as the browser's box does.",
+                "share <id> [--yes] — let everyone signed in read the statements that are safe to share. Asks first in a terminal; --yes is required without one, and --json implies --yes.",
+                "unshare <id> — take it back. Never asks: it only ever narrows who can read.",
+                "move <id> (--to \"<shelf>\"|--clear-shelf) — put it on a different shelf, or take the shelf off.",
+                "A large note is read by a model on the server and can take a couple of minutes; the terminal says so before it waits.",
+                "--json writes one machine-readable object to stdout; every reason, receipt and progress line stays on stderr.",
+                "Sharing and moving need a signed-in session the database can see. If this deployment cannot mint one, they are refused as needs_signed_in_session rather than done with no permission check — and reads say when they came back narrower than the browser's.",
+                "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
+            ],
+        ],
+        [
+            "correct",
+            [
+                "Usage: cockpit correct --claim <claimId> --text \"<what is wrong>\" [--for <person>] [--version <pageId>] [--supersedes <id>] [--dashboard-url <url>] [--json]",
+                "",
+                "Tells Tower that one line on the page is wrong. Same door the website's correction form uses.",
+                "Get the claim id from `cockpit brief --claims`; an id the page does not carry is refused before anything is written.",
+                "--text may be omitted when the correction is piped in on stdin.",
+                "The claim is checked against the live record FIRST. If the record disagrees, JARVIS says so and the correction is still filed with that outcome on it.",
+                "--supersedes <correctionId> takes an earlier correction back; nothing is ever edited or deleted.",
+            ],
+        ],
         [
             "backfill",
             [

package/dist/commands/local.js

@@ -17,6 +17,18 @@
  *   status.ts            `cockpit status`
  *   sessions.ts          `cockpit sessions`
  *   jarvis.ts            terminal adapter for the shared JARVIS gateway
+ *   scout.ts             `cockpit scout` — the board, and the three card verbs
+ *                        (+ scout-render.ts, the pure layout half)
+ *   workbook.ts          `cockpit workbook` — the project document library
+ *                        (+ workbook-render.ts, the pure layout half)
+ *   brief.ts             `cockpit brief` — the TODAY page in the terminal
+ *   correct.ts           `cockpit correct` — one line on it is wrong
+ *   notes.ts             `cockpit notes` — the meeting-notes surface, typed
+ *   notes-file.ts        the local screen a note file passes before it is sent
+ *   tower-command.ts     open a Tower session, call a route, name the refusal
+ *   settings.ts          `cockpit settings` and `cockpit model`
+ *   settings-render.ts   how a settings answer reads in a terminal
+ *   team.ts              `cockpit team` — members, invite, role
  *
  * What stays here is orchestration: onboard, login/logout/start, the sync tick,
  * analyze, serve, autostart and agent-rules.
@@ -34,6 +46,14 @@ import { runInstall, runRelease, runSelfUpdate, runUpdate, SelfUpdateError, } fr
 import { runStatus } from "./status.js";
 import { runSessions } from "./sessions.js";
 import { runJarvis } from "./jarvis.js";
+import { runScout } from "./scout.js";
+import { runModel, runSettings } from "./settings.js";
+import { runTeam } from "./team.js";
+import { asRecord, callTower, openTower } from "./tower-command.js";
+import { runWorkbook } from "./workbook.js";
+import { runBrief } from "./brief.js";
+import { runCorrect } from "./correct.js";
+import { runNotes } from "./notes.js";
 import { createCollectorServer } from "../server.js";
 import { inspectAgentRules, installAgentRules, uninstallAgentRules, } from "../agent-rules.js";
 import { backfillRetryCommand, runBackfill, runBackfillCommand, } from "./backfill.js";
@@ -102,6 +122,22 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
                 return await runAnalyze(command, io);
             case "jarvis":
                 return await runJarvis(command, io);
+            case "model":
+                return await runModel(command, io);
+            case "scout":
+                return await runScout(command, io);
+            case "settings":
+                return await runSettings(command, io);
+            case "team":
+                return await runTeam(command, io);
+            case "workbook":
+                return await runWorkbook(command, io);
+            case "brief":
+                return await runBrief(command, io);
+            case "correct":
+                return await runCorrect(command, io);
+            case "notes":
+                return await runNotes(command, io);
             case "backfill":
                 return await runBackfillCommand(command, io);
             case "status":
@@ -913,16 +949,68 @@ function nextStepForOnboardBlocker(blocker, options = {}) {
             return "Run `cockpit status --json` and report the blocker label plus last failure reason.";
     }
 }
+/**
+ * `cockpit logout` removes the local session file. `--revoke` also tells Tower
+ * to end the device's token (BLI-3461).
+ *
+ * Those are two different facts, and the difference matters when a laptop is
+ * being handed back: without the revoke the machine stops collecting but the
+ * token it held is still one the server would honour. The revoke is attempted
+ * FIRST, because it needs the token the local logout is about to delete, and a
+ * revoke that fails does not stop the local logout — the person asked to be
+ * signed out of this machine, and they get that either way. The outcome of each
+ * half is reported separately rather than folded into one "ok".
+ */
 async function runLogout(command, io) {
+    const revoke = command.revoke ? await revokeThisDevice(command, io) : null;
     const result = await logoutLocalCollector({ homeDir: command.homeDir });
+    writeLine(io.stderr, `[logout] done ${JSON.stringify({
+        local_session: result.removed ? "removed" : "absent",
+        revoke: revoke ? revoke.outcome : "not_requested",
+    })}`);
     if (command.json) {
-        writeLine(io.stdout, JSON.stringify(result, null, 2));
-        return 0;
+        writeLine(io.stdout, JSON.stringify({ ...result, revoke: revoke ?? { outcome: "not_requested" } }, null, 2));
+        return revoke && revoke.outcome !== "revoked" ? 1 : 0;
     }
     writeLine(io.stdout, result.removed
         ? "Tower collector session removed."
         : "No Tower collector session found.");
-    return 0;
+    if (revoke) {
+        writeLine(io.stdout, revoke.outcome === "revoked"
+            ? "This device's Tower token is revoked."
+            : `This device's Tower token was NOT revoked: ${revoke.detail}`);
+    }
+    return revoke && revoke.outcome !== "revoked" ? 1 : 0;
+}
+/**
+ * Ends this device's own session server-side.
+ *
+ * The route gates the device arm on `self_revoke_only`, so the device id is
+ * read from the paired session rather than accepted as an argument — there is
+ * no way to spell "revoke somebody else's laptop" here, and that is deliberate.
+ */
+async function revokeThisDevice(command, io) {
+    let tower;
+    let deviceId;
+    try {
+        const session = await readLocalCollectorSessionFile(getCollectorRuntimePaths(command.homeDir));
+        deviceId = session.device_id;
+        tower = await openTower("logout", command, io);
+    }
+    catch (error) {
+        return { outcome: "no_paired_session", detail: errorMessage(error) };
+    }
+    const result = await callTower(tower, {
+        path: `/api/ambient/devices/${encodeURIComponent(deviceId)}/revoke`,
+        method: "POST",
+        label: "logout revoke",
+        body: { reason: "Signed out from the device" },
+    });
+    if (!result.ok) {
+        return { outcome: result.reason, detail: result.detail };
+    }
+    const body = asRecord(result.body);
+    return { outcome: "revoked", detail: String(asRecord(body.device).revoked_at ?? "") };
 }
 async function runStart(command, io) {
     const worktrees = await discoverCommandWorktrees(command.repoRoot, { maxDepth: command.maxDepth, maxRepos: command.maxRepos, homeDir: command.homeDir }, io);

package/dist/commands/notes-file.js

@@ -0,0 +1,102 @@
+/**
+ * Reads a local file for `cockpit notes upload <paths...>` and `cockpit notes
+ * paste --file <path>` (BLI-3459), before anything is uploaded.
+ *
+ * The dashboard's `/api/notes/upload` route is the ONE authority on whether a
+ * dropped note is acceptable — `checkUploadedNoteFile` in
+ * `@bli-cockpit/harvest-analysis/meeting-notes/uploaded-file` holds the secret
+ * guard, the byte ceiling and the format classification, and this package
+ * cannot import from it (separate workspace, no dependency edge). So this
+ * module only catches what is cheap and purely local to check BEFORE spending a
+ * network round trip: does the path exist, is it a regular file this account can
+ * read, is there anything in it, and is it under the ceiling. Same discipline as
+ * `jarvis-attachment.ts`, and the same rule if the two ever drift: the server's
+ * check wins.
+ *
+ * **There is deliberately no extension refusal here.** BLI-3398 made every file
+ * name resolve to one of nine formats with `unknown` ACCEPTED, kept and labeled
+ * rather than turned away. A local extension allowlist would refuse files the
+ * server would happily store, which is exactly the withholding this repo's
+ * session-first rule forbids. The extension is reported so the terminal can name
+ * what it is sending; it never decides anything.
+ *
+ * Nothing here throws. Every failure mode comes back as a named refusal, so the
+ * command prints a plain sentence rather than a stack trace, and the refusal
+ * label is what travels into the log line.
+ */
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { isSecretLikePathSegment } from "@bli-cockpit/telemetry-core";
+import { errorMessage } from "./cli-io.js";
+/**
+ * Mirrors `UPLOADED_NOTE_MAX_BYTES` in
+ * `packages/cockpit-harvest-analysis/src/meeting-notes/uploaded-file.ts`. A
+ * courtesy check to avoid uploading something the server is certain to refuse,
+ * not a second source of truth.
+ */
+export const NOTE_FILE_MAX_BYTES = 20 * 1024 * 1024;
+/**
+ * Above this, the terminal says it is working before it starts. The route's own
+ * ceiling is `maxDuration = 300` because reading a note is one model call over
+ * the whole file, and a person watching a still cursor for two minutes assumes
+ * it hung.
+ */
+export const NOTE_SLOW_UPLOAD_BYTES = 256 * 1024;
+/** The sentence the terminal prints for a refusal caught locally, before any request goes out. */
+export function noteFileRefusalSentence(refusal, filePath) {
+    switch (refusal) {
+        case "file_not_found":
+            return `I could not find that file: ${filePath}`;
+        case "file_unreadable":
+            return `I could not read that file: ${filePath}`;
+        case "file_empty":
+            return `There is nothing in that file: ${filePath}`;
+        case "file_too_big":
+            return "That file is too big to put in as a note — keep it under 20 MB.";
+        case "looks_like_a_key_file":
+            // The same rule the server's gate applies, said the same way: the name is
+            // all it takes to decide, and looking inside to be sure would already be
+            // the thing the rule forbids.
+            return `That name looks like a key or credential file, so I did not open it: ${filePath}`;
+    }
+}
+/**
+ * Reads and locally screens one note file. Never throws.
+ *
+ * The secret-shaped-name check runs FIRST and on the name alone — the bytes are
+ * never read for a file it turns away.
+ */
+export async function readNoteFile(filePath) {
+    const fileName = path.basename(filePath);
+    const extension = path.extname(filePath).toLowerCase();
+    if (isSecretLikePathSegment(fileName)) {
+        return { ok: false, refusal: "looks_like_a_key_file", detail: "secret_like_name" };
+    }
+    let size;
+    try {
+        const info = await stat(filePath);
+        if (!info.isFile()) {
+            return { ok: false, refusal: "file_unreadable", detail: "not_a_regular_file" };
+        }
+        size = info.size;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT")
+            return { ok: false, refusal: "file_not_found", detail: "enoent" };
+        return { ok: false, refusal: "file_unreadable", detail: errorMessage(error) };
+    }
+    if (size === 0)
+        return { ok: false, refusal: "file_empty", detail: "byte_size_0" };
+    if (size > NOTE_FILE_MAX_BYTES) {
+        return { ok: false, refusal: "file_too_big", detail: `byte_size_${size}` };
+    }
+    let bytes;
+    try {
+        bytes = await readFile(filePath);
+    }
+    catch (error) {
+        return { ok: false, refusal: "file_unreadable", detail: errorMessage(error) };
+    }
+    return { ok: true, bytes, fileName, extension: extension || "none" };
+}