@wirecat/cli-core 0.593.0 → 0.594.0

package/CHANGELOG.md

@@ -7,6 +7,43 @@ shape of this file.
 
 ## Unreleased
 
+## 0.594.0 — 06.11.2026
+
+### Added
+
+- **A CRM write port, `CrmWriter`** (`@wirecat/cli-core/crm`), beside `CrmSource`: `create`, `update`, `move`,
+  `close` and `remove` of deals and leads, each sent once with its `operationId` and answering the whole item as the
+  CRM holds it. `capabilities` names the kinds and verbs it takes and whether it recognises a repeated operation id
+  (Bitrix24's `Idempotency-Key`). Fields use `CrmItem`'s names, plus `owner` (a CRM user's id) and `custom` (the CRM's
+  own fields by code). An adapter refuses a custom code that is a neutral field under another name, such as a stage
+  or an owner. `CRM_WRITE_DEFAULTS` and `CRM_WRITE_KEYS` go into a CLI's `commandPermissions`.
+- **`deals` and `leads` `create`, `update`, `move`, `close` and `delete`** in `addCrmCommands`, mounted by its new
+  `writes` option (the writer's capabilities) and run through `CrmRun.writes`. Each goes through the write guard and
+  the send journal, honours `--dry-run`, and is exposed over MCP as a write. A write is never sent twice: a lost
+  answer is `outcome_unknown`, and `--operation-id` is offered only by a CRM that recognises a repeat. A stage in
+  `create` or `update` also checks the `move` key, and a won or lost stage the `close` key. An owner other than the
+  sign-in's own user (`CrmWrites.self`) checks `crm.assign-others`, denied by default. `delete` asks by default. The
+  item the CRM answers is stored as a sync would store it, and the answer carries it with its `operation_id`.
+  `--field <key=value>` sets a custom field; an empty value clears it.
+- **`crmWriteContract` and a write side on `fakeCrmSource`** (`@wirecat/cli-core/crm/testing`). The contract checks
+  that an update of one field answers the whole item, that a custom code naming a neutral field is refused before
+  anything is sent, and that a lost answer ends after one request.
+- **`CrmItem.closedReason`** is stored as the deal's or lead's `closed_reason`, and `store.crm.refOf` finds the stored
+  copy of a CRM id.
+- **A CRM's deal and lead pipelines may share an id (store version 53).** The unique key of a CRM account's pipelines
+  is now its account, kind and id, so `savePipelines` stores a lead pipeline whose id a deal pipeline already has,
+  and `crmSourceContract` checks pipeline ids are unique within each kind only.
+- **Pipelines and stages the CRM no longer lists are marked deleted (store version 53),** never removed: deals may still
+  stand in them. `savePipelines` takes a kind's whole list, marks what it lacks and brings back what it lists again; an
+  empty list marks nothing. A deleted pipeline is left out of `pipelines()` and of a lookup by name, and still found by
+  its `pipeline:<id>`. A deleted stage is only marked. The migration adds columns and swaps one index; `minCompatible`
+  stays 34.
+
+### Removed
+
+- **The `crm.pipeline-clash` skip reason.** `savePipelines` no longer skips a pipeline for sharing the other kind's id,
+  so `CrmSkipped.reason` is `crm.stage-unknown` or `crm.item-invalid`.
+
 ## 0.593.0 — 06.11.2026
 
 ### Added

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

@@ -4,6 +4,8 @@ import type { AppIdentity } from "../../ports/app.js";
 import type { MessageStore } from "../../store/store.js";
 import type { AccountKey } from "../../store/types.js";
 import type { CrmSource } from "../source.js";
+import type { CrmWriteCapabilities } from "../writer.js";
+import { type CrmWrites } from "../writes.js";
 /**
  * The selected profile's CRM account, opened by the app for one command and closed once its answer is built, before
  * anything is printed (WC-LIFE-4).
@@ -18,6 +20,8 @@ export interface CrmRun {
     source: () => CrmSource;
     /** A profile lock pins the process (WC-ACCT-5): `search all` then reads only this account's deals. */
     locked?: boolean;
+    /** The CRM's writer and the profile's levels, built on first use; needed by every write command. */
+    writes?: () => CrmWrites;
     env?: NodeJS.ProcessEnv;
     close?: () => Promise<void>;
 }
@@ -30,6 +34,8 @@ export interface CrmCommandOptions {
     }) => Promise<CrmRun>;
     /** The CRM has leads: mounts `leads list|show`. True when absent. */
     leads?: boolean;
