@starlove/orbit 1.4.0 → 2.0.0

package/lib/commands/index.js

@@ -0,0 +1,298 @@
+/**
+ * The command language: one grammar table (COMMANDS) that the CLI, both MCP
+ * tools (`orbit_read`, `orbit_write`) and `POST /api/cmd` all run, and from
+ * which help, the MCP tool descriptions and `/llms.txt` are written.
+ *
+ * Whether a line reads or writes is decided from its parsed words, before it
+ * runs, so no option can move a write past `orbit_read`'s check.
+ */
+import { OrbitError } from "../core/errors.js";
+import { asText } from "../core/text.js";
+import { CommandError, fail, noMoreWords, parseArgs, parseCardRef, tokenizeMarked } from "./parse.js";
+import { oneLine } from "./present.js";
+import { hint, setsComputerDefault } from "./session.js";
+import { BOARDS_USAGE, TEXT_TWICE_MESSAGE, agentLines, cmdArchive, cmdAsk, cmdBoards, cmdCard, cmdChanges, cmdEdit, cmdFind, cmdFinish, cmdJournal, cmdLink, cmdMove, cmdNew, cmdNote, cmdRestore, cmdTake, cmdUnlink, cmdView } from "./verbs.js";
+export { createSession, repoBoardFromRequest } from "./session.js";
+export { cardLink, parseCardRef, shellSafe, tokenize } from "./parse.js";
+export { agentLines } from "./verbs.js";
+/** Where `new` puts a card when no lane is given (createTicket's default lane). */
+const NEW_LANE = "With no --lane the card goes to Todo (or the lane a person chose for new cards).";
+/** What `help boards` adds: which board a command uses, and how a repo names its own. */
+const BOARDS_HELP = {
+    cli: [
+        "A command uses the board it names, else ORBIT_BOARD, else this repo's orbit.json, else this computer's default (orbit boards use), else the only board.",
+        'orbit boards link <board> writes { "board": "<board>" } to the nearest orbit.json in this repo, or a new one at its top; other branches and clones see it once it is committed and reaches the main branch. orbit boards unlink takes it out.'
+    ],
+    mcp: [
+        "A command uses the board it names, else this session's (view <board>), else the repo's orbit.json, else this computer's default, else the only board.",
+        "boards link <board> says how a repo names its board in orbit.json; Orbit writes no files from here."
+    ]
+};
+function cmdHelp(session, args) {
+    const { positional } = args;
+    noMoreWords(args, 1, "help [command]");
+    const shell = session.transport === "cli";
+    const say = (line) => hint(session, line);
+    const named = positional[0];
+    if (named) {
+        const command = BY_NAME.get(named.toLowerCase());
+        if (!command)
+            fail(unknownCommand(named));
+        const usage = shell ? say(command.usage).replaceAll(` | ${command.name}`, ` | orbit ${command.name}`) : command.usage;
+        const lines = [usage, command.summary];
+        if (command.aliases.length)
+            lines.push(`Also: ${command.aliases.join(", ")}.`);
+        const field = shell ? '-m "..."' : "the text field";
+        if (command.name === "new") {
+            lines.push(`Every word before the options is the title; the description goes in ${field}.`);
+            lines.push(NEW_LANE);
+        }
+        else if (command.name === "edit")
+            lines.push(`Text: ${field} replaces the description (or the field flagged).`);
+        else if (command.text)
+            lines.push(`Text: ${field} (or the words after the card).`);
+        else {
+            if (command.name === "boards")
+                lines.push(...BOARDS_HELP[shell ? "cli" : "mcp"]);
+            if (command.name === "take")
+                lines.push(`Name the card (${say("take #12")}) to take that one. With no card named it takes the top card in AI Ready at once (highest priority, then oldest; blocked cards and epics wait).`);
+            lines.push("Takes no text.");
+        }
+        return Promise.resolve({ text: lines.join("\n"), data: { command: command.name, usage: command.usage, summary: command.summary, aliases: command.aliases, kind: command.kind } });
+    }
+    const listed = COMMANDS.filter((c) => c.name !== "boards");
+    const lines = [
+        // A shell's overview (src/cli/main.ts) puts these above its Start section.
+        ...(shell ? [] : [...agentLines(session), ""]),
+        "Boards:",
+        `  ${say("boards")}: list boards; * marks the one commands use`,
+        `  ${say("boards new <name> [--slug s]")}: make a board`,
+        shell ? `  ${say("boards link <board>")}: this repo's board, named in its orbit.json (commit it)` : "  boards link <board>: how a repo names its board (orbit.json)",
+        shell ? `  ${say("boards use <board>")}: the default board for every folder on this computer` : "  boards use <board>: choose one for this session",
+        `  With several boards and no default, name one: ${shell ? "orbit view garden, orbit card garden#12" : "view garden (kept for this session), garden#12"}, or --board garden.`,
+        "",
+        shell ? "Cards are numbers: orbit card 12 (in a shell #12 starts a comment; garden#12 works). Lanes by name." : "Cards are #n (or board#n); lanes by name.",
+        "Lanes: Backlog someday, Todo next, AI Ready for an agent, In Progress being worked, Review for a person to check, Done and Cancelled closed.",
+        `${say("new")} puts a card in Todo when no --lane is given (or in the lane a person chose for new cards).`,
+        "AI Ready holds cards an agent may take: each says its goal and when it's done.",
+        "Priorities are words: urgent, high, med, low, maybe (med is the default; view leaves it unsaid).",
+        shell ? 'Long text goes in -m "...". Add --json for structured output.' : "Long text goes in the text field. Add --json for structured output.",
+        "Read:"
+    ];
+    for (const command of listed.filter((c) => c.kind === "read"))
+        lines.push(`  ${say(command.usage)}: ${command.summary}`);
+    lines.push("Write:");
+    for (const command of listed.filter((c) => c.kind !== "read"))
+        lines.push(`  ${say(command.usage)}: ${command.summary}`);
+    lines.push(shell ? 'Work loop: orbit take -> work -> orbit finish 12 -m "...". Unclear? orbit ask 12 -m "...", then stop.' : "Work loop: take -> work -> finish #n. Unclear? ask #n, then stop.");
+    return Promise.resolve({
+        text: lines.join("\n"),
+        data: { commands: COMMANDS.map((c) => ({ name: c.name, usage: c.usage, summary: c.summary, kind: typeof c.kind === "string" ? c.kind : "read" })) }
+    });
+}
+/** Edit distance, for "did you mean". */
+function distance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i += 1) {
+        let prev = row[0] ?? 0;
+        row[0] = i;
+        for (let j = 1; j <= b.length; j += 1) {
+            const next = Math.min((row[j] ?? 0) + 1, (row[j - 1] ?? 0) + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+            prev = row[j] ?? 0;
+            row[j] = next;
+        }
+    }
+    return row[b.length] ?? 0;
+}
+function unknownCommand(verb) {
+    const word = verb.toLowerCase();
+    const best = [...BY_NAME.keys()].map((name) => [name, distance(word, name)]).sort((x, y) => x[1] - y[1])[0];
+    const guess = best && best[1] <= 2 ? ` Did you mean ${BY_NAME.get(best[0])?.name ?? best[0]}?` : "";
+    return `Unknown command "${oneLine(verb, 40)}".${guess} Commands: ${COMMANDS.map((c) => c.name).join(", ")}.`;
+}
+const LINKS = ["use", "link", "unlink"];
+export const COMMANDS = [
+    { name: "view", brief: "view [board] [--all] [--lane L]", aliases: ["board", "ls", "list"], kind: "read", usage: "view [board] [--all] [--lane L]", summary: "the board: lanes in order, one line per open card", flags: { all: "bool", lane: "value" }, run: cmdView },
+    { name: "card", brief: "card #n [--comments]", aliases: ["show", "read", "open"], kind: "read", usage: "card #n [--comments]", summary: "one card: its facts, links and text; --comments for the discussion", flags: { comments: "bool" }, run: cmdCard },
+    { name: "journal", brief: "journal (rules, decisions)", aliases: ["rules", "decisions"], kind: "read", usage: "journal [board]", summary: "the board's rules for agents, and its journal of decisions and lessons", run: cmdJournal },
+    { name: "find", brief: "find <words>", aliases: ["search"], kind: "read", usage: "find <words>", summary: "cards matching words, one line each", run: cmdFind },
+    { name: "changes", brief: "changes [--since 2h]", aliases: ["log", "history"], kind: "read", usage: "changes [--since 2h]", summary: "what happened on the board lately (default: the last 24h)", flags: { since: "value" }, run: cmdChanges },
+    {
+        name: "boards",
+        briefs: { read: "boards; boards use <board>", write: "boards new <name>" },
+        aliases: [],
+        // A listing reads; so do `use`, `link` and `unlink`, except in a shell on
+        // this computer, where `use` saves the default board and `link` writes the
+        // repo's orbit.json.
+        kind: (positional, session) => {
+            const sub = positional[0];
+            if (sub === undefined)
+                return "read";
+            if (LINKS.includes(sub))
+                return setsComputerDefault(session) && (sub === "use" || session.repo?.link) ? "write" : "read";
+            return "write";
+        },
+        label: (positional) => (LINKS.includes(positional[0] ?? "") ? `boards ${positional[0] ?? ""}` : "boards new"),
+        // Anything but `boards new`, `use`, `link` or `unlink` that isn't a listing is a mistake; say how boards works.
+        readOnlyText: (positional) => (["new", ...LINKS].includes(positional[0] ?? "") ? null : `boards takes: ${BOARDS_USAGE}.`),
+        usage: BOARDS_USAGE,
+        summary: "list boards; create one; choose one (in a terminal, the default for every folder on this computer); link: the repo names its board in orbit.json",
+        flags: { slug: "value", "no-ai": "bool" },
+        run: cmdBoards
+    },
+    { name: "help", brief: "help [command]", aliases: ["?"], kind: "read", usage: "help [command]", summary: "this list, or one command", run: cmdHelp },
+    {
+        name: "take",
+        brief: "take [#n]",
+        aliases: ["claim", "start"],
+        kind: "write",
+        usage: "take [#n] [--force]",
+        summary: "claim a card (with no card named: the next AI Ready card); returns it with the board's rules and next steps",
+        flags: { force: "bool", type: "value" },
+        run: cmdTake
+    },
+    { name: "move", brief: "move #n <lane>", aliases: ["mv"], kind: "write", usage: "move #n <lane>", summary: "move a card to a lane, named any way you like", run: cmdMove },
+    {
+        name: "new",
+        text: true,
+        brief: "new <title> [--lane L] [--type bug] [--priority high] [--label a,b] [--parent #n] (text: description)",
+        aliases: ["create", "add"],
+        kind: "write",
+        usage: "new <title> [--lane L] [--type bug] [--priority high] [--label a,b] [--parent #n]",
+        summary: "create a card; its description as text",
+        flags: { lane: "value", type: "value", priority: "value", label: "list", parent: "value" },
+        run: cmdNew
+    },
+    {
+        name: "edit",
+        text: true,
+        brief: "edit #n [--title T] [--priority P] [--label a,b] [--parent #n] (text: description, or --plan)",
+        aliases: ["update", "set"],
+        kind: "write",
+        usage: "edit #n [--title T] [--priority P] [--label a,b] [--add-label x] [--drop-label x] [--type T] [--parent #n|none] [--nebula URL|none] [--plan|--summary|--revisions]",
+        summary: "change a card's fields; text replaces its description (or the field flagged)",
+        flags: { title: "value", type: "value", priority: "value", label: "list", "add-label": "list", "drop-label": "list", parent: "value", nebula: "value", plan: "bool", summary: "bool", revisions: "bool" },
+        run: cmdEdit
+    },
+    {
+        name: "note",
+        text: true,
+        brief: "note #n (text); note --decision|--lesson <title> (journal)",
+        aliases: ["comment"],
+        kind: "write",
+        usage: "note #n | note [#n] --decision|--lesson <title>",
+        summary: "a comment on a card (text), or a decision or lesson for the board's journal",
+        flags: { decision: "bool", lesson: "bool" },
+        run: cmdNote
+    },
+    { name: "ask", text: true, brief: "ask #n", aliases: ["checkpoint"], kind: "write", usage: "ask #n", summary: 'the goal or "done" is unclear: post what\'s missing (text) and hand the card to a person, then stop', run: cmdAsk },
+    {
+        name: "finish",
+        text: true,
+        brief: "finish #n [--pr URL]",
+        aliases: ["complete"],
+        kind: "write",
+        usage: "finish #n [--pr URL] [--lane L]",
+        summary: "done working: the summary (text) of what changed and how you checked; moves the card to Review",
+        flags: { pr: "value", lane: "value" },
+        run: cmdFinish
+    },
+    { name: "link", brief: "link #a blocks|blocked-by|relates #b; unlink #a #b", aliases: [], kind: "write", usage: "link #a blocks|blocked-by|relates #b", summary: "say one card blocks (or relates to) another", run: cmdLink },
+    { name: "unlink", brief: null, aliases: [], kind: "write", usage: "unlink #a #b", summary: "remove the links between two cards", run: cmdUnlink },
+    { name: "archive", brief: "archive #n; restore #n", aliases: [], kind: "write", usage: "archive #n", summary: "put a card away (restore brings it back)", run: cmdArchive },
+    { name: "restore", brief: null, aliases: [], kind: "write", usage: "restore #n", summary: "bring an archived card back", run: cmdRestore }
+];
+const BY_NAME = new Map();
+for (const command of COMMANDS) {
+    BY_NAME.set(command.name, command);
+    for (const alias of command.aliases)
+        BY_NAME.set(alias, command);
+}
+/** `help` (or `help <command>`) for an actor and transport, without a data folder: it reads no board. */
+export async function helpText(actor, transport, words = []) {
+    try {
+        const args = parseArgs(words, {}, "help [command]", [], transport === "cli");
+        return { ok: true, text: (await cmdHelp({ actor, transport }, args)).text };
+    }
+    catch (error) {
+        return { ok: false, text: explain(error) };
+    }
+}
+/** A command by name or alias. */
+export function commandNamed(word) {
+    return BY_NAME.get(word.toLowerCase());
+}
+/** Refusals whose message says the way out (and carries no path), shown as they are. */
+const SAYS_WHAT_TO_DO = new Set(["board_file_missing", "board_files_busy"]);
+/** Core errors are codes (invalid_state); say what they mean. A database's own message is never shown. */
+function explain(error) {
+    if (error instanceof CommandError)
+        return error.message;
+    if (error instanceof OrbitError && SAYS_WHAT_TO_DO.has(error.code) && error.message !== error.code)
+        return error.message;
+    if (error instanceof OrbitError)
+        return `Orbit refused: ${error.code.replace(/_/g, " ")}.`;
+    return "Orbit refused: internal error.";
+}
+/**
+ * Runs one command line. Never throws for a mistake in the line: that comes
+ * back as ok false with a text that says how to put it right.
+ */
+export async function runCommand(input, session) {
+    let words;
+    let marks;
+    try {
+        if (Array.isArray(input.argv)) {
+            // An argv array (a shell, or HTTP) marks its own word boundaries.
+            words = input.argv.map((word) => asText(word));
+            marks = words.map(() => ({ quoted: false, hadQuote: false }));
+        }
+        else {
+            const tokens = tokenizeMarked(input.command ?? input.line ?? "");
+            words = tokens.map((token) => token.text);
+            marks = tokens.map(({ quoted, hadQuote, lost }) => ({ quoted, hadQuote, lost }));
+        }
+    }
+    catch (error) {
+        return { ok: false, text: explain(error), data: null, board: session.board, kind: "read" };
+    }
+    const [verb = "help", ...rest] = words;
+    const command = BY_NAME.get(verb.toLowerCase());
+    if (!command)
+        return { ok: false, text: unknownCommand(verb), data: null, board: session.board, kind: "read" };
+    const staticKind = typeof command.kind === "function" ? "write" : command.kind;
+    let args;
+    try {
+        args = parseArgs(rest, command.flags ?? {}, command.usage, marks.slice(1), session.transport === "cli");
+    }
+    catch (error) {
+        return { ok: false, text: explain(error), data: null, board: session.board, kind: staticKind };
+    }
+    const kind = typeof command.kind === "function" ? command.kind(args.positional, session) : command.kind;
+    if (input.readOnly && kind !== "read") {
+        const refusal = command.readOnlyText?.(args.positional);
+        return { ok: false, text: refusal ?? `${command.label ? command.label(args.positional) : command.name} changes the board; send it with orbit_write.`, data: null, board: session.board, kind };
+    }
+    try {
+        const text = asText(input.text);
+        if (text !== "") {
+            if (args.flags.text !== undefined)
+                fail(TEXT_TWICE_MESSAGE);
+            args.flags.text = text;
+        }
+        if (args.flags.text !== undefined && !command.text) {
+            const card = parseCardRef(args.positional[0]);
+            const keep = card ? ` To keep it, add it as a note: \`${hint(session, `note #${card.n}`)}\` with the text.` : "";
+            fail(`${command.name} takes no text.${keep}`);
+        }
+        const json = Boolean(input.json) || args.flags.json === true;
+        const result = await command.run(session, args);
+        // Only a write that went through marks its board active; reads change nothing at all.
+        if (kind === "write" && result.board)
+            await session.c.store.boards.touch(result.board.board.id, session.c.clock.now());
+        return { ok: true, text: json ? JSON.stringify(result.data ?? null) : result.text, data: result.data ?? null, board: session.board, kind };
+    }
+    catch (error) {
+        return { ok: false, text: explain(error), data: null, board: session.board, kind };
+    }
+}

