@bli-cockpit/cli 0.2.54 → 0.2.56

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

@@ -0,0 +1,314 @@
+/**
+ * The three commands that read a page instead of asking a question: the daily
+ * page (`cockpit brief`), meeting notes (`cockpit notes`), and the document
+ * library (`cockpit workbook`). Split out of local-args-tower.ts (BLI-3636).
+ *
+ * Every parser moved verbatim: same flags, same defaults, same refusal
+ * sentences. The three names `local-args.ts` re-exports from this family
+ * (`WORKBOOK_MIN_WIDTH` and `NotesAction`) are re-exported from
+ * `./local-args-tower.js`, the address they have always had.
+ */
+import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
+/**
+ * `cockpit brief` (BLI-3458) — the TODAY page, in the terminal.
+ *
+ * `--for` is the terminal's `?p=`, and it follows the same rule the website
+ * does: the dashboard resolves it against the roster and the database (or the
+ * route's own mirror of the database's rule) decides whether the page opens.
+ * Nothing is decided here.
+ *
+ * `--date` (BLI-3484) is the terminal's `?d=`, and the same sentence applies to
+ * it twice over: what counts as a date, where that person's day starts, and
+ * whether anything was compiled for it are all the dashboard's answer. A local
+ * copy of "when does Tuesday begin" would be a second answer to a question this
+ * product already answers per person, per zone.
+ */
+export function parseBriefArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [
+            "--home",
+            "--dashboard-url",
+            "--for",
+            "--as",
+            "--who",
+            "--version",
+            "--date",
+            "--delta",
+            "--against",
+            "--days",
+            "--tldr",
+            "--full",
+            "--versions",
+            "--claims",
+            "--render",
+            "--reason",
+            "--wait",
+            "--no-wait",
+            "--json",
+        ],
+        valueFlags: [
+            "--home",
+            "--dashboard-url",
+            "--for",
+            "--as",
+            "--who",
+            "--version",
+            "--date",
+            "--against",
+            "--days",
+            "--reason",
+        ],
+    });
+    // Bare `cockpit brief` reads the page, which is what somebody typing it almost
+    // always wants — the same shape `cockpit notes` and `cockpit scout` have.
+    // `status` (BLI-3462) answers why a brief was or was not delivered.
+    const first = values.positionals[0];
+    const action = (first === undefined ? "read" : first);
+    if (!["read", "edit", "rewrite", "history", "status"].includes(action)) {
+        throw new Error(`Unknown brief command: ${first}. Try edit, rewrite, history or status, or nothing to read it.`);
+    }
+    if (values.positionals.length > (first === undefined ? 0 : 1)) {
+        throw new Error(`brief ${action} does not take "${values.positionals[1]}".`);
+    }
+    const tldr = values.booleans.has("--tldr");
+    const full = values.booleans.has("--full");
+    if (tldr && full) {
+        throw new Error("brief accepts either --tldr or --full, not both.");
+    }
+    const wait = values.booleans.has("--wait");
+    const noWait = values.booleans.has("--no-wait");
+    if (wait && noWait) {
+        throw new Error("brief rewrite accepts either --wait or --no-wait, not both.");
+    }
+    const reason = optionalNonEmpty(values.flags.get("--reason"));
+    if (reason && reason.length > 280) {
+        // The server's own ceiling (`REASON_MAX`). Said here so the person is told
+        // before the page is opened rather than after they have finished editing.
+        throw new Error("A reason is limited to 280 characters.");
+    }
+    if (action !== "edit" && reason) {
+        throw new Error("--reason belongs to `cockpit brief edit`.");
+    }
+    if (action !== "rewrite" && (wait || noWait)) {
+        throw new Error("--wait and --no-wait belong to `cockpit brief rewrite`.");
+    }
+    // ── Reading a past day (BLI-3484) ────────────────────────────────────────
+    const date = optionalNonEmpty(values.flags.get("--date"));
+    const against = optionalNonEmpty(values.flags.get("--against"));
+    const delta = values.booleans.has("--delta");
+    const days = optionalPositiveInteger(values.flags.get("--days"), "--days");
+    if (date && action !== "read") {
+        throw new Error("--date belongs to `cockpit brief` on its own — it reads one day's page.");
+    }
+    if (delta && action !== "read") {
+        throw new Error("--delta belongs to `cockpit brief` on its own.");
+    }
+    if (against && !delta) {
+        // Said rather than silently ignored: somebody who typed `--against` asked
+        // for a comparison, and running the plain read would answer a different
+        // question without saying so.
+        throw new Error("--against needs --delta: it names the day to compare against.");
+    }
+    if (days !== undefined && action !== "history") {
+        throw new Error("--days belongs to `cockpit brief history`.");
+    }
+    if (action === "history" && (values.booleans.has("--tldr") || values.booleans.has("--claims"))) {
+        throw new Error("brief history lists days; --tldr and --claims belong to reading a page.");
+    }
+    // `--as` is accepted as an alias so the two conversational commands read the
+    // same way; `cockpit jarvis --as <person>` has meant this since BLI-3380.
+    // `--who` is the third spelling, and it exists because `cockpit brief status
+    // --who <person>` is the terminal echo of `jarvis:dm --who`.
+    const forPerson = optionalNonEmpty(values.flags.get("--for"));
+    const asPerson = optionalNonEmpty(values.flags.get("--as"));
+    const whoPerson = optionalNonEmpty(values.flags.get("--who"));
+    const named = [forPerson, asPerson, whoPerson].filter(Boolean);
+    if (new Set(named).size > 1) {
+        throw new Error("brief --for, --as and --who must name the same person.");
+    }
+    const render = values.booleans.has("--render");
+    if (render && action !== "status") {
+        throw new Error("brief --render belongs to `cockpit brief status`; the page is printed by default.");
+    }
+    return {
+        kind: "brief",
+        action,
+        render,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        subject: forPerson ?? asPerson ?? whoPerson,
+        version: optionalNonEmpty(values.flags.get("--version")),
+        ...(date ? { date } : {}),
+        ...(delta ? { delta: true } : {}),
+        ...(against ? { against } : {}),
+        ...(days !== undefined ? { days } : {}),
+        tldr,
+        versions: values.booleans.has("--versions"),
+        claims: values.booleans.has("--claims"),
+        ...(reason ? { reason } : {}),
+        // Waiting is the default; only an explicit `--no-wait` turns it off. A
+        // person who typed `rewrite` wants the page, not a receipt.
+        ...(noWait ? { wait: false } : {}),
+        json: values.booleans.has("--json"),
+    };
+}
+const NOTES_ACTIONS = new Set([
+    "list",
+    "show",
+    "shelf",
+    "shelves",
+    "upload",
+    "paste",
+    "share",
+    "unshare",
+    "move",
+]);
+/** Actions whose first positional is the note it acts on. */
+const NOTES_ACTIONS_NEEDING_A_NOTE = new Set([
+    "show",
+    "share",
+    "unshare",
+    "move",
+]);
+export function parseNotesArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [
+            "--home",
+            "--dashboard-url",
+            "--file",
+            "--name",
+            "--exclude",
+            "--to",
+            "--clear-shelf",
+            "--series",
+            "--kind",
+            "--since",
+            "--until",
+            "--limit",
+            "--yes",
+            "--json",
+        ],
+        valueFlags: [
+            "--home",
+            "--dashboard-url",
+            "--file",
+            "--name",
+            "--exclude",
+            "--to",
+            "--series",
+            "--kind",
+            "--since",
+            "--until",
+            "--limit",
+        ],
+    });
+    // Bare `cockpit notes` is the list, which is the thing a person typing it
+    // almost always wants — same reasoning as bare `cockpit` running convergence.
+    const first = values.positionals[0];
+    const action = (first === undefined ? "list" : first);
+    if (!NOTES_ACTIONS.has(action)) {
+        throw new Error(`Unknown notes command: ${first}. Try list, show, shelf, shelves, upload, paste, share, unshare, or move.`);
+    }
+    const rest = values.positionals.slice(first === undefined ? 0 : 1);
+    const json = values.booleans.has("--json");
+    // `--json` implies `--yes`: a machine-readable run has nobody to prompt, and
+    // failing it for want of a confirmation flag it cannot see is a worse
+    // surprise than an explicit share it already asked for by name.
+    const yes = values.booleans.has("--yes") || json;
+    let noteId;
+    if (NOTES_ACTIONS_NEEDING_A_NOTE.has(action)) {
+        noteId = optionalNonEmpty(rest[0]);
+        if (!noteId)
+            throw new Error(`notes ${action} needs a note id.`);
+        if (rest.length > 1) {
+            throw new Error(`notes ${action} takes one note id, not ${rest.length}.`);
+        }
+    }
+    let paths;
+    if (action === "upload") {
+        // Explicit paths only. No globbing happens here — a shell that expands
+        // `*.md` hands us the names it found, and a shell that does not would have
+        // this command silently uploading a file literally called `*.md`.
+        paths = rest.filter((value) => value.trim() !== "");
+        if (paths.length === 0)
+            throw new Error("notes upload needs at least one file path.");
+    }
+    else if (action !== "paste" && !NOTES_ACTIONS_NEEDING_A_NOTE.has(action) && rest.length > 0) {
+        throw new Error(`notes ${action} does not take "${rest[0]}".`);
+    }
+    const to = optionalNonEmpty(values.flags.get("--to"));
+    const clearShelf = values.booleans.has("--clear-shelf");
+    if (action === "move") {
+        if (to && clearShelf) {
+            throw new Error("notes move accepts either --to or --clear-shelf, not both.");
+        }
+        if (!to && !clearShelf) {
+            throw new Error('notes move needs --to "<shelf>" or --clear-shelf.');
+        }
+    }
+    const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
+    return {
+        kind: "notes",
+        action,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        ...(noteId ? { noteId } : {}),
+        ...(paths ? { paths } : {}),
+        filePath: optionalNonEmpty(values.flags.get("--file")),
+        name: optionalNonEmpty(values.flags.get("--name")),
+        exclude: optionalNonEmpty(values.flags.get("--exclude")),
+        ...(to ? { to } : {}),
+        ...(clearShelf ? { clearShelf } : {}),
+        series: optionalNonEmpty(values.flags.get("--series")),
+        meetingKind: optionalNonEmpty(values.flags.get("--kind")),
+        since: optionalNonEmpty(values.flags.get("--since")),
+        until: optionalNonEmpty(values.flags.get("--until")),
+        ...(limit === undefined ? {} : { limit }),
+        yes,
+        json,
+    };
+}
+/** The narrowest width worth wrapping to; below it every line is one word. */
+export const WORKBOOK_MIN_WIDTH = 20;
+/**
+ * `cockpit workbook` with nothing lists the library, one positional lists a
+ * project's shelf, two read a document.
+ */
+export function parseWorkbookArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [
+            "--home",
+            "--dashboard-url",
+            "--section",
+            "--width",
+            "--markdown",
+            "--json",
+        ],
+        valueFlags: ["--home", "--dashboard-url", "--section", "--width"],
+    });
+    if (values.positionals.length > 2) {
+        throw new Error("workbook accepts at most a project and a document.");
+    }
+    const project = optionalNonEmpty(values.positionals[0]);
+    const doc = optionalNonEmpty(values.positionals[1]);
+    const section = optionalNonEmpty(values.flags.get("--section"));
+    const markdown = values.booleans.has("--markdown");
+    if (!doc && (section || markdown)) {
+        throw new Error("workbook --section and --markdown need a project and a document, e.g. `cockpit workbook tower workbook`.");
+    }
+    const width = optionalPositiveInteger(values.flags.get("--width"), "--width");
+    if (width !== undefined && width < WORKBOOK_MIN_WIDTH) {
+        throw new Error(`workbook --width must be at least ${WORKBOOK_MIN_WIDTH}.`);
+    }
+    return {
+        kind: "workbook",
+        project,
+        doc,
+        section,
+        markdown,
+        width,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        json: values.booleans.has("--json"),
+    };
+}