@bli-cockpit/cli 0.2.242 → 0.2.244

package/dist/commands/docs-inbox-args.js

@@ -0,0 +1,93 @@
+/**
+ * `cockpit docs inbox|subscribe|unsubscribe|notifications` argument parsing (BLI-21741, docs parity step 8).
+ *
+ * `inbox [--unread] [--kind mentioned|commented|edited] [--before <cursor>] [--limit <n>]` reads the inbox.
+ * `inbox read <id>... | --all` and `inbox unread <id>...` mark items. `subscribe|unsubscribe <id|slug>` follow or
+ * stop following a page. `notifications [--mentions on|off] [--comments on|off] [--edits on|off]` reads the
+ * three docs notification kinds, or sets the ones named. The door checks authority; this file only checks shape.
+ */
+import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const KINDS = ["mentioned", "commented", "edited"];
+const NOTIFY_FLAGS = ["--mentions", "--comments", "--edits"];
+const VALUE_FLAGS = ["--home", "--dashboard-url", "--kind", "--before", "--limit", ...NOTIFY_FLAGS];
+function onOff(flag, raw) {
+    if (raw === undefined)
+        return undefined;
+    if (raw === "on")
+        return true;
+    if (raw === "off")
+        return false;
+    throw new Error(`${flag} takes on or off, not "${raw}".`);
+}
+export function parseDocsInboxArgs(args) {
+    const values = parseNamedArgs(args, { allowedFlags: [...VALUE_FLAGS, "--unread", "--all", "--json"], valueFlags: VALUE_FLAGS });
+    const verb = args[0];
+    const rest = values.positionals.slice(1);
+    const base = {
+        kind: "docs",
+        clearParent: false,
+        bodyStdin: false,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        json: values.booleans.has("--json"),
+    };
+    const stray = (allowed) => {
+        const bad = [...values.flags.keys(), ...values.booleans].find((flag) => !allowed.includes(flag) && flag !== "--json" && flag !== "--home" && flag !== "--dashboard-url");
+        if (bad)
+            throw new Error(`${bad} does not belong to \`cockpit docs ${verb === "inbox" && rest[0] ? `inbox ${rest[0]}` : verb}\`.`);
+    };
+    if (verb === "subscribe" || verb === "unsubscribe") {
+        stray([]);
+        if (rest.length !== 1)
+            throw new Error(`docs ${verb} needs exactly one document id or slug.`);
+        return { ...base, action: verb, docRef: rest[0] };
+    }
+    if (verb === "notifications") {
+        stray([...NOTIFY_FLAGS]);
+        if (rest.length > 0)
+            throw new Error("docs notifications takes flags only: --mentions, --comments, --edits (on or off).");
+        const set = {
+            mentions: onOff("--mentions", values.flags.get("--mentions")),
+            comments: onOff("--comments", values.flags.get("--comments")),
+            edits: onOff("--edits", values.flags.get("--edits")),
+        };
+        const given = Object.fromEntries(Object.entries(set).filter(([, value]) => value !== undefined));
+        return { ...base, action: "notifications", ...(Object.keys(given).length > 0 ? { notifySet: given } : {}) };
+    }
+    // inbox
+    if (rest[0] === "read" || rest[0] === "unread") {
+        const marking = rest[0];
+        stray(["--all"]);
+        const ids = rest.slice(1);
+        const all = values.booleans.has("--all");
+        if (all && marking === "unread")
+            throw new Error("--all only marks items read. Name the ids to mark unread.");
+        if (all && ids.length > 0)
+            throw new Error("docs inbox read takes ids or --all, not both.");
+        if (!all && ids.length === 0)
+            throw new Error(`docs inbox ${marking} needs one or more item ids (from \`cockpit docs inbox --json\`)${marking === "read" ? ", or --all" : ""}.`);
+        const bad = ids.find((id) => !UUID.test(id));
+        if (bad)
+            throw new Error(`"${bad}" is not an item id (a UUID); take it from \`cockpit docs inbox --json\`.`);
+        return { ...base, action: "inbox-read", inboxRead: marking === "read", ...(all ? { inboxAll: true } : { inboxIds: ids }) };
+    }
+    stray(["--unread", "--kind", "--before", "--limit"]);
+    if (rest.length > 0)
+        throw new Error(`docs inbox does not know "${rest[0]}". Use \`inbox read <id>...\`, \`inbox unread <id>...\`, or flags.`);
+    const kind = optionalNonEmpty(values.flags.get("--kind"));
+    if (kind !== undefined && !KINDS.includes(kind))
+        throw new Error(`--kind takes ${KINDS.join(", ")}, not "${kind}".`);
+    const before = optionalNonEmpty(values.flags.get("--before"));
+    const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
+    if (limit !== undefined && limit > 100)
+        throw new Error("--limit takes a whole number from 1 to 100.");
+    return {
+        ...base,
+        action: "inbox",
+        ...(values.booleans.has("--unread") ? { inboxUnread: true } : {}),
+        ...(kind ? { inboxKind: kind } : {}),
+        ...(before ? { inboxBefore: before } : {}),
+        ...(limit !== undefined ? { limit } : {}),
+    };
+}