package/lib/commands/parse.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Reading a command line: shell-like words, then options and the other words,
+ * with the guards that keep every word where its writer meant it. A command
+ * has a shape (a few fixed words, then at most one free run); extra words, a
+ * run split by an option, or an unquoted value that may have spaces followed
+ * by loose words are refused, never dropped or moved.
+ */
+/** A command's problem, said so the next call can be right. */
+export declare class CommandError extends Error {
+    constructor(message: string);
+}
+export declare function fail(message: string): never;
+/** A command line as a shell takes it: `card #n` -> `card 12`, `link #a ... #b` -> `link 12 ... 13`. */
+export declare function shellSafe(line: string): string;
+/** How a usage is written where the command came from: `orbit card 12` in a shell. */
+export declare function usageText(shell: boolean, usage: string): string;
+/** A word and how it was written. */
+export interface Mark {
+    /** It starts with a quote, so it is a word, never an option. */
+    quoted: boolean;
+    /** Some part of it was quoted, so its end was marked by hand. */
+    hadQuote: boolean;
+    /** The tokenizer ate a character the writer likely meant (a quote inside a word, `C:\new`). */
+    lost?: boolean;
+}
+/** Shell-like words: whitespace splits, quotes group, backslash escapes. */
+export declare function tokenizeMarked(line: string): {
+    text: string;
+    quoted: boolean;
+    hadQuote: boolean;
+    lost: boolean;
+}[];
+export declare function tokenize(line: string): string[];
+export type FlagKind = "value" | "bool" | "text" | "list";
+export declare const TEXT_TWICE = "Text given twice: as -m/--text (or the text field) and as words on the line. Send it once: quote it, or put it all in text.";
+export type FlagValue = string | boolean | string[];
+/** A word that wasn't an option, and where it sat: its run (an option ends a run), its place, and the option just before it. */
+export interface Place {
+    run: number;
+    index: number;
+    after: {
+        word: string;
+        value?: string;
+        end: number;
+    } | null;
+    lost: boolean;
+    quoted: boolean;
+}
+export interface Args {
+    flags: Record<string, FlagValue | undefined>;
+    positional: string[];
+    at: Place[];
+    words: string[];
+    /** Whether usages are written for a shell. */
+    shell: boolean;
+}
+/** The value of an option as a string, when it is one. */
+export declare function flagString(args: Args, name: string): string | undefined;
+export declare function flagList(args: Args, name: string): string[] | undefined;
+export declare function flagOn(args: Args, name: string): boolean;
+/** Options and the other words. */
+export declare function parseArgs(words: string[], spec: Record<string, FlagKind>, usage: string, marks: Mark[], shell: boolean): Args;
+/** Words past the first `max` are refused, never dropped. */
+export declare function noMoreWords(args: Args, max: number, usage: string, help?: string): void;
+/** The words from `from` on, as one run: an option in the middle means they weren't meant as one. */
+export declare function freeWords(args: Args, from: number, what: string): string[];
+/** A card reference: `#12`, `12`, `board#12`, or the link Nebula and the Suite use, `orbit:card/<board>/<n>` (also inside `[[...|label]]`). */
+export declare function parseCardRef(word: string | undefined): {
+    board: string | null;
+    n: number;
+} | null;
+/** The link that names a card everywhere: `orbit:card/<board>/<n>`. */
+export declare function cardLink(slug: string, n: number): string;

