@starlove/orbit 1.4.1 → 2.0.0

package/lib/commands/present.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The command language's answers: compact, line by line, cards as #n, lanes
+ * by name, no ids. Pure functions over plain models, so every transport (the
+ * CLI, MCP, HTTP) prints the same thing. These formats are a public contract,
+ * with size budgets.
+ *
+ * What people wrote can't pass for Orbit's own words: a title is quoted
+ * wherever more of the line follows it; names and labels are folded to one
+ * line; multi-line text sits indented under its heading, so every line that
+ * starts at the left edge is Orbit's.
+ */
+import { laneText, oneLine } from "../core/describe.ts";
+import type { Priority } from "../core/model.ts";
+export { laneText, oneLine };
+/** Orbit stores priority 0 to 4; people and agents see the app's words. */
+export declare const PRIORITY_WORDS: Readonly<Record<number, string>>;
+/** Who wrote something, for an agent: "a person" for someone in the app, else the agent's name, on one line. */
+export declare function authorText(name: unknown): string;
+/** The same, as a token for --json: "person" for someone in the app, else the agent's name. */
+export declare function authorKey(name: unknown): string;
+export declare function plural(count: number, one: string, many?: string): string;
+export declare function priorityWord(priority: number): string;
+/** "3h", "2d": how long ago, or "" under an hour (fresh is the default). */
+export declare function age(iso: string | null | undefined, nowMs?: number): string;
+/** A title inside a line: quoted, so nothing in it reads as the line's own markers. `max` counts the quoted form. */
+export declare function quoted(title: unknown, max?: number): string;
+export interface CardHolder {
+    name: string;
+    since: string;
+}
+/** A card as a view lists it. */
+export interface CardLine {
+    n: number;
+    title: string;
+    type: string;
+    priority: Priority;
+    labels: string[];
+    parent: number | null;
+    sub: number;
+    /** Card numbers on this board; `slug#n` for a card on another board. */
+    blockedBy: (number | string)[];
+    holder: CardHolder | null;
+    comments: number;
+}
+/** `#3 bug high "Title" [labels] ^#1 (2 sub) blocked by #2 @crea 3h 1c` */
+export declare function cardLine(card: CardLine, { nowMs }?: {
+    nowMs?: number;
+}): string;
+export interface ViewLane {
+    name: string;
+    role: string | null;
+    closed: boolean;
+    cards: (CardLine & {
+        id: string;
+    })[];
+}
+export interface ViewModel {
+    slug: string;
+    name: string;
+    open: number;
+    hasRules: boolean;
+    journalCount: number;
+    lanes: ViewLane[];
+}
+/** The board: open lanes list their cards (up to `cap` each); closed lanes (Done, Cancelled) show as counts unless `all`. */
+export declare function renderView(model: ViewModel, options?: {
+    all?: boolean;
+    lane?: string | null;
+    cap?: number;
+    hint?: (line: string) => string;
+    nowMs?: number;
+    shell?: boolean;
+}): string;
+export interface CardBrief {
+    n: number;
+    title: string;
+    lane?: string | undefined;
+    /** Set for a card on another board than the one in view: its slug. */
+    board?: string | undefined;
+}
+/** A short reference to another card: `#2 "Trello import" (Todo)`. */
+export declare function cardRef(card: CardBrief, { lane }?: {
+    lane?: boolean;
+}): string;
+/**
+ * Multi-line text, each line indented under its heading. Every way of
+ * breaking a line becomes a real line break (and so gets the indent), and
+ * other control characters are dropped.
+ */
+export declare function block(text: unknown, indent?: string): string;
+/** `Label: text` when the text is one line, else the label alone with the text indented under it. */
+export declare function labelled(label: string, text: unknown): string;
+export interface CommentLine {
+    author: string;
+    kind: string;
+    body: string;
+    at: string;
+}
+export declare function renderComments(comments: CommentLine[], { limit }?: {
+    limit?: number;
+}): string;
+export interface CardModel {
+    n: number;
+    title: string;
+    type: string;
+    priority: number;
+    lane: string;
+    archived: boolean;
+    labels: string[];
+    author: string;
+    holder: {
+        name: string;
+        id: string | null;
+        since: string;
+    } | null;
+    link: string;
+    parent: CardBrief | null;
+    children: CardBrief[];
+    blockedBy: CardBrief[];
+    blocks: CardBrief[];
+    related: CardBrief[];
+    description: string;
+    plan: string;
+    summary: string;
+    revisions: string;
+    nebula: string;
+    commentCount: number;
+}
+/** One card: title, a facts line (type · priority · lane · labels · author · link), its links, then its text. */
+export declare function renderCard(card: CardModel, options?: {
+    comments?: CommentLine[] | null;
+    hint?: (line: string) => string;
+    nowMs?: number;
+}): string;