+    /** The writer's capabilities: mounts `create`, `update`, `move`, `close` and `delete` of each kind it writes. */
+    writes?: CrmWriteCapabilities;
     now?: () => number;
 }
 /** What `deals list` and `leads list` narrow by, the same in memo and every CRM CLI (WC-OUT-11). */

package/dist/crm/cli/index.js

@@ -1,18 +1,21 @@
 import { CliError } from "@wirecat/cli-base";
 import { annotate, metaOf, sharedCommand } from "@wirecat/cli-base/commands";
-import { InvalidArgumentError } from "commander";
+import { Argument, InvalidArgumentError } from "commander";
 import * as v from "valibot";
 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 } from "../../cli/effects.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 { terminalAsker } from "../../cli/messenger/ask.js";
 import { lineOf } from "../../cli/steps.js";
 import { CRM_KINDS } from "../../domain/crm.js";
 import { DEAL_KINDS, DEAL_STATUSES } from "../../domain/deals.js";
+import { deal as dealEntity } from "../../entities/deal.js";
 import { count, text } from "../../entities/fields.js";
 import { crmStatus, syncCrm } from "../sync.js";
+import { closeCrmItem, createCrmItem, moveCrmItem, removeCrmItem, updateCrmItem, } from "../writes.js";
 import { addCrmSearchAll } from "./search-all.js";
 const MOST = 500;
 const DEAL_FIELDS = [
@@ -83,6 +86,24 @@ const crmSyncProgress = v.strictObject({
     cursor_age_ms: v.nullable(count),
     line: text,
 });
+const crmWrite = v.strictObject({
+    operation_id: text,
+    deal: v.optional(dealEntity),
+    lead: v.optional(dealEntity),
+    untrusted: v.array(text),
+});
+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");
+    return [...previous, value];
+};
+/** `--field code=value` pairs; an empty value clears the field. */
+const customOf = (pairs) => Object.fromEntries(pairs.map((pair) => {
+    const at = pair.indexOf("=");
+    const given = pair.slice(at + 1);
+    return [pair.slice(0, at), given === "" ? null : given];
+}));
 const integer = (most) => (value) => {
     if (!/^[1-9]\d*$/.test(value) || Number(value) > most)
         throw new InvalidArgumentError(`expected 1 to ${most}`);
@@ -219,6 +240,7 @@ const addCrmCommandsDefinition = (program, options) => {
                 return itemOf({ ...snakeKeys(found), untrusted: DEAL_UNTRUSTED });
             });
         });
