@bli-cockpit/cli 0.2.56 → 0.2.58

package/dist/commands/issue.js

@@ -0,0 +1,189 @@
+/**
+ * `cockpit issue` — Tower's issue tracker, typed (BLI-3716).
+ *
+ * Seven verbs over `/api/work/**`, the same doors the browser uses. Every
+ * one of those routes already accepted the collector device token
+ * (`resolveCaller({ allowDeviceToken: true })`, BLI-3703), so this command
+ * is a terminal in front of an existing door, not a new one.
+ *
+ * Three references a person actually types, resolved here or by the door:
+ *  - an ISSUE is `BLI-3654` or a uuid. The SERVER resolves it
+ *    (`lib/work/issue-ref.ts`), so `show`/`move`/`comment`/`history` cost one
+ *    request, not two.
+ *  - a PROJECT is its name or a uuid, resolved by `issue-contracts.ts`
+ *    against the same `GET /api/work/projects` list `cockpit project list`
+ *    prints — exact after case-folding, never fuzzy.
+ *  - a PARENT is another issue reference, resolved with one `GET` so the
+ *    create/patch body carries the uuid its schema demands.
+ *
+ * This file is the router plus the READ verbs (`list`, `show`, `history`);
+ * `issue-write.ts` holds `create`, `update`, `move` and `comment`, and
+ * `issue-contracts.ts` the shapes and resolvers both halves share.
+ *
+ * Bodies never travel on argv: a description or a comment comes from stdin
+ * or `--file`. A refusal keeps the door's own `reason` label verbatim
+ * (`agent-door.ts`) — `issue_not_found_or_unreadable`, `invalid_state`,
+ * `needs_rls_client`, `comment_too_long`, and so on.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { READ_DEADLINE_MS, TAG, resolveProjectId, } from "./issue-contracts.js";
+import { commentIssue, createIssue, moveIssue, updateIssue } from "./issue-write.js";
+export async function runIssue(command, io) {
+    const door = await openAgentDoor("issue", command, io);
+    switch (command.action) {
+        case "list":
+            return listIssues(command, door);
+        case "show":
+            return showIssue(command, door);
+        case "create":
+            return createIssue(command, door);
+        case "update":
+            return updateIssue(command, door);
+        case "move":
+            return moveIssue(command, door);
+        case "comment":
+            return commentIssue(command, door);
+        case "history":
+            return issueHistory(command, door);
+    }
+}
+function issueLine(issue) {
+    return `${issue.identifier.padEnd(9)}  ${issue.state.padEnd(11)}  ${issue.title}`;
+}
+async function listIssues(command, door) {
+    const query = new URLSearchParams();
+    if (command.stateFilter)
+        query.set("state", command.stateFilter);
+    if (command.assignee)
+        query.set("assignee_id", command.assignee);
+    if (command.limit !== undefined)
+        query.set("limit", String(command.limit));
+    if (command.project) {
+        const resolved = await resolveProjectId(door, command.project);
+        if (resolved.status === "list_failed")
+            return failAgentDoor(door, TAG, resolved.reason, resolved.detail);
+        if (resolved.status === "not_found") {
+            return failAgentDoor(door, TAG, "project_not_found_or_unreadable", `No project here is called "${command.project}" — run \`cockpit project list\` for the names.`);
+        }
+        query.set("project_id", resolved.id);
+    }
+    const suffix = query.toString();
+    const answer = await askAgentDoor(door, {
+        path: `/api/work/issues${suffix ? `?${suffix}` : ""}`,
+        method: "GET",
+        label: "issue list",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const issues = answer.body.issues ?? [];
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, issues });
+    if (issues.length === 0) {
+        writeLine(door.io.stdout, "No issues match that.");
+        return 0;
+    }
+    for (const issue of issues)
+        writeLine(door.io.stdout, issueLine(issue));
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${issues.length} issue(s).`);
+    return 0;
+}
+async function showIssue(command, door) {
+    const ref = command.issueRef ?? "";
+    const answer = await askAgentDoor(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}`,
+        method: "GET",
+        label: "issue show",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const issue = answer.body.issue;
+    if (!issue) {
+        return failAgentDoor(door, TAG, "issue_not_found_or_unreadable", `That issue does not exist, or you cannot read it: ${ref}`);
+    }
+    // A comment read that fails does NOT fail the whole `show` — the issue is
+    // already in hand, and a named gap beats losing what was read.
+    const commentsAnswer = await askAgentDoor(door, {
+        path: `/api/work/issues/${encodeURIComponent(issue.id)}/comments`,
+        method: "GET",
+        label: "issue show comments",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    const comments = commentsAnswer.ok
+        ? (commentsAnswer.body.comments ?? [])
+        : [];
+    if (!commentsAnswer.ok) {
+        writeLine(door.io.stderr, `${TAG} comments unread ${JSON.stringify({ reason: commentsAnswer.reason, issue_id: issue.id })}`);
+    }
+    if (door.json) {
+        return emitAgentDoor(door, {
+            ok: true,
+            issue,
+            comments,
+            ...(commentsAnswer.ok ? {} : { comments_unread_reason: commentsAnswer.reason }),
+        });
+    }
+    writeLine(door.io.stdout, `${issue.identifier}  ${issue.title}`);
+    writeLine(door.io.stdout, `${issue.state}  ·  priority ${issue.priority ?? 0}  ·  assignee ${issue.assignee_id ?? "(nobody)"}  ·  updated ${issue.updated_at}`);
+    writeLine(door.io.stdout, `id ${issue.id}${issue.parent_id ? `  ·  parent ${issue.parent_id}` : ""}`);
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, issue.description ?? "(no description)");
+    if (comments.length > 0) {
+        writeLine(door.io.stdout, "");
+        writeLine(door.io.stdout, `--- ${comments.length} comment(s) ---`);
+        for (const comment of comments) {
+            writeLine(door.io.stdout, "");
+            writeLine(door.io.stdout, `[${comment.created_at}] ${comment.author_name ?? comment.author_id ?? "unknown"}`);
+            writeLine(door.io.stdout, comment.body_markdown);
+        }
+    }
+    else if (commentsAnswer.ok) {
+        writeLine(door.io.stdout, "");
+        writeLine(door.io.stdout, "No comments.");
+    }
+    return 0;
+}
+/**
+ * What a history row actually says. A row imported from Linear's issue
+ * TIMESTAMPS (created/started/completed/canceled) carries no state names at
+ * all: the reader refuses to name a workflow state it cannot prove
+ * (`linear-reader.ts` `buildSyntheticTransitions` — "naming a stale workflow
+ * state would be a small invented fact"), and only the state CATEGORY it did
+ * know is dropped on the way into `work_issue_history`. Printing
+ * "(none) -> (none)" is honest and useless; this says which it is, so nobody
+ * reads a real gap as a broken command.
+ */
+function historyChange(row) {
+    if (row.from_value === null && row.to_value === null) {
+        return `(no state names recorded — imported from ${row.source})`;
+    }
+    return `${row.from_value ?? "(none)"} -> ${row.to_value ?? "(none)"}`;
+}
+async function issueHistory(command, door) {
+    const ref = command.issueRef ?? "";
+    const query = command.limit === undefined ? "" : `?limit=${command.limit}`;
+    const answer = await askAgentDoor(door, {
+        path: `/api/work/issues/${encodeURIComponent(ref)}/history${query}`,
+        method: "GET",
+        label: "issue history",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const history = answer.body.history ?? [];
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, history });
+    if (history.length === 0) {
+        writeLine(door.io.stdout, `No recorded changes for ${ref}.`);
+        return 0;
+    }
+    for (const row of history) {
+        writeLine(door.io.stdout, `${row.occurred_at}  ${row.change_type.padEnd(9)}  ${historyChange(row)}  ${row.actor_name ?? ""}`.trimEnd());
+    }
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${history.length} change(s).`);
+    return 0;
+}

package/dist/commands/local-args-tower-docs-msg.js

@@ -0,0 +1,126 @@
+/**
+ * `cockpit docs` and `cockpit msg` argument parsing (BLI-3706). Split into its
+ * own sibling of `local-args-tower.ts` rather than folded into
+ * `local-args-tower-pages.ts`: docs is a page-reading surface like notes and
+ * workbook, but msg is not — it is a live two-way channel, closer to
+ * `cockpit jarvis` in shape. Keeping the pair together names the ticket that
+ * added both without stretching either existing family's own doc comment.
+ */
+import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
+const DOCS_ACTIONS = new Set(["list", "tree", "read", "create", "update"]);
+const DOCS_ACTIONS_NEEDING_A_DOC = new Set(["read", "update"]);
+export function parseDocsArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [
+            "--home",
+            "--dashboard-url",
+            "--title",
+            "--parent",
+            "--clear-parent",
+            "--visibility",
+            "--file",
+            "--body-stdin",
+            "--json",
+        ],
+        valueFlags: ["--home", "--dashboard-url", "--title", "--parent", "--visibility", "--file"],
+    });
+    const first = values.positionals[0];
+    const action = (first === undefined ? "list" : first);
+    if (!DOCS_ACTIONS.has(action)) {
+        throw new Error(`Unknown docs command: ${first}. Try list, tree, read, create, or update.`);
+    }
+    const rest = values.positionals.slice(first === undefined ? 0 : 1);
+    let docRef;
+    if (DOCS_ACTIONS_NEEDING_A_DOC.has(action)) {
+        docRef = optionalNonEmpty(rest[0]);
+        if (!docRef)
+            throw new Error(`docs ${action} needs a document id or slug.`);
+        if (rest.length > 1)
+            throw new Error(`docs ${action} takes one document reference, not ${rest.length}.`);
+    }
+    else if (rest.length > 0) {
+        throw new Error(`docs ${action} does not take "${rest[0]}".`);
+    }
+    const visibility = optionalNonEmpty(values.flags.get("--visibility"));
+    if (visibility && visibility !== "org" && visibility !== "private") {
+        throw new Error('docs --visibility must be "org" or "private".');
+    }
+    const clearParent = values.booleans.has("--clear-parent");
+    const parentId = optionalNonEmpty(values.flags.get("--parent"));
+    if (clearParent && parentId) {
+        throw new Error("docs update accepts either --parent or --clear-parent, not both.");
+    }
+    if (clearParent && action !== "update") {
+        throw new Error("--clear-parent belongs to `cockpit docs update`.");
+    }
+    const title = optionalNonEmpty(values.flags.get("--title"));
+    if (action === "create" && !title) {
+        throw new Error("docs create needs --title.");
+    }
+    return {
+        kind: "docs",
+        action,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        ...(docRef ? { docRef } : {}),
+        title,
+        ...(parentId ? { parentId } : {}),
+        clearParent,
+        visibility: visibility,
+        filePath: optionalNonEmpty(values.flags.get("--file")),
+        bodyStdin: values.booleans.has("--body-stdin"),
+        json: values.booleans.has("--json"),
+    };
+}
+const MSG_ACTIONS = new Set(["channels", "read", "send", "thread"]);
+const MSG_ACTIONS_NEEDING_A_CHANNEL = new Set(["read", "send"]);
+export function parseMsgArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: ["--home", "--dashboard-url", "--channel", "--thread", "--limit", "--json"],
+        valueFlags: ["--home", "--dashboard-url", "--channel", "--thread", "--limit"],
+    });
+    const first = values.positionals[0];
+    const action = (first === undefined ? "channels" : first);
+    if (!MSG_ACTIONS.has(action)) {
+        throw new Error(`Unknown msg command: ${first}. Try channels, read, send, or thread.`);
+    }
+    const rest = values.positionals.slice(first === undefined ? 0 : 1);
+    let channelRef;
+    if (MSG_ACTIONS_NEEDING_A_CHANNEL.has(action)) {
+        channelRef = optionalNonEmpty(rest[0]);
+        if (!channelRef)
+            throw new Error(`msg ${action} needs a channel id or name.`);
+        if (rest.length > 1)
+            throw new Error(`msg ${action} takes one channel, not ${rest.length}.`);
+    }
+    else if (action === "thread") {
+        // `thread <id> --channel <channel>` — the channel is a flag here because
+        // the positional names the THREAD, not the channel (`--channel` below).
+        if (rest.length > 1)
+            throw new Error(`msg thread takes one thread id, not ${rest.length}.`);
+    }
+    else if (rest.length > 0) {
+        throw new Error(`msg ${action} does not take "${rest[0]}".`);
+    }
+    const threadFlag = optionalNonEmpty(values.flags.get("--thread"));
+    const threadId = action === "thread" ? optionalNonEmpty(rest[0]) : threadFlag;
+    if (action === "thread" && !threadId)
+        throw new Error("msg thread needs a thread id.");
+    const channelFlag = optionalNonEmpty(values.flags.get("--channel"));
+    if (action === "thread")
+        channelRef = channelFlag;
+    const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
+    if (limit !== undefined && action !== "read" && action !== "thread") {
+        throw new Error("--limit belongs to `cockpit msg read` or `cockpit msg thread`.");
+    }
+    return {
+        kind: "msg",
+        action,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        ...(channelRef ? { channelRef } : {}),
+        ...(threadId ? { threadId } : {}),
+        ...(limit === undefined ? {} : { limit }),
+        json: values.booleans.has("--json"),
+    };
+}

package/dist/commands/local-args-tower-work.js

@@ -0,0 +1,178 @@
+/**
+ * `cockpit issue` and `cockpit project` argument parsing (BLI-3716) — the
+ * Work surface's half of `local-args-tower.ts`, a sibling of
+ * `local-args-tower-docs-msg.ts` for the same reason that file is a sibling
+ * of the pages family: issues are their own noun with their own vocabulary
+ * (a state, an assignee, a project) and folding them into another family's
+ * parser would stretch that family's doc comment past the truth.
+ *
+ * Two commands, because a person types `cockpit project list`, not
+ * `cockpit issue projects` — the nouns are what a person says.
+ *
+ * Bodies never travel on argv: `create --title` names the issue, but the
+ * DESCRIPTION and every comment come from stdin or `--file`, the same
+ * discipline `cockpit docs` and `cockpit notes paste` keep (BLI-3706, and
+ * the sourcing-secrets verdict before it — argv is world-readable on a
+ * shared machine and lands in shell history).
+ */
+import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
+const ISSUE_ACTIONS = new Set([
+    "list",
+    "show",
+    "create",
+    "update",
+    "move",
+    "comment",
+    "history",
+]);
+/** Every verb except `list` and `create` names ONE issue first. */
+const ISSUE_ACTIONS_NEEDING_AN_ISSUE = new Set([
+    "show",
+    "update",
+    "move",
+    "comment",
+    "history",
+]);
+/**
+ * The closed state vocabulary, copied verbatim from
+ * `apps/dashboard/src/lib/work/api-doors.ts` `WORK_ISSUE_STATES` (which is
+ * itself the migration's CHECK constraint). Duplicated rather than imported
+ * because no dependency edge exists from the collector to the dashboard;
+ * `issue.ts`'s tests pin the list so a drift shows up here rather than as a
+ * 400 on a fleet machine.
+ */
+export const ISSUE_STATES = ["backlog", "todo", "in_progress", "in_review", "done", "canceled"];
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function parseIssueArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [
+            "--home",
+            "--dashboard-url",
+            "--state",
+            "--assignee",
+            "--project",
+            "--limit",
+            "--title",
+            "--priority",
+            "--parent",
+            "--file",
+            "--body-stdin",
+            "--json",
+        ],
+        valueFlags: [
+            "--home",
+            "--dashboard-url",
+            "--state",
+            "--assignee",
+            "--project",
+            "--limit",
+            "--title",
+            "--priority",
+            "--parent",
+            "--file",
+        ],
+    });
+    const first = values.positionals[0];
+    const action = (first === undefined ? "list" : first);
+    if (!ISSUE_ACTIONS.has(action)) {
+        throw new Error(`Unknown issue command: ${first}. Try list, show, create, update, move, comment, or history.`);
+    }
+    const rest = values.positionals.slice(first === undefined ? 0 : 1);
+    let issueRef;
+    let moveState;
+    if (ISSUE_ACTIONS_NEEDING_AN_ISSUE.has(action)) {
+        issueRef = optionalNonEmpty(rest[0]);
+        if (!issueRef)
+            throw new Error(`issue ${action} needs an issue id or identifier, e.g. BLI-3654.`);
+        if (action === "move") {
+            moveState = optionalNonEmpty(rest[1]);
+            if (!moveState) {
+                throw new Error(`issue move needs a state: ${ISSUE_STATES.join(", ")}.`);
+            }
+            if (rest.length > 2)
+                throw new Error(`issue move takes an issue and one state, not ${rest.length} words.`);
+        }
+        else if (rest.length > 1) {
+            throw new Error(`issue ${action} takes one issue reference, not ${rest.length}.`);
+        }
+    }
+    else if (rest.length > 0) {
+        throw new Error(`issue ${action} does not take "${rest[0]}".`);
+    }
+    if (moveState && !ISSUE_STATES.includes(moveState)) {
+        throw new Error(`issue move state must be one of: ${ISSUE_STATES.join(", ")}.`);
+    }
+    const stateFilter = optionalNonEmpty(values.flags.get("--state"));
+    if (stateFilter !== undefined && !ISSUE_STATES.includes(stateFilter)) {
+        throw new Error(`--state must be one of: ${ISSUE_STATES.join(", ")}.`);
+    }
+    if (stateFilter !== undefined && action !== "list") {
+        throw new Error("--state filters `cockpit issue list`; to move an issue use `cockpit issue move <id> <state>`.");
+    }
+    const title = optionalNonEmpty(values.flags.get("--title"));
+    if (action === "create" && !title)
+        throw new Error("issue create needs --title.");
+    // Not `optionalPositiveInteger`: 0 is a legitimate priority ("none", the
+    // column default), and that helper refuses it as non-positive.
+    const priorityRaw = optionalNonEmpty(values.flags.get("--priority"));
+    let priority;
+    if (priorityRaw !== undefined) {
+        priority = Number(priorityRaw);
+        if (!Number.isInteger(priority) || priority < 0 || priority > 4) {
+            throw new Error("--priority must be 0-4 (0 none, 1 urgent, 2 high, 3 medium, 4 low).");
+        }
+    }
+    // An assignee is `me`, `unassigned`, or a person's uuid. A name or an
+    // email is refused HERE rather than travelling to Postgres as a malformed
+    // uuid, which would come back as a 500 that names nothing useful.
+    const assignee = optionalNonEmpty(values.flags.get("--assignee"));
+    if (assignee !== undefined && assignee !== "me" && assignee !== "unassigned" && !UUID_PATTERN.test(assignee)) {
+        throw new Error('--assignee must be "me", "unassigned", or a person\'s uuid (see `cockpit team`).');
+    }
+    if (assignee === "unassigned" && action !== "list") {
+        throw new Error('--assignee unassigned filters `cockpit issue list`; to clear an assignee pass --assignee "" is not supported yet.');
+    }
+    const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
+    if (limit !== undefined && action !== "list" && action !== "history") {
+        throw new Error("--limit belongs to `cockpit issue list` or `cockpit issue history`.");
+    }
+    return {
+        kind: "issue",
+        action,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        ...(issueRef ? { issueRef } : {}),
+        ...(moveState ? { moveState } : {}),
+        ...(stateFilter ? { stateFilter } : {}),
+        ...(assignee ? { assignee } : {}),
+        project: optionalNonEmpty(values.flags.get("--project")),
+        ...(limit === undefined ? {} : { limit }),
+        title,
+        ...(priority === undefined ? {} : { priority }),
+        parentRef: optionalNonEmpty(values.flags.get("--parent")),
+        filePath: optionalNonEmpty(values.flags.get("--file")),
+        bodyStdin: values.booleans.has("--body-stdin"),
+        json: values.booleans.has("--json"),
+    };
+}
+export function parseProjectArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: ["--home", "--dashboard-url", "--archived", "--json"],
+        valueFlags: ["--home", "--dashboard-url"],
+    });
+    const first = values.positionals[0];
+    const action = (first === undefined ? "list" : first);
+    if (action !== "list")
+        throw new Error(`Unknown project command: ${first}. The only verb is list.`);
+    const rest = values.positionals.slice(first === undefined ? 0 : 1);
+    if (rest.length > 0)
+        throw new Error(`project list does not take "${rest[0]}".`);
+    return {
+        kind: "project",
+        action,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        includeArchived: values.booleans.has("--archived"),
+        json: values.booleans.has("--json"),
+    };
+}

package/dist/commands/local-args-tower.js

@@ -16,9 +16,15 @@
  *   local-args-tower-admin.ts   scout, ops, slack, — managing the account or
  *                                settings, team,      watching the pipeline
  *                                model
+ *   local-args-tower-docs-msg.ts docs, msg          — the document library and
+ *                                                      channels/messages (BLI-3706)
+ *   local-args-tower-work.ts    issue, project     — the issue tracker
+ *                                                      (BLI-3716)
  *
  * Every name this module has ever exported is still importable from here.
  */
 export { parseJarvisArgs, parseCorrectArgs } from "./local-args-tower-chat.js";
 export { parseBriefArgs, WORKBOOK_MIN_WIDTH, parseWorkbookArgs, parseNotesArgs, } from "./local-args-tower-pages.js";
-export { SCOUT_MIN_PREFIX_LENGTH, parseScoutArgs, parseOpsArgs, SLACK_WORKSPACE_KEYS, parseSlackArgs, parseSettingsArgs, parseTeamArgs, parseModelArgs, } from "./local-args-tower-admin.js";
+export { SCOUT_MIN_PREFIX_LENGTH, parseScoutArgs, parseOpsArgs, SLACK_WORKSPACE_KEYS, parseSlackArgs, parseSettingsArgs, parseTeamArgs, parseModelArgs, } from "./local-args-tower-admin.js";
+export { parseDocsArgs, parseMsgArgs, } from "./local-args-tower-docs-msg.js";
+export { ISSUE_STATES, parseIssueArgs, parseProjectArgs, } from "./local-args-tower-work.js";

package/dist/commands/local-args.js

@@ -1,11 +1,11 @@
 import { parseAgentRulesArgs, parseAnalyzeArgs, parseAutostartArgs, parseBackfillArgs, parseCleanArgs, parseDoctorArgs, parseInstallArgs, parseLoginArgs, parseMemoryArgs, parseLogoutArgs, parseOnboardArgs, parseReleaseArgs, parseServeArgs, parseSessionsArgs, parseStartArgs, parseStatusArgs, parseSyncArgs, parseUpdateArgs, } from "./local-args-collector.js";
-import { parseBriefArgs, parseCorrectArgs, parseJarvisArgs, parseModelArgs, parseNotesArgs, parseOpsArgs, parseScoutArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, } from "./local-args-tower.js";
+import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseScoutArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, } from "./local-args-tower.js";
 // `normalizeUrl` has always been part of this module's surface — `local.ts` and
 // `local-auth.ts` import it from here — so it stays exported from this address
 // even though it now lives next door. The same goes for the four names the
 // Tower parsers publish.
 export { normalizeUrl } from "./local-arg-values.js";
-export { SCOUT_MIN_PREFIX_LENGTH, SLACK_WORKSPACE_KEYS, WORKBOOK_MIN_WIDTH, } from "./local-args-tower.js";
+export { SCOUT_MIN_PREFIX_LENGTH, SLACK_WORKSPACE_KEYS, WORKBOOK_MIN_WIDTH, ISSUE_STATES, } from "./local-args-tower.js";
 // The six human "set my machine up" doors. They are one thing wearing six
 // hats, so they all run the convergence command — but they keep accepting the
 // flags they always accepted, because DMs, runbooks and AGENTS.md rules across
@@ -84,6 +84,14 @@ export function parseLocalArgs(argv) {
             return parseMemoryArgs(argv.slice(1));
         case "clean":
             return parseCleanArgs(argv.slice(1));
+        case "docs":
+            return parseDocsArgs(argv.slice(1));
+        case "msg":
+            return parseMsgArgs(argv.slice(1));
+        case "issue":
+            return parseIssueArgs(argv.slice(1));
+        case "project":
+            return parseProjectArgs(argv.slice(1));
         case "release":
             return parseReleaseArgs(argv.slice(1));
         default:

package/dist/commands/local-help.js

@@ -40,6 +40,10 @@ export const rootCommandNames = new Set([
     "agent-rules",
     "memory",
     "clean",
+    "docs",
+    "msg",
+    "issue",
+    "project",
     "release",
 ]);
 export function localCommandHelp(command) {
@@ -78,6 +82,10 @@ export function localCommandHelp(command) {
         "  cockpit agent-rules [install|uninstall|status] [--host codex|claude|all] [--workspace <path>] [--json]",
         "  cockpit memory [install|status] [--dashboard-url <url>] [--dry-run] [--json]",
         "  cockpit clean [--dry-run] [--all-committed] [--reconcile] [--dashboard-url <url>] [--json]",
+        "  cockpit docs [list|tree|read <id|slug>|create --title <t>|update <id>] [--parent <id>|--clear-parent] [--visibility org|private] [--file <path>|--body-stdin] [--dashboard-url <url>] [--json]",
+        "  cockpit msg [channels|read <channel>|send <channel>|thread <id> --channel <channel>] [--thread <id>] [--limit <n>] [--dashboard-url <url>] [--json]",
+        "  cockpit issue [list|show <BLI-id>|create --title <t>|update <BLI-id>|move <BLI-id> <state>|comment <BLI-id>|history <BLI-id>] [--state <s>] [--assignee me|unassigned|<uuid>] [--project <name|id>] [--limit <n>] [--priority 0-4] [--parent <BLI-id>] [--file <path>|--body-stdin] [--dashboard-url <url>] [--json]",
+        "  cockpit project [list] [--archived] [--dashboard-url <url>] [--json]",
         "  cockpit release [--dry-run] [--skip-checks] [--no-floor] [--tag <tag>] [--access <public|restricted>] [--otp <code>]",
         "",
         `Default dashboard: ${DEFAULT_DASHBOARD_URL}. Omit --dashboard-url for normal production use; pass it only for staging/custom dashboards or to force a different pairing.`,
@@ -580,6 +588,68 @@ function localSubcommandHelp(command) {
                 "right now.",
             ],
         ],
+        [
+            "docs",
+            [
+                "Usage: cockpit docs [list|tree|read <id|slug>|create|update <id>] [flags]",
+                "",
+                "The Tower document library, typed. Bare `cockpit docs` lists every document you may read.",
+                "list — every document you may see: id, visibility, slug, title.",
+                "tree — the same documents nested under their parent, for a sidebar-shaped view.",
+                "read <id|slug> — one document's title, slug, visibility, and its body.",
+                "create --title \"<title>\" [--parent <id>] [--visibility org|private] [--file <path>|--body-stdin] — the body comes from --file, or stdin (`cat body.md | cockpit docs create --title \"...\"`); neither means an empty body, matching the browser's own default.",
+                "update <id|slug> [--title \"<t>\"] [--visibility org|private] [--parent <id>|--clear-parent] [--file <path>|--body-stdin] — only the fields you pass change; a `--parent` change IS a move, there is no separate move verb.",
+                "A document body is never accepted on the command line — --file (safest on Windows) or a pipe only, same discipline as `cockpit notes paste`.",
+                "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
+                "A refusal keeps Tower's own reason label — needs_rls_client, document_not_found_or_unreadable, document_not_writable, slug_taken, circular_parent, and so on.",
+                "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
+            ],
+        ],
+        [
+            "msg",
+            [
+                "Usage: cockpit msg [channels|read <channel>|send <channel>|thread <id> --channel <channel>] [flags]",
+                "",
+                "Channels and messages, typed. <channel> is a channel id, or its name with or without a leading #.",
+                "channels — every channel you are a member of (or, as a super_admin, every channel).",
+                "read <channel> [--limit <n>] [--thread <id>] — the channel's most recent top-level messages, oldest first; --thread <id> reads one thread's replies instead.",
+                "send <channel> [--thread <id>] — posts a message. The content is never accepted on the command line: pipe it in, e.g. `echo \"hello\" | cockpit msg send general`.",
+                "thread <id> --channel <channel> — one thread's replies by the parent message's id.",
+                "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
+                "A refusal keeps Tower's own reason label — needs_rls_client, channel_not_found_or_unreadable, content_too_long, and so on.",
+                "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
+            ],
+        ],
+        [
+            "issue",
+            [
+                "Usage: cockpit issue [list|show <id>|create|update <id>|move <id> <state>|comment <id>|history <id>] [flags]",
+                "",
+                "Tower's issue tracker. <id> is a BLI-#### identifier (BLI-3654) or an issue's uuid — both work everywhere an issue is named.",
+                "list [--state <s>] [--assignee me|unassigned|<uuid>] [--project <name|id>] [--limit <n>] — the issues you may see, most recently updated first.",
+                "show <id> — one issue: title, state, priority, assignee, description, and every comment on it.",
+                "create --title \"<title>\" [--project <name|id>] [--priority 0-4] [--assignee me|<uuid>] [--parent <id>] [--file <path>] — the DESCRIPTION comes from --file or stdin (`cat plan.md | cockpit issue create --title \"...\"`); neither means no description.",
+                "update <id> [--title \"<t>\"] [--priority 0-4] [--assignee me|<uuid>] [--project <name|id>] [--parent <id>] [--file <path>|--body-stdin] — only the fields you pass change. State does NOT move here; use move.",
+                "move <id> <state> — moves an issue and records the move. States: backlog, todo, in_progress, in_review, done, canceled.",
+                "comment <id> — posts a comment. The body is never taken on the command line: `echo \"shipped\" | cockpit issue comment BLI-3654`.",
+                "history <id> [--limit <n>] — every recorded state move and reassignment, oldest first.",
+                "A project may be named instead of id'd; the name is matched exactly (case-insensitively) against `cockpit project list`.",
+                "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
+                "A refusal keeps Tower's own reason label — needs_rls_client, issue_not_found_or_unreadable, issue_not_writable, invalid_state, comment_too_long, and so on.",
+                "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
+            ],
+        ],
+        [
+            "project",
+            [
+                "Usage: cockpit project [list] [--archived] [--json]",
+                "",
+                "The projects issues are filed under. Bare `cockpit project` lists them.",
+                "list [--archived] — id, active/archived, name. --archived includes archived projects.",
+                "There is no create/update/delete verb: `GET /api/work/projects` is the whole of Tower's project door today.",
+                "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
+            ],
+        ],
         [
             "release",
             [

package/dist/commands/local.js

@@ -32,6 +32,10 @@ import { runAutostart } from "./autostart-command.js";
 import { runAgentRules } from "./agent-rules-command.js";
 import { runMemoryInstall } from "./memory-install.js";
 import { runClean } from "./clean.js";
+import { runDocs } from "./docs.js";
+import { runMsg } from "./msg.js";
+import { runIssue } from "./issue.js";
+import { runProject } from "./project.js";
 import { parseLocalArgs } from "./local-args.js";
 // `./local.js` is the published entry point for this command surface: the
 // public CLI's generated root, commands/root.ts, doctor.ts and the test suite
@@ -131,6 +135,14 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
                 return await runMemoryInstall(command, io);
             case "clean":
                 return await runClean(command, io);
+            case "docs":
+                return await runDocs(command, io);
+            case "msg":
+                return await runMsg(command, io);
+            case "issue":
+                return await runIssue(command, io);
+            case "project":
+                return await runProject(command, io);
             case "release":
                 return await runRelease(command, io);
         }