@wirecat/cli-base 0.24.0 → 0.26.0

package/dist/standards/vocabulary.js

@@ -13,6 +13,22 @@ export const FLAG_TYPES = [
     "path",
     "cursor",
 ];
+/**
+ * What a flag does to a command. There is no `filter`: a list filters with its query, so a flag that filters has no
+ * role and `option-role` reports it.
+ */
+export const FLAG_ROLES = {
+    paging: "which part of a long answer: how many, which page, where to continue",
+    output: "how the answer is shaped or shown",
+    sort: "the order of the answer",
+    mode: "how the command runs, not what it reads",
+    action: "does something extra besides the answer",
+    budget: "how much time or work the command may spend",
+    scope: "which accounts, providers or sources are read; never picked for you, so a flag and not a query field",
+    target: "which thing or time window the command acts on, when that is not a list's filter",
+    value: "sets a field on a write",
+    query: "a query in the query language, beside a search's own words",
+};
 const verbSchema = v.strictObject({ word, meaning: text, replaces: v.optional(v.array(word)) });
 const nounSchema = v.strictObject({
     word,
@@ -27,6 +43,7 @@ const flagSchema = v.strictObject({
     name: v.pipe(v.string(), v.regex(/^--[a-z][a-z0-9]*(-[a-z0-9]+)*$/, "a long flag: --lower-case-words")),
     value: v.optional(v.pipe(v.string(), v.regex(/^<[a-z][a-z0-9-|]*>$/, "a value name such as <n>"))),
     type: v.picklist(FLAG_TYPES),
+    role: v.picklist(Object.keys(FLAG_ROLES)),
     meaning: text,
     unit: v.optional(text),
 });
@@ -215,28 +232,575 @@ const roots = [
     ["search", "searches across resources"],
 ];
 const flags = [
-    { name: "--limit", value: "<n>", type: "count", meaning: "how many items", unit: "items" },
-    { name: "--page", value: "<n>", type: "count", meaning: "which page, from 1, where the source has no cursor" },
+    { name: "--limit", value: "<n>", role: "paging", type: "count", meaning: "how many items", unit: "items" },
+    {
+        name: "--page",
+        value: "<n>",
+        role: "paging",
+        type: "count",
+        meaning: "which page, from 1, where the source has no cursor",
+    },
     {
         name: "--page-size",
         value: "<n>",
+        role: "paging",
         type: "count",
         meaning: "how many items one request to the source asks for",
         unit: "items",
     },
-    { name: "--cursor", value: "<cursor>", type: "cursor", meaning: "continue from where the previous page ended" },
-    { name: "--before-id", value: "<id>", type: "id", meaning: "read what came before this message id" },
-    { name: "--after-id", value: "<id>", type: "id", meaning: "read what came after this message id" },
-    { name: "--before-time", value: "<time>", type: "time", meaning: "read what came before this time" },
-    { name: "--after-time", value: "<time>", type: "time", meaning: "read what came after this time" },
-    { name: "--since-time", value: "<time>", type: "time", meaning: "only what came since this time" },
-    { name: "--until-time", value: "<time>", type: "time", meaning: "only what came up to and including this time" },
-    { name: "--at-time", value: "<time>", type: "time", meaning: "do it at this time" },
-    { name: "--before-n", value: "<n>", type: "count", meaning: "how many messages before it", unit: "messages" },
-    { name: "--after-n", value: "<n>", type: "count", meaning: "how many messages after it", unit: "messages" },
-    { name: "--timeout", value: "<duration>", type: "duration", meaning: "give up after this long" },
-    { name: "--dry-run", type: "switch", meaning: "judge and plan; do nothing" },
-    { name: "--debug", type: "switch", meaning: "on failure, show the full error record: cause and stack" },
+    {
+        name: "--cursor",
+        value: "<cursor>",
+        role: "paging",
+        type: "cursor",
+        meaning: "continue from where the previous page ended",
+    },
+    { name: "--before-id", value: "<id>", role: "paging", type: "id", meaning: "read what came before this message id" },
+    { name: "--after-id", value: "<id>", role: "paging", type: "id", meaning: "read what came after this message id" },
+    { name: "--before-time", value: "<time>", role: "target", type: "time", meaning: "read what came before this time" },
+    { name: "--after-time", value: "<time>", role: "target", type: "time", meaning: "read what came after this time" },
+    { name: "--since-time", value: "<time>", role: "target", type: "time", meaning: "only what came since this time" },
+    {
+        name: "--until-time",
+        value: "<time>",
+        role: "target",
+        type: "time",
+        meaning: "only what came up to and including this time",
+    },
+    { name: "--at-time", value: "<time>", role: "value", type: "time", meaning: "do it at this time" },
+    {
+        name: "--before-n",
+        value: "<n>",
+        role: "output",
+        type: "count",
+        meaning: "how many messages before it",
+        unit: "messages",
+    },
+    {
+        name: "--after-n",
+        value: "<n>",
+        role: "output",
+        type: "count",
+        meaning: "how many messages after it",
+        unit: "messages",
+    },
+    { name: "--timeout", value: "<duration>", role: "budget", type: "duration", meaning: "give up after this long" },
+    {
+        name: "--account",
+        value: "<account>",
+        role: "scope",
+        type: "string",
+        meaning: "the account to use; never assumed",
+    },
+    {
+        name: "--provider",
+        value: "<provider>",
+        role: "scope",
+        type: "choice",
+        meaning: "read every account of this provider",
+    },
+    {
+        name: "--source",
+        value: "<accounts>",
+        role: "scope",
+        type: "list",
+        meaning: "what to read: provider:account, a provider, a kind or group:<name>; comma-separated",
+    },
+    { name: "--dry-run", role: "mode", type: "switch", meaning: "judge and plan; do nothing" },
+    {
+        name: "--debug",
+        role: "output",
+        type: "switch",
+        meaning: "on failure, show the full error record: cause and stack",
+    },
+    {
+        name: "--agent-json",
+        role: "output",
+        type: "switch",
+        meaning: "JSON with control and direction characters made visible in strings and keys",
+    },
+    {
+        name: "--brief",
+        role: "output",
+        type: "switch",
+        meaning: "each item as its reference, title, time and excerpt only",
+    },
+    {
+        name: "--chart-kind",
+        value: "<messages|active|membership>",
+        role: "output",
+        type: "choice",
+        meaning: "what a chart draws",
+    },
+    {
+        name: "--checkpoints",
+        value: "<durations>",
+        role: "output",
+        type: "list",
+        meaning: "the ages to report on, comma-separated: 1d,7d,30d",
+    },
+    {
+        name: "--fields",
+        value: "<paths>",
+        role: "output",
+        type: "list",
+        meaning: "only these comma-separated fields of each item; list metadata stays",
+    },
+    { name: "--format", value: "<format>", role: "output", type: "choice", meaning: "the format of the file written" },
+    { name: "--full", role: "output", type: "switch", meaning: "each item with its whole text and every field" },
+    {
+        name: "--json",
+        role: "output",
+        type: "switch",
+        meaning: "machine-readable output: one JSON value on stdout, nothing else",
+    },
+    { name: "--jsonl", role: "output", type: "switch", meaning: "machine-readable output: one JSON object per line" },
+    { name: "--output", value: "<file>", role: "output", type: "path", meaning: "the file to write" },
+    {
+        name: "--output-dir",
+        value: "<dir>",
+        role: "output",
+        type: "path",
+        meaning: "the folder to write into, created if missing",
+    },
+    { name: "--quiet", role: "output", type: "switch", meaning: "no diagnostics on stderr" },
+    { name: "--show-phone", role: "output", type: "switch", meaning: "print the whole phone number" },
+    {
+        name: "--thread-within",
+        value: "<duration>",
+        role: "output",
+        type: "duration",
+        meaning: "messages within this long either side of the hit",
+    },
+    {
+        name: "--trace",
+        role: "output",
+        type: "switch",
+        meaning: "one line per request on stderr: ids and timings, never content",
+    },
+    { name: "--verbose", role: "output", type: "switch", meaning: "more detail in what is shown; repeat for more" },
+    { name: "--version", role: "output", type: "switch", meaning: "print the version number" },
+    { name: "--with-notes", role: "output", type: "switch", meaning: "include the owner's private notes" },
+    { name: "--measure", value: "<name>", role: "sort", type: "choice", meaning: "the metric a ranking is ordered by" },
+    { name: "--newest", role: "sort", type: "switch", meaning: "newest first instead of best first" },
+    {
+        name: "--order",
+        value: "<recent|name>",
+        role: "sort",
+        type: "choice",
+        meaning: "the order of a list: most recent first, or by name",
+    },
+    { name: "--score", value: "<preset>", role: "sort", type: "choice", meaning: "the named ranking score preset" },
+    {
+        name: "--weights",
+        value: "<json>",
+        role: "sort",
+        type: "string",
+        meaning: "the ranking component weights, all of them",
+    },
+    { name: "--accept-terms", role: "mode", type: "switch", meaning: "accept the model's licence terms" },
+    {
+        name: "--allow-any-file",
+        role: "mode",
+        type: "switch",
+        meaning: "send a file even from a credential folder or the tool's own folders",
+    },
+    {
+        name: "--allow-dangerous",
+        role: "mode",
+        type: "switch",
+        meaning: "go ahead without the question an ask level puts before a deletion",
+    },
+    {
+        name: "--allow-writes",
+        role: "mode",
+        type: "switch",
+        meaning: "acknowledge that the profile offers writing tools",
+    },
+    { name: "--as-file", role: "mode", type: "switch", meaning: "send every file as a plain file to download" },
+    { name: "--background", role: "mode", type: "switch", meaning: "run as a job that outlives this command" },
+    {
+        name: "--base-url",
+        value: "<url>",
+        role: "mode",
+        type: "string",
+        meaning: "the address of an OpenAI-compatible model API",
+    },
+    { name: "--dims", value: "<n>", role: "mode", type: "count", meaning: "the embedding vector size" },
+    {
+        name: "--discover",
+        role: "mode",
+        type: "switch",
+        meaning: "also find partial matches; the results are evidence, not answers",
+    },
+    {
+        name: "--encrypt",
+        role: "mode",
+        type: "switch",
+        meaning: "compress and encrypt with a password that is never kept",
+    },
+    { name: "--exact", role: "mode", type: "switch", meaning: "bare words and quotes match their exact form only" },
+    {
+        name: "--fingerprint",
+        value: "<hash>",
+        role: "mode",
+        type: "string",
+        meaning: "refuse if the plan it names has changed",
+    },
+    {
+        name: "--for-everyone",
+        role: "mode",
+        type: "switch",
+        meaning: "delete for everyone in the chat, not only for the owner",
+    },
+    { name: "--http", role: "mode", type: "switch", meaning: "serve over HTTP on 127.0.0.1" },
+    { name: "--language", value: "<lucene|legacy>", role: "mode", type: "choice", meaning: "the query language" },
+    { name: "--local", role: "mode", type: "switch", meaning: "use the model on this machine, never the source" },
+    {
+        name: "--max-age",
+        value: "<duration>",
+        role: "mode",
+        type: "duration",
+        meaning: "how old a stored snapshot may be and still count as fresh",
+    },
+    { name: "--md", role: "mode", type: "switch", meaning: "the text is the messenger's Markdown" },
+    { name: "--no-backup", role: "mode", type: "switch", meaning: "do not back the file up before deleting it" },
+    { name: "--no-input", role: "mode", type: "switch", meaning: "never prompt or open an interactive login" },
+    { name: "--no-preview", role: "mode", type: "switch", meaning: "no preview card for a link in the text" },
+    {
+        name: "--no-record",
+        role: "mode",
+        type: "switch",
+        meaning: "do not keep this run, whatever the configuration says",
+    },
+    { name: "--no-registries", role: "mode", type: "switch", meaning: "do not ask the public ban lists" },
+    { name: "--notify", role: "mode", type: "switch", meaning: "tell the chat's members about it" },
+    { name: "--offline", role: "mode", type: "switch", meaning: "answer from what was recorded and never connect" },
+    { name: "--port", value: "<port>", role: "mode", type: "number", meaning: "the local port for --http" },
+    {
+        name: "--public-url",
+        value: "<url>",
+        role: "mode",
+        type: "string",
+        meaning: "the public https address of the tunnel",
+    },
+    {
+        name: "--record",
+        role: "mode",
+        type: "switch",
+        meaning: "keep this run under runs: ids and timings, never content",
+    },
+    { name: "--regex", role: "mode", type: "switch", meaning: "the words are one regular expression" },
+    {
+        name: "--send-id",
+        value: "<id>",
+        role: "mode",
+        type: "id",
+        meaning: "identify a send attempt, so a retry reuses it",
+    },
+    { name: "--silent", role: "mode", type: "switch", meaning: "deliver without a notification" },
+    { name: "--thread", role: "mode", type: "switch", meaning: "the stored reply chain instead of time neighbours" },
+    {
+        name: "--timezone",
+        value: "<zone>",
+        role: "mode",
+        type: "string",
+        meaning: "the IANA timezone dates and times are read in",
+    },
+    {
+        name: "--yes",
+        role: "mode",
+        type: "switch",
+        meaning: "go ahead with the write without asking or previewing first",
+    },
+    { name: "--analyze", role: "action", type: "switch", meaning: "also analyze with the configured provider" },
+    { name: "--catch-up", role: "action", type: "switch", meaning: "prepare local search after this run" },
+    { name: "--extract", role: "action", type: "switch", meaning: "also read the text inside the files written" },
+    {
+        name: "--mark-read",
+        role: "action",
+        type: "switch",
+        meaning: "also mark the chat read up to the newest message shown; the other person sees it",
+    },
+    { name: "--no-catch-up", role: "action", type: "switch", meaning: "skip local preparation after this run" },
+    { name: "--retract", role: "action", type: "switch", meaning: "take the owner's vote back" },
+    { name: "--revoke", role: "action", type: "switch", meaning: "forget every login given to a browser app" },
+    { name: "--track", role: "action", type: "switch", meaning: "also do it daily while serve runs" },
+    {
+        name: "--transcribe",
+        role: "action",
+        type: "switch",
+        meaning: "also transcribe voice messages not transcribed yet, on this machine",
+    },
+    {
+        name: "--catch-up-chunks",
+        value: "<n>",
+        role: "budget",
+        type: "count",
+        meaning: "at most this many chunks prepared after the run",
+        unit: "chunks",
+    },
+    {
+        name: "--catch-up-messages",
+        value: "<n>",
+        role: "budget",
+        type: "count",
+        meaning: "skip the graph rebuild above this many messages",
+        unit: "messages",
+    },
+    {
+        name: "--concurrency",
+        value: "<n>",
+        role: "budget",
+        type: "count",
+        meaning: "requests to the source at once",
+        unit: "requests",
+    },
+    {
+        name: "--deep",
+        value: "<n>",
+        role: "budget",
+        type: "count",
+        meaning: "also check the top n in full, one a second",
+        unit: "people",
+    },
+    {
+        name: "--max-actions",
+        value: "<n>",
+        role: "budget",
+        type: "count",
+        meaning: "at most this many actions in one run",
+        unit: "actions",
+    },
+    {
+        name: "--max-chats",
+        value: "<n>",
+        role: "budget",
+        type: "count",
+        meaning: "at most this many chats in one run",
+        unit: "chats",
+    },
+    {
+        name: "--max-chunks",
+        value: "<n>",
+        role: "budget",
+        type: "count",
+        meaning: "at most this many chunks in one run",
+        unit: "chunks",
+    },
+    {
+        name: "--max-gaps",
+        value: "<n>",
+        role: "budget",
+        type: "count",
+        meaning: "at most this many gaps repaired in one run",
+        unit: "gaps",
+    },
+    {
+        name: "--max-input-bytes",
+        value: "<bytes>",
+        role: "budget",
+        type: "count",
+        meaning: "at most this many bytes of buffered stdin",
+        unit: "bytes",
+    },
+    {
+        name: "--max-messages",
+        value: "<n>",
+        role: "budget",
+        type: "count",
+        meaning: "at most this many messages in one run",
+        unit: "messages",
+    },
+    {
+        name: "--max-replies",
+        value: "<n>",
+        role: "budget",
+        type: "count",
+        meaning: "at most this many replies read",
+        unit: "replies",
+    },
+    {
+        name: "--max-tokens",
+        value: "<n>",
+        role: "budget",
+        type: "count",
+        meaning: "at most this many model tokens in one run",
+        unit: "tokens",
+    },
+    {
+        name: "--thread-bytes",
+        value: "<n>",
+        role: "budget",
+        type: "count",
+        meaning: "at most this many bytes in each thread context",
+        unit: "bytes",
+    },
+    {
+        name: "--thread-hops",
+        value: "<n>",
+        role: "budget",
+        type: "count",
+        meaning: "at most this many links from the hit",
+        unit: "links",
+    },
+    {
+        name: "--thread-messages",
+        value: "<n>",
+        role: "budget",
+        type: "count",
+        meaning: "at most this many messages in each thread context",
+        unit: "messages",
+    },
+    {
+        name: "--batch",
+        value: "<id>",
+        role: "target",
+        type: "id",
+        meaning: "the batch to act on, by the id that listed it",
+    },
+    {
+        name: "--component",
+        value: "<name>",
+        role: "target",
+        type: "string",
+        meaning: "the ranking component to read the evidence of",
+    },
+    {
+        name: "--counters",
+        value: "<names>",
+        role: "target",
+        type: "list",
+        meaning: "the counters to read: views, reactions, comments",
+    },
+    { name: "--failed", role: "target", type: "switch", meaning: "every chat whose newest job failed or died" },
+    { name: "--left", role: "target", type: "switch", meaning: "only the chats this account has left" },
+    { name: "--others", role: "target", type: "switch", meaning: "every session but this one" },
+    {
+        name: "--saved",
+        value: "<name|id>",
+        role: "target",
+        type: "string",
+        meaning: "run a saved search, or an earlier run by its id",
+    },
+    {
+        name: "--selection",
+        value: "<json>",
+        role: "target",
+        type: "string",
+        meaning: "the resolved ranking selection a drilldown returned",
+    },
+    {
+        name: "--add",
+        value: "<chat>",
+        role: "value",
+        type: "id",
+        meaning: "put this chat into the set being changed; repeat it for more",
+    },
+    { name: "--all-can-pin", value: "<on|off>", role: "value", type: "choice", meaning: "every member may pin messages" },
+    { name: "--anonymous", role: "value", type: "switch", meaning: "nobody sees who voted for what" },
+    {
+        name: "--approval",
+        role: "value",
+        type: "switch",
+        meaning: "who joins by the link asks first, and an admin lets them in",
+    },
+    { name: "--can", value: "<rights>", role: "value", type: "list", meaning: "what an admin may do, comma-separated" },
+    { name: "--channel", role: "value", type: "switch", meaning: "a channel instead of a group" },
+    {
+        name: "--closed",
+        value: "<on|off>",
+        role: "value",
+        type: "choice",
+        meaning: "close it to new messages, or reopen it",
+    },
+    { name: "--comment-to", value: "<post>", role: "value", type: "id", meaning: "comment on this channel post" },
+    { name: "--description", value: "<text>", role: "value", type: "string", meaning: "the new description" },
+    { name: "--expire-time", value: "<time>", role: "value", type: "time", meaning: "it stops working at this time" },
+    { name: "--first-name", value: "<name>", role: "value", type: "string", meaning: "the account's first name" },
+    { name: "--hidden", value: "<on|off>", role: "value", type: "choice", meaning: "hide it from the list, or show it" },
+    { name: "--last-name", value: "<name>", role: "value", type: "string", meaning: "the account's last name" },
+    {
+        name: "--max-uses",
+        value: "<n>",
+        role: "value",
+        type: "count",
+        meaning: "at most this many people join by it",
+        unit: "people",
+    },
+    {
+        name: "--members-see-link",
+        value: "<on|off>",
+        role: "value",
+        type: "choice",
+        meaning: "members may see the invite link",
+    },
+    { name: "--multiple", role: "value", type: "switch", meaning: "people may pick several answers" },
+    {
+        name: "--only-admins-add",
+        value: "<on|off>",
+        role: "value",
+        type: "choice",
+        meaning: "only admins may add members",
+    },
+    {
+        name: "--only-admins-call",
+        value: "<on|off>",
+        role: "value",
+        type: "choice",
+        meaning: "only admins may start a call",
+    },
+    {
+        name: "--only-owner-edits-info",
+        value: "<on|off>",
+        role: "value",
+        type: "choice",
+        meaning: "only the owner may change the name and photo",
+    },
+    {
+        name: "--photo",
+        value: "<file>",
+        role: "value",
+        type: "path",
+        meaning: "an image file: a profile or chat photo, or a photo to send",
+    },
+    {
+        name: "--pinned",
+        value: "<on|off>",
+        role: "value",
+        type: "choice",
+        meaning: "pin it at the top of the list, or unpin it",
+    },
+    {
+        name: "--remove",
+        value: "<chat>",
+        role: "value",
+        type: "id",
+        meaning: "take this chat out of the set being changed; repeat it for more",
+    },
+    {
+        name: "--reply-to",
+        value: "<message>",
+        role: "value",
+        type: "id",
+        meaning: "answer this message in the same chat",
+    },
+    { name: "--revote", role: "value", type: "switch", meaning: "people may change their vote" },
+    { name: "--send-as", value: "<id>", role: "value", type: "id", meaning: "send as this identity of the chat" },
+    {
+        name: "--voice",
+        value: "<file>",
+        role: "value",
+        type: "path",
+        meaning: "an Ogg Opus file sent as a voice message",
+    },
+    {
+        name: "--filter",
+        value: "<query>",
+        role: "query",
+        type: "string",
+        meaning: "a query every result must also match, beside the search's own words",
+    },
 ];
 /** The words every CLI on cli-base is judged against. Seeded from STANDARD's command-name rules and the glossary. */
 export const VOCABULARY = defineVocabulary({