@wirecat/cli-core 0.545.0 → 0.547.0

package/dist/cli/program.js

@@ -13,6 +13,7 @@ import { recorded, wasSettled } from "../runs/recording.js";
 import { runContextOf } from "../runs/run-context.js";
 import { processRun, useAsProcessRun } from "../runs/scope.js";
 import { AUTHORITY_KEY, BOT_API_KEY, isBotApi, keyForCommand } from "../sends/permissions.js";
+import { liftOptionsAfterDashes } from "./after-dashes.js";
 import { logParsedArgv, logVersion } from "./argv-log.js";
 import { commandAvailability } from "./command-availability.js";
 import { commandPathOf } from "./command-contract.js";
@@ -135,15 +136,16 @@ export const run = async (argv, definition, options = {}) => {
         useAsProcessRun(outer);
     }
 };
+const isMachine = (words) => words.some((word) => word === "--json" || word.startsWith("--json=") || word === "--jsonl");
 const runOnce = async (argv, definition, options) => {
     const streams = options.streams ?? processStreams;
     if (!options.streams)
         quietBrokenPipes();
     const delimiter = argv.indexOf("--");
     const flags = argv.slice(0, delimiter < 0 ? undefined : delimiter);
-    const machine = flags.some((word) => word === "--json" || word.startsWith("--json=") || word === "--jsonl");
-    const debug = flags.includes("--debug");
-    const reporting = machine ? { ...options, tty: false } : options;
+    let machine = isMachine(flags);
+    let debug = flags.includes("--debug");
+    let reporting = machine ? { ...options, tty: false } : options;
     const control = execution(streams, { maxOutputBytes: 0 });
     let restoreInput;
     let signalExit;
@@ -439,12 +441,21 @@ const runOnce = async (argv, definition, options) => {
     forEachCommand(program, (child) => child.exitOverride());
     // Before commander, not inside it: commander has no hook that runs before it decides which
     // subcommand it is looking at.
-    const { profile, rest: lifted } = liftProfile(argv, commandWords(program), valuedOptions(program));
+    const profiled = liftProfile(argv, commandWords(program), valuedOptions(program));
+    const { profile } = profiled;
+    // An agent's call builds its own argv, with its values after `--` on purpose: none of them may become an option.
+    const lifted = options.agent
+        ? profiled.rest
+        : liftOptionsAfterDashes(profiled.rest, (words) => commandAt(program, commandPath(program, words)));
+    const liftedEnd = lifted.indexOf("--");
+    const liftedFlags = lifted.slice(0, liftedEnd < 0 ? undefined : liftedEnd);
+    machine ||= isMachine(liftedFlags);
+    debug ||= liftedFlags.includes("--debug");
+    reporting = machine ? { ...options, tty: false } : options;
     // `wa 'chats list' --help` reads "chats list" as a profile and prints the root help with exit 0.
     try {
         // Only before `--`: what follows is a positional, an agent's text among them, never a command word.
-        const end = lifted.indexOf("--");
-        for (const words of [flags, end < 0 ? lifted : lifted.slice(0, end)])
+        for (const words of [flags, liftedFlags])
             refuseJoinedPath(program, words.filter((word) => !word.startsWith("-")), profile !== undefined && !/\s/.test(profile) ? [profile] : []);
     }
     catch (failure) {

package/dist/cli/schedule/schedule-command.js

@@ -110,6 +110,7 @@ export const scheduleCommandFor = ({ app, context: contextOf }) => {
         return { context, system, state, say, timer, environment, save };
     };
     withWhen(grantsAuthority(annotate(command.command("command"), {
+        literal_after_dashes: true,
         effects: LOCAL_WRITE,
         examples: [
             `${app.command} personal schedule command health --every 1h -- doctor`,

package/dist/domain/message-link.d.ts

@@ -24,13 +24,16 @@ export type MessageLink = MessagePermalink & {
     files?: FileLink[];
 };
 export declare const fileLinks: (attachments: readonly Attachment[]) => FileLink[];
+/** A chat and a message id, or one reference naming both; a reference's account is for the caller to check. */
 export declare const messageLinkTarget: (reference: string, message: string | undefined, provider: string) => {
     chat: string;
     message: string;
     account: string;
+    text: string;
 } | {
     chat: string;
     message: string;
     account: undefined;
+    text: string;
 };
 export declare const validatePermalink: (link: MessagePermalink) => MessagePermalink;

package/dist/domain/message-link.js

@@ -1,6 +1,6 @@
 import { CliError } from "@wirecat/cli-base";
 import { hitFiles } from "./attachments.js";
-import { isLocator, parseLocator } from "./locator.js";
+import { chatReferenceOf } from "./ref-arguments.js";
 export const fileLinks = (attachments) => hitFiles(attachments).map(({ position, kind, name }) => ({
     position,
     kind,
@@ -8,28 +8,23 @@ export const fileLinks = (attachments) => hitFiles(attachments).map(({ position,
     url: null,
     reason: "unsupported_provider",
 }));
+/** A chat and a message id, or one reference naming both; a reference's account is for the caller to check. */
 export const messageLinkTarget = (reference, message, provider) => {
-    if (isLocator(reference)) {
+    const named = chatReferenceOf(reference, provider, "message");
+    if (named?.message !== undefined) {
         if (message !== undefined)
             throw new CliError("validation_error", "a locator already names the message");
-        let target;
-        try {
-            target = parseLocator(reference);
-        }
-        catch {
-            throw new CliError("validation_error", "expected msg:<provider>/<account>/<chat>/<message>");
-        }
-        if (target.provider !== provider)
-            throw new CliError("validation_error", "that locator belongs to another messenger");
-        validMessageId(target.message);
-        return { chat: target.chat, message: target.message, account: target.account };
+        validMessageId(named.message);
+        return { chat: named.chat, message: named.message, account: named.account, text: named.text };
     }
     if (message === undefined)
         throw new CliError("validation_error", "which message? give its id after the chat");
     validMessageId(message);
+    if (named)
+        return { chat: named.chat, message, account: named.account, text: named.text };
     if (!reference.trim())
         throw new CliError("validation_error", "which chat? give its id or title");
-    return { chat: reference, message, account: undefined };
+    return { chat: reference, message, account: undefined, text: reference };
 };
 const validMessageId = (id) => {
     if (!id ||

package/dist/domain/money-words.d.ts

@@ -0,0 +1,11 @@
+import type { TaskCategory } from "./task-categories.js";
+/**
+ * Verb classes for reading money in a chat, matched by stem as task categories are. A stem cannot tell the imperative
+ * from the past tense (`оплати`, `оплатил` → `оплат`) or from a promise (`pagué`, `pagaré` → `pag`), so a stem that
+ * several classes share is listed once, under the request, and a word only counts where its stem is its own. The
+ * signal that reads these keeps the sender's side (owner or other) to decide the direction.
+ */
+export declare const MONEY_REQUEST = "money-request";
+export declare const MONEY_DONE = "money-done";
+export declare const PROMISE = "promise";
+export declare const MONEY_WORDS: readonly TaskCategory[];

package/dist/domain/money-words.js

@@ -0,0 +1,38 @@
+/**
+ * Verb classes for reading money in a chat, matched by stem as task categories are. A stem cannot tell the imperative
+ * from the past tense (`оплати`, `оплатил` → `оплат`) or from a promise (`pagué`, `pagaré` → `pag`), so a stem that
+ * several classes share is listed once, under the request, and a word only counts where its stem is its own. The
+ * signal that reads these keeps the sender's side (owner or other) to decide the direction.
+ */
+export const MONEY_REQUEST = "money-request";
+export const MONEY_DONE = "money-done";
+export const PROMISE = "promise";
+export const MONEY_WORDS = [
+    {
+        name: MONEY_REQUEST,
+        meaning: "asks for a payment or sends an invoice",
+        triggers: {
+            en: ["pay", "send", "transfer", "invoice", "owe", "refund", "remit"],
+            ru: ["переведи", "оплати", "заплати", "вышли", "отправь", "скинь", "верни", "счёт", "выстави", "должен"],
+            es: ["envía", "transfiere", "factura", "debes", "devuelve", "abona"],
+        },
+    },
+    {
+        name: MONEY_DONE,
+        meaning: "says a payment was made or received",
+        triggers: {
+            en: ["paid", "sent", "received", "settled"],
+            ru: ["перевёл", "перевела", "выслал", "вернул", "скинул", "получил", "получила"],
+            es: ["recibido"],
+        },
+    },
+    {
+        name: PROMISE,
+        meaning: "promises to pay or send later",
+        triggers: {
+            en: ["promise", "promised", "guarantee"],
+            ru: ["оплачу", "заплачу", "отправлю", "обещаю", "гарантирую"],
+            es: ["prometo", "transferiré", "devolveré"],
+        },
+    },
+];

package/dist/domain/providers.d.ts

@@ -11,6 +11,8 @@ export interface ProviderEntry {
 }
 /** The seed: what cli-core knows before any CLI has written its entry into the store. */
 export declare const PROVIDERS: readonly ProviderEntry[];
+/** How a text names a provider to a person: `MAX`, not `max`. */
+export declare const providerLabel: (provider: Provider) => string;
 /**
  * A notes folder is an `accounts` row of one of these providers; people call every one `notes`. `obsidian` is a vault,
  * `local` a plain folder (store version 32). `folder` is what they were before, and what Drive's stand-in folders and

package/dist/domain/providers.js

@@ -3,11 +3,11 @@ import { CliError } from "@wirecat/cli-base";
 export const KINDS = ["messages", "mail", "notes", "documents", "meetings", "events"];
 /** The seed: what cli-core knows before any CLI has written its entry into the store. */
 export const PROVIDERS = [
-    { name: "telegram", kind: "messages", aliases: ["tg"] },
+    { name: "telegram", kind: "messages", aliases: ["tg"], command: "tg" },
     { name: "telegram-bot", kind: "messages", aliases: ["tg-bot"] },
-    { name: "max", kind: "messages", aliases: [] },
+    { name: "max", kind: "messages", aliases: [], command: "max" },
     { name: "max-bot", kind: "messages", aliases: [] },
-    { name: "whatsapp", kind: "messages", aliases: ["wa"] },
+    { name: "whatsapp", kind: "messages", aliases: ["wa"], command: "wa" },
     { name: "whatsapp-bot", kind: "messages", aliases: ["wa-bot"] },
     { name: "email", kind: "mail", aliases: [] },
     { name: "notes", kind: "notes", aliases: [] },
@@ -15,6 +15,18 @@ export const PROVIDERS = [
     { name: "obsidian", kind: "notes", aliases: [] },
     { name: "zoom", kind: "meetings", aliases: [] },
 ];
+const LABELS = {
+    telegram: "Telegram",
+    "telegram-bot": "Telegram bot",
+    max: "MAX",
+    "max-bot": "MAX bot",
+    whatsapp: "WhatsApp",
+    "whatsapp-bot": "WhatsApp bot",
+    "google-drive": "Google Drive",
+    email: "mail",
+};
+/** How a text names a provider to a person: `MAX`, not `max`. */
+export const providerLabel = (provider) => LABELS[provider] ?? provider;
 /**
  * A notes folder is an `accounts` row of one of these providers; people call every one `notes`. `obsidian` is a vault,
  * `local` a plain folder (store version 32). `folder` is what they were before, and what Drive's stand-in folders and

package/dist/domain/ref-arguments.d.ts

@@ -0,0 +1,31 @@
+import { CliError } from "@wirecat/cli-base";
+import type { Id, Provider } from "./models.js";
+/** A `chat:` or `msg:` reference given where a messenger command takes a chat or a message. */
+export interface ChatReference {
+    text: string;
+    provider: Provider;
+    account: Id;
+    chat: Id;
+    message?: Id;
+}
+/** The account a reference must belong to; `account` is `undefined` while this profile's is not known yet. */
+export interface RefScope {
+    account: Id | undefined;
+    profile?: string;
+}
+/** The profiles of this app the store saw on an account; `undefined` when that cannot be told. */
+export type ProfilesOn = (account: Id) => Promise<readonly string[] | undefined>;
+/**
+ * The chat or message a reference names, when `text` is one of this provider's; `undefined` for text that is no
+ * reference, which stays an id or a title. Another kind or another messenger is refused, never read as a title.
+ */
+export declare const chatReferenceOf: (text: string, provider: Provider, takes?: "chat" | "message") => ChatReference | undefined;
+/**
+ * The identity a `contact:` reference names, when it is one of this provider's; `undefined` for any other text. A
+ * `person:` reference is the store's person, which the callers that take one read before this.
+ */
+export declare const contactReferenceOf: (text: string, provider: Provider | undefined) => Id | undefined;
+/** The refusal of another account's reference: switching to it silently would read or send as somebody else. */
+export declare const wrongAccount: (reference: Pick<ChatReference, "text" | "account">, scope: RefScope, profiles?: readonly string[]) => CliError;
+/** Refuses a reference of another account than the scope's, naming the profiles that have it. */
+export declare const ensureAccount: (reference: Pick<ChatReference, "text" | "account">, scope: RefScope, profilesOn?: ProfilesOn) => Promise<void>;

package/dist/domain/ref-arguments.js

@@ -0,0 +1,79 @@
+import { CliError } from "@wirecat/cli-base";
+import { providerLabel, providerNamed } from "./providers.js";
+import { looksLikeReference, parseReference } from "./references.js";
+const TAKES = {
+    chat: "a chat: chat:<provider>/<account>/<chat>, its id or its title",
+    message: "a message: msg:<provider>/<account>/<chat>/<message>, or a chat and the message's id",
+};
+const OPENS = {
+    chat: "messages list",
+    message: "messages show",
+    contact: "contacts show",
+};
+const article = (word) => (/^[aeiou]/.test(word) ? "an" : "a");
+const wrongKind = (text, kind, takes) => new CliError("validation_error", `${text} names ${article(kind)} ${kind}; this takes ${TAKES[takes]}`, {
+    reason: "ref.wrong-kind",
+});
+const wrongProvider = (text, provider, kind) => {
+    const command = providerNamed(provider)?.command;
+    const opens = OPENS[kind];
+    const how = command && opens ? `open it with ${command} <profile> ${opens} ${text}` : "open it with its own CLI";
+    const label = providerLabel(provider);
+    return new CliError("validation_error", `${text} is ${article(label.toLowerCase())} ${label} ${kind}; ${how}`, {
+        reason: "ref.wrong-provider",
+    });
+};
+/**
+ * The chat or message a reference names, when `text` is one of this provider's; `undefined` for text that is no
+ * reference, which stays an id or a title. Another kind or another messenger is refused, never read as a title.
+ */
+export const chatReferenceOf = (text, provider, takes = "chat") => {
+    const trimmed = text.trim();
+    if (!looksLikeReference(trimmed))
+        return undefined;
+    const reference = parseReference(trimmed);
+    if (reference.type !== "chat" && reference.type !== "message")
+        throw wrongKind(trimmed, reference.type, takes);
+    if (reference.provider !== provider)
+        throw wrongProvider(trimmed, reference.provider, reference.type);
+    const found = {
+        text: trimmed,
+        provider: reference.provider,
+        account: reference.account,
+        chat: reference.chat,
+        ...(reference.type === "message" ? { message: reference.message } : {}),
+    };
+    return found;
+};
+/**
+ * The identity a `contact:` reference names, when it is one of this provider's; `undefined` for any other text. A
+ * `person:` reference is the store's person, which the callers that take one read before this.
+ */
+export const contactReferenceOf = (text, provider) => {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith("contact:"))
+        return undefined;
+    const reference = parseReference(trimmed);
+    if (reference.type !== "contact")
+        return undefined;
+    if (provider !== undefined && reference.provider !== provider)
+        throw wrongProvider(trimmed, reference.provider, reference.type);
+    return reference.id;
+};
+/** The refusal of another account's reference: switching to it silently would read or send as somebody else. */
+export const wrongAccount = (reference, scope, profiles) => {
+    const here = scope.account === undefined
+        ? "the account of this profile is not known yet"
+        : `${scope.profile === undefined ? "this profile" : `profile ${scope.profile}`} is account ${scope.account}`;
+    const others = profiles === undefined
+        ? ""
+        : `. Profiles signed in to ${reference.account}: ${profiles.length > 0 ? profiles.join(", ") : "none here"}`;
+    return new CliError("validation_error", `${reference.text} belongs to account ${reference.account}; ${here}${others}`, { reason: "ref.wrong-account" });
+};
+/** Refuses a reference of another account than the scope's, naming the profiles that have it. */
+export const ensureAccount = async (reference, scope, profilesOn) => {
+    if (scope.account !== undefined && scope.account === reference.account)
+        return;
+    const profiles = await profilesOn?.(reference.account).catch(() => undefined);
+    throw wrongAccount(reference, scope, profiles);
+};

package/dist/domain/references.d.ts

@@ -1,3 +1,4 @@
+import { type MeetingReference } from "../meetings/index.js";
 /**
  * One typed form for every kind of thing a link, a tag or an argument can name. The prefix makes a
  * wrong kind fail loudly instead of matching another row. Parts that are ids of someone else's system
@@ -27,14 +28,31 @@ export type Reference = {
     type: "folder";
     id: string;
     path: string | null;
-};
+} | MeetingReference;
 /**
  * Things named by their store id (a task also by its key or the task package's id). `entity` is the name
  * before organizations and projects: it still parses, so an old file's reference resolves as not found.
  */
-export declare const SIMPLE_REFERENCES: readonly ["note", "document", "person", "organization", "project", "task", "memory", "fact", "bot", "entity"];
+export declare const SIMPLE_REFERENCES: readonly ["note", "document", "person", "organization", "project", "task", "memory", "fact", "bot", "event", "entity"];
 export type SimpleReference = (typeof SIMPLE_REFERENCES)[number];
+export type RefKindName = Exclude<Reference["type"], "entity">;
+export interface RefKindSpec<R extends Reference = Reference> {
+    /** The word before the first colon: `chat`, `msg`, `document`. */
+    prefix: string;
+    type: R["type"];
+    /** For error texts: `chat:<provider>/<account>/<chat>`. */
+    shape: string;
+    parse(rest: string, text: string): R;
+    format(reference: R): string;
+}
+/** Every kind of reference. A new kind is one row here; nothing else switches on the prefix. */
+export declare const REF_KINDS: readonly RefKindSpec[];
 export declare const formatReference: (reference: Reference) => string;
 export declare const parseReference: (text: string) => Reference;
 /** The stored spelling of a reference, so two spellings of one thing compare equal. */
 export declare const canonicalReference: (text: string) => string;
+/**
+ * Strict: the whole text is one reference of a known kind, with no space. A title such as "Note: plan" is not, so an
+ * argument that takes either a reference or a title can tell them apart. The shape is checked only by parsing it.
+ */
+export declare const looksLikeReference: (text: string) => boolean;

package/dist/domain/references.js

@@ -1,4 +1,5 @@
 import { CliError, singleLine } from "@wirecat/cli-base";
+import { formatMeetingReference, parseMeetingReference } from "../meetings/index.js";
 import { formatLocator, parseLocator } from "./locator.js";
 /**
  * Things named by their store id (a task also by its key or the task package's id). `entity` is the name
@@ -14,70 +15,154 @@ export const SIMPLE_REFERENCES = [
     "memory",
     "fact",
     "bot",
+    "event",
     "entity",
 ];
-const parts = (rest, count, reference, shape) => {
+const malformed = (text, shape) => new CliError("validation_error", `"${singleLine(text)}" is not a reference — expected ${shape}`, {
+    reason: "ref.malformed",
+});
+const parts = (rest, count, text, shape) => {
     const split = rest.split("/");
     if (split.length !== count || split.some((part) => part === ""))
-        throw new CliError("validation_error", `"${singleLine(reference)}" is not a reference — expected ${shape}`);
+        throw malformed(text, shape);
     return split.map(decodeURIComponent);
 };
-export const formatReference = (reference) => {
-    switch (reference.type) {
-        case "message":
-            return formatLocator(reference);
-        case "chat":
-            return `chat:${[reference.provider, reference.account, reference.chat].map(encodeURIComponent).join("/")}`;
-        case "contact":
-            return `contact:${[reference.provider, reference.id].map(encodeURIComponent).join("/")}`;
-        case "folder":
-            return reference.path === null
-                ? `folder:${encodeURIComponent(reference.id)}`
-                : `folder:${encodeURIComponent(reference.id)}/${encodeURIComponent(reference.path)}`;
-        default:
-            return `${reference.type}:${reference.id}`;
-    }
+const encoded = (...values) => values.map(encodeURIComponent).join("/");
+/** A subfolder spelled one way: no leading, trailing or doubled slash, and `.` for the folder itself. */
+const folderPath = (path) => {
+    const clean = path
+        .split("/")
+        .filter((part) => part !== "" && part !== ".")
+        .join("/");
+    return clean === "" ? (path.trim() === "" ? "" : null) : clean;
 };
-export const parseReference = (text) => {
-    const reference = text.trim();
-    const colon = reference.indexOf(":");
-    const prefix = colon < 0 ? "" : reference.slice(0, colon);
-    const rest = reference.slice(colon + 1);
-    switch (prefix) {
-        case "msg":
-            return { type: "message", ...parseLocator(reference) };
-        case "chat": {
-            const [provider, account, chat] = parts(rest, 3, reference, "chat:<provider>/<account>/<chat>");
+const MEETING_SHAPE = "meeting:<account>/<meeting>[/<transcript>[/<cue>]] with safe integer ids";
+const kind = (spec) => spec;
+const simple = (prefix) => kind({
+    prefix,
+    type: prefix,
+    shape: `${prefix}:<id>`,
+    parse: (rest, text) => {
+        if (!rest.trim())
+            throw new CliError("validation_error", `"${singleLine(text)}" names no ${prefix}`, {
+                reason: "ref.malformed",
+            });
+        return { type: prefix, id: rest };
+    },
+    format: (reference) => `${reference.type}:${reference.id}`,
+});
+/** Every kind of reference. A new kind is one row here; nothing else switches on the prefix. */
+export const REF_KINDS = [
+    kind({
+        prefix: "msg",
+        type: "message",
+        shape: "msg:<provider>/<account>/<chat>/<message>",
+        parse: (_, text) => {
+            try {
+                return { type: "message", ...parseLocator(text) };
+            }
+            catch {
+                throw malformed(text, "msg:<provider>/<account>/<chat>/<message>");
+            }
+        },
+        format: formatLocator,
+    }),
+    kind({
+        prefix: "chat",
+        type: "chat",
+        shape: "chat:<provider>/<account>/<chat>",
+        parse: (rest, text) => {
+            const [provider, account, chat] = parts(rest, 3, text, "chat:<provider>/<account>/<chat>");
             return { type: "chat", provider, account, chat };
-        }
-        case "contact": {
-            const [provider, id] = parts(rest, 2, reference, "contact:<provider>/<id>");
+        },
+        format: ({ provider, account, chat }) => `chat:${encoded(provider, account, chat)}`,
+    }),
+    kind({
+        prefix: "contact",
+        type: "contact",
+        shape: "contact:<provider>/<id>",
+        parse: (rest, text) => {
+            const [provider, id] = parts(rest, 2, text, "contact:<provider>/<id>");
             return { type: "contact", provider, id };
-        }
-        case "folder": {
+        },
+        format: ({ provider, id }) => `contact:${encoded(provider, id)}`,
+    }),
+    kind({
+        prefix: "folder",
+        type: "folder",
+        shape: "folder:<id>[/<path>]",
+        parse: (rest, text) => {
             const slash = rest.indexOf("/");
             const id = decodeURIComponent(slash < 0 ? rest : rest.slice(0, slash));
             const path = slash < 0 ? null : folderPath(decodeURIComponent(rest.slice(slash + 1)));
             if (!id.trim() || path === "")
-                throw new CliError("validation_error", `"${singleLine(reference)}" is not a reference — expected folder:<id>[/<path>]`);
+                throw malformed(text, "folder:<id>[/<path>]");
             return { type: "folder", id, path };
-        }
-        default:
-            if (SIMPLE_REFERENCES.includes(prefix)) {
-                if (!rest.trim())
-                    throw new CliError("validation_error", `"${singleLine(reference)}" names no ${prefix}`);
-                return { type: prefix, id: rest };
+        },
+        format: ({ id, path }) => (path === null ? `folder:${encodeURIComponent(id)}` : `folder:${encoded(id, path)}`),
+    }),
+    kind({
+        prefix: "meeting",
+        type: "meeting",
+        shape: MEETING_SHAPE,
+        parse: (_, text) => {
+            try {
+                return parseMeetingReference(text);
             }
-            throw new CliError("validation_error", `"${singleLine(reference)}" is not a reference — expected msg:, chat:, contact:, folder:, ${SIMPLE_REFERENCES.filter((one) => one !== "entity").join(":, ")}:`);
+            catch {
+                throw malformed(text, MEETING_SHAPE);
+            }
+        },
+        format: formatMeetingReference,
+    }),
+    ...SIMPLE_REFERENCES.map(simple),
+];
+const byPrefix = new Map(REF_KINDS.map((spec) => [spec.prefix, spec]));
+const byType = new Map(REF_KINDS.map((spec) => [spec.type, spec]));
+/** The prefixes people are told about: `entity` only still parses. */
+const offered = REF_KINDS.map(({ prefix }) => prefix).filter((prefix) => prefix !== "entity");
+const distance = (a, b) => {
+    let row = Array.from({ length: b.length + 1 }, (_, at) => at);
+    for (const [i, x] of [...a].entries()) {
+        const next = [i + 1];
+        for (const [j, y] of [...b].entries())
+            next.push(Math.min(row[j + 1] + 1, next[j] + 1, row[j] + (x === y ? 0 : 1)));
+        row = next;
     }
+    return row[b.length];
 };
-/** A subfolder spelled one way: no leading, trailing or doubled slash, and `.` for the folder itself. */
-const folderPath = (path) => {
-    const clean = path
-        .split("/")
-        .filter((part) => part !== "" && part !== ".")
-        .join("/");
-    return clean === "" ? (path.trim() === "" ? "" : null) : clean;
+/** `doc` reads as `document`, not as `bot` one letter away: a typed start of a prefix wins over spelling. */
+const nearest = (typed) => offered.find((prefix) => typed.length >= 2 && prefix.startsWith(typed)) ??
+    offered
+        .map((prefix) => ({ prefix, far: distance(typed, prefix) }))
+        .filter(({ far }) => far <= 2)
+        .sort((a, b) => a.far - b.far)[0]?.prefix;
+const unknownKind = (text, prefix, rest) => {
+    const near = prefix === "" ? undefined : nearest(prefix);
+    const kinds = offered.map((one) => `${one}:`).join(", ");
+    const hint = near === undefined ? `; kinds: ${kinds}` : `; did you mean ${near}:${singleLine(rest)}? Kinds: ${kinds}`;
+    return new CliError("validation_error", `"${singleLine(text)}" is no kind of reference${hint}`, {
+        reason: "ref.unknown-kind",
+    });
+};
+export const formatReference = (reference) => byType.get(reference.type).format(reference);
+export const parseReference = (text) => {
+    const reference = text.trim();
+    const colon = reference.indexOf(":");
+    const prefix = colon < 0 ? "" : reference.slice(0, colon);
+    const rest = reference.slice(colon + 1);
+    const spec = byPrefix.get(prefix);
+    if (!spec)
+        throw unknownKind(reference, prefix, rest);
+    return spec.parse(rest, reference);
 };
 /** The stored spelling of a reference, so two spellings of one thing compare equal. */
 export const canonicalReference = (text) => formatReference(parseReference(text));
+/**
+ * Strict: the whole text is one reference of a known kind, with no space. A title such as "Note: plan" is not, so an
+ * argument that takes either a reference or a title can tell them apart. The shape is checked only by parsing it.
+ */
+export const looksLikeReference = (text) => {
+    const match = /^([a-z]+):\S+$/.exec(text.trim());
+    return match !== null && byPrefix.has(match[1]);
+};