+        addWrites(group, kind);
     };
     /** A row of this profile's account: another account's copy, or the owner's own, is not found here. */
     const ownCopy = async (run, kind, reference) => {
@@ -231,6 +253,100 @@ const addCrmCommandsDefinition = (program, options) => {
             throw new CliError("not_found", `${reference} is not a copy from this profile's CRM account`);
         return found;
     };
+    const writes = options.writes;
+    const addWrites = (group, kind) => {
+        if (!writes?.kinds.includes(kind))
+            return;
+        const plural = `${kind}s`;
+        const contextOf = (run, command) => {
+            if (!run.writes)
+                throw new CliError("configuration_error", "this profile cannot write to its CRM");
+            return {
+                store: run.store,
+                account: run.account,
+                writes: run.writes(),
+                ask: terminalAsker(command),
+                source: run.source,
+                names: { id: "--operation-id" },
+            };
+        };
+        const answered = (operationId, item) => itemOf({
+            operation_id: operationId,
+            [kind]: { ...snakeKeys(item), untrusted: DEAL_UNTRUSTED },
+            untrusted: DEAL_UNTRUSTED.map((field) => `${kind}.${field}`),
+        });
+        const write = (name, verb, description) => {
+            if (!writes.verbs.includes(verb))
+                return undefined;
+            const command = answerEntity(annotate(group.command(name), { effects: REMOTE_WRITE, offline: false }), verb === "remove" ? "crm_removal" : "crm_write", verb === "remove" ? crmRemoval : crmWrite).description(description);
+            if (writes.idempotent)
+                command.option("--operation-id <id>", "the operation_id a write that ended in outcome_unknown named: the CRM answers the repeat from its record");
+            return command;
+        };
+        const reference = (command) => command.argument("<ref>", `${kind}:<id>, as a list shows it`);
+        const fields = (command) => command
+            .option("--title <title>", `the ${kind}'s title`)
+            .option("--pipeline <pipeline>", "pipeline:<id>, or a name only one of the CRM's pipelines has")
+            .option("--stage <stage>", "a stage of its pipeline, by the CRM's id or name; checks the move key too, and the close key for a won or lost stage")
+            .option("--amount <decimal>", "the expected sum, such as 1500.50, with --currency")
+            .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, 
+        // 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) } : {}),
+        });
+        const idOf = (opts) => opts.operationId === undefined ? {} : { operationId: opts.operationId };
+        const run = (command, work) => within(command, (opened) => work(contextOf(opened, command)));
+        const create = write("create", "create", `make a ${kind} in the CRM, then store the CRM's copy of it`);
+        if (create)
+            example(fields(create), `${plural} create --title "Example kitchen" --amount 15000 --currency EUR`, `${plural} create --title "Example office" --pipeline Sales --stage "Quote sent" --field UF_CRM_SOURCE=web`).action(async (opts, command) => {
+                await run(command, async (context) => {
+                    const done = await createCrmItem(context, kind, inputOf(opts), idOf(opts));
+                    return answered(done.operationId, done.item);
+                });
+            });
+        const update = write("update", "update", `change a ${kind} in the CRM; what is left out keeps its value; the CRM's copy is stored again`);
+        if (update)
+            example(fields(reference(update)), `${plural} update ${kind}:12 --amount 18000`, `${plural} update ${kind}:12 --field UF_CRM_SOURCE=`).action(async (ref, opts, command) => {
+                await run(command, async (context) => {
+                    const done = await updateCrmItem(context, kind, ref, inputOf(opts), idOf(opts));
+                    return answered(done.operationId, done.item);
+                });
+            });
+        const move = write("move", "move", `move a ${kind} to another stage of its pipeline; a won or lost stage checks the close key too`);
+        if (move)
+            example(reference(move).argument("<stage>", "the stage, by the CRM's id or a name only one stage of its pipeline has"), `${plural} move ${kind}:12 "Quote sent"`).action(async (ref, stage, opts, command) => {
+                await run(command, async (context) => {
+                    const done = await moveCrmItem(context, kind, ref, stage, idOf(opts));
+                    return answered(done.operationId, done.item);
+                });
+            });
+        const close = write("close", "close", `mark a ${kind} won or lost, the CRM's own way`);
+        if (close)
+            example(reference(close)
+                .addArgument(new Argument("<outcome>", "how it ended").choices(["won", "lost"]))
+                .option("--reason <text>", "why, in a few words; kept with it"), `${plural} close ${kind}:12 won`, `${plural} close ${kind}:12 lost --reason "Example: chose another supplier"`).action(async (ref, outcome, opts, command) => {
+                await run(command, async (context) => {
+                    const done = await closeCrmItem(context, kind, ref, outcome, {
+                        ...idOf(opts),
+                        ...(opts.reason === undefined ? {} : { reason: opts.reason }),
+                    });
+                    return answered(done.operationId, done.item);
+                });
+            });
+        const remove = write("delete", "remove", `delete a ${kind} in the CRM; asks first unless allowed`);
+        if (remove)
+            example(reference(remove), `${plural} delete ${kind}:12`).action(async (ref, opts, command) => {
+                await run(command, async (context) => {
+                    const done = await removeCrmItem(context, kind, ref, idOf(opts));
+                    return itemOf({ operation_id: done.operationId, ref: done.ref, removed: done.removed });
+                });
+            });
+    };
     items("deal");
     if (options.leads !== false)
         items("lead");

package/dist/crm/index.d.ts

