@wirecat/cli-core 0.596.0 → 0.597.0

package/CHANGELOG.md

@@ -5,6 +5,56 @@ Notable changes to `@wirecat/cli-core` (`@wirecat/cli-messaging` up to 0.261.0,
 minor version may break callers, and says how under "Changed — may break callers". `pnpm docs:check` checks the
 shape of this file.
 
+## Unreleased
+
+## 0.597.0 — 07.11.2026
+
+### Added
+
+- **`--field` by label.** CRM `create` and `update` resolve `--field <key>=<value>` by the synced field definitions:
+  a field by its code or whole label (a label two fields share is refused as `field.ambiguous` with both codes, an
+  unknown one as `field.unknown` with close candidates), a list field's option by its id or label
+  (`field.unknown-option`), and a multiple field's repeats into a list; a single field given twice is refused. A CRM
+  whose definitions are not stored takes codes as typed.
+- **`CrmWrites.alsoChecks(kind, verb)`**: a CLI's own keys a write also checks, such as `api.crm.deal.update`.
+  `crmAlsoChecks(also)` gives `commandPermissions({ alsoChecks })` every key a CRM write may check, so `--dry-run`
+  names the implied move, close and `crm.assign-others` keys and the CLI's own. A key an argument implies is a
+  `ConditionalKey` `{ key, when }`: `commandPermissions({ alsoChecks })` may return one, and the preview shows its level
+  and `when` but never refuses on it.
+- **A deal's and lead's `provider_metadata` and `assignee`.** The CRM's own field values, by code as
+  `{ label, value, option_id? }` (`CrmValue`), kept as stored in `metadata`, codes never renamed; `CrmItem.assignee`, the
+  CRM user it is assigned to, answered as the identity `<account>/user/<id>`.
+- **CRM field definitions (store version 54).** `CrmSource.fields?(kind)` lists a CRM's own fields on deals, leads,
+  contacts or companies: `CrmField` `{ code, label, type, multiple, filterable, options? }`. `syncCrm` reads them every
+  run, after the pipelines, and `store.crm.saveFields` keeps each kind's whole list in `crm_fields`: one the CRM no
+  longer lists is marked deleted, and an empty list marks them all. `store.crm.fields(account, kind)` reads them in
+  the CRM's order. Values stay in `metadata`, keyed by code. The migration adds one table; `minCompatible` stays 34.
+- **`fields list <deals|leads|people|organizations>`** in `addCrmCommands`: the synced fields of one kind, with
+  `--limit`, `--page` and `--all`, in bitrix24-cli's `fields list` shape plus `untrusted`. An unknown kind is refused
+  as `field.unknown-kind` with the allowed words.
+- **`crmSourceContract` checks `fields()`** when an adapter has it, and `crmSyncContract` checks they are stored. The
+  fake CRM has `setFields`, `calls.fields` and `SOURCE_FIELD` on its deals.
+- **A schedule's Telegram delivery is Telegram HTML.** `--to telegram-bot:<profile>/<chat>` converts the report's
+  Markdown (headings, bold, italic, code, links, lists, tables as label lines, rules) to the tags `tg` accepts and
+  sends it with `--html`; the 4096 and 1024 character limits count the converted text, and a long report's caption
+  is cut until its HTML fits. When `tg` answers `validation_error`, the send is repeated once as plain text and
+  recorded as `delivery.html-fallback`; any other failure is never resent. Email stays plain text.
+
+### Changed — may break callers
+
+- **`CrmFieldsInput.custom` is the `--field` pairs as typed** (`[name, value][]`), and `CrmFields.custom` values may be
+  a list for a multiple field.
+- **A write the CRM made whose item could not be read back is journaled as sent.** A `CrmWriter` throws it with
+  `sent: true` in the details; the error is answered with the write's `operation_id`, no longer journaled as failed.
+- **A CRM sync with `fields()` makes one more request per kind**, so a `--max-pages` budget reaches the items later.
+
+### Fixed
+
+- **A search over a read-only store no longer fails with "attempt to write a readonly database".** The message index
+  top-up and the notes, mail, events, memories and tasks index drains are skipped on a connection with `query_only`
+  (every read-only open), so `search all` in a CRM CLI answers from every source of a store only a CRM sync wrote. They
+  run on the next writable open.
+
 ## 0.596.0 — 06.11.2026
 
 ### Added

package/dist/background/deliver.d.ts

@@ -22,9 +22,13 @@ export declare const DELIVERY_REASONS: {
     readonly routeInvalid: "delivery.route-invalid";
     readonly timeout: "delivery.timeout";
     readonly failed: "delivery.failed";
+    readonly htmlFallback: "delivery.html-fallback";
 };
 export type DeliveryReason = (typeof DELIVERY_REASONS)[keyof typeof DELIVERY_REASONS];
-/** One route's outcome, kept in `last.json`. `error` is the sending CLI's error code and reason id, never its message. */
+/**
+ * One route's outcome, kept in `last.json`. `error` is the sending CLI's error code and reason id, never its message.
+ * A send that went as plain text because Telegram refused the HTML is `ok` with the `html-fallback` reason.
+ */
 export interface Delivery {
     to: string;
     ok: boolean;
@@ -46,6 +50,8 @@ export interface Parcel {
     /** A failed run: one line, no file. */
     line?: string;
 }
+/** The caption as HTML: the head is cut in Markdown, where no tag can be split, and cut shorter until its HTML fits. */
+export declare const htmlHeadOf: (title: string, report: string, limit?: number) => string;
 /** Hands the parcel to each route's CLI, one after another; a route that fails is recorded and the next one still goes. */
 export declare const deliver: (system: ServerSystem, env: NodeJS.ProcessEnv, routes: readonly string[], parcel: Parcel, { find, errorOf, locked, timeoutMs, }: {
     /** Where a program is on the run's PATH. */

package/dist/background/deliver.js

@@ -3,6 +3,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { CliError } from "@wirecat/cli-base";
 import { TIMED_OUT } from "./system.js";
+import { toTelegramHtml } from "./telegram-html.js";
 const PROGRAMS = {
     "telegram-bot": { command: "tg", prefix: "TG" },
     email: { command: "mail", prefix: "MAIL" },
@@ -36,6 +37,7 @@ export const DELIVERY_REASONS = {
     routeInvalid: "delivery.route-invalid",
     timeout: "delivery.timeout",
     failed: "delivery.failed",
+    htmlFallback: "delivery.html-fallback",
 };
 /** Telegram's limits, in UTF-16 units as JavaScript counts them: a message's text, and a file's caption. */
 export const TELEGRAM_TEXT_CHARS = 4096;
@@ -52,17 +54,61 @@ export const headOf = (title, report, limit = CAPTION_CHARS) => {
     const line = cut.lastIndexOf("\n");
     return `${title}\n${line > room / 2 ? cut.slice(0, line) : cut}${more}`;
 };
+/**
+ * `tg` answers a 400 from Telegram, which is what a refused HTML text is, as `validation_error`, and says nothing
+ * more exact. Any other code (network_error, outcome_unknown, provider_error…) may mean the message arrived.
+ */
+const REFUSED_CONTENT = "validation_error";
+const codeOf = (stderr) => {
+    for (const line of stderr.split("\n").reverse()) {
+        try {
+            const { code } = JSON.parse(line).error ?? {};
+            if (typeof code === "string")
+                return code;
+        }
+        catch { }
+    }
+};
+const textOf = (title, report) => (report.trim() ? `${title}\n${report.trim()}` : title);
+/** The same text as Telegram HTML; the length that counts against the limits is this one. */
+const htmlOf = (title, report) => toTelegramHtml(textOf(title, report));
+/** The caption as HTML: the head is cut in Markdown, where no tag can be split, and cut shorter until its HTML fits. */
+export const htmlHeadOf = (title, report, limit = CAPTION_CHARS) => {
+    let room = limit;
+    for (;;) {
+        const html = toTelegramHtml(headOf(title, report, room));
+        if (html.length <= limit || room <= title.length + 40)
+            return html.slice(0, limit);
+        room -= Math.max(html.length - limit, 1);
+    }
+};
 /**
  * The words that send along `route`. A bot sends a report that fits one message as its text, and a longer one as a
- * file with its head as the caption; mail takes the text on stdin. The text goes after `--`, so a report that starts
- * with a dash stays text.
+ * file with its head as the caption, both as Telegram HTML unless `plain`; mail takes the text on stdin. The text goes
+ * after `--`, so a report that starts with a dash stays text.
  */
-const argvOf = (program, route, title, report, copy) => {
+const argvOf = (program, route, title, report, copy, plain = false) => {
     const lead = [program, route.profile, "--json", "--no-input"];
     if (route.kind === "email")
         return [...lead, "messages", "send", "--to", route.address, "--subject", title];
-    const text = copy ? headOf(title, report) : report.trim() ? `${title}\n${report.trim()}` : title;
-    return [...lead, "bot", "messages", "send", ...(copy ? ["--file", copy] : []), "--", route.chat, text];
+    const text = plain
+        ? copy
+            ? headOf(title, report)
+            : headOf(title, report, TELEGRAM_TEXT_CHARS)
+        : copy
+            ? htmlHeadOf(title, report)
+            : htmlOf(title, report);
+    return [
+        ...lead,
+        "bot",
+        "messages",
+        "send",
+        ...(copy ? ["--file", copy] : []),
+        ...(plain ? [] : ["--html"]),
+        "--",
+        route.chat,
+        text,
+    ];
 };
 /** Hands the parcel to each route's CLI, one after another; a route that fails is recorded and the next one still goes. */
 export const deliver = async (system, env, routes, parcel, { find, errorOf, locked, timeoutMs = DELIVERY_TIMEOUT_MS, }) => {
@@ -94,7 +140,7 @@ export const deliver = async (system, env, routes, parcel, { find, errorOf, lock
             out.push(failed(to, DELIVERY_REASONS.programMissing, command));
             continue;
         }
-        const tooLong = `${parcel.title}\n${report.trim()}`.length > TELEGRAM_TEXT_CHARS;
+        const tooLong = route.kind === "telegram-bot" && htmlOf(parcel.title, report).length > TELEGRAM_TEXT_CHARS;
         // The sending CLI refuses its own and the other WireCat folders, where the report lives, so it gets a copy.
         const folder = route.kind === "telegram-bot" && parcel.file && tooLong ? mkdtempSync(join(tmpdir(), "wirecat-deliver-")) : "";
         const copy = folder && parcel.file ? join(folder, parcel.file.name) : undefined;
@@ -102,12 +148,22 @@ export const deliver = async (system, env, routes, parcel, { find, errorOf, lock
             if (copy && parcel.file)
                 copyFileSync(parcel.file.path, copy);
             const { [`${prefix}_PROFILE`]: _, ...childEnv } = env;
-            const ran = await system.run(argvOf(program, route, parcel.title, report, copy), childEnv, {
+            const options = {
                 timeoutMs,
                 ...(route.kind === "email" ? { input: report.trim() ? report : parcel.title } : {}),
-            });
-            if (ran.code === 0)
-                out.push({ to, ok: true });
+            };
+            let ran = await system.run(argvOf(program, route, parcel.title, report, copy), childEnv, options);
+            let fellBack = "";
+            if (route.kind === "telegram-bot" &&
+                ran.code !== 0 &&
+                ran.code !== TIMED_OUT &&
+                codeOf(ran.stderr) === REFUSED_CONTENT) {
+                fellBack = errorOf(ran.stderr, ran.code);
+                ran = await system.run(argvOf(program, route, parcel.title, report, copy, true), childEnv, options);
+            }
+            if (ran.code === 0) {
+                out.push(fellBack ? { to, ok: true, reason: DELIVERY_REASONS.htmlFallback, error: fellBack } : { to, ok: true });
+            }
             else if (ran.code === TIMED_OUT)
                 out.push(failed(to, DELIVERY_REASONS.timeout));
             else

package/dist/background/telegram-html.d.ts

@@ -0,0 +1,2 @@
+/** The report's common Markdown as Telegram HTML (<b>, <i>, <a>, <code>, <pre>); everything else is escaped text. */
+export declare const toTelegramHtml: (markdown: string) => string;

package/dist/background/telegram-html.js

@@ -0,0 +1,66 @@
+const esc = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+const SLOT = "\u0000";
+/** Inline Markdown to the tags Telegram's HTML accepts; code and links are set aside first so nothing inside them is touched. */
+const inline = (text) => {
+    const kept = [];
+    const keep = (html) => `${SLOT}${kept.push(html) - 1}${SLOT}`;
+    const done = esc(text.replaceAll(SLOT, ""))
+        .replace(/`([^`\n]+)`/g, (_, code) => keep(`<code>${code}</code>`))
+        .replace(/\[([^\]\n]+)\]\((https?:\/\/[^\s)"]+)\)/g, (_, label, url) => keep(`<a href="${url}">${label}</a>`))
+        .replace(/\*\*(?=\S)(.+?)(?<=\S)\*\*|__(?=\S)(.+?)(?<=\S)__/g, (_, a, b) => `<b>${a ?? b}</b>`)
+        .replace(/(?<![\w*])\*(?=[^\s*])([^*\n]+?)(?<=[^\s*])\*(?![\w*])/g, "<i>$1</i>")
+        .replace(/(?<!\w)_(?=[^\s_])([^_\n]+?)(?<=[^\s_])_(?!\w)/g, "<i>$1</i>");
+    return done.replace(new RegExp(`${SLOT}(\\d+)${SLOT}`, "g"), (_, at) => kept[Number(at)] ?? "");
+};
+const cells = (row) => row
+    .trim()
+    .replace(/^\||\|$/g, "")
+    .split("|")
+    .map((cell) => cell.trim());
+const isRule = (row) => /^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*$/.test(row);
+/** A table has no Telegram form: each row becomes a bullet, its first cell the label and the rest `header: value`. */
+const tableLines = (rows) => {
+    const [head = [], ...body] = rows.filter((row) => !isRule(row)).map(cells);
+    return body.map(([first = "", ...rest]) => {
+        const parts = rest.map((cell, at) => {
+            const name = head[at + 1];
+            return name && rest.length > 1 ? `${name}: ${inline(cell)}` : inline(cell);
+        });
+        return `• ${parts.length ? `<b>${inline(first)}</b>: ${parts.join(" · ")}` : inline(first)}`;
+    });
+};
+/** The report's common Markdown as Telegram HTML (<b>, <i>, <a>, <code>, <pre>); everything else is escaped text. */
+export const toTelegramHtml = (markdown) => {
+    const out = [];
+    const lines = markdown.replace(/\r\n?/g, "\n").split("\n");
+    for (let at = 0; at < lines.length; at += 1) {
+        const line = lines[at] ?? "";
+        if (/^\s*```/.test(line)) {
+            const code = [];
+            at += 1;
+            while (at < lines.length && !/^\s*```/.test(lines[at] ?? ""))
+                code.push(lines[at++] ?? "");
+            out.push(`<pre>${esc(code.join("\n"))}</pre>`);
+        }
+        else if (/^\s*\|.*\|\s*$/.test(line)) {
+            const rows = [line];
+            while (/^\s*\|.*\|\s*$/.test(lines[at + 1] ?? "")) {
+                at += 1;
+                rows.push(lines[at] ?? "");
+            }
+            for (const row of tableLines(rows))
+                out.push(row);
+        }
+        else if (/^#{1,6}\s+\S/.test(line)) {
+            out.push(`<b>${inline(line.replace(/^#{1,6}\s+/, "").replace(/\*\*|__/g, "")).trimEnd()}</b>`);
+        }
+        else if (/^\s*([-*_])(\s*\1){2,}\s*$/.test(line)) {
+            out.push("──────");
+        }
+        else {
+            const bullet = /^(\s*)[-*+]\s+(.*)$/.exec(line);
+            out.push(bullet ? `${bullet[1]}• ${inline(bullet[2] ?? "")}` : inline(line));
+        }
+    }
+    return out.join("\n");
+};

package/dist/calendar/mcp/index.d.ts

@@ -10,13 +10,13 @@ export declare const calendarTools: ({
     inputSchema: {
         type: string;
         properties: {
-            limit?: undefined;
             account_id: {
                 type: string;
                 minimum: number;
             };
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
         } | {
@@ -45,9 +45,9 @@ export declare const calendarTools: ({
             };
             event?: undefined;
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event: {
                 type: string;
@@ -58,9 +58,9 @@ export declare const calendarTools: ({
                 minimum: number;
             };
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
             account_id?: undefined;
@@ -80,13 +80,13 @@ export declare const calendarTools: ({
     inputSchema: {
         type: string;
         properties: {
-            limit?: undefined;
             account_id: {
                 type: string;
                 minimum: number;
             };
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
         } | {
@@ -115,9 +115,9 @@ export declare const calendarTools: ({
             };
             event?: undefined;
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event: {
                 type: string;
@@ -128,9 +128,9 @@ export declare const calendarTools: ({
                 minimum: number;
             };
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
             account_id?: undefined;
@@ -150,13 +150,13 @@ export declare const calendarTools: ({
     inputSchema: {
         type: string;
         properties: {
-            limit?: undefined;
             account_id: {
                 type: string;
                 minimum: number;
             };
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
         } | {
@@ -185,9 +185,9 @@ export declare const calendarTools: ({
             };
             event?: undefined;
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event: {
                 type: string;
@@ -198,9 +198,9 @@ export declare const calendarTools: ({
                 minimum: number;
             };
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
             account_id?: undefined;
@@ -220,13 +220,13 @@ export declare const calendarTools: ({
     inputSchema: {
         type: string;
         properties: {
-            limit?: undefined;
             account_id: {
                 type: string;
                 minimum: number;
             };
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
         } | {
@@ -255,9 +255,9 @@ export declare const calendarTools: ({
             };
             event?: undefined;
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event: {
                 type: string;
@@ -268,9 +268,9 @@ export declare const calendarTools: ({
                 minimum: number;
             };
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
             account_id?: undefined;

package/dist/cli/index.d.ts

@@ -115,7 +115,7 @@ export { type Saving, stored } from "./messenger/stored.js";
 export { dateOrNone } from "./messenger/tasks-command.js";
 export { MODEL_CATALOGUE_QUERY, type ModelCatalogueOptions } from "./model-catalogue-command.js";
 export { positiveCount, window, withPaging } from "./paging.js";
-export { type CommandPermissions, commandPathKey, commandPermissions, knownBeside, knownPermissionKeys, type PermissionKeyOf, type PermissionKeySource, refuseUnknownPermissionKeys, unknownPermissionIssues, unknownPermissionKeys, } from "./permission-keys.js";
+export { type CommandPermissions, type ConditionalKey, commandPathKey, commandPermissions, knownBeside, knownPermissionKeys, type PermissionKeyOf, type PermissionKeySource, refuseUnknownPermissionKeys, unknownPermissionIssues, unknownPermissionKeys, } from "./permission-keys.js";
 export { asFirstWord, commandWords, liftProfile, profileFree, refuseCommandName, rootOf, takesProfile, usableProfileName, } from "./profile.js";
 export { createProgram, type ProgramDefinition, type ProgramOptions, type RunOptions, run } from "./program.js";
 export { type ProjectTextHints, projectAnswerParts, projectCutoffTime, projectEvidenceText, projectWindowOf, withSyncCommands, } from "./project-evidence.js";

package/dist/cli/permission-keys.d.ts

@@ -14,8 +14,16 @@ export interface CommandPermissions {
     extra: readonly PermissionKey[];
     /** cli-core's built-in levels and the CLI's own; they only ever tighten. */
     defaults: Readonly<Record<PermissionKey, Level>>;
-    /** The other keys a command's real run checks, so its `--dry-run` preview shows each: gcal's `api.calendar.*`. */
-    alsoChecks?: (path: readonly string[]) => readonly PermissionKey[];
+    /**
+     * The other keys a command's real run checks, so its `--dry-run` preview shows each: gcal's `api.calendar.*`. A
+     * key with `when` is checked only for some arguments, such as a stage that closes a deal: shown, never refused.
+     */
+    alsoChecks?: (path: readonly string[]) => readonly (PermissionKey | ConditionalKey)[];
+}
+/** A key a write checks only when its arguments ask for it; `when` says which, in a few words. */
+export interface ConditionalKey {
+    key: PermissionKey;
+    when: string;
 }
 /** Either way of naming a program's keys: a messenger's per-command mapping, or a declared CLI's own. */
 export type PermissionKeySource = PermissionKeyOf | CommandPermissions;

package/dist/cli/preview.d.ts

@@ -13,6 +13,7 @@ export declare const preview: (command: Command, settings: Pick<Settings, "permi
         also?: {
             key: PermissionKey;
             level: string;
+            when?: string;
         }[];
     } | undefined;
     validation: {
@@ -49,6 +50,7 @@ export declare const previewBody: (command: Command, permission: {
     also?: {
         key: PermissionKey;
         level: string;
+        when?: string;
     }[];
 } | undefined, messenger: boolean) => {
     preview: boolean;
@@ -59,6 +61,7 @@ export declare const previewBody: (command: Command, permission: {
         also?: {
             key: PermissionKey;
             level: string;
+            when?: string;
         }[];
     } | undefined;
     validation: {

package/dist/cli/preview.js

@@ -23,11 +23,15 @@ export const preview = (command, settings, tool, keys, messenger = true) => {
         (!declared && key !== null && key !== undefined && WRITE_KEYS.includes(key));
     if (level === "deny" || (writes && level === "readonly"))
         throw new CliError("permission_error", `this profile does not permit ${path.join(" ")}`, { permission: key });
-    const also = (declared?.alsoChecks?.(path) ?? []).map((one) => ({
-        key: one,
-        level: levelFor(permissions, one, declared?.defaults).level,
-    }));
-    const stopped = also.find((one) => one.level === "deny" || (writes && one.level === "readonly"));
+    const also = (declared?.alsoChecks?.(path) ?? []).map((one) => {
+        const key = typeof one === "string" ? one : one.key;
+        return {
+            key,
+            level: levelFor(permissions, key, declared?.defaults).level,
+            ...(typeof one === "string" ? {} : { when: one.when }),
+        };
+    });
+    const stopped = also.find((one) => one.when === undefined && (one.level === "deny" || (writes && one.level === "readonly")));
     if (stopped)
         throw new CliError("permission_error", `this profile does not permit ${stopped.key}`, { permission: stopped.key });
     return previewBody(command, { key: key ?? null, level, ...(also.length ? { also } : {}) }, messenger);

package/dist/crm/cli/index.js

@@ -6,8 +6,8 @@ import { answerEntity } from "../../cli/answer-entity.js";
 import { environmentOf, outputFor, runBudgetOf } from "../../cli/context.js";
 import { honoursDryRun } from "../../cli/dry-run-guard.js";
 import { FETCH, LOCAL_READ, NO_EFFECTS, REMOTE_WRITE } from "../../cli/effects.js";
-import { itemOf, listOf, renderAnswer, snakeKeys } from "../../cli/envelope.js";
-import { queryTerms, termField, withQuery } from "../../cli/list-query.js";
+import { itemOf, listOf, renderAnswer, snakeKeys, snakeKeysKeeping } from "../../cli/envelope.js";
+import { queryTerms, termField, unfilteredQuery, withQuery } from "../../cli/list-query.js";
 import { terminalAsker } from "../../cli/messenger/ask.js";
 import { lineOf } from "../../cli/steps.js";
 import { CRM_KINDS } from "../../domain/crm.js";
@@ -41,7 +41,15 @@ export const STAGES_QUERY = {
     ],
 };
 /** A CRM's users typed these; a list item names its own, as `events list` does. */
-const DEAL_UNTRUSTED = ["title", "summary", "stage", "pipeline_name", "organization.name", "people.name"];
+const DEAL_UNTRUSTED = [
+    "title",
+    "summary",
+    "stage",
+    "pipeline_name",
+    "organization.name",
+    "people.name",
+    "provider_metadata",
+];
 const PIPELINE_UNTRUSTED = ["name", "stages.name"];
 const STAGE_UNTRUSTED = ["name", "pipeline_name"];
 const crmSync = v.strictObject({
@@ -92,18 +100,36 @@ const crmWrite = v.strictObject({
     lead: v.optional(dealEntity),
     untrusted: v.array(text),
 });
+/** b24's `fields list` answer, so a CRM CLI's own command can go; `untrusted` names what the CRM's users typed. */
+const crmField = v.strictObject({
+    code: v.string(),
+    label: v.nullable(v.string()),
+    type: v.string(),
+    multiple: v.boolean(),
+    filterable: v.boolean(),
+    options: v.optional(v.array(v.strictObject({ id: v.string(), label: v.string() }))),
+    untrusted: v.array(text),
+});
+const FIELDS_QUERY = unfilteredQuery("crm_field", crmField);
+const FIELD_UNTRUSTED = ["label", "options.label"];
+/** The words `fields list` takes: its sibling commands' nouns. */
+const FIELD_KINDS = {
+    deals: "deal",
+    leads: "lead",
+    people: "person",
+    organizations: "organization",
+};
 const crmRemoval = v.strictObject({ operation_id: text, ref: text, removed: count });
 const collect = (value, previous = []) => {
     if (value.indexOf("=") < 1)
-        throw new InvalidArgumentError("expected code=value");
+        throw new InvalidArgumentError("expected key=value");
     return [...previous, value];
 };
-/** `--field code=value` pairs; an empty value clears the field. */
-const customOf = (pairs) => Object.fromEntries(pairs.map((pair) => {
+/** `--field` as typed, split at the first `=`. */
+const pairsOf = (typed) => typed.map((pair) => {
     const at = pair.indexOf("=");
-    const given = pair.slice(at + 1);
-    return [pair.slice(0, at), given === "" ? null : given];
-}));
+    return [pair.slice(0, at), pair.slice(at + 1)];
+});
 const integer = (most) => (value) => {
     if (!/^[1-9]\d*$/.test(value) || Number(value) > most)
         throw new InvalidArgumentError(`expected 1 to ${most}`);
@@ -111,7 +137,9 @@ const integer = (most) => (value) => {
 };
 /** The words below the program, as `page.next` and `sync`'s next step run it again. */
 const pathOf = (command) => command.parent?.parent ? [...pathOf(command.parent), command.name()] : [command.name()];
-const marked = (items, untrusted) => items.map((item) => ({ ...snakeKeys(item), untrusted }));
+/** A CRM's own field codes are its keys, never ours to rename. */
+const dealKeys = snakeKeysKeeping(["providerMetadata"]);
+const marked = (items, untrusted) => items.map((item) => ({ ...dealKeys(item), untrusted }));
 const addCrmCommandsDefinition = (program, options) => {
     const now = () => options.now?.() ?? Date.now();
     const within = async (command, work) => {
@@ -237,7 +265,7 @@ const addCrmCommandsDefinition = (program, options) => {
             .argument("<ref>", `${kind}:<id>, as a list shows it`), `${plural} show ${kind}:12`).action(async (reference, _opts, command) => {
             await within(command, async (run) => {
                 const found = await ownCopy(run, kind, reference);
-                return itemOf({ ...snakeKeys(found), untrusted: DEAL_UNTRUSTED });
+                return itemOf({ ...dealKeys(found), untrusted: DEAL_UNTRUSTED });
             });
         });
         addWrites(group, kind);
@@ -272,7 +300,7 @@ const addCrmCommandsDefinition = (program, options) => {
         };
         const answered = (operationId, item) => itemOf({
             operation_id: operationId,
-            [kind]: { ...snakeKeys(item), untrusted: DEAL_UNTRUSTED },
+            [kind]: { ...dealKeys(item), untrusted: DEAL_UNTRUSTED },
             untrusted: DEAL_UNTRUSTED.map((field) => `${kind}.${field}`),
         });
         const write = (name, verb, description) => {
@@ -292,12 +320,14 @@ const addCrmCommandsDefinition = (program, options) => {
             .option("--currency <code>", "an ISO 4217 code, such as EUR")
             .option("--close-date <date>", "the day it is expected to close, YYYY-MM-DD")
             .option("--owner <user>", "the CRM user it is assigned to; anyone but the sign-in's own user checks crm.assign-others")
-            .option("--field <key=value>", "one of the CRM's own fields, by its code; repeat for more, empty clears it", collect, 
+            .option("--field <key=value>", "one of the CRM's own fields, by its code or label as `fields list` prints them, and its value; a list " +
+            "field takes its option's label or id; repeat it for more fields, or for each value of a multiple field; " +
+            "an empty value clears it", collect, 
         // The empty default marks the flag as repeatable, so an agent's tool takes a list.
         []);
         const inputOf = ({ field, operationId: _id, ...rest }) => ({
             ...Object.fromEntries(Object.entries(rest).filter(([, value]) => value !== undefined)),
-            ...(field?.length ? { custom: customOf(field) } : {}),
+            ...(field?.length ? { custom: pairsOf(field) } : {}),
         });
         const idOf = (opts) => opts.operationId === undefined ? {} : { operationId: opts.operationId };
         const run = (command, work) => within(command, (opened) => work(contextOf(opened, command)));
@@ -408,6 +438,33 @@ const addCrmCommandsDefinition = (program, options) => {
             });
         });
     });
+    const fieldKinds = Object.keys(FIELD_KINDS).filter((word) => word !== "leads" || options.leads !== false);
+    const fields = annotate(program.command("fields"), { effects: NO_EFFECTS }).description("the CRM's own fields on deals, leads, people and organizations, as last synced");
+    example(withQuery(answerEntity(annotate(fields.command("list"), { effects: LOCAL_READ }), "crm_field", crmField)
+        .description("the CRM's custom fields of one kind, in its order, with a list field's options")
+        .argument("<kind>", fieldKinds.join(", "))
+        .option("--limit <n>", `fields per page, 1–${MOST}`, integer(MOST), 50)
+        .option("--page <n>", "which page, starting at 1", integer(1_000_000), 1)
+        .option("--all", "every field, no paging"), FIELDS_QUERY), "fields list deals", "fields list people --json").action(async (kind, words, opts, command) => {
+        if (!fieldKinds.includes(kind))
+            throw new CliError("validation_error", `fields are listed for ${fieldKinds.join(", ")}; got ${kind}`, {
+                reason: "field.unknown-kind",
+                allowed: fieldKinds,
+            });
+        queryTerms(words, FIELDS_QUERY, "fields list");
+        await within(command, async (run) => {
+            const found = await run.store.crm.fields(run.account, FIELD_KINDS[kind]);
+            const offset = opts.all ? 0 : (opts.page - 1) * opts.limit;
+            const end = opts.all ? found.length : offset + opts.limit;
+            return listOf(pathOf(command).join(" "), {
+                items: found.slice(offset, end).map((field) => ({ ...field, untrusted: FIELD_UNTRUSTED })),
+                limit: opts.all ? Math.max(1, found.length) : opts.limit,
+                page: opts.page,
+                has_more: found.length > end,
+                ...(words.length ? { args: { query: words } } : {}),
+            });
+        });
+    });
     const search = program.commands.find((one) => one.name() === "search") ??
         annotate(program.command("search"), { effects: NO_EFFECTS }).description("search what the local store holds");
     addCrmSearchAll(search, { within, app: options.app, example });

package/dist/crm/index.d.ts

@@ -1,4 +1,4 @@
 export type { CrmChanges, CrmIdPage, CrmPage, CrmSource, CrmSourceTraits } from "./source.js";
 export { type CrmCursor, type CrmSyncIssue, type CrmSyncOptions, type CrmSyncReport, type CrmSyncResult, crmStatus, cursorName, parseCrmCursor, syncCrm, } from "./sync.js";
-export { CRM_ASSIGN_OTHERS_KEY, CRM_VERBS, CRM_WRITE_DEFAULTS, CRM_WRITE_KEYS, type CrmDraft, type CrmFields, type CrmVerb, type CrmWriteCapabilities, type CrmWriteOptions, type CrmWriter, } from "./writer.js";
+export { CRM_ASSIGN_OTHERS_KEY, CRM_VERBS, CRM_WRITE_DEFAULTS, CRM_WRITE_KEYS, type CrmDraft, type CrmFields, type CrmVerb, type CrmWriteCapabilities, type CrmWriteOptions, type CrmWriter, crmAlsoChecks, } from "./writer.js";
 export { type CrmFieldsInput, type CrmWriteContext, type CrmWrites, type CrmWritten, closeCrmItem, createCrmItem, moveCrmItem, removeCrmItem, updateCrmItem, } from "./writes.js";