package/dist/commands/docs-inbox.js

@@ -0,0 +1,126 @@
+/**
+ * `cockpit docs inbox|subscribe|unsubscribe|notifications` — the docs inbox from a terminal (BLI-21741).
+ * A sibling of `docs.ts`, like `docs-comments.ts`.
+ *
+ * `inbox [--unread] [--kind k] [--before c] [--limit n]` → `GET    /api/docs/inbox`
+ * `inbox read <id>... | --all`, `inbox unread <id>...`   → `POST   /api/docs/inbox/read`
+ * `subscribe <id|slug>`                                  → `PUT    /api/docs/documents/[id]/follow`
+ * `unsubscribe <id|slug>`                                → `DELETE /api/docs/documents/[id]/follow`
+ * `notifications [--mentions on|off] ...`                → `GET|PUT /api/docs/notifications/settings`
+ *
+ * The door's `reason` labels (`inbox_ids_invalid`, `inbox_too_many_ids`, `invalid_notification_setting`,
+ * `document_not_found_or_unreadable`, ...) come back verbatim, and the mention policy sentence is printed as the door says it.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { resolveDocId } from "./docs.js";
+const TAG = "[docs inbox cli]";
+const DEADLINE_MS = 30_000;
+function itemLine(item) {
+    const who = item.actor_name ?? "Someone";
+    const what = item.kind === "mentioned" ? `${who} mentioned you`
+        : item.kind === "commented" ? (item.event_count > 1 ? `${who} and others: ${item.event_count} comments` : `${who} commented`)
+            : (item.event_count > 1 ? `${who} edited: ${item.event_count} edits` : `${who} edited`);
+    return `${item.id}  ${item.read_at === null ? "unread" : "read  "}  ${item.title || "Untitled"}  ${what}  ${item.updated_at}  (page ${item.document_id})`;
+}
+function settingsLine(settings) {
+    const word = (on) => (on ? "on" : "off");
+    return `mentions ${word(settings.mentions)}, comments ${word(settings.comments)}, edits ${word(settings.edits)}`;
+}
+async function readInbox(command, door) {
+    const params = new URLSearchParams();
+    if (command.inboxUnread)
+        params.set("unread", "true");
+    if (command.inboxKind)
+        params.set("kind", command.inboxKind);
+    if (command.inboxBefore)
+        params.set("before", command.inboxBefore);
+    if (command.limit !== undefined)
+        params.set("limit", String(command.limit));
+    const query = params.toString();
+    const answer = await askAgentDoor(door, { path: `/api/docs/inbox${query ? `?${query}` : ""}`, method: "GET", label: "docs inbox", timeoutMs: DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} read ${JSON.stringify({ returned: body.coverage.returned, dropped: body.coverage.dropped, unread: body.counts.unread })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    writeLine(door.io.stdout, `${body.counts.unread}${body.counts.capped ? "+" : ""} unread. Showing ${body.coverage.returned}.`);
+    if (body.items.length === 0)
+        writeLine(door.io.stdout, body.explanation ?? (command.inboxUnread ? "No unread activity." : "No activity yet."));
+    for (const item of body.items)
+        writeLine(door.io.stdout, itemLine(item));
+    if (body.coverage.dropped > 0)
+        writeLine(door.io.stdout, `${body.coverage.dropped} item(s) hidden because you can no longer read their page.`);
+    if (body.next_cursor)
+        writeLine(door.io.stdout, `More: --before ${body.next_cursor}`);
+    return 0;
+}
+async function markInbox(command, door) {
+    const read = command.inboxRead !== false;
+    const answer = await askAgentDoor(door, {
+        path: "/api/docs/inbox/read", method: "POST", label: read ? "docs inbox read" : "docs inbox unread", timeoutMs: DEADLINE_MS,
+        body: command.inboxAll ? { all: true, read: true } : { ids: command.inboxIds ?? [], read },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} mark ${JSON.stringify({ requested: body.requested, updated: body.updated, skipped: body.skipped, read: body.read })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    writeLine(door.io.stdout, `Marked ${body.updated} item(s) ${body.read ? "read" : "unread"}${body.skipped > 0 ? ` (${body.skipped} skipped: another unread item already covers that thread or page)` : ""}. ${body.counts.unread} unread.`);
+    return 0;
+}
+async function followDoc(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 follow = command.action === "subscribe";
+    const label = follow ? "docs subscribe" : "docs unsubscribe";
+    const answer = await askAgentDoor(door, {
+        path: `/api/docs/documents/${encodeURIComponent(resolved.id)}/follow`, method: follow ? "PUT" : "DELETE", label, timeoutMs: DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} ${label} ${JSON.stringify({ document_id: body.document_id, following: body.following, reason: body.reason })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    writeLine(door.io.stdout, `${body.following ? "Following" : "Not following"} ${body.document_id} (${body.reason}).`);
+    writeLine(door.io.stdout, body.mention_policy);
+    return 0;
+}
+async function notifications(command, door) {
+    const set = command.notifySet;
+    const answer = await askAgentDoor(door, {
+        path: "/api/docs/notifications/settings", method: set ? "PUT" : "GET", label: set ? "docs notifications set" : "docs notifications", timeoutMs: DEADLINE_MS,
+        ...(set ? { body: set } : {}),
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} notifications ${JSON.stringify({ set: Boolean(set), ...body.settings })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    writeLine(door.io.stdout, settingsLine(body.settings));
+    if (body.explanation)
+        writeLine(door.io.stdout, body.explanation);
+    return 0;
+}
+export async function runDocsInbox(command, door) {
+    switch (command.action) {
+        case "inbox":
+            return readInbox(command, door);
+        case "inbox-read":
+            return markInbox(command, door);
+        case "subscribe":
+        case "unsubscribe":
+            return followDoc(command, door);
+        default:
+            return notifications(command, door);
+    }
+}

package/dist/commands/docs-notion.js

@@ -16,6 +16,7 @@
 import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
 import { writeLine } from "./cli-io.js";
 import { resolveDocId } from "./docs.js";
+import { printSyncDetail } from "./docs-sync.js";
 const TAG = "[docs cli]";
 const READ_DEADLINE_MS = 30_000;
 const WRITE_DEADLINE_MS = 60_000;
@@ -45,6 +46,10 @@ export async function syncStatusDocs(command, door) {
     if (!answer.ok)
         return failAgentDoor(door, TAG, answer.reason, answer.detail);
     const body = answer.body;
+    // BLI-21875: one page also answers with its receipts, losses and conflicts; those lines are the door's own sentences.
+    if (!door.json && command.docRef && answer.body.detail) {
+        return printSyncDetail(door, command.docRef, answer.body);
+    }
     if (door.json) {
         return emitAgentDoor(door, {
             ...answer.body,

package/dist/commands/docs-read.js

@@ -93,7 +93,8 @@ async function fetchOneDocument(door, ref, id) {
 }
 function writeDocumentBlock(io, document) {
     writeLine(io.stdout, String(document["title"] ?? ""));
-    writeLine(io.stdout, `${document["slug"] ?? "(no slug)"}  ·  ${document["visibility"] ?? ""}  ·  ${document["source"] ?? ""}`);
+    const revision = typeof document["revision"] === "number" ? `  ·  revision ${document["revision"]}` : "";
+    writeLine(io.stdout, `${document["slug"] ?? "(no slug)"}  ·  ${document["visibility"] ?? ""}  ·  ${document["source"] ?? ""}${revision}`);
     writeLine(io.stdout, "");
     writeLine(io.stdout, String(document["body_markdown"] ?? ""));
 }

package/dist/commands/docs-recovery.js

@@ -0,0 +1,173 @@
+/**
+ * `cockpit docs trash`, `docs restore` and `docs versions` — recovery from a terminal (BLI-21413).
+ * A sibling of `docs.ts`, like `docs-share.ts`.
+ *
+ * `trash [--cursor C] [--limit N]`                      → `GET  /api/docs/trash`
+ * `restore <id>`                                        → `POST /api/docs/documents/[id]/restore`
+ * `versions <id|slug> [--before N] [--limit N]`         → `GET  /api/docs/documents/[id]/versions`
+ * `versions <id|slug> --version V`                      → `GET  /api/docs/documents/[id]/versions/[V]` (one body)
+ * `restore <id|slug> --version V [--expected-revision N]` → `POST .../versions/[V]/restore`
+ *
+ * Every refusal keeps the door's own reason label (`not_restore_manager`, `not_in_trash`,
+ * `revision_conflict`, `version_not_found`, ...). A restore that had to change the page's address says
+ * so in plain words.
+ */
+import { randomUUID } from "node:crypto";
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { resolveDocId } from "./docs.js";
+const TAG = "[docs cli]";
+const READ_DEADLINE_MS = 30_000;
+const WRITE_DEADLINE_MS = 60_000;
+export async function trashDocs(command, door) {
+    const params = new URLSearchParams();
+    if (command.limit !== undefined)
+        params.set("limit", String(command.limit));
+    if (command.cursor)
+        params.set("cursor", command.cursor);
+    const search = params.toString();
+    const answer = await askAgentDoor(door, {
+        path: search ? `/api/docs/trash?${search}` : "/api/docs/trash",
+        method: "GET",
+        label: "docs trash",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    const documents = body.documents ?? [];
+    writeLine(door.io.stderr, `${TAG} trash ${JSON.stringify({ returned: documents.length, complete: body.complete === true })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body, documents });
+    if (documents.length === 0) {
+        writeLine(door.io.stdout, "Nothing to restore: the trash holds no page you may restore.");
+        return 0;
+    }
+    for (const doc of documents) {
+        writeLine(door.io.stdout, `${doc.id}  ${doc.deleted_at ?? "?"}  ${doc.slug ?? "(no slug)"}  ${doc.title}`);
+    }
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${documents.length} deleted page(s). Restore one with \`cockpit docs restore <id>\`.`);
+    if (body.next_cursor)
+        writeLine(door.io.stdout, `More: cockpit docs trash --cursor ${body.next_cursor}`);
+    return 0;
+}
+export async function versionsDocs(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 base = `/api/docs/documents/${encodeURIComponent(resolved.id)}/versions`;
+    if (command.versionId) {
+        const one = await askAgentDoor(door, {
+            path: `${base}/${encodeURIComponent(command.versionId)}`,
+            method: "GET",
+            label: "docs version",
+            timeoutMs: READ_DEADLINE_MS,
+        });
+        if (!one.ok)
+            return failAgentDoor(door, TAG, one.reason, one.detail);
+        const version = one.body.version ?? {};
+        writeLine(door.io.stderr, `${TAG} version ${JSON.stringify({ document_id: resolved.id, version_id: command.versionId, chars: version.body_markdown?.length ?? 0 })}`);
+        if (door.json)
+            return emitAgentDoor(door, { ok: true, version });
+        writeLine(door.io.stdout, version.body_markdown ?? "");
+        return 0;
+    }
+    const params = new URLSearchParams();
+    if (command.limit !== undefined)
+        params.set("limit", String(command.limit));
+    if (command.before !== undefined)
+        params.set("before", String(command.before));
+    const search = params.toString();
+    const answer = await askAgentDoor(door, {
+        path: search ? `${base}?${search}` : base,
+        method: "GET",
+        label: "docs versions",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    const versions = body.versions ?? [];
+    writeLine(door.io.stderr, `${TAG} versions ${JSON.stringify({ document_id: resolved.id, returned: versions.length, total: body.total ?? null })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, document_id: resolved.id, ...body, versions });
+    if (versions.length === 0) {
+        writeLine(door.io.stdout, "No earlier version yet.");
+        return 0;
+    }
+    for (const version of versions) {
+        writeLine(door.io.stdout, `v${String(version.version_number).padEnd(5)} ${version.id}  ${version.created_at}${version.origin ? `  (${version.origin})` : ""}`);
+    }
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${versions.length} of ${body.total ?? "?"} versions, newest first. Read one with --version <id>; restore one with \`cockpit docs restore ${ref} --version <id>\`.`);
+    if (body.next_before !== null && body.next_before !== undefined)
+        writeLine(door.io.stdout, `Older: cockpit docs versions ${ref} --before ${body.next_before}`);
+    return 0;
+}
+/** Says where the restore stands, then fails with the door's own reason (a conflict names the current revision). */
+function refuse(door, answer, requestId) {
+    const mutation = answer.body?.mutation;
+    writeLine(door.io.stderr, `${TAG} retry unchanged input with --request-id ${requestId}.`);
+    if (mutation?.current) {
+        writeLine(door.io.stderr, `${TAG} conflict ${JSON.stringify({ request_id: requestId, current_revision: mutation.current.revision ?? mutation.revision })}`);
+    }
+    return failAgentDoor(door, TAG, answer.reason, answer.detail, mutation ? { mutation } : {});
+}
+export async function restoreDocs(command, door) {
+    const requestId = command.requestId ?? randomUUID();
+    const ref = command.docRef ?? "";
+    if (!command.versionId) {
+        // Undelete: the page is not in the live list, so the argument is its id (the trash prints it).
+        writeLine(door.io.stderr, `${TAG} request ${JSON.stringify({ request_id: requestId })}`);
+        const answer = await askAgentDoor(door, {
+            path: `/api/docs/documents/${encodeURIComponent(ref)}/restore`,
+            method: "POST",
+            label: "docs restore",
+            timeoutMs: WRITE_DEADLINE_MS,
+            body: { request_id: requestId },
+        });
+        if (!answer.ok)
+            return refuse(door, answer, requestId);
+        const result = answer.body;
+        writeLine(door.io.stderr, `${TAG} restored ${JSON.stringify({ document_id: result.document_id ?? ref, slug_changed: result.slug_changed === true })}`);
+        if (door.json)
+            return emitAgentDoor(door, { ok: true, ...result });
+        writeLine(door.io.stdout, `Restored ${result.document_id ?? ref} from the trash with the same id.`);
+        if (result.slug_changed) {
+            writeLine(door.io.stdout, `Its address changed: another page now uses ${result.old_slug ?? "the old address"}, so this page is now ${result.new_slug ?? "at a new address"}.`);
+        }
+        return 0;
+    }
+    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}`);
+    }
+    writeLine(door.io.stderr, `${TAG} request ${JSON.stringify({ request_id: requestId, expected_revision: command.expectedRevision })}`);
+    const answer = await askAgentDoor(door, {
+        path: `/api/docs/documents/${encodeURIComponent(resolved.id)}/versions/${encodeURIComponent(command.versionId)}/restore`,
+        method: "POST",
+        label: "docs restore version",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            request_id: requestId,
+            ...(command.expectedRevision !== undefined ? { expected_revision: command.expectedRevision } : {}),
+        },
+    });
+    if (!answer.ok)
+        return refuse(door, answer, requestId);
+    const { document = {}, mutation } = answer.body;
+    writeLine(door.io.stderr, `${TAG} version restored ${JSON.stringify({ document_id: resolved.id, version_id: command.versionId, request_id: requestId, revision: mutation?.["revision"] ?? null })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, document, mutation });
+    writeLine(door.io.stdout, mutation?.["reason"] === "unchanged"
+        ? `That version already matched the page; nothing changed (revision ${String(mutation?.["revision"] ?? "?")}).`
+        : `Restored the version as the current text of ${String(document["title"] ?? resolved.id)}, revision ${String(mutation?.["revision"] ?? "?")}. What was there before is kept as a version.`);
+    return 0;
+}

package/dist/commands/docs-refs-args.js

@@ -0,0 +1,104 @@
+/**
+ * `cockpit docs templates|refs|review|maintenance` and `docs create --template` argument parsing (BLI-21849, docs parity step 11).
+ *
+ * `templates` lists the curated templates. `create --template <id|slug> --title <t>` copies one into a new page (no body is accepted
+ * beside a template). `refs <id|slug>` shows links from and to a page. `review <id|slug>` shows the owner and review schedule;
+ * with `--owner <email|me|none>`, `--every <days>`, `--no-schedule` or `--reviewed` it changes them. `maintenance [--mine] [--state ...]`
+ * lists pages that are due, unowned or yours. The door checks authority; this file only checks shape.
+ */
+import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+const VALUE_FLAGS = ["--home", "--dashboard-url", "--template", "--title", "--parent", "--visibility", "--owner", "--every", "--state"];
+const BOOLEAN_FLAGS = ["--json", "--mine", "--no-schedule", "--reviewed"];
+const STATES = ["review_due", "unowned", "all"];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function isDocsRefsInvocation(args) {
+    return ["templates", "refs", "review", "maintenance"].includes(args[0] ?? "") || (args[0] === "create" && args.some((arg) => arg === "--template" || arg.startsWith("--template=")));
+}
+export function parseDocsRefsArgs(args) {
+    const values = parseNamedArgs(args, { allowedFlags: [...VALUE_FLAGS, ...BOOLEAN_FLAGS], valueFlags: VALUE_FLAGS });
+    const verb = args[0];
+    const rest = values.positionals.slice(1);
+    const base = {
+        kind: "docs",
+        clearParent: false,
+        bodyStdin: false,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        json: values.booleans.has("--json"),
+    };
+    const only = (allowed) => {
+        for (const flag of [...VALUE_FLAGS.slice(2), ...BOOLEAN_FLAGS.slice(1)]) {
+            const given = values.flags.has(flag) || values.booleans.has(flag);
+            if (given && !allowed.includes(flag))
+                throw new Error(`${flag} does not belong to \`cockpit docs ${verb}\`.`);
+        }
+    };
+    if (verb === "templates") {
+        only([]);
+        if (rest.length !== 0)
+            throw new Error("docs templates takes no arguments.");
+        return { ...base, action: "templates" };
+    }
+    if (verb === "create") {
+        only(["--template", "--title", "--parent", "--visibility"]);
+        if (rest.length !== 0)
+            throw new Error("docs create --template takes no body: the template's text is the body. Use --title for the name.");
+        const title = optionalNonEmpty(values.flags.get("--title"));
+        if (!title)
+            throw new Error("docs create needs --title.");
+        const parent = optionalNonEmpty(values.flags.get("--parent"));
+        if (parent && !UUID.test(parent))
+            throw new Error("--parent must be a document id (a UUID).");
+        const visibility = optionalNonEmpty(values.flags.get("--visibility"));
+        if (visibility && visibility !== "org" && visibility !== "private")
+            throw new Error("--visibility must be org or private.");
+        return {
+            ...base,
+            action: "create",
+            title,
+            ...(parent ? { parentId: parent } : {}),
+            ...(visibility ? { visibility: visibility } : {}),
+            docsRefs: { templateId: optionalNonEmpty(values.flags.get("--template")) },
+        };
+    }
+    if (verb === "maintenance") {
+        only(["--mine", "--state"]);
+        if (rest.length !== 0)
+            throw new Error("docs maintenance takes no page, e.g. `cockpit docs maintenance --state review_due`.");
+        const state = optionalNonEmpty(values.flags.get("--state")) ?? "all";
+        if (!STATES.includes(state))
+            throw new Error(`--state must be one of ${STATES.join(", ")}.`);
+        return { ...base, action: "maintenance", docsRefs: { state: state, mine: values.booleans.has("--mine") } };
+    }
+    if (rest.length !== 1)
+        throw new Error(`docs ${verb} needs exactly one page id or slug, e.g. \`cockpit docs ${verb} runbook\`.`);
+    if (verb === "refs") {
+        only([]);
+        return { ...base, action: "refs", docRef: rest[0] };
+    }
+    only(["--owner", "--every", "--no-schedule", "--reviewed"]);
+    const owner = optionalNonEmpty(values.flags.get("--owner"));
+    const everyRaw = optionalNonEmpty(values.flags.get("--every"));
+    const noSchedule = values.booleans.has("--no-schedule");
+    if (everyRaw !== undefined && noSchedule)
+        throw new Error("--every and --no-schedule say opposite things; give one.");
+    let everyDays;
+    if (everyRaw !== undefined) {
+        everyDays = /^\d+$/.test(everyRaw) ? Number(everyRaw) : Number.NaN;
+        if (!Number.isInteger(everyDays) || everyDays < 1 || everyDays > 730)
+            throw new Error("--every is a whole number of days from 1 to 730.");
+    }
+    else if (noSchedule) {
+        everyDays = null;
+    }
+    return {
+        ...base,
+        action: "review",
+        docRef: rest[0],
+        docsRefs: {
+            ...(owner !== undefined ? { owner: owner.toLowerCase() === "none" ? null : owner } : {}),
+            ...(everyDays !== undefined ? { everyDays } : {}),
+            ...(values.booleans.has("--reviewed") ? { reviewed: true } : {}),
+        },
+    };
+}