package/lib/commands/parse.js

@@ -0,0 +1,231 @@
+/**
+ * Reading a command line: shell-like words, then options and the other words,
+ * with the guards that keep every word where its writer meant it. A command
+ * has a shape (a few fixed words, then at most one free run); extra words, a
+ * run split by an option, or an unquoted value that may have spaces followed
+ * by loose words are refused, never dropped or moved.
+ */
+import { oneLine } from "./present.js";
+/** A command's problem, said so the next call can be right. */
+export class CommandError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CommandError";
+    }
+}
+export function fail(message) {
+    throw new CommandError(message);
+}
+/** A command line as a shell takes it: `card #n` -> `card 12`, `link #a ... #b` -> `link 12 ... 13`. */
+export function shellSafe(line) {
+    const refs = { n: "12", a: "12", b: "13" };
+    return line.replace(/(^|[\s([|`])#(n|a|b|\d+)\b/g, (_, before, ref) => `${before}${refs[ref] ?? ref}`);
+}
+/** How a usage is written where the command came from: `orbit card 12` in a shell. */
+export function usageText(shell, usage) {
+    return shell ? `orbit ${shellSafe(usage)}` : usage;
+}
+/** Shell-like words: whitespace splits, quotes group, backslash escapes. */
+export function tokenizeMarked(line) {
+    const tokens = [];
+    let word = "";
+    let quote = null;
+    let started = false;
+    let quoted = false;
+    let hadQuote = false;
+    let lost = false;
+    const push = () => {
+        tokens.push({ text: word, quoted, hadQuote, lost: lost || (hadQuote && !quoted) });
+    };
+    for (let i = 0; i < line.length; i += 1) {
+        const ch = line.charAt(i);
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+            else if (ch === "\\" && quote === '"' && i + 1 < line.length)
+                word += line.charAt(++i);
+            else
+                word += ch;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            if (!started)
+                quoted = true;
+            quote = ch;
+            hadQuote = true;
+            started = true;
+        }
+        else if (ch === "\\" && i + 1 < line.length) {
+            const next = line.charAt(++i);
+            if (!/["'\\\s]/.test(next))
+                lost = true;
+            word += next;
+            started = true;
+        }
+        else if (/\s/.test(ch)) {
+            if (started)
+                push();
+            word = "";
+            started = false;
+            quoted = false;
+            hadQuote = false;
+            lost = false;
+        }
+        else {
+            word += ch;
+            started = true;
+        }
+    }
+    if (quote)
+        fail(`Unclosed ${quote} quote in: ${oneLine(line, 120)}`);
+    if (started)
+        push();
+    return tokens;
+}
+export function tokenize(line) {
+    return tokenizeMarked(line).map((token) => token.text);
+}
+/** Options every command takes. */
+const GLOBAL_FLAGS = { board: "value", json: "bool", m: "text", message: "text", text: "text" };
+/** Options whose values often have spaces. Unquoted and followed by more words, Orbit can't tell where the value ends, so it asks. */
+const SPACED_VALUES = {
+    lane: '--lane "AI Ready"',
+    label: '--label "ui, backend"',
+    "add-label": '--add-label "needs review"',
+    "drop-label": '--drop-label "needs review"',
+    title: '--title "Fix login bug"',
+    m: '-m "..."',
+    message: '--message "..."',
+    text: '--text "..."',
+    since: "--since 2h"
+};
+export const TEXT_TWICE = "Text given twice: as -m/--text (or the text field) and as words on the line. Send it once: quote it, or put it all in text.";
+/** The value of an option as a string, when it is one. */
+export function flagString(args, name) {
+    const value = args.flags[name];
+    return typeof value === "string" ? value : undefined;
+}
+export function flagList(args, name) {
+    const value = args.flags[name];
+    return Array.isArray(value) ? value : undefined;
+}
+export function flagOn(args, name) {
+    return args.flags[name] === true;
+}
+/** Options and the other words. */
+export function parseArgs(words, spec, usage, marks, shell) {
+    const flags = {};
+    const positional = [];
+    const at = [];
+    let run = 0;
+    let lastFlag = null;
+    const allowed = { ...GLOBAL_FLAGS, ...spec };
+    const optionAt = (j) => {
+        const word = words[j];
+        return word !== undefined && !marks[j]?.quoted && !/^-\d/.test(word) && /^--?[a-z][a-z-]*(=.*)?$/i.test(word);
+    };
+    for (let i = 0; i < words.length; i += 1) {
+        const word = words[i] ?? "";
+        const match = /^--?([a-z][a-z-]*)(?:=(.*))?$/i.exec(word);
+        if (!match || /^-\d/.test(word) || marks[i]?.quoted) {
+            positional.push(word);
+            at.push({ run, index: i, after: lastFlag, lost: Boolean(marks[i]?.lost), quoted: Boolean(marks[i]?.quoted) });
+            continue;
+        }
+        run += 1;
+        const name = (match[1] ?? "").toLowerCase();
+        const kind = allowed[name];
+        if (!kind) {
+            const names = Object.keys(spec).map((flag) => `--${flag}`);
+            fail(`Unknown option ${word}. Usage: ${usageText(shell, usage)}${names.length ? ` (options: ${names.join(", ")})` : ""}`);
+        }
+        const inlineValue = match[2];
+        const flagWord = inlineValue !== undefined ? word.slice(0, word.indexOf("=")) : word;
+        if (kind === "bool") {
+            flags[name] = inlineValue === undefined ? true : !/^(0|false|no)$/i.test(inlineValue);
+            lastFlag = { word: flagWord, end: i };
+            continue;
+        }
+        if (inlineValue === undefined && optionAt(i + 1))
+            fail(`${flagWord} needs a value. Usage: ${usageText(shell, usage)}`);
+        const value = inlineValue ?? words[++i];
+        if (value === undefined)
+            fail(`${flagWord} needs a value. Usage: ${usageText(shell, usage)}`);
+        if (kind === "value" && !value.trim())
+            fail(name === "title" ? "A card needs a title." : `${flagWord} needs a value. Usage: ${usageText(shell, usage)}`);
+        lastFlag = { word: flagWord, value, end: i };
+        // The value's end is clear when it was quoted, has a space (an argv word), is a whole time, or the next word was quoted.
+        const marked = Boolean(marks[i]?.hadQuote) || /\s/.test(value) || (name === "since" && /^\d+\s*(m|min|h|d|w)$/i.test(value)) || Boolean(marks[i + 1]?.quoted) || /\s/.test(words[i + 1] ?? "");
+        const example = SPACED_VALUES[name];
+        if (example && !marked && i + 1 < words.length && !optionAt(i + 1)) {
+            let j = i + 1;
+            const loose = [];
+            while (j < words.length && !optionAt(j))
+                loose.push(words[j++] ?? "");
+            const shown = example.replace(/^--?[a-z-]+/, flagWord);
+            const how = name === "since" ? `Write the time as one word (${shown})` : `Quote a value with spaces (${shown})`;
+            fail(`"${oneLine(loose.join(" "), 80)}" follows ${flagWord} ${oneLine(value, 40)}, so Orbit can't tell where its value ends. ${how}, or put options after the other words.`);
+        }
+        if (kind === "list") {
+            const before = flags[name];
+            flags[name] = [...(Array.isArray(before) ? before : []), ...value.split(",").map((v) => v.trim()).filter(Boolean)];
+        }
+        else if (kind === "text") {
+            if (flags.text !== undefined)
+                fail(TEXT_TWICE);
+            flags.text = value;
+        }
+        else {
+            flags[name] = value;
+        }
+    }
+    return { flags, positional, at, words, shell };
+}
+/** Words past the first `max` are refused, never dropped. */
+export function noMoreWords(args, max, usage, help = "") {
+    if (args.positional.length <= max)
+        return;
+    const extra = args.positional.slice(max).join(" ");
+    const first = args.at[max];
+    const flag = first?.after;
+    const tail = help ? ` ${help}` : "";
+    if (first && flag?.value !== undefined && first.index === flag.end + 1) {
+        const run = args.positional.slice(max).filter((_, i) => args.at[max + i]?.run === first.run).join(" ");
+        fail(`"${oneLine(extra, 80)}" follows ${flag.word} ${oneLine(flag.value, 40)}. If they belong to it, quote it: ${flag.word} ${JSON.stringify(oneLine(`${flag.value} ${run}`, 120))}.${tail}`);
+    }
+    fail(`Unexpected words "${oneLine(extra, 80)}". Usage: ${usageText(args.shell, usage)}${tail}`);
+}
+/** The words from `from` on, as one run: an option in the middle means they weren't meant as one. */
+export function freeWords(args, from, what) {
+    const at = args.at.slice(from);
+    // A quoted word groups only when it is the whole run; inside longer words its quotes would vanish.
+    if (at.some((place) => place.lost || (place.quoted && at.length > 1))) {
+        const how = what === "text" ? 'Send the text as text (-m "..." in a shell)' : `Quote the whole ${what}`;
+        fail(`Quotes or backslashes in the ${what} would be lost. ${how}, so every character is kept.`);
+    }
+    const first = at[0];
+    const split = at.find((place) => place.run !== first?.run);
+    if (first && split) {
+        const last = at[at.length - 1] ?? first;
+        const span = args.words.slice(first.index, last.index + 1).join(" ");
+        const flag = split.after;
+        const shown = flag ? `${flag.word}${flag.value !== undefined ? ` ${oneLine(flag.value, 40)}` : ""}` : "an option";
+        fail(`Words on both sides of ${shown}. If they're all the ${what}, quote it: ${JSON.stringify(oneLine(span, 160))}. Otherwise put options after the ${what}.`);
+    }
+    return args.positional.slice(from);
+}
+/** A card reference: `#12`, `12`, `board#12`, or the link Nebula and the Suite use, `orbit:card/<board>/<n>` (also inside `[[...|label]]`). */
+export function parseCardRef(word) {
+    const text = (word ?? "").trim().replace(/^\[\[/, "").replace(/(\|[^\]]*)?\]\]$/, "");
+    let match = /^orbit:card\/([^/\s]+)\/#?(\d+)$/i.exec(text);
+    if (match)
+        return { board: match[1] ?? null, n: Number(match[2]) };
+    match = /^(?:([a-z0-9][a-z0-9._-]*)#|#)?(\d+)$/i.exec(text);
+    if (match)
+        return { board: match[1] ?? null, n: Number(match[2]) };
+    return null;
+}
+/** The link that names a card everywhere: `orbit:card/<board>/<n>`. */
+export function cardLink(slug, n) {
+    return `orbit:card/${slug}/${n}`;
+}