@@ -1,2 +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 { type CrmFieldsInput, type CrmWriteContext, type CrmWrites, type CrmWritten, closeCrmItem, createCrmItem, moveCrmItem, removeCrmItem, updateCrmItem, } from "./writes.js";

package/dist/crm/index.js

@@ -1 +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 { closeCrmItem, createCrmItem, moveCrmItem, removeCrmItem, updateCrmItem, } from "./writes.js";

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

@@ -1,3 +1,4 @@
-export { exampleDeal, exampleLead, exampleOrganization, examplePerson, type FakeCrmSource, type FakeCrmSourceOptions, 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, } 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,3 +1,4 @@
-export { exampleDeal, exampleLead, exampleOrganization, examplePerson, fakeCrmSource, LEAD_PIPELINE, SALES_PIPELINE, } from "./source.js";
+export { exampleDeal, exampleLead, exampleOrganization, examplePerson, FAKE_CRM_ALIASES, fakeCrmSource, LEAD_PIPELINE, SALES_PIPELINE, } 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

@@ -29,11 +29,11 @@ const listAll = async (source, kind, cursor) => {
 export const crmSourceContract = (make) => {
     const cases = [
         {
-            name: "pipelines: unique ids across both kinds, stages with a known outcome and unique ids",
+            name: "pipelines: unique ids in each kind, stages with a known outcome and unique ids",
             async run() {
                 const { source } = await make();
-                const seen = new Set();
                 for (const kind of DEAL_KINDS.filter((one) => source.traits.kinds.includes(one))) {
+                    const seen = new Set();
                     const pipelines = await source.pipelines(kind);
                     assert.ok(pipelines.length > 0, `${kind}: at least one pipeline`);
                     for (const pipeline of pipelines) {

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

@@ -1,13 +1,27 @@
 import type { 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";
 export interface FakeCrmSourceOptions {
     traits?: Partial<CrmSourceTraits>;
     /** Rows per page of `changes()` and `ids()`; 2 when absent, so every list has several pages. */
     pageSize?: number;
+    /** What the write side takes: every verb on both kinds, not idempotent, when absent. */
+    capabilities?: Partial<CrmWriteCapabilities>;
 }
-/** A CRM held in memory, with a change feed: what the contracts sync against, and what a CLI's tests may use. */
-export interface FakeCrmSource extends CrmSource {
+/** One write the fake CRM was sent, in order. */
+export interface FakeCrmWrite {
+    verb: CrmVerb;
+    kind: DealKind;
+    externalId: string | null;
+    operationId: string;
+}
+/**
+ * A CRM held in memory, with a change feed and a write side: what the contracts sync and write against, and what a
+ * CLI's tests may use. Custom field codes `stage`, `pipeline`, `owner` and `status` are refused, as an adapter refuses
+ * a custom code that names one of the neutral fields.
+ */
+export interface FakeCrmSource extends CrmSource, CrmWriter {
     /** Adds or changes a row; it is in the next `changes()`. */
     put<K extends CrmKind>(kind: K, record: CrmRecords[K]): void;
     /** Deletes a row: named in `removed` when `removedInChanges`, otherwise only missing from `ids()`. */
@@ -17,13 +31,19 @@ export interface FakeCrmSource extends CrmSource {
     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;
     /** Requests made, by method. */
     readonly calls: {
         pipelines: number;
         changes: number;
         ids: number;
     };
+    /** Writes sent, refused ones included. */
+    readonly writes: FakeCrmWrite[];
 }
+/** 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;
 export declare const LEAD_PIPELINE: CrmPipeline;
 export declare const fakeCrmSource: (options?: FakeCrmSourceOptions) => FakeCrmSource;

package/dist/crm/testing/source.js

@@ -1,3 +1,7 @@
+import { CliError } from "@wirecat/cli-base";
+import { CRM_VERBS } from "../writer.js";
+/** Custom codes the fake refuses: each is a neutral field under another name. */
+export const FAKE_CRM_ALIASES = ["stage", "pipeline", "owner", "status"];
 /** When the fake CRM's changes happened: well before any `now` a contract syncs at. */
 const STAMPED_FROM = Date.UTC(2026, 0, 1);
 export const SALES_PIPELINE = {
@@ -32,6 +36,16 @@ export const fakeCrmSource = (options = {}) => {
     const expired = new Map();
     let hidden = false;
     const calls = { pipelines: 0, changes: 0, ids: 0 };
+    const capabilities = {
+        kinds: ["deal", "lead"],
+        verbs: CRM_VERBS,
+        idempotent: false,
+        ...options.capabilities,
+    };
+    const writes = [];
+    const answered = new Map();
+    let made = 0;
+    let lose = false;
     const of = (kind) => {
         const held = rows.get(kind) ?? new Map();
         rows.set(kind, held);
@@ -42,10 +56,111 @@ export const fakeCrmSource = (options = {}) => {
         const next = at + size;
         return { slice: list.slice(at, next), nextPage: next < list.length ? String(next) : undefined };
     };
-    return {
+    const held = (kind, externalId) => {
+        const found = of(kind).get(externalId);
+        if (!found || found.deleted)
+            throw new CliError("not_found", `the CRM has no ${kind} ${externalId}`);
+        return found.record;
+    };
+    const placed = (kind, pipelineId, stageId) => {
+        const pipeline = pipelineId === undefined ? pipelines[kind][0] : pipelines[kind].find((one) => one.externalId === pipelineId);
+        const stage = stageId === undefined ? pipeline?.stages[0] : pipeline?.stages.find((one) => one.externalId === stageId);
+        if (!pipeline || !stage)
+            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 } } : {}),
+        };
+        return {
+            ...item,
+            ...Object.fromEntries(Object.entries(named).filter(([, value]) => value !== undefined)),
+            ...(pipeline === undefined ? {} : { pipeline }),
+            ...(stage === undefined ? {} : { stage }),
+            metadata,
+            updatedAt: null,
+        };
+    };
+    const refuseAliases = (fields) => {
+        const refused = Object.keys(fields.custom ?? {}).find((code) => FAKE_CRM_ALIASES.includes(code));
+        if (refused)
+            throw new CliError("validation_error", `${refused} is not a custom field`);
+    };
+    /** Each write once: a repeated idempotent id answers its first outcome; a lost answer still made the change. */
+    const write = (verb, kind, externalId, operationId, act) => {
+        writes.push({ verb, kind, externalId, operationId });
+        if (capabilities.idempotent && answered.has(operationId))
+            return answered.get(operationId);
+        const done = act();
+        if (capabilities.idempotent)
+            answered.set(operationId, done);
+        if (lose) {
+            lose = false;
+            throw new CliError("outcome_unknown", "the CRM did not answer");
+        }
+        return done;
+    };
+    const saved = (kind, item) => {
+        fake.put(kind, item);
+        return held(kind, item.externalId);
+    };
+    const fake = {
         provider: "example-crm",
         traits,
         calls,
+        capabilities,
+        writes,
+        loseNextAnswer() {
+            lose = 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 }));
+            });
+        },
+        async update(kind, externalId, patch, { operationId }) {
+            refuseAliases(patch);
+            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 }));
+            });
+        },
+        async move(kind, externalId, stage, { operationId }) {
+            return write("move", kind, externalId, operationId, () => {
+                const item = held(kind, externalId);
+                return saved(kind, { ...item, stage: placed(kind, item.pipeline, stage).stage, status: null, updatedAt: null });
+            });
+        },
+        async close(kind, externalId, outcome, { operationId, reason }) {
+            return write("close", kind, externalId, operationId, () => {
+                const item = held(kind, externalId);
+                const pipeline = pipelines[kind].find((one) => one.externalId === item.pipeline);
+                const closing = pipeline?.stages.find((one) => one.outcome === outcome);
+                return saved(kind, {
+                    ...item,
+                    ...(closing ? { stage: closing.externalId } : {}),
+                    status: outcome,
+                    closedReason: reason ?? null,
+                    updatedAt: null,
+                });
+            });
+        },
+        async remove(kind, externalId, { operationId }) {
+            write("remove", kind, externalId, operationId, () => {
+                held(kind, externalId);
+                fake.delete(kind, externalId);
+                return undefined;
+            });
+        },
         put(kind, record) {
             version += 1;
             // A CRM stamps each change; without one here the store would take its own clock, which an id pass skips.
@@ -99,6 +214,7 @@ export const fakeCrmSource = (options = {}) => {
             return { ids: slice, ...(nextPage === undefined ? {} : { nextPage }) };
         },
     };
+    return fake;
 };
 export const exampleDeal = (externalId, extra = {}) => ({
     externalId,

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

@@ -138,12 +138,13 @@ export const crmSyncContract = (make) => CRM_TRAIT_COMBINATIONS.flatMap((traits)
             assert.deepEqual(await deals(), ["d2"]);
             assert.deepEqual(run.issues.map(({ kind, reason, externalId }) => [kind, reason, externalId]), [["deal", "crm.stage-unknown", "d1"]]);
         }),
-        test("a pipeline sharing the other kind's pipeline id is named as an issue, and the rest syncs", async ({ source, sync, deals, }) => {
+        test("a lead pipeline may share a deal pipeline's id", async ({ source, sync, deals }) => {
             source.setPipelines("lead", [{ ...LEAD_PIPELINE, externalId: SALES_PIPELINE.externalId }]);
             source.put("deal", exampleDeal("d1"));
+            source.put("lead", exampleLead("l1", { pipeline: SALES_PIPELINE.externalId }));
             const run = await sync();
             assert.deepEqual(await deals(), ["d1"]);
-            assert.ok(run.issues.some(({ kind, reason }) => kind === "lead" && reason === "crm.pipeline-clash"));
+            assert.deepEqual(run.issues, []);
         }),
         test("a contact joins a person by exact email, and a company never joins an organization by name", async ({ source, sync, store, account, }) => {
             const own = await store.knowledge.addOrganization({ kind: "company", name: "Example company c1" });

package/dist/crm/testing/write-contract.d.ts

@@ -0,0 +1,21 @@
+import type { CrmPipeline } from "../../domain/crm.js";
+import { type DealKind } from "../../domain/deals.js";
+import type { ContractCase } from "../../meetings/index.js";
+import { type CrmWriter } from "../writer.js";
+/**
+ * One adapter over recorded or faked responses, fresh for each case, that takes writes of `kind`. `pipeline` is one
+ * of the kind's pipelines with at least two open stages and a won one.
+ */
+export interface CrmWriteFixture {
+    writer: CrmWriter;
+    kind?: DealKind;
+    pipeline: CrmPipeline;
+    /** Custom field codes that are a neutral field under the CRM's own name (Bitrix24's `stageId`, `ASSIGNED_BY_ID`). */
+    aliases: readonly string[];
+    /** Makes the next write's answer lost after the CRM got it, as a dropped connection does. */
+    loseNextAnswer: () => void;
+    /** How many write requests reached the CRM so far. */
+    requests: () => number;
+}
+/** What every CRM adapter's write side does, whatever the CRM: run each case in the adapter's tests. */
+export declare const crmWriteContract: (make: () => CrmWriteFixture | Promise<CrmWriteFixture>) => ContractCase[];

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

@@ -0,0 +1,127 @@
+import assert from "node:assert/strict";
+import { isCliError } from "@wirecat/cli-base";
+import { DEAL_KINDS } from "../../domain/deals.js";
+import { CRM_VERBS } from "../writer.js";
+let operations = 0;
+const operation = () => {
+    operations += 1;
+    return { operationId: `contract-${Date.now()}-${operations}` };
+};
+const refusedWith = async (code, act) => {
+    try {
+        await act();
+    }
+    catch (error) {
+        assert.ok(isCliError(error), `a CliError, not ${String(error)}`);
+        assert.equal(error.code, code);
+        return;
+    }
+    assert.fail(`expected ${code}`);
+};
+const outcomeOf = (pipeline, item) => item.status ?? pipeline.stages.find((stage) => stage.externalId === item.stage)?.outcome;
+/** What every CRM adapter's write side does, whatever the CRM: run each case in the adapter's tests. */
+export const crmWriteContract = (make) => {
+    const openStages = async () => {
+        const fixture = await make();
+        const open = fixture.pipeline.stages.filter((stage) => stage.outcome === "open");
+        assert.ok(open.length >= 2, "the fixture's pipeline has two open stages");
+        const kind = fixture.kind ?? "deal";
+        const made = await fixture.writer.create(kind, {
+            title: "Example contract deal",
+            pipeline: fixture.pipeline.externalId,
+            stage: open[0]?.externalId,
+            amount: "1500.50",
+            currency: "EUR",
+        }, operation());
+        return { ...fixture, kind, open, made };
+    };
+    return [
+        {
+            name: "capabilities: known verbs and kinds, and a yes or no for repeated writes",
+            async run() {
+                const { writer } = await make();
+                const { kinds, verbs, idempotent } = writer.capabilities;
+                assert.ok(kinds.length > 0 && kinds.every((kind) => DEAL_KINDS.includes(kind)));
+                assert.ok(verbs.length > 0 && verbs.every((verb) => CRM_VERBS.includes(verb)));
+                assert.equal(typeof idempotent, "boolean");
+            },
+        },
+        {
+            name: "create answers the whole item in the stage it was given, with its new id",
+            async run() {
+                const { made, pipeline, open } = await openStages();
+                assert.ok(made.externalId, "an id");
+                assert.equal(made.title, "Example contract deal");
+                assert.equal(made.pipeline, pipeline.externalId);
+                assert.equal(made.stage, open[0]?.externalId);
+                assert.equal(made.currency, "EUR");
+                assert.equal(Number(made.amount), 1500.5);
+            },
+        },
+        {
+            name: "update of one field answers the whole item, every other field as it was",
+            async run() {
+                const { writer, kind, made } = await openStages();
+                const changed = await writer.update(kind, made.externalId, { title: "Example renamed" }, operation());
+                assert.equal(changed.externalId, made.externalId);
+                assert.equal(changed.title, "Example renamed");
+                for (const field of ["pipeline", "stage", "amount", "currency", "organization"])
+                    assert.deepEqual(changed[field] ?? null, made[field] ?? null, `${field} kept`);
+                assert.deepEqual(changed.people ?? [], made.people ?? [], "people kept");
+            },
+        },
+        {
+            name: "move goes to the stage given; close marks it won",
+            async run() {
+                const { writer, kind, made, open, pipeline } = await openStages();
+                const moved = await writer.move(kind, made.externalId, open[1]?.externalId, operation());
+                assert.equal(moved.stage, open[1]?.externalId);
+                assert.equal(outcomeOf(pipeline, moved), "open");
+                const closed = await writer.close(kind, made.externalId, "won", operation());
+                assert.equal(outcomeOf(pipeline, closed), "won");
+            },
+        },
+        {
+            name: "remove answers once the CRM deleted it",
+            async run() {
+                const { writer, kind, made } = await openStages();
+                await writer.remove(kind, made.externalId, operation());
+            },
+        },
+        {
+            name: "a custom code that is a neutral field under another name is refused, and nothing is sent",
+            async run() {
+                const { writer, kind, made, aliases, requests, open } = await openStages();
+                assert.ok(aliases.length > 0, "the fixture names the CRM's own names for stage and owner");
+                for (const code of aliases) {
+                    const before = requests();
+                    await refusedWith("validation_error", () => writer.update(kind, made.externalId, { custom: { [code]: open[1]?.externalId } }, operation()));
+                    assert.equal(requests(), before, `${code}: nothing sent`);
+                }
+            },
+        },
+        {
+            name: "a lost answer is outcome_unknown after one request, never retried",
+            async run() {
+                const fixture = await openStages();
+                const before = fixture.requests();
+                fixture.loseNextAnswer();
+                await refusedWith("outcome_unknown", () => fixture.writer.update(fixture.kind, fixture.made.externalId, { title: "Example lost" }, operation()));
+                assert.equal(fixture.requests(), before + 1, "one request");
+            },
+        },
+        {
+            name: "an idempotent CRM answers a repeated operation id from its record",
+            async run() {
+                const { writer, kind, pipeline } = await make();
+                if (!writer.capabilities.idempotent)
+                    return;
+                const once = operation();
+                const draft = { title: "Example repeated", pipeline: pipeline.externalId };
+                const first = await writer.create(kind ?? "deal", draft, once);
+                const again = await writer.create(kind ?? "deal", draft, once);
+                assert.equal(again.externalId, first.externalId);
+            },
+        },
+    ];
+};