package/lib/commands/present.js

@@ -0,0 +1,198 @@
+/**
+ * The command language's answers: compact, line by line, cards as #n, lanes
+ * by name, no ids. Pure functions over plain models, so every transport (the
+ * CLI, MCP, HTTP) prints the same thing. These formats are a public contract,
+ * with size budgets.
+ *
+ * What people wrote can't pass for Orbit's own words: a title is quoted
+ * wherever more of the line follows it; names and labels are folded to one
+ * line; multi-line text sits indented under its heading, so every line that
+ * starts at the left edge is Orbit's.
+ */
+import { laneText, oneLine } from "../core/describe.js";
+import { asText } from "../core/text.js";
+export { laneText, oneLine };
+/** Orbit stores priority 0 to 4; people and agents see the app's words. */
+export const PRIORITY_WORDS = Object.freeze({ 0: "maybe", 1: "low", 2: "med", 3: "high", 4: "urgent" });
+/** The default priority goes unsaid in a view's card line (one card's facts always say it). */
+const QUIET_PRIORITY = 2;
+/** The names Orbit stores for a person in the app (it has no accounts), as the app's actor labels know them. */
+const PERSON_NAMES = new Set(["local", "local-owner", "owner", "human"]);
+/** Who wrote something, for an agent: "a person" for someone in the app, else the agent's name, on one line. */
+export function authorText(name) {
+    const clean = oneLine(name, 40);
+    return PERSON_NAMES.has(clean.toLowerCase()) ? "a person" : clean;
+}
+/** The same, as a token for --json: "person" for someone in the app, else the agent's name. */
+export function authorKey(name) {
+    const clean = oneLine(name, 40);
+    return PERSON_NAMES.has(clean.toLowerCase()) ? "person" : clean;
+}
+export function plural(count, one, many = `${one}s`) {
+    return `${count} ${count === 1 ? one : many}`;
+}
+export function priorityWord(priority) {
+    return PRIORITY_WORDS[priority] ?? PRIORITY_WORDS[QUIET_PRIORITY] ?? "med";
+}
+/** "3h", "2d": how long ago, or "" under an hour (fresh is the default). */
+export function age(iso, nowMs = Date.now()) {
+    const then = Date.parse(iso ?? "");
+    if (!Number.isFinite(then))
+        return "";
+    const minutes = Math.floor((nowMs - then) / 60_000);
+    if (minutes < 60)
+        return "";
+    const hours = Math.floor(minutes / 60);
+    if (hours < 48)
+        return `${hours}h`;
+    return `${Math.floor(hours / 24)}d`;
+}
+/** A title inside a line: quoted, so nothing in it reads as the line's own markers. `max` counts the quoted form. */
+export function quoted(title, max = 120) {
+    const full = oneLine(title, 100_000);
+    for (let cut = Math.min(full.length, max); cut > 1; cut -= 1) {
+        const text = cut < full.length ? `${full.slice(0, cut - 1).trimEnd()}…` : full;
+        const out = JSON.stringify(text);
+        if (out.length <= max + 2)
+            return out;
+    }
+    return JSON.stringify("…");
+}
+/** A label as one bare run: no brackets or commas to close the list early. */
+function labelText(label) {
+    return oneLine(label, 40).replace(/[[\],]/g, "").trim();
+}
+/** `#3 bug high "Title" [labels] ^#1 (2 sub) blocked by #2 @crea 3h 1c` */
+export function cardLine(card, { nowMs } = {}) {
+    const parts = [`#${card.n}`];
+    if (card.type === "bug" || card.type === "epic")
+        parts.push(card.type);
+    if (card.priority !== QUIET_PRIORITY)
+        parts.push(priorityWord(card.priority));
+    parts.push(quoted(card.title));
+    if (card.labels.length)
+        parts.push(`[${card.labels.map(labelText).join(",")}]`);
+    if (card.parent)
+        parts.push(`^#${card.parent}`);
+    if (card.sub)
+        parts.push(`(${card.sub} sub)`);
+    if (card.blockedBy.length)
+        parts.push(`blocked by ${card.blockedBy.map((n) => (typeof n === "number" ? `#${n}` : n)).join(",")}`);
+    if (card.holder) {
+        const since = age(card.holder.since, nowMs);
+        parts.push(`@${oneLine(card.holder.name, 40).replace(/\s+/g, "-")}${since ? ` ${since}` : ""}`);
+    }
+    if (card.comments)
+        parts.push(`${card.comments}c`);
+    return parts.join(" ");
+}
+/** The board: open lanes list their cards (up to `cap` each); closed lanes (Done, Cancelled) show as counts unless `all`. */
+export function renderView(model, options = {}) {
+    const { all = false, lane = null, cap = 20, hint = (line) => line, nowMs, shell = false } = options;
+    const named = model.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") === model.slug ? "" : ` (${quoted(model.name, 60)})`;
+    const lines = [`Orbit board "${model.slug}"${named}: ${model.open} open. Cards are #n${shell ? " (in a shell: orbit card 12)" : ""}, med unless marked; lanes by name.`];
+    if (model.hasRules || model.journalCount) {
+        const what = [model.hasRules ? "board rules" : "", model.journalCount ? plural(model.journalCount, "entry", "entries") : ""].filter(Boolean).join(", ");
+        lines.push(`Read first: ${hint("journal")} (${what})`);
+    }
+    const hidden = [];
+    for (const column of model.lanes) {
+        if (lane && column.name !== lane)
+            continue;
+        if (column.closed && !all && !lane) {
+            hidden.push(`${laneText(column.name)} ${column.cards.length}`);
+            continue;
+        }
+        lines.push(`${laneText(column.name)} (${column.cards.length})`);
+        const limit = all || lane ? column.cards.length : cap;
+        for (const card of column.cards.slice(0, limit))
+            lines.push(`  ${cardLine(card, { nowMs })}`);
+        if (column.cards.length > limit)
+            lines.push(`  … ${column.cards.length - limit} more (${hint(`view --lane ${JSON.stringify(laneText(column.name))}`)})`);
+    }
+    if (hidden.length)
+        lines.push(`Hidden: ${hidden.join(", ")} (${hint("view --all")})`);
+    return lines.join("\n");
+}
+function stamp(iso) {
+    return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(iso) ? `${iso.slice(0, 10)} ${iso.slice(11, 16)}` : iso;
+}
+/** A short reference to another card: `#2 "Trello import" (Todo)`. */
+export function cardRef(card, { lane = true } = {}) {
+    return `${card.board ?? ""}#${card.n} ${quoted(card.title, 80)}${lane && card.lane ? ` (${laneText(card.lane)})` : ""}`;
+}
+const COMMENT_VERBS = { checkpoint: "asked", completion: "finished" };
+/**
+ * Multi-line text, each line indented under its heading. Every way of
+ * breaking a line becomes a real line break (and so gets the indent), and
+ * other control characters are dropped.
+ */
+export function block(text, indent = "  ") {
+    return asText(text ?? "")
+        .replace(/\r\n?|[\u0085\u2028\u2029\u000b\u000c]/g, "\n")
+        .replace(/[\u0000-\u0008\u000e-\u001f\u007f-\u009f]/g, "")
+        .trim()
+        .split("\n")
+        .map((line) => `${indent}${line}`.trimEnd())
+        .join("\n");
+}
+/** `Label: text` when the text is one line, else the label alone with the text indented under it. */
+export function labelled(label, text) {
+    const body = block(text, "");
+    return body.includes("\n") ? `${label}\n${block(text)}` : `${label} ${body}`;
+}
+export function renderComments(comments, { limit = 20 } = {}) {
+    if (!comments.length)
+        return "No comments.";
+    const shown = comments.slice(-limit);
+    const lines = [];
+    if (comments.length > shown.length)
+        lines.push(`(${comments.length - shown.length} earlier comments not shown)`);
+    for (const comment of shown) {
+        const verb = COMMENT_VERBS[comment.kind] ? ` ${COMMENT_VERBS[comment.kind] ?? ""}` : "";
+        const body = block(comment.body).replace(/^ {2}/, "");
+        lines.push(`- ${authorText(comment.author)}${verb} (${stamp(comment.at)}): ${body}`);
+    }
+    return lines.join("\n");
+}
+/** One card: title, a facts line (type · priority · lane · labels · author · link), its links, then its text. */
+export function renderCard(card, options = {}) {
+    const { comments = null, hint = (line) => line, nowMs } = options;
+    // One card always says its priority, med too: unsaid, it read as "no priority".
+    const facts = [card.type, priorityWord(card.priority)];
+    facts.push(card.archived ? `${laneText(card.lane)}, archived` : laneText(card.lane));
+    if (card.labels.length)
+        facts.push(`[${card.labels.map(labelText).join(", ")}]`);
+    if (card.author)
+        facts.push(`by ${authorText(card.author)}`);
+    if (card.holder) {
+        const since = age(card.holder.since, nowMs);
+        facts.push(`held by @${oneLine(card.holder.name, 40)}${since ? ` ${since}` : ""}`);
+    }
+    facts.push(card.link);
+    const lines = [`#${card.n} ${oneLine(card.title, 200)}`, facts.join(" · ")];
+    if (card.parent)
+        lines.push(`Parent: ${cardRef(card.parent, { lane: false })}`);
+    if (card.children.length)
+        lines.push(`Sub-cards: ${card.children.map((child) => cardRef(child)).join("; ")}`);
+    if (card.blockedBy.length)
+        lines.push(`Blocked by: ${card.blockedBy.map((other) => cardRef(other)).join("; ")}`);
+    if (card.blocks.length)
+        lines.push(`Blocks: ${card.blocks.map((other) => cardRef(other)).join("; ")}`);
+    if (card.related.length)
+        lines.push(`Related: ${card.related.map((other) => cardRef(other)).join("; ")}`);
+    // A stored link has no spaces or line breaks (src/core/nebula-link.ts); oneLine keeps it so.
+    if (card.nebula)
+        lines.push(`Nebula: ${oneLine(card.nebula, 2048)}`);
+    for (const [label, text] of [["Description:", card.description], ["Plan:", card.plan], ["Summary:", card.summary], ["Revisions:", card.revisions]]) {
+        if (!block(text, ""))
+            continue;
+        lines.push("", label, block(text));
+    }
+    lines.push("");
+    if (comments)
+        lines.push(renderComments(comments));
+    else
+        lines.push(`Comments: ${card.commentCount}${card.commentCount ? ` (${hint(`card #${card.n} --comments`)})` : ""}`);
+    return lines.join("\n");
+}

package/lib/commands/session.d.ts

@@ -0,0 +1,85 @@
+/**
+ * One conversation with Orbit: who is asking, through what (a shell, MCP,
+ * HTTP), and the board it has chosen, like `cd`. A choice one caller makes
+ * never moves another caller's commands: an agent's choice stays in its
+ * session, and only a person's shell on the computer itself (`cli`, not
+ * `shared`) sets the computer's default board.
+ */
+import type { Ctx } from "../core/context.ts";
+import type { Actor, RegisteredBoard } from "../core/model.ts";
+export type Transport = "cli" | "mcp" | "http";
+/** A repo's orbit.json, as read: the board it names, or why it can't be used. */
+export interface RepoChoice {
+    board: string | null;
+    problem?: "not_file" | "too_big" | "not_json" | "not_slug";
+    value?: unknown;
+}
+/**
+ * Where a repo's board comes from: a computer reads orbit.json where the
+ * command runs (and a shell there may write it); a remote client sends what
+ * it read. Only `read` is needed.
+ */
+export interface RepoSource {
+    read(): RepoChoice;
+    /** How the caller's place is said: "this repo", "this folder". */
+    place?: string;
+    /** Writes or clears `board` in the file (`boards link`, `boards unlink`); only a shell on this computer has it. */
+    link?: (sub: "link" | "unlink", slug: string | null) => {
+        ok: boolean;
+        text: string;
+        data: unknown;
+    };
+}
+/** Why a repo's orbit.json can't name a board, in one line. */
+export declare function repoProblemText(repo: RepoChoice): string;
+/**
+ * A repo's board as a server gets it from a remote client (`repo_board`,
+ * `repo_board_problem`), checked again: the request is no more trusted than
+ * the file. Null when the client sent none.
+ */
+export declare function repoBoardFromRequest(board: unknown, problem: unknown): RepoChoice | null;
+export interface Session {
+    readonly c: Ctx;
+    readonly actor: Actor;
+    transport: Transport;
+    /** The board this session chose (`view <board>`, `ORBIT_BOARD`), as a slug. */
+    board: string | null;
+    /** True for a command over HTTP to an Orbit others use: it may choose a board for itself, never the default for everyone. */
+    readonly shared: boolean;
+    readonly repo: RepoSource | null;
+}
+export declare function createSession(c: Ctx, options?: {
+    transport?: Transport;
+    board?: string | null;
+    shared?: boolean;
+    repo?: RepoSource | null;
+}): Session;
+/** True in a shell: usages say `orbit card 12`, since a shell drops a word that starts with #. */
+export declare const inShell: (session: Pick<Session, "transport">) => boolean;
+/** How a command is written in this transport: `orbit view` in a shell, `view` elsewhere. */
+export declare function hint(session: Pick<Session, "transport">, line: string): string;
+/**
+ * The answer when there is no board: how to make one, and, while an older
+ * Orbit's boards wait on this computer, the migration first (with no path: an
+ * agent never sees one). A shell on this computer may run it; over MCP or a
+ * shared Orbit the agent asks its person, who runs it where Orbit runs.
+ */
+export declare function noBoardsText(session: Pick<Session, "transport" | "c" | "shared">): string;
+/** Only a shell on this computer sets its default board; agents over MCP or HTTP choose for themselves. */
+export declare function setsComputerDefault(session: Session): boolean;
+/** Where the caller runs, for "let ... name it". */
+export declare function callerPlace(session: Session): string;
+export declare const DEFAULT_BOARD = "default_board";
+export declare function boardList(session: Session): Promise<string>;
+export declare function boardRowFor(session: Session, ident: string): Promise<RegisteredBoard | null>;
+/** The computer's default board (`boards use` in a shell), when it still exists. */
+export declare function savedDefault(session: Session): Promise<RegisteredBoard | null>;
+declare function repoChoice(session: Session): RepoChoice;
+export { repoChoice };
+/**
+ * The board a command uses: the one it names, else the session's, else the
+ * repo's orbit.json, else this computer's default, else the only one. A
+ * repo file that can't be used, or names a board this Orbit lacks, is
+ * refused: never a quiet fall-through to another board.
+ */
+export declare function resolveBoard(session: Session, explicit?: string | null): Promise<RegisteredBoard>;

package/lib/commands/session.js

@@ -0,0 +1,138 @@
+/**
+ * One conversation with Orbit: who is asking, through what (a shell, MCP,
+ * HTTP), and the board it has chosen, like `cd`. A choice one caller makes
+ * never moves another caller's commands: an agent's choice stays in its
+ * session, and only a person's shell on the computer itself (`cli`, not
+ * `shared`) sets the computer's default board.
+ */
+import { isSlug, slugify } from "../core/text.js";
+import { fail, shellSafe } from "./parse.js";
+import { oneLine } from "./present.js";
+const ONE_LINE = '{"board": "<slug>"}';
+/** Why a repo's orbit.json can't name a board, in one line. */
+export function repoProblemText(repo) {
+    const tail = " Or name a board in the command.";
+    switch (repo.problem) {
+        case "too_big":
+            return `This repo's orbit.json is over 16 KB, so Orbit doesn't read it. It needs only ${ONE_LINE}.${tail}`;
+        case "not_json":
+            return `This repo's orbit.json isn't a JSON object, so Orbit doesn't read it. It needs only ${ONE_LINE}.${tail}`;
+        case "not_slug": {
+            const shown = typeof repo.value === "string" ? JSON.stringify(oneLine(repo.value, 60)) : oneLine(JSON.stringify(repo.value), 40);
+            const like = slugify(typeof repo.value === "string" ? repo.value : "") || "garden";
+            return `This repo's orbit.json names board ${shown}, which isn't a board slug (lowercase letters, digits and dashes, like ${like}).${tail}`;
+        }
+        case "not_file":
+        case undefined:
+            return `This repo's orbit.json isn't a plain file, so Orbit doesn't read it. Make it a file holding ${ONE_LINE}.${tail}`;
+    }
+}
+const PROBLEMS = ["not_file", "too_big", "not_json", "not_slug"];
+/**
+ * A repo's board as a server gets it from a remote client (`repo_board`,
+ * `repo_board_problem`), checked again: the request is no more trusted than
+ * the file. Null when the client sent none.
+ */
+export function repoBoardFromRequest(board, problem) {
+    if (PROBLEMS.includes(problem))
+        return { board: null, problem: problem, value: typeof board === "string" ? board : undefined };
+    if (board === undefined || board === null || board === "")
+        return null;
+    if (!isSlug(board))
+        return { board: null, problem: "not_slug", value: board };
+    return { board };
+}
+export function createSession(c, options = {}) {
+    return { c, actor: c.actor, transport: options.transport ?? "mcp", board: options.board ?? null, shared: Boolean(options.shared), repo: options.repo ?? null };
+}
+/** True in a shell: usages say `orbit card 12`, since a shell drops a word that starts with #. */
+export const inShell = (session) => session.transport === "cli";
+/** How a command is written in this transport: `orbit view` in a shell, `view` elsewhere. */
+export function hint(session, line) {
+    return session.transport === "cli" ? `orbit ${shellSafe(line)}` : line;
+}
+/**
+ * The answer when there is no board: how to make one, and, while an older
+ * Orbit's boards wait on this computer, the migration first (with no path: an
+ * agent never sees one). A shell on this computer may run it; over MCP or a
+ * shared Orbit the agent asks its person, who runs it where Orbit runs.
+ */
+export function noBoardsText(session) {
+    if (!session.c.deployment.older_data)
+        return `No boards yet. Create one: ${hint(session, "boards new <name>")}`;
+    const fresh = `\`${hint(session, "boards new <name>")}\``;
+    const run = session.transport === "cli" && !session.shared ? "run `orbit migrate`" : "ask your person to run `orbit migrate` in a terminal";
+    return `Boards from an older Orbit are waiting: ${run} to bring them here (it only reads the old files). Or start fresh: ${fresh}.`;
+}
+/** Only a shell on this computer sets its default board; agents over MCP or HTTP choose for themselves. */
+export function setsComputerDefault(session) {
+    return session.transport === "cli" && !session.shared;
+}
+/** Where the caller runs, for "let ... name it". */
+export function callerPlace(session) {
+    if (session.repo?.place)
+        return session.repo.place;
+    return session.transport === "cli" ? "this repo" : "the repo";
+}
+export const DEFAULT_BOARD = "default_board";
+export async function boardList(session) {
+    return (await session.c.store.boards.list()).map((row) => row.slug).join(", ");
+}
+export async function boardRowFor(session, ident) {
+    return (await session.c.store.boards.bySlug(ident)) ?? (await session.c.store.boards.get(ident));
+}
+/** The computer's default board (`boards use` in a shell), when it still exists. */
+export async function savedDefault(session) {
+    const slug = await session.c.store.settings.get(DEFAULT_BOARD);
+    return slug ? session.c.store.boards.bySlug(slug) : null;
+}
+function repoChoice(session) {
+    return session.repo?.read() ?? { board: null };
+}
+export { repoChoice };
+/** This repo's orbit.json names a board this Orbit doesn't have. */
+async function missingRepoBoard(session, slug) {
+    const all = await session.c.store.boards.list();
+    const named = `This repo's orbit.json names board ${oneLine(slug, 60)}, which this Orbit doesn't have.`;
+    const first = all[0];
+    if (!first)
+        return `${named} No boards here yet. Create one: ${hint(session, "boards new <name>")}`;
+    // The link names no board: the first one is rarely this repo's.
+    const way = session.transport === "cli" ? `Name one (orbit view ${first.slug}) or link one: orbit boards link <board>.` : `Name one (view ${first.slug}) or link one (boards link <board> says how).`;
+    return `${named} Boards here: ${await boardList(session)}. ${way}`;
+}
+/**
+ * The board a command uses: the one it names, else the session's, else the
+ * repo's orbit.json, else this computer's default, else the only one. A
+ * repo file that can't be used, or names a board this Orbit lacks, is
+ * refused: never a quiet fall-through to another board.
+ */
+export async function resolveBoard(session, explicit) {
+    const named = explicit || session.board;
+    if (named) {
+        const row = await boardRowFor(session, named);
+        if (!row)
+            fail(`No board "${oneLine(named, 60)}". Boards: ${(await boardList(session)) || "none yet"}.`);
+        return row;
+    }
+    const repo = repoChoice(session);
+    if (repo.problem)
+        fail(repoProblemText(repo));
+    if (repo.board)
+        return (await session.c.store.boards.bySlug(repo.board)) ?? fail(await missingRepoBoard(session, repo.board));
+    const saved = await savedDefault(session);
+    if (saved)
+        return saved;
+    const all = await session.c.store.boards.list();
+    const [first] = all;
+    if (all.length === 1 && first)
+        return first;
+    if (!first)
+        fail(noBoardsText(session));
+    const list = await boardList(session);
+    // The link names no board: the first one is rarely this folder's.
+    if (session.transport !== "cli") {
+        fail(`Which board? ${list}. Name it (view ${first.slug} keeps it for this session, ${first.slug}#12, or --board ${first.slug}), or let ${callerPlace(session)} name it (boards link <board> says how).`);
+    }
+    fail(`Which board? ${list}. Name it (orbit view ${first.slug}, orbit card ${first.slug}#12, or --board ${first.slug}) or let ${callerPlace(session)} name it: orbit boards link <board>.`);
+}

package/lib/commands/verbs.d.ts

@@ -0,0 +1,35 @@
+/**
+ * What each command does: reads the board through the port, changes it
+ * through the core's use cases (never by writing records itself), and says
+ * what happened in Orbit's words (./present.ts), with JSON data for --json.
+ */
+import type { BoardCtx } from "../core/context.ts";
+import type { Args } from "./parse.ts";
+import type { Session } from "./session.ts";
+/** What a command did: its text, its data, and the board it acted on (a write marks that board active). */
+export interface Outcome {
+    text: string;
+    data: unknown;
+    board?: BoardCtx;
+}
+export declare const TEXT_TWICE_MESSAGE = "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 declare function cmdView(session: Session, args: Args): Promise<Outcome>;
+export declare function cmdCard(session: Session, args: Args): Promise<Outcome>;
+/** The overview's first lines for an agent: how to name itself (while it has no name) and the default work rules. */
+export declare function agentLines(session: Pick<Session, "actor" | "transport">): string[];
+export declare function cmdTake(session: Session, args: Args): Promise<Outcome>;
+export declare function cmdMove(session: Session, args: Args): Promise<Outcome>;
+export declare function cmdFinish(session: Session, args: Args): Promise<Outcome>;
+export declare function cmdAsk(session: Session, args: Args): Promise<Outcome>;
+export declare function cmdNote(session: Session, args: Args): Promise<Outcome>;
+export declare function cmdNew(session: Session, args: Args): Promise<Outcome>;
+export declare function cmdEdit(session: Session, args: Args): Promise<Outcome>;
+export declare function cmdJournal(session: Session, args: Args): Promise<Outcome>;
+export declare function cmdFind(session: Session, args: Args): Promise<Outcome>;
+export declare function cmdChanges(session: Session, args: Args): Promise<Outcome>;
+export declare const BOARDS_USAGE = "boards | boards new <name> [--slug s] | boards use <board> | boards link <board> | boards unlink";
+export declare function cmdBoards(session: Session, args: Args): Promise<Outcome>;
+export declare function cmdLink(session: Session, args: Args): Promise<Outcome>;
+export declare function cmdUnlink(session: Session, args: Args): Promise<Outcome>;
+export declare function cmdArchive(session: Session, args: Args): Promise<Outcome>;
+export declare function cmdRestore(session: Session, args: Args): Promise<Outcome>;