@bli-cockpit/cli 0.2.237 → 0.2.239

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

@@ -0,0 +1,346 @@
+/**
+ * What a person may type at `cockpit notes` (BLI-3459, BLI-4383, BLI-4394): the
+ * argument table for the meeting-notes surface, split out of
+ * `local-args-tower-pages.ts` when that file crossed the 700-line ceiling.
+ * Every flag, default and refusal sentence moved verbatim; `parseNotesArgs` and
+ * `NotesAction` are still exported from `./local-args-tower-pages.js`, the
+ * address they have always had.
+ */
+import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
+/**
+ * The notetakers `cockpit notes connect` will actually seal a key for
+ * (BLI-4391). It mirrors `CONNECTABLE_NOTES_PROVIDERS` in the dashboard, and
+ * the door is still the authority — this list only saves a round trip and a
+ * sealed key for a provider with no reader.
+ *
+ * `otter` and `granola` are deliberately absent: Otter's public API is
+ * Enterprise-only and Granola still runs on its own server-side cron.
+ */
+const CONNECTABLE_PROVIDERS = ["fellow", "circleback", "wisprflow"];
+/**
+ * BLI-12926. Providers with no API key at all: the person signs in through
+ * their browser and `connect` runs that sign-in itself. `--key-stdin` is
+ * optional for these, and carries a pre-built sign-in bundle when given.
+ */
+const PROVIDERS_SIGNED_IN_BY_BROWSER = ["wisprflow"];
+/** The provider whose API is per workspace, so its account needs a subdomain. */
+const PROVIDERS_NEEDING_A_WORKSPACE = ["fellow"];
+const NOTES_ACTIONS = new Set([
+    "folders", "mkdir", "rmdir", "rename",
+    "list",
+    "show",
+    "shelf",
+    "shelves",
+    "upload",
+    "paste",
+    "share",
+    "unshare",
+    "summarize",
+    "move",
+    "place",
+    // BLI-4383: the notetaker a person connects, and the meetings it records.
+    "accounts",
+    "connect",
+    "detach",
+    "sync",
+    "sync-status",
+    // BLI-12926: the alternates of a meeting several notetakers recorded.
+    "recordings",
+    "recording",
+    // BLI-4394: arm that notetaker's webhook with the vendor's signing secret.
+    "webhook",
+    // Ticket 10718: the Granola cron's own last-several-runs health.
+    "granola-status",
+    "transcription-stats",
+    "bot-upcoming",
+]);
+/** Actions whose first positional is the note it acts on. */
+const NOTES_ACTIONS_NEEDING_A_NOTE = new Set([
+    "show",
+    "share",
+    "unshare",
+    "summarize",
+    "move",
+    "place",
+    // BLI-12926: `recordings` names the note, `recording` names the recording.
+    "recordings",
+    "recording",
+]);
+/**
+ * BLI-4383. Actions whose first positional is a NOTETAKER ACCOUNT id, not a
+ * note id. `sync` takes one too, and is handled beside these rather than in
+ * this set because its id is checked at the door instead of here.
+ */
+const NOTES_ACTIONS_NEEDING_AN_ACCOUNT = new Set(["detach", "webhook"]);
+const NOTES_ALLOWED_FLAGS = [
+    "--wait",
+    "--home",
+    "--dashboard-url",
+    "--file",
+    "--name",
+    "--exclude",
+    "--to",
+    "--folder",
+    "--clear-shelf",
+    "--apply",
+    "--series",
+    "--kind",
+    "--since",
+    "--until",
+    "--limit",
+    "--month",
+    "--offset",
+    "--yes",
+    "--json",
+    "--tree",
+    // BLI-4383. `--key-stdin` is a FLAG and not a value: the key itself is
+    // read from stdin and never from argv.
+    "--provider",
+    "--key-stdin",
+    // BLI-4391. Fellow's API is per WORKSPACE, and a subdomain is a label,
+    // not a secret, so this one carries a value while the key never does.
+    "--workspace",
+    // BLI-4394. `--secret-stdin` is a FLAG and not a value, for the same
+    // reason `--key-stdin` is: the signing secret never touches argv.
+    "--secret-stdin",
+    "--show-webhook",
+    // BLI-18006. `sync <id> --repair-truncated` re-reads Wispr Flow notes whose
+    // transcript was stored cut short. A FLAG, not a verb: it is the same sync
+    // door with a different request.
+    "--repair-truncated",
+];
+const NOTES_VALUE_FLAGS = [
+    "--home",
+    "--dashboard-url",
+    "--file",
+    "--name",
+    "--exclude",
+    "--to",
+    "--folder",
+    "--series",
+    "--kind",
+    "--since",
+    "--until",
+    "--limit",
+    "--month",
+    "--offset",
+    "--provider",
+    "--workspace",
+    "--show-webhook",
+];
+export function parseNotesArgs(args) {
+    const values = parseNamedArgs(args, { allowedFlags: NOTES_ALLOWED_FLAGS, valueFlags: NOTES_VALUE_FLAGS });
+    const action = readNotesAction(values.positionals[0]);
+    const rest = values.positionals.slice(values.positionals[0] === undefined ? 0 : 1);
+    const { json, yes } = readNotesConfirmation(values);
+    const noteId = readNotesNoteId(action, rest);
+    const showWebhook = optionalNonEmpty(values.flags.get("--show-webhook"));
+    const accountId = readNotesAccountId(action, rest, showWebhook);
+    requireWebhookSecretOnlyForWebhook(action, values);
+    const provider = optionalNonEmpty(values.flags.get("--provider"));
+    const workspace = optionalNonEmpty(values.flags.get("--workspace"));
+    if (action === "connect")
+        rejectBadConnectRequest(values, provider, workspace, rest);
+    const paths = readNotesPaths(action, rest);
+    if (action === "rename" && !optionalNonEmpty(values.flags.get("--name")))
+        throw new Error("notes rename needs --name <name>.");
+    const { to, clearShelf } = readNotesShelfTarget(action, values);
+    const repairTruncated = readRepairTruncated(action, values);
+    const { limit, month, offset } = readNotesWindow(action, values);
+    return {
+        kind: "notes",
+        ...(values.booleans.has("--wait") ? { wait: true } : {}),
+        action,
+        ...(values.flags.has("--folder") ? { folder: values.flags.get("--folder") } : {}),
+        ...(action === "mkdir" || action === "rmdir" || action === "rename" ? { folder: rest[0] } : {}),
+        ...(values.booleans.has("--tree") ? { tree: true } : {}),
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        ...(noteId ? { noteId } : {}),
+        ...(accountId ? { accountId } : {}),
+        ...(provider ? { provider } : {}),
+        ...(workspace ? { workspace } : {}),
+        ...(showWebhook ? { showWebhook: true } : {}),
+        ...(action === "connect" && values.booleans.has("--key-stdin") ? { keyStdin: true } : {}),
+        ...(paths ? { paths } : {}),
+        filePath: optionalNonEmpty(values.flags.get("--file")),
+        name: optionalNonEmpty(values.flags.get("--name")),
+        exclude: optionalNonEmpty(values.flags.get("--exclude")),
+        ...(to ? { to } : {}),
+        ...(clearShelf ? { clearShelf } : {}),
+        // BLI-4058. `place` says where a note belongs; only `--apply` moves it.
+        ...(values.booleans.has("--apply") ? { apply: true } : {}),
+        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 }),
+        ...(month ? { month } : {}),
+        ...(offset === undefined ? {} : { offset }),
+        ...(repairTruncated ? { repairTruncated: true } : {}),
+        yes,
+        json,
+    };
+}
+function readNotesAction(first) {
+    // 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 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, summarize, move, place, accounts, connect, detach, sync, sync-status, recordings, recording, webhook, granola-status, or transcription-stats.`);
+    }
+    return action;
+}
+function readRepairTruncated(action, values) {
+    const repairTruncated = values.booleans.has("--repair-truncated");
+    if (repairTruncated && action !== "sync") {
+        throw new Error("--repair-truncated belongs to `cockpit notes sync <account-id> --repair-truncated`.");
+    }
+    return repairTruncated;
+}
+function readNotesConfirmation(values) {
+    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.
+    return { json, yes: values.booleans.has("--yes") || json };
+}
+/** How much of what to read: `--limit`, the transcription-stats month, the `show` offset. */
+function readNotesWindow(action, values) {
+    const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
+    const month = readNotesMonth(action, values);
+    const offset = readNotesOffset(action, values);
+    return { limit, month, offset };
+}
+function readNotesNoteId(action, rest) {
+    if (!NOTES_ACTIONS_NEEDING_A_NOTE.has(action))
+        return undefined;
+    const 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}.`);
+    }
+    return noteId;
+}
+/** The notetaker account a verb names; `--show-webhook <id>` names one on `accounts`. */
+function readNotesAccountId(action, rest, showWebhook) {
+    let accountId;
+    if (NOTES_ACTIONS_NEEDING_AN_ACCOUNT.has(action) || action === "sync" || action === "sync-status") {
+        accountId = optionalNonEmpty(rest[0]);
+        if (!accountId && NOTES_ACTIONS_NEEDING_AN_ACCOUNT.has(action)) {
+            throw new Error(`notes ${action} needs a notetaker account id.`);
+        }
+        if (rest.length > 1) {
+            throw new Error(`notes ${action} takes one account id, not ${rest.length}.`);
+        }
+    }
+    // BLI-4394. `--show-webhook <id>` is a flag on `accounts` rather than a verb
+    // of its own, because "what is this one's webhook URL?" is the question a
+    // person asks WHILE looking at the list.
+    if (showWebhook === undefined)
+        return accountId;
+    if (action !== "accounts") {
+        throw new Error("--show-webhook belongs to `cockpit notes accounts --show-webhook <account-id>`.");
+    }
+    return showWebhook;
+}
+function requireWebhookSecretOnlyForWebhook(action, values) {
+    if (action !== "webhook") {
+        if (values.booleans.has("--secret-stdin")) {
+            throw new Error("--secret-stdin belongs to `cockpit notes webhook <account-id> --secret-stdin`.");
+        }
+        return;
+    }
+    if (!values.booleans.has("--secret-stdin")) {
+        // Naming the flag is the point: it says out loud that the signing secret
+        // is not an argument, so nobody goes looking for a `--secret` that will
+        // never exist.
+        throw new Error('notes webhook reads the signing secret from stdin. Say so: printf "%s" "<secret>" | cockpit notes webhook <account-id> --secret-stdin');
+    }
+}
+function rejectBadConnectRequest(values, provider, workspace, rest) {
+    if (!provider) {
+        throw new Error(`notes connect needs --provider ${CONNECTABLE_PROVIDERS.join("|")}.`);
+    }
+    if (!CONNECTABLE_PROVIDERS.includes(provider)) {
+        throw new Error(`notes connect does not know the provider "${provider}". Tower reads ${CONNECTABLE_PROVIDERS.join(" and ")}.`);
+    }
+    if (PROVIDERS_NEEDING_A_WORKSPACE.includes(provider) && !workspace) {
+        throw new Error(`notes connect --provider ${provider} needs --workspace <subdomain>: its API lives at https://<subdomain>.fellow.app, so a key alone cannot address anything.`);
+    }
+    if (workspace !== undefined && !/^[a-z0-9-]{1,63}$/.test(workspace)) {
+        throw new Error("--workspace is a workspace subdomain: lowercase letters, digits and hyphens, 1 to 63 characters.");
+    }
+    if (!values.booleans.has("--key-stdin") && !PROVIDERS_SIGNED_IN_BY_BROWSER.includes(provider)) {
+        // Naming the flag is the point: it says out loud that the key is not an
+        // argument, so nobody goes looking for a `--key` that will never exist.
+        throw new Error('notes connect reads the key from stdin. Say so: printf "%s" "<key>" | cockpit notes connect --provider fellow --workspace <subdomain> --key-stdin');
+    }
+    if (rest.length > 0)
+        throw new Error(`notes connect does not take "${rest[0]}".`);
+}
+/** The upload paths, and a refusal for stray positionals on verbs that take none. */
+function readNotesPaths(action, rest) {
+    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`.
+        const paths = rest.filter((value) => value.trim() !== "");
+        if (paths.length === 0)
+            throw new Error("notes upload needs at least one file path.");
+        return paths;
+    }
+    if (action === "mkdir" || action === "rmdir" || action === "rename") {
+        if (rest.length !== 1 || !rest[0]?.trim())
+            throw new Error(`notes ${action} needs one folder path.`);
+        return undefined;
+    }
+    const takesNoPositional = action !== "paste"
+        && action !== "connect"
+        && action !== "sync"
+        && action !== "sync-status"
+        && !NOTES_ACTIONS_NEEDING_A_NOTE.has(action)
+        && !NOTES_ACTIONS_NEEDING_AN_ACCOUNT.has(action);
+    if (takesNoPositional && rest.length > 0) {
+        throw new Error(`notes ${action} does not take "${rest[0]}".`);
+    }
+    return undefined;
+}
+function readNotesShelfTarget(action, values) {
+    const to = optionalNonEmpty(values.flags.get("--to"));
+    const clearShelf = values.booleans.has("--clear-shelf");
+    if (action !== "move")
+        return { to, clearShelf };
+    if (to && clearShelf) {
+        throw new Error("notes move accepts either --to or --clear-shelf, not both.");
+    }
+    if (!to && !clearShelf && !values.flags.get("--folder")) {
+        throw new Error('notes move needs --to "<shelf>", --clear-shelf, or --folder "<path>".');
+    }
+    return { to, clearShelf };
+}
+function readNotesMonth(action, values) {
+    const month = optionalNonEmpty(values.flags.get("--month"));
+    if (month === undefined)
+        return undefined;
+    if (action !== "transcription-stats") {
+        throw new Error("--month belongs to `cockpit notes transcription-stats --month YYYY-MM`.");
+    }
+    if (!/^\d{4}-(0[1-9]|1[0-2])$/.test(month)) {
+        throw new Error("--month is a calendar month like 2026-10.");
+    }
+    return month;
+}
+/** BLI-18006: a long note is read in parts, like `cockpit docs read --offset`. */
+function readNotesOffset(action, values) {
+    const offsetRaw = optionalNonEmpty(values.flags.get("--offset"));
+    if (offsetRaw === undefined)
+        return undefined;
+    if (action !== "show")
+        throw new Error("--offset belongs to `cockpit notes show <id> --offset <characters> --limit <characters>`.");
+    const offset = Number(offsetRaw);
+    if (!Number.isInteger(offset) || offset < 0)
+        throw new Error("--offset must be a whole number 0 or greater.");
+    return offset;
+}