@wirecat/cli-core 0.547.0 → 0.549.0

package/dist/cli/context.d.ts

@@ -1,6 +1,6 @@
 import { type KeyringStore, type Renderer, type RenderFormat, type Streams } from "@wirecat/cli-base";
-import type { ErrorObject } from "@wirecat/cli-base/standards";
-import type { Command } from "commander";
+import { type ErrorObject } from "@wirecat/cli-base/standards";
+import { type Command } from "commander";
 import { type Deadline, type RunBudget } from "../background/budget.js";
 import type { MessageEvent } from "../domain/models.js";
 import type { AppIdentity } from "../ports/app.js";
@@ -13,6 +13,8 @@ import { type Closeable } from "./deadline.js";
 import { type GlobalFlags, type ResolveOptions, type Settings } from "./settings.js";
 /** What every CLI's commands write to, when it is not the real terminal. A CLI adds its own fields. */
 export interface BaseEnvironment {
+    /** The app's own compact rows (`ProgramDefinition.rows`), for `renderAnswer`. */
+    rows?: import("./compact.js").RowTable;
     discoveryAvailability?: (command: import("./command-availability.js").AvailabilityCommand) => import("./command-availability.js").CommandAvailability | undefined;
     streams?: Streams;
     /** Whether a person is looking. Defaults to whether stdout is a terminal. */
@@ -121,12 +123,16 @@ export declare const environmentOf: <E extends BaseEnvironment = BaseEnvironment
  * output goes and a test that captures it sees it. `readSecret(prompt, { ...secretInputOf(this), echo: true })`.
  */
 export declare const secretInputOf: (command: Command) => Pick<SecretInput, "input" | "output">;
+/** Whether the run asked for one line per item (WC-OUT-24). */
+export declare const compactOf: (command: Command) => boolean;
 /** For the commands that print but never need settings or a connection. */
 export declare const outputFor: (command: Command) => {
     format: "json" | "jsonl" | "pretty";
     color: boolean;
     streams: Streams;
     renderer: Renderer;
+    compact?: boolean | undefined;
+    full?: boolean | undefined;
 };
 export interface BaseContext {
     settings: Settings;
@@ -135,6 +141,9 @@ export interface BaseContext {
     /** Whether the human view may use colour — for views that print their own text. */
     color: boolean;
     streams: Streams;
+    /** One line per item; `renderAnswer` draws it, `full` keeps each text whole. */
+    compact?: boolean;
+    full?: boolean;
     env: NodeJS.ProcessEnv;
     keyring?: KeyringStore;
     /**

package/dist/cli/context.js

@@ -1,5 +1,7 @@
 import { CliError } from "@wirecat/cli-base";
 import { metaOf } from "@wirecat/cli-base/commands";
+import { COMPACT_FLAG } from "@wirecat/cli-base/standards";
+import { Option } from "commander";
 import { runBudget } from "../background/budget.js";
 import { resolveOutput } from "../output.js";
 import { recorded } from "../runs/recording.js";
@@ -43,22 +45,27 @@ export const secretInputOf = (command) => {
     const { stdin, stderr } = environmentOf(command);
     return { ...(stdin ? { input: stdin } : {}), ...(stderr ? { output: stderr } : {}) };
 };
+const detailOf = ({ brief, full }) => {
+    if (brief && full)
+        throw new CliError("validation_error", "--brief and --full ask for opposite things — pick one");
+    return brief ? { hitDetail: "brief" } : full ? { hitDetail: "full" } : {};
+};
+const COMPACT_KEY = new Option(COMPACT_FLAG).attributeName();
+/** Whether the run asked for one line per item (WC-OUT-24). */
+export const compactOf = (command) => command.optsWithGlobals()[COMPACT_KEY] === true;
 /** For the commands that print but never need settings or a connection. */
 export const outputFor = (command) => {
     const { streams, tty, env, agent } = environmentOf(command);
     return resolveOutput({
         ...command.optsWithGlobals(),
+        ...detailOf(command.optsWithGlobals()),
+        compact: compactOf(command),
         ...(agent ? { capture: agent.result } : {}),
         ...(streams ? { streams } : {}),
         ...(env ? { env } : {}),
         ...(tty === undefined ? {} : { tty }),
     });
 };
-const detailOf = ({ brief, full }) => {
-    if (brief && full)
-        throw new CliError("validation_error", "--brief and --full ask for opposite things — pick one");
-    return brief ? { hitDetail: "brief" } : full ? { hitDetail: "full" } : {};
-};
 /** Everything a command needs that no messenger decides, resolved once. */
 export const baseContext = (command, resolveSettings) => {
     const environment = environmentOf(command);
@@ -66,9 +73,10 @@ export const baseContext = (command, resolveSettings) => {
     const flags = command.optsWithGlobals();
     const overrides = environment.agent?.overrides ?? [];
     const settings = resolveSettings(overrides.length > 0 ? { ...flags, permission: [...overrides, ...(flags.permission ?? [])] } : flags, { env });
-    const { renderer, format, color, streams } = resolveOutput({
+    const { renderer, format, color, streams, compact, full } = resolveOutput({
         ...settings,
         env,
+        compact: compactOf(command),
         ...detailOf(command.optsWithGlobals()),
         ...(command.optsWithGlobals().fields
             ? { fields: command.optsWithGlobals().fields }
@@ -85,6 +93,7 @@ export const baseContext = (command, resolveSettings) => {
         format,
         color,
         streams,
+        ...(compact ? { compact, full: full === true } : {}),
         env,
         ...(environment.keyring ? { keyring: environment.keyring } : {}),
         // The deadline inside the record, so a timeout finishes the run as failed rather than leaving it running.

package/dist/cli/envelope.d.ts

@@ -193,6 +193,10 @@ export interface AnswerOutput {
     renderer: Renderer;
     format: RenderFormat;
     streams: Streams;
+    /** One line per item from the same answer (WC-OUT-24); an agent's run keeps JSON. */
+    compact?: boolean;
+    /** With `compact`: each text whole, not cut. */
+    full?: boolean;
 }
 /** An answer as JSON-lines records, for a writer that streams objects: one per item, then the end record. */
 export declare const jsonlRecords: <T>(body: Body<T>) => object[];
@@ -201,7 +205,7 @@ export declare const jsonlRecords: <T>(body: Body<T>) => object[];
  * the items — `view` draws them — and each next step this CLI has, as a line on stderr. A partial answer the
  * command does not declare `partial` exits with its first issue's code, after printing what was read.
  */
-export declare const renderAnswer: <T>(command: Command, { renderer, format, streams }: AnswerOutput, body: Body<T>, view?: (body: Body<T>) => string) => void;
+export declare const renderAnswer: <T>(command: Command, { renderer, format, streams, compact, full }: AnswerOutput, body: Body<T>, view?: (body: Body<T>) => string) => void;
 /**
  * A document that is not an answer about the owner's data — the command registry, a `--dry-run` preview of what a
  * command would do — printed whole, with no envelope.

package/dist/cli/envelope.js

@@ -1,8 +1,9 @@
 import { exitCodeOfAnswer } from "@wirecat/cli-base";
 import { metaOf } from "@wirecat/cli-base/commands";
-import { itemEnvelopeSchema, jsonlOf, listEnvelopeSchema, MAX_NEXT_STEPS, } from "@wirecat/cli-base/standards";
+import { COMPACT_FLAG, itemEnvelopeSchema, jsonlOf, listEnvelopeSchema, MAX_NEXT_STEPS, } from "@wirecat/cli-base/standards";
 import * as v from "valibot";
 import { currentRun } from "../runs/scope.js";
+import { compactText, entityRows, rowShapeOf, rowsOfEntity, TEXT_CHARS } from "./compact.js";
 import { environmentOf, setExitCode } from "./context.js";
 import { withoutProviderRefs } from "./provider-refs.js";
 import { nextStep, rootOf, runnable, stepLine, withLines, withSafety } from "./steps.js";
@@ -128,6 +129,8 @@ export const sealed = (value) => {
     const { meta, ...rest } = withoutProviderRefs(value);
     return { ...rest, meta: metaNow(meta) };
 };
+/** The steps a compact answer prints, each rerunning in the compact form the caller chose. */
+const compactSteps = (root, steps) => steps.map((step) => step.kind === "command" ? { ...step, line: `${step.line ?? stepLine(root, step)} ${COMPACT_FLAG}` } : step);
 /** An answer as JSON lines: one line per item, then the end line. One thing is a list of one that has no more. */
 const linesOf = (body) => jsonlOf("items" in body ? body : { items: [body.item], page: { mode: "page", limit: 1, has_more: false }, meta: body.meta });
 /** An answer as JSON-lines records, for a writer that streams objects: one per item, then the end record. */
@@ -139,7 +142,7 @@ export const jsonlRecords = (body) => linesOf(sealed(body))
  * the items — `view` draws them — and each next step this CLI has, as a line on stderr. A partial answer the
  * command does not declare `partial` exits with its first issue's code, after printing what was read.
  */
-export const renderAnswer = (command, { renderer, format, streams }, body, view) => {
+export const renderAnswer = (command, { renderer, format, streams, compact, full }, body, view) => {
     if (!isBody(body))
         refuse(body);
     const root = rootOf(command);
@@ -149,7 +152,15 @@ export const renderAnswer = (command, { renderer, format, streams }, body, view)
     if (next.length === 0)
         delete kept.next;
     const whole = sealed(kept);
-    if (format === "json")
+    const environment = environmentOf(command);
+    const drawn = compact && !environment.agent;
+    if (drawn) {
+        const lined = whole.next ? { ...whole, next: compactSteps(root, whole.next) } : whole;
+        const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        const { rows } = environment;
+        streams.data(compactText(lined, rowShapeOf(command, rows && entityRows(rows)), { timezone, textChars: full ? 0 : TEXT_CHARS }, rowsOfEntity(rows)));
+    }
+    else if (format === "json")
         renderer.result(whole);
     else if (format === "jsonl")
         for (const line of linesOf(whole).split("\n"))
@@ -161,7 +172,7 @@ export const renderAnswer = (command, { renderer, format, streams }, body, view)
     const code = exitCodeOfAnswer(whole.meta, metaOf(command).partial === true);
     if (code !== 0)
         setExitCode(command, code);
-    if (format === "json")
+    if (drawn || format === "json")
         return;
     for (const step of next)
         renderer.note(step.kind === "command" ? `→ ${step.why}: ${stepLine(root, step)}` : `→ ${step.why}`);

package/dist/cli/index.d.ts

@@ -1,5 +1,6 @@
 export { AI_ENTRIES, AI_SETTING_KEYS, type AISettings, resolveAISettings } from "../analysis/settings.js";
 export { parseDuration } from "../domain/duration.js";
+export { openOf, PROFILE_PLACEHOLDER, type ProfilesFor, type RefOpen, type RefSummary, refLabel, } from "../domain/ref-summaries.js";
 export { botTemplate } from "../entities/list-results.js";
 export { syncProgress } from "../entities/store-records.js";
 export { isCliFailure, isCommanderFailure } from "../errors/failures.js";
@@ -58,6 +59,7 @@ export type { CommandAvailability, DiscoveredCommand } from "./command-availabil
 export { commandContract, type JsonSchema, SCHEMA_DIALECT } from "./command-contract.js";
 export { type CommandRunOptions, type CommandRuns, commandRuns, type ProviderAnswer, type ProviderCall, providerEvent, providerRequest, type RunSettings, recordRuns, runSettings, type SavedRunSettings, } from "./command-runs.js";
 export { CONTRACT } from "./commands-command.js";
+export { type CompactOptions, compactText, entityRows, GENERIC_ROW, type RowColumn, type RowShape, type RowsResolver, type RowTable, type RowValue, rowShapeOf, rowsOfEntity, SHARED_ROWS, } from "./compact.js";
 export { refuseUnknownKey } from "./config-command.js";
 export { type ConfigIssue, type ConfigIssueKind, checkConfigText, issueMessage, readConfigFile, readConfigText, settingPathOf, withoutSetting, } from "./config-issues.js";
 export { loadSnakeCaseConfig } from "./config-keys.js";

package/dist/cli/index.js

@@ -1,5 +1,6 @@
 export { AI_ENTRIES, AI_SETTING_KEYS, resolveAISettings } from "../analysis/settings.js";
 export { parseDuration } from "../domain/duration.js";
+export { openOf, PROFILE_PLACEHOLDER, refLabel, } from "../domain/ref-summaries.js";
 export { botTemplate } from "../entities/list-results.js";
 export { syncProgress } from "../entities/store-records.js";
 export { isCliFailure, isCommanderFailure } from "../errors/failures.js";
@@ -50,6 +51,7 @@ export { PressLog, UpdatesCursor } from "./bot/updates.js";
 export { commandContract, SCHEMA_DIALECT } from "./command-contract.js";
 export { commandRuns, providerEvent, providerRequest, recordRuns, runSettings, } from "./command-runs.js";
 export { CONTRACT } from "./commands-command.js";
+export { compactText, entityRows, GENERIC_ROW, rowShapeOf, rowsOfEntity, SHARED_ROWS, } from "./compact.js";
 export { refuseUnknownKey } from "./config-command.js";
 export { checkConfigText, issueMessage, readConfigFile, readConfigText, settingPathOf, withoutSetting, } from "./config-issues.js";
 export { loadSnakeCaseConfig } from "./config-keys.js";

package/dist/cli/messenger/search-command.d.ts

@@ -1,5 +1,15 @@
 import { Command } from "commander";
+import type { SearchAllIncludingMeetingsFound } from "../../services/search-all-meetings.js";
 import { type Messenger } from "./context.js";
+import { type SourceSearched } from "./search-answers.js";
+export declare const searchAllOnlyOf: (value: string) => SourceSearched[];
+/** One `search all` hit as a person reads it. */
+export declare const searchAllLine: (item: SearchAllIncludingMeetingsFound["items"][number]) => string;
+/**
+ * `search all`'s scope, paging and matching options, the same in every CLI that mounts it (WC-ACCT-8): a messenger's
+ * and a calendar's.
+ */
+export declare const searchAllOptions: (command: Command) => Command;
 /**
  * `search <resource>`: every search of the tool, one leaf per resource (STANDARD.md, "Search
  * hierarchy"). `topics` only where the CLI has forum topics.

package/dist/cli/messenger/search-command.js

@@ -15,7 +15,7 @@ import { messagesSearchCommand } from "./messages-search-command.js";
 import { allAnswer, meaningNote, notesAnswer, offsetOf, SOURCE_SEARCHED, shownOf, } from "./search-answers.js";
 import { backendOptions, backendRequest, noteServer } from "./search-backend-options.js";
 import { topicsSearchCommand } from "./topics-command.js";
-const onlyOf = (value) => {
+export const searchAllOnlyOf = (value) => {
     const chosen = value.split(",").map((one) => one.trim());
     if (chosen.includes("mail"))
         throw new CliError("validation_error", "mail is searched by the separate memo CLI: install @wirecat/cli-memo, then `memo search mail …`");
@@ -24,7 +24,8 @@ const onlyOf = (value) => {
         throw new CliError("validation_error", `--only takes ${SOURCE_SEARCHED.join(", ")}, separated by commas; meetings when --source names a meeting account`);
     return [...new Set(chosen)];
 };
-const lineOf = (item) => item.kind === "meeting"
+/** One `search all` hit as a person reads it. */
+export const searchAllLine = (item) => item.kind === "meeting"
     ? `meeting · ${item.provider} · ${singleLine(item.title ?? "")}  ${item.ref}\n  ${item.timestamp ?? "time unknown"}  ${singleLine(item.text).slice(0, 200)}\n`
     : `${item.kind} · ${item.provider} · ${singleLine(item.title ?? "")}  ${item.ref}${item.url ? `\n  ${singleLine(item.url)}` : ""}\n  ${item.timestamp}${item.from?.name ? `  ${singleLine(item.from.name)}` : ""}  ${singleLine(item.text)}\n`;
 const maxMeetingsOf = (value) => {
@@ -34,6 +35,19 @@ const maxMeetingsOf = (value) => {
         throw new CliError("validation_error", "--max-meetings takes a whole number from 1, or all");
     return Number(value);
 };
+/**
+ * `search all`'s scope, paging and matching options, the same in every CLI that mounts it (WC-ACCT-8): a messenger's
+ * and a calendar's.
+ */
+export const searchAllOptions = (command) => command
+    .option("--only <resources>", "only these resources, separated by commas: messages, notes, events; meetings when --source names a meeting account", searchAllOnlyOf)
+    .option("--source <accounts>", "only these accounts, separated by commas: provider:account as a hit shows it, a provider, a kind or " +
+    "group:<name>; each resource reads the ones of its kind, and meetings only when it names one")
+    .option("--max-meetings <n>", "how many of the meeting account's meetings to look through, newest first, or all for every one (default 100)", maxMeetingsOf)
+    .option("--limit <n>", "how many", positiveCount("--limit"))
+    .option("--page <n>", "which page, starting at 1", positiveCount("--page"))
+    .option("--exact", "bare words and quotes match their exact form only, as exact:word does")
+    .option("--timezone <zone>", "the IANA timezone for calendar date boundaries");
 const allCommand = (messenger) => {
     const command = annotate(new Command("all"), { effects: REMOTE_READ, partial: true })
         .summary("search stored messages, notes, calendar events and selected meeting transcripts")
@@ -48,16 +62,8 @@ const allCommand = (messenger) => {
         .argument("<query...>", 'strict Lucene query: words, "phrases", AND/OR/NOT, field groups and date ranges')
         .addHelpText("after", SAVE_HELP)
         .addHelpText("after", `transcript: narrows a message search to voice transcripts, content: to the text of files, filename: to their names — \`${messenger.app.command} search all 'content:invoice'\`.
---json: the list is items; each result's reference is ref, with its kind.`)
-        .option("--only <resources>", "only these resources, separated by commas: messages, notes, events; meetings when --source names a meeting account", onlyOf)
-        .option("--source <accounts>", "only these accounts, separated by commas: provider:account as a hit shows it, a provider, a kind or " +
-        "group:<name>; each resource reads the ones of its kind, and meetings only when it names one")
-        .option("--max-meetings <n>", "how many of the meeting account's meetings to look through, newest first, or all for every one (default 100)", maxMeetingsOf)
-        .option("--limit <n>", "how many", positiveCount("--limit"))
-        .option("--page <n>", "which page, starting at 1", positiveCount("--page"))
-        .option("--exact", "bare words and quotes match their exact form only, as exact:word does")
-        .option("--timezone <zone>", "the IANA timezone for calendar date boundaries");
-    return backendOptions(annotate(command, { output: { entity: "hit" } }), messenger).action(async function (words) {
+--json: the list is items; each result's reference is ref, with its kind.`);
+    return backendOptions(annotate(searchAllOptions(command), { output: { entity: "hit" } }), messenger).action(async function (words) {
         const context = messengerContext(this, messenger);
         const { only, source, maxMeetings, limit: typed, page, exact, timezone, } = this.opts();
         const limit = typed ?? context.settings.limit;
@@ -99,7 +105,7 @@ const allCommand = (messenger) => {
                 context.renderer.note(found.server && !found.server.skipped
                     ? "nothing found in the local store or on the messenger's server"
                     : "nothing found in what the local store holds");
-            return found.items.map(lineOf).join("");
+            return found.items.map(searchAllLine).join("");
         });
     });
 };

package/dist/cli/messenger/store-maintenance-command.d.ts

@@ -3,9 +3,9 @@ import type { CacheDatabase } from "../../store/driver.js";
 import type { Messenger } from "./context.js";
 /** `doctor`'s short summary of the store. Must answer for a broken file, so an error is a field. */
 export declare const storeSummary: (env: NodeJS.ProcessEnv) => Promise<{
-    error?: undefined;
     path: string;
     exists: boolean;
+    error?: undefined;
 } | {
     path: string;
     exists: boolean;

package/dist/cli/program.d.ts

@@ -1,5 +1,6 @@
 import { Command } from "commander";
 import { type AppIdentity } from "../ports/app.js";
+import { type RowTable } from "./compact.js";
 import { type BaseEnvironment } from "./context.js";
 import { type FirstScreen } from "./help/first-screen.js";
 import type { CommandPermissions } from "./permission-keys.js";
@@ -16,6 +17,8 @@ export interface ProgramDefinition {
         resolveSettings: (flags?: GlobalFlags, options?: ResolveOptions) => Pick<Settings, "profile" | "keepFailedRuns" | "keepRunsForDays" | "skillHint"> & Partial<Pick<Settings, "recordInput" | "keepSuccessfulRunsForDays" | "permissions" | "permissionSources" | "configPath" | "savedPermissions" | "sources">>;
     };
     configure?: (program: Command) => void;
+    /** The app's own rows for `--compact`, by entity name; a shared entity's name is refused. */
+    rows?: RowTable;
     /** The tool's pitch and "what you can do" lines on `--help` and a bare run. */
     firstScreen?: FirstScreen;
     prepare?: (program: Command, environment: RunOptions) => void | Promise<void>;

package/dist/cli/program.js

@@ -2,6 +2,7 @@ import { join } from "node:path";
 import { CliError, errorObjectOf, errorRecordOf, exitCodeFor, exitCodeOfError, processStreams, renderError, resolvePaths, } from "@wirecat/cli-base";
 import { metaOf, refuseJoinedPath } from "@wirecat/cli-base/commands";
 import { skillHint } from "@wirecat/cli-base/skill";
+import { COMPACT_FLAG } from "@wirecat/cli-base/standards";
 import { Command, Help } from "commander";
 import { relayCommand } from "../background/relay.js";
 import { failingNotice, scheduledRuns } from "../background/schedules.js";
@@ -17,6 +18,7 @@ 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";
+import { entityRows } from "./compact.js";
 import { outputFor, provide } from "./context.js";
 import { refuseByCommandPermissions, refuseWriteBeforeConnecting } from "./early-refusal.js";
 import { changesAuthorityAt, changesAuthorityNow, isLogin, isStoreChange, judgedEffects, judgedTargets, storeChangeRefusal, } from "./effects.js";
@@ -73,6 +75,7 @@ export const createProgram = (definition, { out, err } = {}) => {
         .option("--max-output-bytes <bytes>", "maximum machine output bytes (default: 4194304; 0 disables)")
         .option("--brief", `${found} as reference, title, time, ${messenger ? "sender" : "author"} and excerpt only`)
         .option("--full", `${found} with their whole text and every provider field`)
+        .option(COMPACT_FLAG, "one line per item for an agent: reference first, text last, paging and next steps as # lines")
         .option("--dry-run", "preview parsed arguments and permissions before running the action")
         .option("--yes", "go ahead without the question an ask level puts before a write")
         .option("--record", "keep this run even where the config says record false; record_input false leaves the typed words out")
@@ -82,6 +85,8 @@ export const createProgram = (definition, { out, err } = {}) => {
         program.addCommand(command);
     configure?.(program);
     if (!contractsChecked.has(definition)) {
+        if (definition.rows)
+            entityRows(definition.rows);
         assertSharedContracts(program);
         contractsChecked.add(definition);
     }
@@ -136,7 +141,7 @@ export const run = async (argv, definition, options = {}) => {
         useAsProcessRun(outer);
     }
 };
-const isMachine = (words) => words.some((word) => word === "--json" || word.startsWith("--json=") || word === "--jsonl");
+const isMachine = (words) => words.some((word) => word === "--json" || word.startsWith("--json=") || word === "--jsonl" || word === COMPACT_FLAG);
 const runOnce = async (argv, definition, options) => {
     const streams = options.streams ?? processStreams;
     if (!options.streams)
@@ -218,6 +223,7 @@ const runOnce = async (argv, definition, options) => {
         commandSignal: control.signal,
         trackCloseable: control.trackCloseable,
         app: definition.app,
+        ...(definition.rows ? { rows: definition.rows } : {}),
         platform: options.platform ?? process.platform,
         exit,
         runCommand: (words, given) => run(words, definition, given),

package/dist/domain/providers.d.ts

@@ -1,4 +1,5 @@
 import type { Provider } from "./models.js";
+import { type RefKindName } from "./references.js";
 /** What a search reads; the same names `--only`, `searched` and `skipped` use. */
 export declare const KINDS: readonly ["messages", "mail", "notes", "documents", "meetings", "events"];
 export type Kind = (typeof KINDS)[number];
@@ -8,6 +9,8 @@ export interface ProviderEntry {
     aliases: readonly string[];
     /** The CLI that wrote the entry (`zm`, `drive`). One CLI may write several providers, so it is not an alias. */
     command?: string;
+    /** The read command, after `<command> <profile>`, that opens a ref of each kind: `{ chat: "messages list" }`. */
+    opens?: Partial<Record<RefKindName, string>>;
 }
 /** The seed: what cli-core knows before any CLI has written its entry into the store. */
 export declare const PROVIDERS: readonly ProviderEntry[];

package/dist/domain/providers.js

@@ -1,13 +1,15 @@
 import { CliError } from "@wirecat/cli-base";
+import { REF_KINDS } from "./references.js";
 /** What a search reads; the same names `--only`, `searched` and `skipped` use. */
 export const KINDS = ["messages", "mail", "notes", "documents", "meetings", "events"];
+const MESSENGER_OPENS = { chat: "messages list", message: "messages show", contact: "contacts show" };
 /** 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"], command: "tg" },
+    { name: "telegram", kind: "messages", aliases: ["tg"], command: "tg", opens: MESSENGER_OPENS },
     { name: "telegram-bot", kind: "messages", aliases: ["tg-bot"] },
-    { name: "max", kind: "messages", aliases: [], command: "max" },
+    { name: "max", kind: "messages", aliases: [], command: "max", opens: MESSENGER_OPENS },
     { name: "max-bot", kind: "messages", aliases: [] },
-    { name: "whatsapp", kind: "messages", aliases: ["wa"], command: "wa" },
+    { name: "whatsapp", kind: "messages", aliases: ["wa"], command: "wa", opens: MESSENGER_OPENS },
     { name: "whatsapp-bot", kind: "messages", aliases: ["wa-bot"] },
     { name: "email", kind: "mail", aliases: [] },
     { name: "notes", kind: "notes", aliases: [] },
@@ -58,11 +60,23 @@ const invalid = (message) => {
 const wordOf = (value, what) => typeof value === "string" && WORD.test(value)
     ? value
     : invalid(`${what} is lowercase letters, digits, - and _ — not ${JSON.stringify(value)}`);
+const OPEN_KINDS = new Set(REF_KINDS.map(({ type }) => type).filter((type) => type !== "entity"));
+const COMMAND_WORDS = /^[a-z0-9][a-z0-9_-]*( [a-z0-9][a-z0-9_-]*)*$/;
+/** A kind this build does not know is dropped, not refused: a newer CLI may open kinds added after this release. */
+const opensOf = (value, named) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return invalid(`provider ${named}'s opens maps a kind of reference to a command`);
+    const known = Object.entries(value).filter(([kind]) => OPEN_KINDS.has(kind));
+    for (const [kind, command] of known)
+        if (typeof command !== "string" || !COMMAND_WORDS.test(command))
+            invalid(`provider ${named} opens a ${kind} with command words, not ${JSON.stringify(command)}`);
+    return Object.fromEntries(known);
+};
 /** An entry as a CLI or the store gives it, checked: anything else is a `validation_error`. */
 export const providerEntryOf = (value) => {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return invalid("a provider entry is an object");
-    const { name, kind, aliases = [], command } = value;
+    const { name, kind, aliases = [], command, opens } = value;
     const named = wordOf(name, "a provider's name");
     if (typeof kind !== "string" || !KINDS.includes(kind))
         invalid(`provider ${named}'s kind is one of ${KINDS.join(", ")} — not ${JSON.stringify(kind)}`);
@@ -73,6 +87,7 @@ export const providerEntryOf = (value) => {
         kind: kind,
         aliases: [...new Set(aliases.map((alias) => wordOf(alias, `an alias of ${named}`)))],
         ...(command === undefined ? {} : { command: wordOf(command, `the command of ${named}`) }),
+        ...(opens === undefined ? {} : { opens: opensOf(opens, named) }),
     };
 };
 const describe = ({ name, kind, command }) => `${name} (${kind}${command ? `, from ${command}` : ""})`;
@@ -87,6 +102,7 @@ const joined = (known, entry) => {
             ...same,
             aliases: [...new Set([...same.aliases, ...entry.aliases])],
             ...(entry.command ? { command: entry.command } : {}),
+            ...(entry.opens ? { opens: { ...same.opens, ...entry.opens } } : {}),
         }
         : entry;
     const others = known.filter((one) => one !== same);

package/dist/domain/ref-arguments.js

@@ -5,18 +5,14 @@ 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 entry = providerNamed(provider);
+    const command = entry?.command;
+    const opens = kind === "entity" ? undefined : entry?.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}`, {

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

@@ -0,0 +1,56 @@
+import type { RefKindName } from "./references.js";
+export type RefState = "available" | "deleted" | "unavailable";
+/** A message or chat of the `email` provider is mail, so it reads as `email` and `email_thread`. */
+export type RefSummaryKind = RefKindName | "email" | "email_thread" | "unknown";
+/** What a reference names, read from the store in one batch so a page of refs costs one query per kind. */
+export interface RefSummary {
+    /** Canonical spelling; the map key is the text the caller passed. */
+    ref: string;
+    kind: RefSummaryKind;
+    /** One line, at most 120 characters, never a message body. `null` when the store has no title. */
+    title: string | null;
+    /** What holds it, one line: a message's chat title, a task's project, a document's provider label. */
+    in: string | null;
+    /** ISO 8601 UTC. */
+    at: string | null;
+    provider: string | null;
+    /** The external id of the account that holds it, for `ProfilesFor`; `null` when it belongs to no account. */
+    account: string | null;
+    /** The CLI that opens it (`max`, `tg`, `drive`); `null` when no CLI has registered the provider. */
+    tool: string | null;
+    state: RefState;
+    /** Only with `{ excerpt: true }`: at most 280 characters of the body. */
+    excerpt?: string | null;
+}
+export interface RefsStore {
+    /** One query per kind present. Never throws for a bad ref: it comes back `unknown`, `unavailable`. */
+    summaries(refs: readonly string[], options?: {
+        excerpt?: boolean;
+    }): Promise<Map<string, RefSummary>>;
+}
+/** The caller's answer to "which profile opens this": one signed in, or the choices and why there is not one. */
+export type ProfilesFor = (provider: string, account: string | null) => {
+    profile: string;
+} | {
+    why: string;
+    profiles: string[];
+};
+export interface RefOpen {
+    /** Ready to run; contains `<profile>` when `profiles` is not exactly one. `null` when no CLI opens it. */
+    argv: string[] | null;
+    profiles: string[];
+    why: string | null;
+}
+export declare const PROFILE_PLACEHOLDER = "<profile>";
+/** A title from someone else's text, as one line: a newline in it would break every row it is printed in. */
+export declare const oneLine: (text: string) => string;
+/**
+ * The command that opens a ref. A registered provider opens its own kinds; anything else opens with the caller's
+ * `local` words (memo's `notes show`). The profile is never picked: with none or several, `argv` keeps `<profile>`.
+ */
+export declare const openOf: (summary: RefSummary, ports: {
+    profilesFor: ProfilesFor;
+    local?: Partial<Record<RefKindName, string[]>>;
+}) => RefOpen;
+/** `Chat «Сайт + автоматизация» (MAX)`: the one label every review row, status line and `show` prints. */
+export declare const refLabel: (summary: RefSummary) => string;

package/dist/domain/ref-summaries.js

@@ -0,0 +1,63 @@
+import { singleLine } from "@wirecat/cli-base";
+import { providerNamed } from "./providers.js";
+export const PROFILE_PLACEHOLDER = "<profile>";
+/** A title from someone else's text, as one line: a newline in it would break every row it is printed in. */
+export const oneLine = (text) => singleLine(text.replace(/\s+/g, " ").trim());
+/** Mail is a message and a chat to the provider registry: `opens` is keyed by the reference kind. */
+const openKind = (kind) => kind === "email" ? "message" : kind === "email_thread" ? "chat" : kind === "unknown" ? undefined : kind;
+/**
+ * The command that opens a ref. A registered provider opens its own kinds; anything else opens with the caller's
+ * `local` words (memo's `notes show`). The profile is never picked: with none or several, `argv` keeps `<profile>`.
+ */
+export const openOf = (summary, ports) => {
+    const kind = openKind(summary.kind);
+    if (kind === undefined)
+        return { argv: null, profiles: [], why: `${summary.ref} is not a reference` };
+    const entry = summary.provider === null ? undefined : providerNamed(summary.provider);
+    const words = entry?.command === undefined ? undefined : entry.opens?.[kind];
+    if (entry?.command !== undefined && words !== undefined && summary.provider !== null) {
+        const command = [...words.split(" "), summary.ref];
+        const asked = ports.profilesFor(summary.provider, summary.account);
+        return "profile" in asked
+            ? { argv: [entry.command, asked.profile, ...command], profiles: [asked.profile], why: null }
+            : { argv: [entry.command, PROFILE_PLACEHOLDER, ...command], profiles: asked.profiles, why: asked.why };
+    }
+    const local = ports.local?.[kind];
+    if (local !== undefined)
+        return { argv: [...local, summary.ref], profiles: [], why: null };
+    return {
+        argv: null,
+        profiles: [],
+        why: summary.provider === null
+            ? `nothing here opens a ${kind}`
+            : `no CLI has registered ${summary.provider} in this store yet; run its CLI once`,
+    };
+};
+const WORDS = {
+    message: "Message",
+    chat: "Chat",
+    contact: "Contact",
+    folder: "Folder",
+    meeting: "Meeting",
+    event: "Event",
+    note: "Note",
+    document: "Document",
+    person: "Person",
+    organization: "Organization",
+    project: "Project",
+    task: "Task",
+    memory: "Memory",
+    fact: "Fact",
+    bot: "Bot",
+    email: "Email",
+    email_thread: "Email thread",
+    unknown: "Unknown",
+};
+/** `Chat «Сайт + автоматизация» (MAX)`: the one label every review row, status line and `show` prints. */
+export const refLabel = (summary) => {
+    const named = summary.title === null ? summary.ref : `«${oneLine(summary.title)}»`;
+    const notes = [summary.in === null ? null : oneLine(summary.in), summary.state === "available" ? null : summary.state]
+        .filter((one) => one !== null)
+        .join(", ");
+    return `${WORDS[summary.kind]} ${named}${notes === "" ? "" : ` (${notes})`}`;
+};