@bli-cockpit/cli 0.2.56 → 0.2.58

package/dist/commands/agent-door.js

@@ -0,0 +1,85 @@
+/**
+ * One request, and a refusal that keeps the DOOR'S own words (BLI-3706).
+ *
+ * `docs`/`msg` answer a refusal with `{ code: "BLI-E<status>", reason, message }`
+ * (`lib/docs/api-doors.ts` / `lib/msg/api-doors.ts`), a different shape from
+ * the meeting-notes doors' `{ headline, lines, reason }` that `notes.ts`'s own
+ * `ask()` reads. This is that same discipline for the newer shape: the
+ * `reason` label a door chose travels to the terminal UNCHANGED, and `message`
+ * is the sentence a person reads — never a second wording invented here.
+ *
+ * `cockpit docs` and `cockpit msg` both call this rather than keeping two
+ * copies, because the shape is identical on both surfaces (BLI-3654 Wave 1a
+ * and Wave 3a share `resolveCaller` + a `{code,reason,message}` refusal).
+ */
+import { writeLine } from "./cli-io.js";
+import { loadPairedSession, towerFailureDetail, towerRequest, } from "../tower-client.js";
+import { readResponseJson } from "../upload-http.js";
+/** Loads the paired session and builds the door every verb in one command run shares. */
+export async function openAgentDoor(commandName, command, io) {
+    const session = await loadPairedSession(commandName, command.homeDir);
+    return {
+        dashboardUrl: command.dashboardUrl ?? session.dashboard_url,
+        deviceToken: session.device_token,
+        io,
+        json: command.json,
+    };
+}
+export async function askAgentDoor(door, options) {
+    const result = await towerRequest({
+        dashboardUrl: door.dashboardUrl,
+        path: options.path,
+        deviceToken: door.deviceToken,
+        fetch: door.io.fetch,
+        method: options.method,
+        label: options.label,
+        timeoutMs: options.timeoutMs,
+        ...(options.body === undefined ? {} : { body: options.body }),
+        log: (line) => writeLine(door.io.stderr, line),
+    });
+    if (!result.ok) {
+        const failure = result;
+        return { ok: false, reason: failure.reason, detail: towerFailureDetail(failure.reason, failure.detail) };
+    }
+    const body = await readResponseJson(result.response);
+    if (!result.response.ok) {
+        const status = result.response.status;
+        return {
+            ok: false,
+            httpStatus: status,
+            reason: doorReason(body) ?? `http_${status}`,
+            detail: doorMessage(body) ?? `Tower answered ${status} and said nothing about why.`,
+        };
+    }
+    return { ok: true, httpStatus: result.response.status, body };
+}
+/** The door's own `reason` label (`document_not_found_or_unreadable`, `needs_rls_client`, …), verbatim. */
+function doorReason(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const record = body;
+    const value = record["reason"] ?? record["error"];
+    return typeof value === "string" && value.trim() !== "" ? value : null;
+}
+function doorMessage(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const record = body;
+    const value = record["message"];
+    return typeof value === "string" && value.trim() !== "" ? value : null;
+}
+/** One machine-readable object on stdout, and nothing else on it. */
+export function emitAgentDoor(door, body, exitCode = 0) {
+    writeLine(door.io.stdout, JSON.stringify(body));
+    return exitCode;
+}
+export function failAgentDoor(door, tag, reason, detail) {
+    writeLine(door.io.stderr, `${tag} refused ${JSON.stringify({ reason })}`);
+    if (door.json) {
+        writeLine(door.io.stdout, JSON.stringify({ ok: false, error: reason, detail }));
+    }
+    else {
+        writeLine(door.io.stderr, detail);
+    }
+    return 1;
+}

package/dist/commands/docs.js

