@wirecat/cli-core 0.595.0 → 0.597.0

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";

package/dist/crm/index.js

@@ -1,3 +1,3 @@
 export { crmStatus, cursorName, parseCrmCursor, syncCrm, } from "./sync.js";
-export { CRM_ASSIGN_OTHERS_KEY, CRM_VERBS, CRM_WRITE_DEFAULTS, CRM_WRITE_KEYS, } from "./writer.js";
+export { CRM_ASSIGN_OTHERS_KEY, CRM_VERBS, CRM_WRITE_DEFAULTS, CRM_WRITE_KEYS, crmAlsoChecks, } from "./writer.js";
 export { closeCrmItem, createCrmItem, moveCrmItem, removeCrmItem, updateCrmItem, } from "./writes.js";

package/dist/crm/source.d.ts

@@ -1,4 +1,4 @@
-import type { CrmKind, CrmPipeline, CrmRecords } from "../domain/crm.js";
+import type { CrmField, CrmKind, CrmPipeline, CrmRecords } from "../domain/crm.js";
 import type { DealKind } from "../domain/deals.js";
 export interface CrmSourceTraits {
     /** What this CRM has: one without leads leaves `lead` out. Contacts and companies come before the items on them. */
@@ -38,6 +38,11 @@ export interface CrmSource {
      * reads by its own modified time, with an overlap, and gives that time back as the cursor.
      */
     changes<K extends CrmKind>(kind: K, cursor: string | null, page?: string): Promise<CrmChanges<CrmRecords[K]>>;
+    /**
+     * The CRM's own fields on one kind, in its order: what the codes in a row's `metadata` mean. Read every sync; a CRM
+     * without custom fields leaves it out, and one that has none on a kind answers `[]`.
+     */
+    fields?(kind: CrmKind): Promise<CrmField[]>;
     /** Every id the CRM holds of the kind, a page at a time: how deletions are found when `removedInChanges` is false. */
     ids?(kind: CrmKind, page?: string): Promise<CrmIdPage>;
 }

package/dist/crm/sync.d.ts

@@ -87,10 +87,11 @@ export interface CrmSyncReport {
     hint?: string;
 }
 /**
- * Brings one CRM account's copy up to date: both kinds' pipelines, then contacts, companies, deals and leads, each
- * from its cursor or listed in full, a page at a time, each page saved with the round's place in the cursor, so a
- * run the budget stops, or one that fails, goes on from there. Deletions come from `changes()`, or from a list of
- * every id that marks only after its last page arrived, and never more than half of a kind without `--rescan`.
+ * Brings one CRM account's copy up to date: both kinds' pipelines and each kind's fields, then contacts, companies,
+ * deals and leads, each from its cursor or listed in full, a page at a time, each page saved with the round's place in
+ * the cursor, so a run the budget stops, or one that fails, goes on from there. Deletions come from `changes()`, or
+ * from a list of every id that marks only after its last page arrived, and never more than half of a kind without
+ * `--rescan`.
  */
 export declare const syncCrm: (source: CrmSource, store: MessageStore, account: AccountKey, options?: CrmSyncOptions) => Promise<CrmSyncReport>;
 /** Each kind's sync in the WC-LIFE-14 shape: `cursor_age_ms` growing on a `partial` one means nothing moves it. */

package/dist/crm/sync.js

@@ -57,6 +57,16 @@ const readPipelines = async (run, kind) => {
         run.report.issues.push({ kind, ...one });
     return null;
 };
+const readFields = async (run, kind) => {
+    const why = run.budget.take();
+    if (why)
+        return why;
+    const fields = await run.source.fields.call(run.source, kind);
+    const { skipped } = await run.store.crm.saveFields(run.account, kind, fields);
+    for (const one of skipped)
+        run.report.issues.push({ kind, ...one });
+    return null;
+};
 /** One page saved; an item whose stage is unknown gets one more chance after the kind's pipelines are read again. */
 const savePage = async (run, kind, page) => {
     const { store, account } = run;
@@ -185,10 +195,11 @@ const syncKind = async (run, kind, options, result) => {
     return null;
 };
 /**
- * Brings one CRM account's copy up to date: both kinds' pipelines, then contacts, companies, deals and leads, each
- * from its cursor or listed in full, a page at a time, each page saved with the round's place in the cursor, so a
- * run the budget stops, or one that fails, goes on from there. Deletions come from `changes()`, or from a list of
- * every id that marks only after its last page arrived, and never more than half of a kind without `--rescan`.
+ * Brings one CRM account's copy up to date: both kinds' pipelines and each kind's fields, then contacts, companies,
+ * deals and leads, each from its cursor or listed in full, a page at a time, each page saved with the round's place in
+ * the cursor, so a run the budget stops, or one that fails, goes on from there. Deletions come from `changes()`, or
+ * from a list of every id that marks only after its last page arrived, and never more than half of a kind without
+ * `--rescan`.
  */
 export const syncCrm = async (source, store, account, options = {}) => {
     const now = options.now ?? Date.now();
@@ -225,6 +236,13 @@ export const syncCrm = async (source, store, account, options = {}) => {
             if (options.signal?.aborted)
                 stopped = "cancelled";
         }
+    if (run.source.fields)
+        for (const kind of kinds)
+            if (!stopped) {
+                stopped = await readFields(run, kind);
+                if (options.signal?.aborted)
+                    stopped = "cancelled";
+            }
     for (const kind of kinds) {
         const result = {
             kind,

package/dist/crm/testing/index.d.ts

@@ -1,4 +1,4 @@
-export { exampleDeal, exampleLead, exampleOrganization, examplePerson, FAKE_CRM_ALIASES, type FakeCrmSource, type FakeCrmSourceOptions, type FakeCrmWrite, fakeCrmSource, LEAD_PIPELINE, SALES_PIPELINE, } from "./source.js";
+export { exampleDeal, exampleLead, exampleOrganization, examplePerson, FAKE_CRM_ALIASES, type FakeCrmSource, type FakeCrmSourceOptions, type FakeCrmWrite, fakeCrmSource, LEAD_PIPELINE, SALES_PIPELINE, SOURCE_FIELD, } from "./source.js";
 export { type CrmSourceFixture, crmSourceContract } from "./source-contract.js";
 export { CRM_TRAIT_COMBINATIONS, type CrmSyncFixture, crmSyncContract } from "./sync-contract.js";
 export { type CrmWriteFixture, crmWriteContract } from "./write-contract.js";

package/dist/crm/testing/index.js

@@ -1,4 +1,4 @@
-export { exampleDeal, exampleLead, exampleOrganization, examplePerson, FAKE_CRM_ALIASES, fakeCrmSource, LEAD_PIPELINE, SALES_PIPELINE, } from "./source.js";
+export { exampleDeal, exampleLead, exampleOrganization, examplePerson, FAKE_CRM_ALIASES, fakeCrmSource, LEAD_PIPELINE, SALES_PIPELINE, SOURCE_FIELD, } from "./source.js";
 export { crmSourceContract } from "./source-contract.js";
 export { CRM_TRAIT_COMBINATIONS, crmSyncContract } from "./sync-contract.js";
 export { crmWriteContract } from "./write-contract.js";

package/dist/crm/testing/source-contract.js

@@ -51,6 +51,34 @@ export const crmSourceContract = (make) => {
                 }
             },
         },
+        {
+            name: "fields: unique codes in each kind, a type, yes-or-no flags, and a list field's options with unique ids",
+            async run() {
+                const { source } = await make();
+                if (!source.fields)
+                    return;
+                for (const kind of source.traits.kinds) {
+                    const fields = await source.fields(kind);
+                    assert.ok(Array.isArray(fields), `${kind}: fields() answers a list`);
+                    const codes = new Set();
+                    for (const field of fields) {
+                        assert.ok(typeof field.code === "string" && field.code.trim(), `${kind}: a field has a code`);
+                        assert.ok(!codes.has(field.code), `${kind} field ${field.code} is listed twice`);
+                        codes.add(field.code);
+                        assert.ok(field.label === null || typeof field.label === "string", `${field.code}: a label or null`);
+                        assert.ok(typeof field.type === "string" && field.type.trim(), `${field.code} has a type`);
+                        assert.equal(typeof field.multiple, "boolean", `${field.code}: multiple is true or false`);
+                        assert.equal(typeof field.filterable, "boolean", `${field.code}: filterable is true or false`);
+                        if (field.options === undefined)
+                            continue;
+                        const ids = new Set(field.options.map(({ id }) => id));
+                        assert.equal(ids.size, field.options.length, `${field.code}: option ids are unique`);
+                        for (const option of field.options)
+                            assert.ok(typeof option.id === "string" && typeof option.label === "string", `${field.code}'s options`);
+                    }
+                }
+            },
+        },
         {
             name: "changes: a full list pages to its end, every item stands in a listed stage, fields in the neutral shape",
             async run() {

package/dist/crm/testing/source.d.ts

@@ -1,4 +1,4 @@
-import type { CrmItem, CrmKind, CrmOrganization, CrmPerson, CrmPipeline, CrmRecords } from "../../domain/crm.js";
+import type { CrmField, CrmItem, CrmKind, CrmOrganization, CrmPerson, CrmPipeline, CrmRecords } from "../../domain/crm.js";
 import type { DealKind } from "../../domain/deals.js";
 import type { CrmSource, CrmSourceTraits } from "../source.js";
 import { type CrmVerb, type CrmWriteCapabilities, type CrmWriter } from "../writer.js";
@@ -27,15 +27,20 @@ export interface FakeCrmSource extends CrmSource, CrmWriter {
     /** Deletes a row: named in `removed` when `removedInChanges`, otherwise only missing from `ids()`. */
     delete(kind: CrmKind, externalId: string): void;
     setPipelines(kind: DealKind, pipelines: CrmPipeline[]): void;
+    /** The kind's own fields from the next `fields()` on: deals have `SOURCE_FIELD` and the rest none until set. */
+    setFields(kind: CrmKind, fields: CrmField[]): void;
     /** The kind's cursors older than its latest change are refused, once, with `{ reset: true }`. */
     expireCursors(kind: CrmKind): void;
     /** Lists no id at all, as a CRM does for a sign-in that lost its rights. */
     hideAll(hidden: boolean): void;
     /** The next write is carried out and its answer lost: it throws `outcome_unknown`. */
     loseNextAnswer(): void;
+    /** The next write is carried out and its item cannot be read back: it throws with `sent: true`. */
+    failNextReadBack(): void;
     /** Requests made, by method. */
     readonly calls: {
         pipelines: number;
+        fields: number;
         changes: number;
         ids: number;
     };
@@ -45,6 +50,8 @@ export interface FakeCrmSource extends CrmSource, CrmWriter {
 /** Custom codes the fake refuses: each is a neutral field under another name. */
 export declare const FAKE_CRM_ALIASES: string[];
 export declare const SALES_PIPELINE: CrmPipeline;
+/** A deal's list field, as a CRM lists one: what the fake's deals have. */
+export declare const SOURCE_FIELD: CrmField;
 export declare const LEAD_PIPELINE: CrmPipeline;
 export declare const fakeCrmSource: (options?: FakeCrmSourceOptions) => FakeCrmSource;
 export declare const exampleDeal: (externalId: string, extra?: Partial<CrmItem>) => CrmItem;

package/dist/crm/testing/source.js

@@ -14,6 +14,18 @@ export const SALES_PIPELINE = {
         { externalId: "lost", name: "Lost", position: 4, outcome: "lost" },
     ],
 };
+/** A deal's list field, as a CRM lists one: what the fake's deals have. */
+export const SOURCE_FIELD = {
+    code: "UF_SOURCE",
+    label: "Source",
+    type: "enumeration",
+    multiple: false,
+    filterable: true,
+    options: [
+        { id: "1", label: "Website" },
+        { id: "2", label: "Fair" },
+    ],
+};
 export const LEAD_PIPELINE = {
     externalId: "lead-1",
     name: "Example leads",
@@ -32,10 +44,11 @@ export const fakeCrmSource = (options = {}) => {
     const size = options.pageSize ?? 2;
     const rows = new Map();
     const pipelines = { deal: [SALES_PIPELINE], lead: [LEAD_PIPELINE] };
+    const fields = { deal: [SOURCE_FIELD], lead: [], person: [], organization: [] };
     let version = 0;
     const expired = new Map();
     let hidden = false;
-    const calls = { pipelines: 0, changes: 0, ids: 0 };
+    const calls = { pipelines: 0, fields: 0, changes: 0, ids: 0 };
     const capabilities = {
         kinds: ["deal", "lead"],
         verbs: CRM_VERBS,
@@ -46,6 +59,7 @@ export const fakeCrmSource = (options = {}) => {
     const answered = new Map();
     let made = 0;
     let lose = false;
+    let unread = false;
     const of = (kind) => {
         const held = rows.get(kind) ?? new Map();
         rows.set(kind, held);
@@ -69,18 +83,32 @@ export const fakeCrmSource = (options = {}) => {
             throw new CliError("validation_error", `the CRM has no stage ${stageId} there`);
         return { pipeline: pipeline.externalId, stage: stage.externalId, outcome: stage.outcome };
     };
-    const applied = (item, fields) => {
-        const { custom, owner, pipeline, stage, ...named } = fields;
-        const metadata = {
-            ...item.metadata,
-            ...(owner === undefined ? {} : { owner }),
-            ...(custom ? { custom: { ...item.metadata?.custom, ...custom } } : {}),
+    /** A custom value as a CRM answers it: by code, with the field's label and a list option's label. */
+    const customValue = (kind, code, value) => {
+        const field = fields[kind].find((one) => one.code === code);
+        const label = (id) => field?.options?.find((option) => option.id === id)?.label ?? id;
+        if (!field?.options)
+            return { label: field?.label ?? null, value };
+        return {
+            label: field.label,
+            value: Array.isArray(value) ? value.map(label) : label(value),
+            option_id: value,
         };
+    };
+    const applied = (kind, item, given) => {
+        const { custom, owner, pipeline, stage, ...named } = given;
+        const metadata = { ...item.metadata };
+        for (const [code, value] of Object.entries(custom ?? {}))
+            if (value === null)
+                delete metadata[code];
+            else
+                metadata[code] = customValue(kind, code, value);
         return {
             ...item,
             ...Object.fromEntries(Object.entries(named).filter(([, value]) => value !== undefined)),
             ...(pipeline === undefined ? {} : { pipeline }),
             ...(stage === undefined ? {} : { stage }),
+            ...(owner === undefined ? {} : { assignee: owner }),
             metadata,
             updatedAt: null,
         };
@@ -102,6 +130,12 @@ export const fakeCrmSource = (options = {}) => {
             lose = false;
             throw new CliError("outcome_unknown", "the CRM did not answer");
         }
+        if (unread) {
+            unread = false;
+            throw new CliError("provider_error", `the CRM made the ${verb} but its ${kind} could not be read back`, {
+                sent: true,
+            });
+        }
         return done;
     };
     const saved = (kind, item) => {
@@ -117,13 +151,16 @@ export const fakeCrmSource = (options = {}) => {
         loseNextAnswer() {
             lose = true;
         },
+        failNextReadBack() {
+            unread = true;
+        },
         async create(kind, draft, { operationId }) {
             refuseAliases(draft);
             return write("create", kind, null, operationId, () => {
                 const { pipeline, stage } = placed(kind, draft.pipeline, draft.stage);
                 made += 1;
                 const blank = { externalId: `${kind}-new-${made}`, title: draft.title, pipeline, stage };
-                return saved(kind, applied(blank, { ...draft, pipeline, stage }));
+                return saved(kind, applied(kind, blank, { ...draft, pipeline, stage }));
             });
         },
         async update(kind, externalId, patch, { operationId }) {
@@ -131,7 +168,7 @@ export const fakeCrmSource = (options = {}) => {
             return write("update", kind, externalId, operationId, () => {
                 const item = held(kind, externalId);
                 const at = patch.stage === undefined ? {} : placed(kind, patch.pipeline ?? item.pipeline, patch.stage);
-                return saved(kind, applied(item, { ...patch, ...at }));
+                return saved(kind, applied(kind, item, { ...patch, ...at }));
             });
         },
         async move(kind, externalId, stage, { operationId }) {
@@ -179,6 +216,13 @@ export const fakeCrmSource = (options = {}) => {
         setPipelines(kind, list) {
             pipelines[kind] = list;
         },
+        setFields(kind, list) {
+            fields[kind] = list;
+        },
+        async fields(kind) {
+            calls.fields += 1;
+            return fields[kind];
+        },
         expireCursors(kind) {
             expired.set(kind, version);
         },

package/dist/crm/testing/sync-contract.js

@@ -1,7 +1,7 @@
 import assert from "node:assert/strict";
 import { runBudget } from "../../background/budget.js";
 import { syncCrm } from "../sync.js";
-import { exampleDeal, exampleLead, exampleOrganization, examplePerson, fakeCrmSource, LEAD_PIPELINE, SALES_PIPELINE, } from "./source.js";
+import { exampleDeal, exampleLead, exampleOrganization, examplePerson, fakeCrmSource, LEAD_PIPELINE, SALES_PIPELINE, SOURCE_FIELD, } from "./source.js";
 /** Both ways a CRM may report deletions: the engine must handle each. */
 export const CRM_TRAIT_COMBINATIONS = [
     { removedInChanges: false },
@@ -68,7 +68,7 @@ export const crmSyncContract = (make) => CRM_TRAIT_COMBINATIONS.flatMap((traits)
             await sync();
             source.delete("deal", "d1");
             now += DAY;
-            const stopped = await sync({ budget: runBudget({ requests: 7 }) });
+            const stopped = await sync({ budget: runBudget({ requests: 11 }) });
             assert.equal(stopped.state, "partial");
             assert.equal(stopped.hint, "run sync again to continue");
             assert.deepEqual(await deals(), ["d1", "d2", "d3", "d4", "d5"]);
@@ -90,6 +90,17 @@ export const crmSyncContract = (make) => CRM_TRAIT_COMBINATIONS.flatMap((traits)
             await sync({ rescan: true });
             assert.deepEqual(await deals(), []);
         }),
+        test("stores each kind's own fields, and marks deleted one the CRM no longer lists", async ({ source, sync, store, account, }) => {
+            const note = { code: "UF_NOTE", label: "Note", type: "string", multiple: true, filterable: false };
+            source.setFields("person", [note]);
+            await sync();
+            assert.deepEqual(await store.crm.fields(account, "deal"), [SOURCE_FIELD]);
+            assert.deepEqual(await store.crm.fields(account, "person"), [note]);
+            source.setFields("deal", []);
+            await sync();
+            assert.deepEqual(await store.crm.fields(account, "deal"), []);
+            assert.deepEqual(await store.crm.fields(account, "person"), [note]);
+        }),
         test("a dead cursor starts a full round, marked reset", async ({ source, sync, deals }) => {
             seeded(source);
             await sync();
@@ -103,7 +114,7 @@ export const crmSyncContract = (make) => CRM_TRAIT_COMBINATIONS.flatMap((traits)
         }),
         test("a run its budget stops saves its pages and the next goes on from the page it stopped at", async ({ source, sync, deals, }) => {
             seeded(source, 9);
-            const stopped = await sync({ budget: runBudget({ requests: 6 }) });
+            const stopped = await sync({ budget: runBudget({ requests: 10 }) });
             assert.equal(stopped.state, "partial");
             assert.equal(stopped.stopped, "requests");
             const kept = (await deals()).length;

package/dist/crm/writer.d.ts

@@ -1,3 +1,4 @@
+import type { ConditionalKey } from "../cli/permission-keys.js";
 import type { CrmItem } from "../domain/crm.js";
 import type { DealKind, DealRole } from "../domain/deals.js";
 import type { Level, PermissionKey } from "../sends/permissions.js";
@@ -35,7 +36,8 @@ export interface CrmFields {
     }[];
     /** The CRM user it is assigned to: a user's id, never a contact's. */
     owner?: string | null;
-    custom?: Record<string, string | null>;
+    /** A list field's option by its id; a multiple field's values as a list; `null` clears it. */
+    custom?: Record<string, string | string[] | null>;
 }
 export type CrmDraft = CrmFields & {
     title: string;
@@ -47,7 +49,8 @@ export interface CrmWriteOptions {
 /**
  * Writes to one CRM account. Each answers the whole item as the CRM holds it after the write, every field and not
  * only the changed ones: the store replaces its copy with it. None of them retries: a write whose answer was lost
- * throws `outcome_unknown`.
+ * throws `outcome_unknown`. A write the CRM made whose item could then not be read back throws with `sent: true` in
+ * its details: it is journaled as sent, and the read's failure is answered on its own.
  */
 export interface CrmWriter {
     readonly provider: string;
@@ -69,6 +72,12 @@ export interface CrmWriter {
 export declare const CRM_ASSIGN_OTHERS_KEY: PermissionKey;
 /** The keys the CRM writes check beyond their command paths, for a CLI's `commandPermissions({ extra })`. */
 export declare const CRM_WRITE_KEYS: readonly PermissionKey[];
+/**
+ * Every key a CRM write command may check beyond its own path, for `commandPermissions({ alsoChecks })`, so its
+ * `--dry-run` names each: a stage implies the move key and a won or lost one the close key, an owner other than the
+ * sign-in's `crm.assign-others`, and `also` the CLI's own (the same `CrmWrites.alsoChecks` the real run checks).
+ */
+export declare const crmAlsoChecks: (also?: (kind: DealKind, verb: CrmVerb) => readonly PermissionKey[]) => (path: readonly string[]) => readonly (PermissionKey | ConditionalKey)[];
 /**
  * Built in, and only ever tightening (WC-PERM-7): an ordinary change goes ahead, a deletion asks, and a record is not
  * given to somebody else until the owner allows it.

package/dist/crm/writer.js

@@ -3,6 +3,37 @@ export const CRM_VERBS = ["create", "update", "move", "close", "remove"];
 export const CRM_ASSIGN_OTHERS_KEY = "crm.assign-others";
 /** The keys the CRM writes check beyond their command paths, for a CLI's `commandPermissions({ extra })`. */
 export const CRM_WRITE_KEYS = [CRM_ASSIGN_OTHERS_KEY];
+const PLURALS = { deals: "deal", leads: "lead" };
+const VERB_OF = {
+    create: "create",
+    update: "update",
+    move: "move",
+    close: "close",
+    delete: "remove",
+};
+/**
+ * Every key a CRM write command may check beyond its own path, for `commandPermissions({ alsoChecks })`, so its
+ * `--dry-run` names each: a stage implies the move key and a won or lost one the close key, an owner other than the
+ * sign-in's `crm.assign-others`, and `also` the CLI's own (the same `CrmWrites.alsoChecks` the real run checks).
+ */
+export const crmAlsoChecks = (also) => (path) => {
+    const [noun, command] = path;
+    const kind = noun === undefined ? undefined : PLURALS[noun];
+    const verb = command === undefined ? undefined : VERB_OF[command];
+    if (path.length !== 2 || kind === undefined || verb === undefined)
+        return [];
+    const close = { key: `${noun}.close`, when: "a won or lost stage" };
+    const implied = verb === "create" || verb === "update"
+        ? [
+            { key: `${noun}.move`, when: "--stage" },
+            close,
+            { key: CRM_ASSIGN_OTHERS_KEY, when: "--owner other than the sign-in's user" },
+        ]
+        : verb === "move"
+            ? [close]
+            : [];
+    return [...implied, ...(also?.(kind, verb) ?? [])];
+};
 /**
  * Built in, and only ever tightening (WC-PERM-7): an ordinary change goes ahead, a deletion asks, and a record is not
  * given to somebody else until the owner allows it.

package/dist/crm/writes.d.ts

@@ -2,11 +2,12 @@ import type { DealKind } from "../domain/deals.js";
 import type { AppIdentity } from "../ports/app.js";
 import type { Warn } from "../runs/events.js";
 import { type Asker, type GuardSettings } from "../sends/guard.js";
+import { type PermissionKey } from "../sends/permissions.js";
 import type { Deal } from "../store/sqlite/deals.js";
 import type { MessageStore } from "../store/store.js";
 import type { AccountKey } from "../store/types.js";
 import type { CrmSource } from "./source.js";
-import { type CrmWriter } from "./writer.js";
+import { type CrmVerb, type CrmWriter } from "./writer.js";
 /** What a CLI hands the CRM writes for one profile. */
 export interface CrmWrites {
     writer: CrmWriter;
@@ -17,6 +18,11 @@ export interface CrmWrites {
     self?: string;
     env?: NodeJS.ProcessEnv;
     warn?: Warn;
+    /**
+     * The CLI's own keys a write also checks, such as Bitrix24's `api.crm.deal.update`; pass the same function to
+     * `crmAlsoChecks` so `--dry-run` names them.
+     */
+    alsoChecks?: (kind: DealKind, verb: CrmVerb) => readonly PermissionKey[];
 }
 export interface CrmWriteContext {
     store: MessageStore;
@@ -40,7 +46,11 @@ export interface CrmFieldsInput {
     currency?: string;
     closeDate?: string;
     owner?: string;
-    custom?: Record<string, string | null>;
+    /**
+     * `--field` pairs as typed, in order: a field by its code or whole label, a list field's option by its id or label,
+     * repeated for each value of a multiple field; an empty value clears it.
+     */
+    custom?: readonly (readonly [name: string, value: string])[];
 }
 export interface CrmWritten {
     operationId: string;

package/dist/crm/writes.js

@@ -118,14 +118,80 @@ const fieldsOf = (input, pipeline, currency) => {
             throw invalid("--owner is the CRM user's id", "--owner");
         fields.owner = input.owner.trim();
     }
-    if (input.custom !== undefined && Object.keys(input.custom).length) {
-        for (const code of Object.keys(input.custom))
-            if (!FIELD_CODE.test(code))
-                throw invalid(`${code} is not a field code`, "--field");
-        fields.custom = input.custom;
-    }
     return { fields, stage };
 };
+/** Case, spaces and underscores aside: `lead_source` and `Lead source` are one name, as bitrix24-cli folds them. */
+const folded = (name) => name
+    .trim()
+    .toLocaleLowerCase()
+    .replace(/[\s_]+/gu, " ");
+const named = ({ code, label }) => ({ code, label });
+/** A field by its code or its whole label; two with that label are refused with both, never guessed. */
+const fieldNamed = (fields, name) => {
+    const want = folded(name);
+    const byCode = fields.find((field) => folded(field.code) === want);
+    if (byCode)
+        return byCode;
+    const labelled = fields.filter((field) => field.label !== null && folded(field.label) === want);
+    if (labelled.length === 1)
+        return labelled[0];
+    if (labelled.length > 1)
+        throw new CliError("validation_error", `${labelled.length} custom fields are labelled ${name}; name one by its code`, {
+            reason: "field.ambiguous",
+            param: "--field",
+            candidates: labelled.map(named),
+        });
+    const close = fields.filter((field) => [field.code, field.label ?? ""].some((one) => {
+        const other = folded(one);
+        return other !== "" && (other.includes(want) || want.includes(other));
+    }));
+    throw new CliError("validation_error", `no custom field is named ${name}${close.length ? "; close ones are in candidates" : ""} — \`fields list\` lists them`, { reason: "field.unknown", param: "--field", candidates: close.map(named) });
+};
+const optionOf = (field, value) => {
+    if (!field.options)
+        return value;
+    const found = field.options.find((option) => option.id === value.trim()) ??
+        field.options.find((option) => folded(option.label) === folded(value));
+    if (!found)
+        throw new CliError("validation_error", `${field.label ?? field.code} has no option ${value}`, {
+            reason: "field.unknown-option",
+            param: "--field",
+            field: field.code,
+            allowed: field.options,
+        });
+    return found.id;
+};
+/**
+ * `--field` pairs by the synced field definitions: a label to its code, an option to its id, a multiple field's
+ * repeats into a list. A CRM whose definitions are not stored takes codes as typed.
+ */
+const customOf = async (context, kind, pairs) => {
+    if (!pairs?.length)
+        return undefined;
+    const fields = await context.store.crm.fields(context.account, kind);
+    const values = new Map();
+    for (const [name, value] of pairs) {
+        const field = fields.length ? fieldNamed(fields, name) : null;
+        const code = field?.code ?? name.trim();
+        if (!field && !FIELD_CODE.test(code))
+            throw invalid(`${name} is not a field code`, "--field");
+        const held = values.get(code) ?? { field, all: [] };
+        held.all.push(value === "" ? null : field ? optionOf(field, value) : value);
+        values.set(code, held);
+    }
+    return Object.fromEntries([...values].map(([code, { field, all }]) => {
+        const given = all.filter((one) => one !== null);
+        if (field?.multiple)
+            return [code, given.length ? given : null];
+        if (all.length > 1)
+            throw new CliError("validation_error", `${field?.label ?? code} holds one value; give --field once`, {
+                reason: "deal.field",
+                param: "--field",
+                field: code,
+            });
+        return [code, all[0] ?? null];
+    }));
+};
 /** Every key the write checks: its own, and each action its fields also take (WC-PERM-22). */
 const keysOf = (context, kind, verb, { stage, owner }) => {
     const extra = [];
@@ -135,7 +201,7 @@ const keysOf = (context, kind, verb, { stage, owner }) => {
         extra.push(keyOf(kind, "close"));
     if (owner != null && owner !== context.writes.self)
         extra.push(CRM_ASSIGN_OTHERS_KEY);
-    return { key: keyOf(kind, verb), extra };
+    return { key: keyOf(kind, verb), extra: [...extra, ...(context.writes.alsoChecks?.(kind, verb) ?? [])] };
 };
 /** The profile's guard over the write's own key and the keys its fields imply (`keyedGuard`). */
 const guardOf = (context, extra) => {
@@ -146,7 +212,20 @@ const guardOf = (context, extra) => {
 /** Sends the write once, never again: a lost answer is `outcome_unknown`, with what the owner may do about it. */
 const written = async (context, { key, extra }, operationId, act) => {
     try {
-        return await guardedWrite(guardOf(context, extra), { chatId: null, kind: "edit", key, operationId }, act);
+        // A write the CRM made and could not read back is sent: its journal line says so, and the read's failure follows.
+        const done = await guardedWrite(guardOf(context, extra), { chatId: null, kind: "edit", key, operationId }, async () => {
+            try {
+                return { item: await act(), unread: null };
+            }
+            catch (error) {
+                if (isCliError(error) && error.details.sent === true)
+                    return { item: null, unread: error };
+                throw error;
+            }
+        });
+        if (done.unread)
+            throw new CliError(done.unread.code, `${done.unread.message} — the CRM made the change; sync to store it, do not write it again`, { ...done.unread.details, operation_id: operationId });
+        return done.item;
     }
     catch (error) {
         if (!isCliError(error) || error.code !== "outcome_unknown")
@@ -192,6 +271,9 @@ export const createCrmItem = async (context, kind, input, options = {}) => {
         throw invalid(`a new ${kind} needs --title`, "--title");
     const pipeline = await pipelineOf(context, kind, input.pipeline);
     const { fields, stage } = fieldsOf({ ...input, pipeline: pipeline.ref }, pipeline, null);
+    const custom = await customOf(context, kind, input.custom);
+    if (custom)
+        fields.custom = custom;
     const operationId = operationOf(context, options.operationId);
     const item = await written(context, keysOf(context, kind, "create", { stage, owner: fields.owner }), operationId, () => writer.create(kind, fields, { operationId }));
     return { operationId, item: await kept(context, kind, item, operationId) };
@@ -206,6 +288,9 @@ export const updateCrmItem = async (context, kind, reference, input, options = {
         ? undefined
         : await pipelineOf(context, kind, input.pipeline === undefined ? copy.pipeline : input.pipeline);
     const { fields, stage } = fieldsOf(input, pipeline, copy.currency);
+    const custom = await customOf(context, kind, input.custom);
+    if (custom)
+        fields.custom = custom;
     if (Object.keys(fields).length === 0)
         throw invalid("nothing to change: name a field");
     const operationId = operationOf(context, options.operationId);