@@ -0,0 +1,227 @@
+/**
+ * `cockpit docs` — the document library, typed (BLI-3706).
+ *
+ * Five verbs over `/api/docs/**`, the same doors the `/workbook`… no, the
+ * SEPARATE `/api/docs/**` surface (BLI-3654 Wave 3a) that the browser's own
+ * document editor reads and writes. Every `/api/docs/**` route already opted
+ * into the collector device token via `resolveCaller({ allowDeviceToken: true
+ * })` — this command needed no server-side door change, only a terminal in
+ * front of the existing one.
+ *
+ * `read <id|slug>` and `update <id>` both accept a full document id OR its
+ * slug. There is no `GET` by slug on the server (`getDocument` reads by id
+ * only), so a slug is resolved locally against the flat list `GET
+ * /api/docs/documents` already returns — the same read `docs list` prints,
+ * never a second query the server does not already answer.
+ *
+ * A refusal keeps the door's own `reason` label verbatim (`agent-door.ts`):
+ * `needs_rls_client`, `document_not_found_or_unreadable`,
+ * `document_not_writable`, `title_too_long`, `content_too_long`,
+ * `circular_parent`, and so on — never rephrased here.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+import { readNoteFile } from "./notes-file.js";
+const TAG = "[docs cli]";
+const READ_DEADLINE_MS = 30_000;
+const WRITE_DEADLINE_MS = 60_000;
+const BODY_MAX_CHARS = 2_000_000;
+export async function runDocs(command, io) {
+    const door = await openAgentDoor("docs", command, io);
+    switch (command.action) {
+        case "list":
+            return listDocs(door);
+        case "tree":
+            return treeDocs(door);
+        case "read":
+            return readDoc(command, door);
+        case "create":
+            return createDoc(command, door);
+        case "update":
+            return updateDoc(command, door);
+    }
+}
+async function listDocs(door) {
+    const answer = await askAgentDoor(door, {
+        path: "/api/docs/documents",
+        method: "GET",
+        label: "docs list",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const documents = (answer.body.documents ?? []);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, documents });
+    if (documents.length === 0) {
+        writeLine(door.io.stdout, "No documents.");
+        return 0;
+    }
+    for (const doc of documents) {
+        writeLine(door.io.stdout, `${doc.id}  ${doc.visibility.padEnd(7)}  ${doc.slug ?? "(no slug)"}  ${doc.title}`);
+    }
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${documents.length} document(s).`);
+    return 0;
+}
+function renderTree(nodes, io, depth) {
+    for (const node of nodes) {
+        writeLine(io.stdout, `${"  ".repeat(depth)}${node.title} (${node.slug ?? node.id})`);
+        if (node.children.length > 0)
+            renderTree(node.children, io, depth + 1);
+    }
+}
+async function treeDocs(door) {
+    const answer = await askAgentDoor(door, {
+        path: "/api/docs/tree",
+        method: "GET",
+        label: "docs tree",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const tree = (answer.body.tree ?? []);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, tree });
+    if (tree.length === 0) {
+        writeLine(door.io.stdout, "No documents.");
+        return 0;
+    }
+    renderTree(tree, door.io, 0);
+    return 0;
+}
+/** Finds a document id by exact id or exact slug against the flat list. Never fuzzy. */
+async function resolveDocId(door, ref) {
+    const answer = await askAgentDoor(door, {
+        path: "/api/docs/documents",
+        method: "GET",
+        label: "docs resolve",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return { status: "list_failed", reason: answer.reason, detail: answer.detail };
+    const documents = (answer.body.documents ?? []);
+    const byId = documents.find((doc) => doc.id === ref);
+    if (byId)
+        return { status: "ok", id: byId.id };
+    const bySlug = documents.find((doc) => doc.slug === ref);
+    if (bySlug)
+        return { status: "ok", id: bySlug.id };
+    return { status: "not_found" };
+}
+async function readDoc(command, door) {
+    const ref = command.docRef ?? "";
+    const resolved = await resolveDocId(door, ref);
+    if (resolved.status === "list_failed")
+        return failAgentDoor(door, TAG, resolved.reason, resolved.detail);
+    if (resolved.status === "not_found") {
+        return failAgentDoor(door, TAG, "document_not_found_or_unreadable", `That document does not exist, or you cannot read it: ${ref}`);
+    }
+    const answer = await askAgentDoor(door, {
+        path: `/api/docs/documents/${encodeURIComponent(resolved.id)}`,
+        method: "GET",
+        label: "docs read",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const document = answer.body.document ?? {};
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, document });
+    writeLine(door.io.stdout, String(document["title"] ?? ""));
+    writeLine(door.io.stdout, `${document["slug"] ?? "(no slug)"}  ·  ${document["visibility"] ?? ""}  ·  ${document["source"] ?? ""}`);
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, String(document["body_markdown"] ?? ""));
+    return 0;
+}
+/** Body on stdin, never argv (BLI-3706) — `--file` is the safest way on Windows, same as `cockpit notes paste`. */
+async function readBody(command, io) {
+    if (command.filePath) {
+        const read = await readNoteFile(command.filePath);
+        if (!read.ok)
+            return { ok: false, reason: read.refusal, detail: `Could not read ${command.filePath}: ${read.detail}` };
+        return { ok: true, text: read.bytes.toString("utf8") };
+    }
+    if (isInteractiveStdin(io))
+        return { ok: true, text: "" };
+    try {
+        const text = await readPipedText(io.stdin, {
+            maxChars: BODY_MAX_CHARS,
+            overflowMessage: `A document body is limited to ${BODY_MAX_CHARS} characters.`,
+        });
+        return { ok: true, text };
+    }
+    catch (error) {
+        return { ok: false, reason: "body_too_long", detail: error instanceof Error ? error.message : String(error) };
+    }
+}
+async function createDoc(command, door) {
+    if (!command.title)
+        return failAgentDoor(door, TAG, "invalid_body", "docs create needs --title.");
+    const body = await readBody(command, door.io);
+    if (!body.ok)
+        return failAgentDoor(door, TAG, body.reason, body.detail);
+    const answer = await askAgentDoor(door, {
+        path: "/api/docs/documents",
+        method: "POST",
+        label: "docs create",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            title: command.title,
+            body_markdown: body.text,
+            ...(command.parentId ? { parent_id: command.parentId } : {}),
+            ...(command.visibility ? { visibility: command.visibility } : {}),
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const document = answer.body.document ?? {};
+    writeLine(door.io.stderr, `${TAG} created ${JSON.stringify({ document_id: document["id"] ?? null, byte_size: Buffer.byteLength(body.text, "utf8") })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, document });
+    writeLine(door.io.stdout, `Created ${String(document["title"] ?? "")} (${String(document["id"] ?? "")}).`);
+    return 0;
+}
+async function updateDoc(command, door) {
+    const ref = command.docRef ?? "";
+    const resolved = await resolveDocId(door, ref);
+    if (resolved.status === "list_failed")
+        return failAgentDoor(door, TAG, resolved.reason, resolved.detail);
+    if (resolved.status === "not_found") {
+        return failAgentDoor(door, TAG, "document_not_found_or_unreadable", `That document does not exist, or you cannot write to it: ${ref}`);
+    }
+    let bodyMarkdown;
+    if (command.bodyStdin || command.filePath) {
+        const body = await readBody(command, door.io);
+        if (!body.ok)
+            return failAgentDoor(door, TAG, body.reason, body.detail);
+        bodyMarkdown = body.text;
+    }
+    if (bodyMarkdown === undefined
+        && command.title === undefined
+        && command.visibility === undefined
+        && command.parentId === undefined
+        && !command.clearParent) {
+        return failAgentDoor(door, TAG, "invalid_body", "docs update needs at least one of --title, --visibility, --parent/--clear-parent, or a body on --body-stdin/--file.");
+    }
+    const answer = await askAgentDoor(door, {
+        path: `/api/docs/documents/${encodeURIComponent(resolved.id)}`,
+        method: "PATCH",
+        label: "docs update",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            ...(command.title !== undefined ? { title: command.title } : {}),
+            ...(bodyMarkdown !== undefined ? { body_markdown: bodyMarkdown } : {}),
+            ...(command.visibility !== undefined ? { visibility: command.visibility } : {}),
+            ...(command.clearParent ? { parent_id: null } : command.parentId ? { parent_id: command.parentId } : {}),
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const document = answer.body.document ?? {};
+    writeLine(door.io.stderr, `${TAG} updated ${JSON.stringify({ document_id: document["id"] ?? resolved.id })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, document });
+    writeLine(door.io.stdout, `Updated ${String(document["title"] ?? "")} (${String(document["id"] ?? resolved.id)}).`);
+    return 0;
+}

package/dist/commands/issue-contracts.js

@@ -0,0 +1,99 @@
+/**
+ * What `cockpit issue` hands between its own halves (BLI-3716): the row
+ * shapes the `/api/work/**` doors answer with, the two deadlines, and the
+ * three "which one did you mean" resolvers both the read half (`issue.ts`)
+ * and the write half (`issue-write.ts`) need.
+ *
+ * Split out so neither half carries the other's weight — the same table-of-
+ * contents discipline `commands/session-sync*.ts` and `commands/backfill*.ts`
+ * follow, applied before the file got large rather than after.
+ */
+import { askAgentDoor } from "./agent-door.js";
+import { isInteractiveStdin, readPipedText } from "./cli-io.js";
+import { readNoteFile } from "./notes-file.js";
+export const TAG = "[issue cli]";
+export const READ_DEADLINE_MS = 30_000;
+export const WRITE_DEADLINE_MS = 60_000;
+export const BODY_MAX_CHARS = 200_000;
+/** A project id from a project NAME or a uuid — exact after case-folding. */
+export async function resolveProjectId(door, ref) {
+    const answer = await askAgentDoor(door, {
+        path: "/api/work/projects?include_archived=true",
+        method: "GET",
+        label: "issue project resolve",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return { status: "list_failed", reason: answer.reason, detail: answer.detail };
+    const projects = answer.body.projects ?? [];
+    const wanted = ref.toLowerCase();
+    const match = projects.find((project) => project.id === ref || project.name.toLowerCase() === wanted);
+    return match ? { status: "ok", id: match.id } : { status: "not_found" };
+}
+/** A parent issue's uuid from any issue reference, via the door's own resolver. */
+export async function resolveIssueUuid(door, ref) {
+    const answer = await askAgentDoor(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}`,
+        method: "GET",
+        label: "issue parent resolve",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return { status: "failed", reason: answer.reason, detail: answer.detail };
+    const issue = answer.body.issue;
+    if (!issue?.id) {
+        return {
+            status: "failed",
+            reason: "issue_not_found_or_unreadable",
+            detail: `That issue does not exist, or you cannot read it: ${ref}`,
+        };
+    }
+    return { status: "ok", id: issue.id };
+}
+/** Body on stdin, never argv — `--file` is the safest way on Windows. */
+export async function readBody(command, io) {
+    if (command.filePath) {
+        const read = await readNoteFile(command.filePath);
+        if (!read.ok) {
+            return { ok: false, reason: read.refusal, detail: `Could not read ${command.filePath}: ${read.detail}` };
+        }
+        return { ok: true, text: read.bytes.toString("utf8") };
+    }
+    if (isInteractiveStdin(io))
+        return { ok: true, text: "" };
+    try {
+        const text = await readPipedText(io.stdin, {
+            maxChars: BODY_MAX_CHARS,
+            overflowMessage: `An issue description is limited to ${BODY_MAX_CHARS} characters.`,
+        });
+        return { ok: true, text };
+    }
+    catch (error) {
+        return { ok: false, reason: "description_too_long", detail: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** The project/parent halves both `create` and `update` need, resolved once. */
+export async function resolveRefs(command, door) {
+    let projectId;
+    let parentId;
+    if (command.project) {
+        const resolved = await resolveProjectId(door, command.project);
+        if (resolved.status === "list_failed")
+            return { ok: false, reason: resolved.reason, detail: resolved.detail };
+        if (resolved.status === "not_found") {
+            return {
+                ok: false,
+                reason: "project_not_found_or_unreadable",
+                detail: `No project here is called "${command.project}" — run \`cockpit project list\` for the names.`,
+            };
+        }
+        projectId = resolved.id;
+    }
+    if (command.parentRef) {
+        const resolved = await resolveIssueUuid(door, command.parentRef);
+        if (resolved.status === "failed")
+            return { ok: false, reason: resolved.reason, detail: resolved.detail };
+        parentId = resolved.id;
+    }
+    return { ok: true, ...(projectId ? { projectId } : {}), ...(parentId ? { parentId } : {}) };
+}

package/dist/commands/issue-write.js

@@ -0,0 +1,129 @@
+/**
+ * The verbs that CHANGE something: `cockpit issue create|update|move|comment`
+ * (BLI-3716). The reads and the router live in `issue.ts`, the shared shapes
+ * and resolvers in `issue-contracts.ts`.
+ *
+ * Every write prints a receipt line on stderr naming what it did and to
+ * which row, success included — `--json` owns stdout, so a receipt that went
+ * there would corrupt the one machine-readable object a caller parses.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor, } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { TAG, WRITE_DEADLINE_MS, readBody, resolveRefs, } from "./issue-contracts.js";
+export async function createIssue(command, door) {
+    if (!command.title)
+        return failAgentDoor(door, TAG, "invalid_body", "issue create needs --title.");
+    const refs = await resolveRefs(command, door);
+    if (!refs.ok)
+        return failAgentDoor(door, TAG, refs.reason, refs.detail);
+    const body = await readBody(command, door.io);
+    if (!body.ok)
+        return failAgentDoor(door, TAG, body.reason, body.detail);
+    const answer = await askAgentDoor(door, {
+        path: "/api/work/issues",
+        method: "POST",
+        label: "issue create",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            title: command.title,
+            ...(body.text ? { description: body.text } : {}),
+            ...(refs.projectId ? { project_id: refs.projectId } : {}),
+            ...(refs.parentId ? { parent_id: refs.parentId } : {}),
+            ...(command.priority === undefined ? {} : { priority: command.priority }),
+            ...(command.assignee ? { assignee_id: command.assignee } : {}),
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const issue = answer.body.issue;
+    writeLine(door.io.stderr, `${TAG} created ${JSON.stringify({ issue_id: issue?.id ?? null, identifier: issue?.identifier ?? null, description_bytes: Buffer.byteLength(body.text, "utf8") })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, issue });
+    writeLine(door.io.stdout, `Created ${issue?.identifier ?? ""} — ${issue?.title ?? ""} (${issue?.id ?? ""}).`);
+    return 0;
+}
+export async function updateIssue(command, door) {
+    const ref = command.issueRef ?? "";
+    const refs = await resolveRefs(command, door);
+    if (!refs.ok)
+        return failAgentDoor(door, TAG, refs.reason, refs.detail);
+    let description;
+    if (command.bodyStdin || command.filePath) {
+        const body = await readBody(command, door.io);
+        if (!body.ok)
+            return failAgentDoor(door, TAG, body.reason, body.detail);
+        description = body.text;
+    }
+    if (description === undefined
+        && command.title === undefined
+        && command.priority === undefined
+        && command.assignee === undefined
+        && refs.projectId === undefined
+        && refs.parentId === undefined) {
+        return failAgentDoor(door, TAG, "invalid_body", "issue update needs at least one of --title, --priority, --assignee, --project, --parent, or a description on --body-stdin/--file.");
+    }
+    const answer = await askAgentDoor(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}`,
+        method: "PATCH",
+        label: "issue update",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            ...(command.title !== undefined ? { title: command.title } : {}),
+            ...(description !== undefined ? { description } : {}),
+            ...(command.priority === undefined ? {} : { priority: command.priority }),
+            ...(command.assignee ? { assignee_id: command.assignee } : {}),
+            ...(refs.projectId ? { project_id: refs.projectId } : {}),
+            ...(refs.parentId ? { parent_id: refs.parentId } : {}),
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const issue = answer.body.issue;
+    writeLine(door.io.stderr, `${TAG} updated ${JSON.stringify({ issue_id: issue?.id ?? null, identifier: issue?.identifier ?? null })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, issue });
+    writeLine(door.io.stdout, `Updated ${issue?.identifier ?? ref} — ${issue?.title ?? ""}.`);
+    return 0;
+}
+export async function moveIssue(command, door) {
+    const ref = command.issueRef ?? "";
+    const answer = await askAgentDoor(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}/state`,
+        method: "POST",
+        label: "issue move",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: { state: command.moveState },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const issue = answer.body.issue;
+    writeLine(door.io.stderr, `${TAG} moved ${JSON.stringify({ issue_id: issue?.id ?? null, identifier: issue?.identifier ?? null, to_state: command.moveState })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, issue });
+    writeLine(door.io.stdout, `${issue?.identifier ?? ref} is now ${issue?.state ?? command.moveState}.`);
+    return 0;
+}
+export async function commentIssue(command, door) {
+    const ref = command.issueRef ?? "";
+    const body = await readBody(command, door.io);
+    if (!body.ok)
+        return failAgentDoor(door, TAG, body.reason, body.detail);
+    if (body.text.trim() === "") {
+        return failAgentDoor(door, TAG, "invalid_body", 'A comment is never taken on the command line — pipe it in: `echo "..." | cockpit issue comment BLI-3654`.');
+    }
+    const answer = await askAgentDoor(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}/comments`,
+        method: "POST",
+        label: "issue comment",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: { body_markdown: body.text },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const comment = answer.body.comment;
+    writeLine(door.io.stderr, `${TAG} commented ${JSON.stringify({ comment_id: comment?.id ?? null, byte_size: Buffer.byteLength(body.text, "utf8") })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, comment });
+    writeLine(door.io.stdout, `Commented on ${ref} (${comment?.id ?? ""}).`);
+    return 0;
+}