@wirecat/cli-core 0.590.0 → 0.592.0

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

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

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

@@ -16,13 +16,13 @@ import { messagesSearchCommand } from "./messages-search-command.js";
 import { allAnswer, meaningNote, notesAnswer, offsetOf, SOURCE_SEARCHED, shownOf, } from "./search-answers.js";
 import { backendOptions, backendRequest, noteServer } from "./search-backend-options.js";
 import { topicsSearchCommand } from "./topics-command.js";
-export const searchAllOnlyOf = (value) => {
+export const searchAllOnlyOf = (value, allowed = SOURCE_SEARCHED) => {
     const chosen = value.split(",").map((one) => one.trim());
     if (chosen.includes("mail"))
         throw new CliError("validation_error", "mail is searched by the separate memo CLI: install @wirecat/cli-memo, then `memo search mail …`");
-    const unknown = chosen.find((one) => !SOURCE_SEARCHED.includes(one));
+    const unknown = chosen.find((one) => !allowed.includes(one));
     if (unknown !== undefined || chosen.length === 0)
-        throw new CliError("validation_error", `--only takes ${SOURCE_SEARCHED.join(", ")}, separated by commas; meetings when --source names a meeting account`);
+        throw new CliError("validation_error", `--only takes ${allowed.join(", ")}, separated by commas; meetings when --source names a meeting account`);
     return [...new Set(chosen)];
 };
 /** One `search all` hit as a person reads it. */
@@ -40,8 +40,10 @@ const maxMeetingsOf = (value) => {
  * `search all`'s scope, paging and matching options, the same in every CLI that mounts it (WC-ACCT-8): a messenger's
  * and a calendar's.
  */
-export const searchAllOptions = (command) => command
-    .option("--only <resources>", "only these resources, separated by commas: messages, notes, events; meetings when --source names a meeting account", searchAllOnlyOf)
+/** `allowed`: the resources `--only` takes, a CRM CLI's with `crm`. */
+export const searchAllOptions = (command, allowed = SOURCE_SEARCHED) => command
+    .option("--only <resources>", `only these resources, separated by commas: ${allowed.filter((one) => one !== "meetings").join(", ")}; ` +
+    "meetings when --source names a meeting account", (value) => searchAllOnlyOf(value, allowed))
     .option("--source <accounts>", "only these accounts, separated by commas: provider:account as a hit shows it, a provider, a kind or " +
     "group:<name>; each resource reads the ones of its kind, and meetings only when it names one")
     .option("--max-meetings <n>", "how many of the meeting account's meetings to look through, newest first, or all for every one (default 100)", maxMeetingsOf)

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

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

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

@@ -3,7 +3,8 @@ import { dirname, join } from "node:path";
 import { CliError, resolvePaths, writeSecurely } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
 import { Argument, Command, Option } from "commander";
-import { describeWhen, findProgram, lastRun, listSchedules, readSchedule, recordSkip, runSchedule, SCHEDULE_DEFAULTS, scheduleFile, scheduleName, spentToday, timerFor, } from "../../background/schedules.js";
+import { parseRoute, ROUTE_HELP, routeText } from "../../background/deliver.js";
+import { describeWhen, findProgram, lastRun, listSchedules, NOTIFY_WHEN, notifyOf, readSchedule, recordSkip, runSchedule, SCHEDULE_DEFAULTS, SKIP_REASONS, scheduleFile, scheduleName, spentToday, timerFor, } from "../../background/schedules.js";
 import { thisMachine } from "../../background/system.js";
 import { locationVariables } from "../../background/units.js";
 import { parseDuration } from "../../domain/duration.js";
@@ -79,7 +80,14 @@ const scheduleAnswer = ({ environment, createdAt, ...schedule }, extra) => ({
 const withWhen = (command) => command
     .option("--every <duration>", "repeat: 30m, 2h, 1d")
     .option("--at <HH:MM>", "every day at this local time")
-    .option("--at-time <time>", "one run: 30m, 2d from now, or an ISO time; the schedule removes itself after it");
+    .option("--at-time <time>", "one run: 30m, 2d from now, or an ISO time; the schedule removes itself after it")
+    .addOption(new Option("--notify-on <when>", "desktop notice after a run (default failures for an agent that repeats with --every, else always)").choices(NOTIFY_WHEN))
+    .option("--to <route>", `also send the result, when --notify-on says so, by the owner's own tg or mail: ${ROUTE_HELP}; repeat it for more`, (route, routes = []) => [...routes, routeText(parseRoute(route))]);
+/** What a schedule keeps of `--notify-on` and `--to`. */
+const deliveryOf = ({ notifyOn, to }) => ({
+    ...(notifyOn ? { notify: notifyOn } : {}),
+    ...(to?.length ? { to } : {}),
+});
 /** What the schedule command needs of a CLI: who it is and, per command, where it prints and which profile runs. */
 /** `skill show follow-ups` exists only for messenger CLIs; any other CLI gets a read-only summary it can run. */
 const promptExample = (app) => app.messenger === false
@@ -209,8 +217,8 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, limits: c
             const spent = spentToday(file);
             if (spent >= maxCostPerDay) {
                 const why = `today's runs cost ${usd(spent)}, the ${usd(maxCostPerDay)} a day allowed; it runs again tomorrow`;
-                recordSkip(file, why);
-                return why;
+                recordSkip(file, why, SKIP_REASONS.costDayCap);
+                return { why, reason: SKIP_REASONS.costDayCap };
             }
         }
         const holder = schedule.onNewMail;
@@ -219,13 +227,18 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, limits: c
         const waiting = await newMail(self, holder);
         if (waiting.unmarked)
             return undefined;
-        if (waiting.emails === 0)
-            return `no mail stored past ${holder}'s mark`;
+        if (waiting.emails === 0) {
+            const why = `no mail stored past ${holder}'s mark`;
+            recordSkip(file, why, SKIP_REASONS.mailNone);
+            return { why, reason: SKIP_REASONS.mailNone };
+        }
         const waited = waiting.oldestStoredAt === null ? 0 : Date.now() - waiting.oldestStoredAt;
         if (!timed || waiting.emails >= mailBatch || waited >= mailWaitMinutes * 60_000)
             return undefined;
-        return (`${waiting.emails} email(s) wait past ${holder}'s mark; it starts at ${mailBatch}, ` +
-            `or once the oldest has waited ${mailWaitMinutes}m`);
+        const why = `${waiting.emails} email(s) wait past ${holder}'s mark; it starts at ${mailBatch}, ` +
+            `or once the oldest has waited ${mailWaitMinutes}m`;
+        recordSkip(file, why, SKIP_REASONS.mailBelowThreshold);
+        return { why, reason: SKIP_REASONS.mailBelowThreshold };
     };
     withWhen(grantsAuthority(annotate(command.command("command"), {
         literal_after_dashes: true,
@@ -248,6 +261,7 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, limits: c
             when: whenOf(this.opts(), COMMAND_MINIMUM_MINUTES),
             environment: environment(),
             createdAt: new Date().toISOString(),
+            ...deliveryOf(this.opts()),
         });
     });
     withWhen(grantsAuthority(annotate(command.command("agent"), {
@@ -329,6 +343,7 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, limits: c
             ...(mailWaitMinutes === undefined ? {} : { mailWaitMinutes }),
             ...(mailBatch === undefined ? {} : { mailBatch }),
             ...(options.maxCostPerDay === undefined ? {} : { maxCostPerDay: options.maxCostPerDay }),
+            ...deliveryOf(options),
         });
     });
     if (newMail)
@@ -349,6 +364,8 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, limits: c
             name: schedule.name,
             kind: schedule.kind,
             when: describeWhen(schedule.when),
+            notify: notifyOf(schedule),
+            ...(schedule.to?.length ? { to: schedule.to } : {}),
             last: lastRun(scheduleFile(state, schedule.name)) ?? null,
             ...(schedule.kind === "agent"
                 ? {
@@ -369,10 +386,12 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, limits: c
                 return "";
             }
             return rows
-                .map(({ name, kind, when, last, spentTodayUsd, maxCostPerDayUsd }) => [
+                .map(({ name, kind, when, notify, to, last, spentTodayUsd, maxCostPerDayUsd }) => [
                 name,
                 kind,
                 when,
+                `notify ${notify}`,
+                ...(to ? [`to ${to.join(", ")}`] : []),
                 last
                     ? `last ${last.at.slice(0, 16).replace("T", " ")} exit ${last.exitCode}` +
                         (last.failures
@@ -386,6 +405,9 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, limits: c
                 ...(last?.skipped
                     ? [`skipped ${last.skipped.at.slice(0, 16).replace("T", " ")}: ${last.skipped.why}`]
                     : []),
+                ...(last?.deliveries ?? [])
+                    .filter((one) => !one.ok)
+                    .map((one) => `not delivered to ${one.to}: ${one.reason}${one.error ? ` (${one.error})` : ""}`),
             ].join("  "))
                 .join("\n");
         });
@@ -398,9 +420,10 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, limits: c
         .argument("<name>", "the schedule's name, as `schedule list` shows it")
         .action(async function (name) {
         const { context, system, state, say, timer } = prepare(this);
-        const why = await waits(this, scheduleFile(state, scheduleName(name)), { timed: false });
-        if (why !== undefined)
-            return say({ name, skipped: true, why }, [`${name}: skipped — ${why}`]);
+        const skip = await waits(this, scheduleFile(state, scheduleName(name)), { timed: false });
+        if (skip !== undefined) {
+            return say({ name, skipped: true, why: skip.why, reason: skip.reason }, [`${name}: skipped — ${skip.why}`]);
+        }
         const last = await untilChildEnds(this, (signal) => runSchedule(app, system, context.env, scheduleFile(state, scheduleName(name)), {
             timer: timer(),
             agentRuns,

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

@@ -0,0 +1,57 @@
+import { type Command } from "commander";
+import { type Body } from "../../cli/envelope.js";
+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";
+/**
+ * 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).
+ */
+export interface CrmRun {
+    /** The profile's name, which `store status` gives as each sync's `profile`. */
+    profile: string;
+    /** The profile's CRM account as the shared store names it: every command reads and syncs only it. */
+    account: AccountKey;
+    store: MessageStore;
+    /** The CRM, built on first use: a command that only reads the store never reads the sign-in. */
+    source: () => CrmSource;
+    /** A profile lock pins the process (WC-ACCT-5): `search all` then reads only this account's deals. */
+    locked?: boolean;
+    env?: NodeJS.ProcessEnv;
+    close?: () => Promise<void>;
+}
+export interface CrmCommandOptions {
+    /** The CLI itself: the first word of examples, and `search all`. */
+    app: AppIdentity;
+    /** Opens the selected profile for one command; `readOnly` when the command only reads the store. */
+    open: (command: Command, access: {
+        readOnly: boolean;
+    }) => Promise<CrmRun>;
+    /** The CRM has leads: mounts `leads list|show`. True when absent. */
+    leads?: boolean;
+    now?: () => number;
+}
+/** What `deals list` and `leads list` narrow by, the same in memo and every CRM CLI (WC-OUT-11). */
+export declare const DEALS_QUERY: {
+    readonly entity: "deal";
+    readonly backend: "native";
+    readonly fields: import("@wirecat/cli-base/query").FieldSpec[];
+};
+export declare const LEADS_QUERY: {
+    readonly entity: "lead";
+    readonly backend: "native";
+    readonly fields: import("@wirecat/cli-base/query").FieldSpec[];
+};
+export declare const PIPELINES_QUERY: {
+    readonly entity: "pipeline";
+    readonly backend: "native";
+    readonly fields: readonly [import("@wirecat/cli-base/query").FieldSpec];
+};
+export declare const STAGES_QUERY: {
+    readonly entity: "stage";
+    readonly backend: "native";
+    readonly fields: readonly [import("@wirecat/cli-base/query").FieldSpec, import("@wirecat/cli-base/query").FieldSpec];
+};
+export type CrmWithin = (command: Command, work: (run: CrmRun) => Promise<Body>) => Promise<void>;
+export declare const addCrmCommands: (program: Command, options: CrmCommandOptions) => void;

package/dist/crm/cli/index.js

@@ -0,0 +1,300 @@
+import { CliError } from "@wirecat/cli-base";
+import { annotate, metaOf, sharedCommand } from "@wirecat/cli-base/commands";
+import { 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 { itemOf, listOf, renderAnswer, snakeKeys } from "../../cli/envelope.js";
+import { queryTerms, termField, withQuery } from "../../cli/list-query.js";
+import { lineOf } from "../../cli/steps.js";
+import { CRM_KINDS } from "../../domain/crm.js";
+import { DEAL_KINDS, DEAL_STATUSES } from "../../domain/deals.js";
+import { count, text } from "../../entities/fields.js";
+import { crmStatus, syncCrm } from "../sync.js";
+import { addCrmSearchAll } from "./search-all.js";
+const MOST = 500;
+const DEAL_FIELDS = [
+    termField("status", "enum", "status:open", { values: DEAL_STATUSES }),
+    termField("stage", "kw", 'stage:"Quote sent"', { relation: "a stage's name, in any letter case" }),
+    termField("pipeline", "kw", "pipeline:Sales", { relation: "pipeline:<id>, or a name only one pipeline has" }),
+    termField("organization", "ref", 'organization:"organization:3"'),
+];
+/** What `deals list` and `leads list` narrow by, the same in memo and every CRM CLI (WC-OUT-11). */
+export const DEALS_QUERY = { entity: "deal", backend: "native", fields: DEAL_FIELDS };
+export const LEADS_QUERY = { entity: "lead", backend: "native", fields: DEAL_FIELDS };
+export const PIPELINES_QUERY = {
+    entity: "pipeline",
+    backend: "native",
+    fields: [termField("kind", "enum", "kind:lead", { values: DEAL_KINDS })],
+};
+export const STAGES_QUERY = {
+    entity: "stage",
+    backend: "native",
+    fields: [
+        termField("kind", "enum", "kind:deal", { values: DEAL_KINDS }),
+        termField("pipeline", "kw", "pipeline:Sales", { relation: "pipeline:<id>, or a name only one pipeline has" }),
+    ],
+};
+/** 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 PIPELINE_UNTRUSTED = ["name", "stages.name"];
+const STAGE_UNTRUSTED = ["name", "pipeline_name"];
+const crmSync = v.strictObject({
+    provider: text,
+    account: text,
+    pipelines: count,
+    synced: v.array(v.strictObject({
+        kind: v.picklist(CRM_KINDS),
+        round: v.picklist(["full", "changes"]),
+        reset: v.boolean(),
+        state: v.picklist(["partial", "complete"]),
+        saved: count,
+        removed: count,
+        unlisted: count,
+        pass: v.optional(v.picklist(["complete", "partial", "held"])),
+        error: v.optional(text),
+    })),
+    issues: v.array(v.strictObject({
+        kind: v.picklist(CRM_KINDS),
+        reason: text,
+        message: text,
+        external_id: v.optional(text),
+    })),
+    complete: v.boolean(),
+    state: v.picklist(["partial", "complete"]),
+    stopped: v.optional(v.picklist(["requests", "deadline", "cancelled"])),
+    progress: v.strictObject({ requests: count, saved: count, steps: count }),
+    hint: v.optional(text),
+});
+const crmSyncProgress = v.strictObject({
+    kind: v.picklist(CRM_KINDS),
+    round: v.nullable(v.picklist(["full", "changes"])),
+    id_pass: v.nullable(text),
+    stored: count,
+    job: text,
+    profile: text,
+    done: count,
+    total: v.nullable(count),
+    remaining: v.nullable(count),
+    state: v.picklist(["partial", "complete"]),
+    updated_at: v.nullable(text),
+    cursor_age_ms: v.nullable(count),
+    line: text,
+});
+const integer = (most) => (value) => {
+    if (!/^[1-9]\d*$/.test(value) || Number(value) > most)
+        throw new InvalidArgumentError(`expected 1 to ${most}`);
+    return Number(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 }));
+const addCrmCommandsDefinition = (program, options) => {
+    const now = () => options.now?.() ?? Date.now();
+    const within = async (command, work) => {
+        const run = await options.open(command, { readOnly: metaOf(command).effects?.local !== "write" });
+        let body;
+        try {
+            body = await work(run);
+        }
+        finally {
+            await run.close?.();
+        }
+        renderAnswer(command, outputFor(command), body);
+    };
+    const example = (command, ...lines) => annotate(command, { examples: lines.map((line) => `${options.app.command} work ${line}`) });
+    example(answerEntity(annotate(program.command("sync"), { effects: FETCH, offline: false, cooperative: true, partial: true }), "crm_sync", crmSync).description("bring the CRM's copy in the local store up to date: pipelines, companies, contacts, deals and leads that " +
+        "changed since the last sync, or everything with --rescan; a run stops before its deadline or --max-pages " +
+        "and the next one goes on from there"), "sync", "sync --rescan", "sync --max-pages 20")
+        .option("--rescan", "list everything again, every id too, dropping a round in progress")
+        .option("--max-pages <pages>", "at most this many requests to the CRM in this run", integer(100_000))
+        .action(async (opts, command) => {
+        const { signal } = environmentOf(command);
+        await within(command, async (run) => {
+            const report = await syncCrm(run.source(), run.store, run.account, {
+                now: now(),
+                budget: runBudgetOf(command, opts.maxPages),
+                ...(signal ? { signal } : {}),
+                ...(opts.rescan ? { rescan: true } : {}),
+            });
+            const failed = report.synced.filter((one) => one.error !== undefined);
+            const timeout = command.optsWithGlobals().timeout;
+            // The same command again, never --rescan: that would drop the round this run leaves in progress.
+            const stuck = report.state === "partial" && report.progress.steps === 0 && failed.length === 0;
+            const next = failed.length || (report.state === "partial" && !stuck)
+                ? [
+                    {
+                        kind: "command",
+                        step: "crm.sync",
+                        command: "sync",
+                        args: Object.fromEntries(Object.entries({ max_pages: opts.maxPages, timeout }).filter(([, value]) => value !== undefined)),
+                        why: failed.length
+                            ? "a kind failed to sync; running sync again retries it"
+                            : "the sync stopped before its end to answer in time; running it again goes on from there",
+                        safe_to_auto_execute: true,
+                    },
+                ]
+                : undefined;
+            const progressAt = lineOf(command, "store status");
+            const hint = failed.length
+                ? `${failed.map((one) => `${one.kind}: ${one.error}`).join("; ")} — run sync again to retry`
+                : stuck
+                    ? `this run moved nothing on: raise --timeout or --max-pages, then run sync again; see progress: ${progressAt}`
+                    : report.state === "partial"
+                        ? `run sync again to continue; see progress: ${progressAt}`
+                        : undefined;
+            const { hint: _hint, ...rest } = report;
+            // What the healthy kinds brought is saved and answered; each failure and each item not kept is an issue.
+            const issues = [
+                ...failed.map((one) => ({
+                    code: "provider_error",
+                    reason: "sync.partial",
+                    source: `crm:${one.kind}`,
+                })),
+                ...report.issues.map((one) => ({
+                    code: "validation_error",
+                    reason: one.reason,
+                    source: one.externalId === undefined ? `crm:${one.kind}` : `crm:${one.kind}/${one.externalId}`,
+                })),
+            ];
+            const partial = report.state === "partial" || issues.length > 0;
+            return itemOf(snakeKeys({ ...rest, ...(hint === undefined ? {} : { hint }) }), {
+                ...(partial ? { meta: { complete: false, ...(issues.length ? { issues } : {}) } } : {}),
+                ...(next ? { next } : {}),
+            });
+        });
+    });
+    const store = annotate(program.command("store").description("the local copy of the CRM"), { effects: NO_EFFECTS });
+    example(answerEntity(annotate(store.command("status"), { effects: LOCAL_READ }), "crm_sync_progress", crmSyncProgress).description("how far each kind's sync is: rows saved, partial or complete, when it last moved, how many are stored"), "store status --json").action(async (_opts, command) => {
+        await within(command, async (run) => {
+            const status = await crmStatus(run.store, run.account, { profile: run.profile, now: now() });
+            return listOf(pathOf(command).join(" "), {
+                items: status.items,
+                limit: status.limit,
+                has_more: false,
+                page: 1,
+            });
+        });
+    });
+    const items = (kind) => {
+        const plural = `${kind}s`;
+        const query = kind === "deal" ? DEALS_QUERY : LEADS_QUERY;
+        const group = annotate(program.command(plural), { effects: NO_EFFECTS }).description(kind === "deal"
+            ? "the CRM's deals as last synced: stage, status, amount and the people on them"
+            : "the CRM's leads as last synced");
+        example(withQuery(annotate(group.command("list"), { effects: LOCAL_READ, output: { entity: kind } }).description(`${plural} copied from the CRM, newest first; run sync to bring them up to date`), query)
+            .option("--limit <n>", `${plural} per page, 1–${MOST}`, integer(MOST), 50)
+            .option("--page <n>", "which page, starting at 1", integer(1_000_000), 1), `${plural} list status:open --json`, `${plural} list stage:"Quote sent"`).action(async (words, opts, command) => {
+            const terms = queryTerms(words, query, `${plural} list`);
+            await within(command, async (run) => {
+                const filter = {
+                    kind,
+                    account: run.account,
+                    ...(terms.has("status") ? { status: terms.get("status") } : {}),
+                    ...(terms.has("stage") ? { stage: terms.get("stage") } : {}),
+                    ...(terms.has("pipeline") ? { pipeline: terms.get("pipeline") } : {}),
+                    ...(terms.has("organization") ? { organization: terms.get("organization") } : {}),
+                };
+                const found = await run.store.deals.list({
+                    ...filter,
+                    limit: Math.min(opts.limit + 1, MOST),
+                    offset: (opts.page - 1) * opts.limit,
+                });
+                return listOf(pathOf(command).join(" "), {
+                    items: marked(found.slice(0, opts.limit), DEAL_UNTRUSTED),
+                    limit: opts.limit,
+                    page: opts.page,
+                    has_more: found.length > opts.limit,
+                    ...(words.length ? { args: { query: words } } : {}),
+                });
+            });
+        });
+        example(annotate(group.command("show"), { effects: LOCAL_READ, output: { entity: kind } })
+            .description(`one ${kind} with its pipeline, stage, status, amount and the people on it`)
+            .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 });
+            });
+        });
+    };
+    /** 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) => {
+        if (!reference.startsWith(`${kind}:`))
+            throw new CliError("validation_error", `${kind}s show takes a ${kind}:<id> reference, as a list shows it`, {
+                reason: "ref.malformed",
+            });
+        const found = await run.store.deals.get(reference);
+        if (found.account?.provider !== run.account.provider || found.account.account !== run.account.account)
+            throw new CliError("not_found", `${reference} is not a copy from this profile's CRM account`);
+        return found;
+    };
+    items("deal");
+    if (options.leads !== false)
+        items("lead");
+    const pipelines = annotate(program.command("pipelines"), { effects: NO_EFFECTS }).description("the CRM's pipelines and their stages, as last synced");
+    example(withQuery(annotate(pipelines.command("list"), { effects: LOCAL_READ, output: { entity: "pipeline" } }).description("pipelines copied from the CRM, with their stages in order and how many are open in each"), PIPELINES_QUERY), "pipelines list --json", "pipelines list kind:lead").action(async (words, _opts, command) => {
+        const terms = queryTerms(words, PIPELINES_QUERY, "pipelines list");
+        await within(command, async (run) => {
+            const found = await run.store.deals.pipelines({
+                account: run.account,
+                ...(terms.has("kind") ? { kind: terms.get("kind") } : {}),
+            });
+            return listOf(pathOf(command).join(" "), {
+                items: marked(found, PIPELINE_UNTRUSTED),
+                limit: Math.max(1, found.length),
+                page: 1,
+                has_more: false,
+                ...(words.length ? { args: { query: words } } : {}),
+            });
+        });
+    });
+    example(annotate(pipelines.command("show"), { effects: LOCAL_READ, output: { entity: "pipeline" } })
+        .description("one pipeline with its funnel: how many reached each stage, how many went on, and the win rate")
+        .argument("<pipeline>", "pipeline:<id>, or a name only one of the CRM's pipelines has"), "pipelines show pipeline:3").action(async (reference, _opts, command) => {
+        await within(command, async (run) => {
+            const report = await run.store.deals.pipeline(reference, { account: run.account });
+            return itemOf({ ...snakeKeys(report), untrusted: PIPELINE_UNTRUSTED });
+        });
+    });
+    const stages = annotate(program.command("stages"), { effects: NO_EFFECTS }).description("the stages of the CRM's pipelines, as last synced");
+    example(withQuery(annotate(stages.command("list"), { effects: LOCAL_READ, output: { entity: "stage" } }).description("every stage of the CRM's pipelines in order, with its outcome and how many are open in it"), STAGES_QUERY), "stages list --json", "stages list kind:lead").action(async (words, _opts, command) => {
+        const terms = queryTerms(words, STAGES_QUERY, "stages list");
+        await within(command, async (run) => {
+            const kind = terms.has("kind") ? terms.get("kind") : undefined;
+            const all = await run.store.deals.pipelines({ account: run.account, ...(kind ? { kind } : {}) });
+            const chosen = terms.has("pipeline")
+                ? [
+                    await run.store.deals.pipeline(terms.get("pipeline"), {
+                        account: run.account,
+                        ...(kind ? { kind } : {}),
+                    }),
+                ]
+                : all;
+            const found = chosen.flatMap((pipeline) => pipeline.stages.map(({ name, position, outcome, externalId, open }) => ({
+                name,
+                position,
+                outcome,
+                externalId,
+                open,
+                pipeline: pipeline.ref,
+                pipelineName: pipeline.name,
+                kind: pipeline.kind,
+            })));
+            return listOf(pathOf(command).join(" "), {
+                items: marked(found, STAGE_UNTRUSTED),
+                limit: Math.max(1, found.length),
+                page: 1,
+                has_more: false,
+                ...(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 });
+};
+// honoursDryRun: a host program other than `run` would otherwise let a write through under --dry-run.
+export const addCrmCommands = honoursDryRun(sharedCommand(addCrmCommandsDefinition));

package/dist/crm/cli/search-all.d.ts

@@ -0,0 +1,12 @@
+import { Command } from "commander";
+import type { AppIdentity } from "../../ports/app.js";
+import type { CrmWithin } from "./index.js";
+/**
+ * `search all` in a CRM CLI: the shared search over the store, its own deals and leads beside the messages, notes and
+ * events other WireCat tools stored. A locked profile reads only its own account's deals.
+ */
+export declare const addCrmSearchAll: (searches: Command, { within, app, example, }: {
+    within: CrmWithin;
+    app: AppIdentity;
+    example: (command: Command, ...lines: string[]) => Command;
+}) => void;

package/dist/crm/cli/search-all.js

@@ -0,0 +1,63 @@
+import { CliError } from "@wirecat/cli-base";
+import { annotate } from "@wirecat/cli-base/commands";
+import { Command } from "commander";
+import { outputFor } from "../../cli/context.js";
+import { LOCAL_READ } from "../../cli/effects.js";
+import { historySkipsOf } from "../../cli/messenger/history-gaps.js";
+import { allAnswer, offsetOf, SOURCE_SEARCHED } from "../../cli/messenger/search-answers.js";
+import { searchAllOptions } from "../../cli/messenger/search-command.js";
+import { SAVE_HELP } from "../../meetings/index.js";
+import { meaningLane } from "../../services/messages-meaning.js";
+import { searchAllWithMeetings } from "../../services/search-all-meetings.js";
+/** What a CRM CLI's `search all` reads: its deals and leads first, then what the other tools stored. */
+const SEARCHED = ["crm", ...SOURCE_SEARCHED];
+const DEFAULT_LIMIT = 20;
+/**
+ * `search all` in a CRM CLI: the shared search over the store, its own deals and leads beside the messages, notes and
+ * events other WireCat tools stored. A locked profile reads only its own account's deals.
+ */
+export const addCrmSearchAll = (searches, { within, app, example, }) => {
+    const all = annotate(new Command("all"), { effects: LOCAL_READ, partial: true, output: { entity: "hit" } })
+        .summary("search stored deals and leads, messages, notes and calendar events")
+        .description("search the CRM's deals and leads by the words of their title, and messages, notes and calendar events other " +
+        "WireCat tools stored — best match first. Use it when you do not know where something was written")
+        .argument("<query...>", 'words and "phrases"; deals and leads match the words of their title')
+        .addHelpText("after", SAVE_HELP);
+    searches.addCommand(searchAllOptions(all, SEARCHED));
+    example(all, "search all Example LLC", "search all website --only crm --json");
+    all.action(async (words, _opts, leaf) => {
+        const opts = leaf.opts();
+        await within(leaf, async (run) => {
+            if (run.locked && opts.source !== undefined)
+                throw new CliError("permission_error", "this process is locked to one profile; search all reads its own CRM account only, without --source", { reason: "profile.locked" });
+            const limit = opts.limit ?? DEFAULT_LIMIT;
+            const offset = offsetOf(opts.page, limit);
+            const env = run.env ?? process.env;
+            const found = await searchAllWithMeetings(run.store, run.account, {
+                text: words.join(" "),
+                limit,
+                ...(offset === undefined ? {} : { offset }),
+                ...(opts.exact ? { exact: true } : {}),
+                ...(opts.timezone === undefined ? {} : { timezone: opts.timezone }),
+                env,
+                only: opts.only ?? SEARCHED,
+                ...(opts.source === undefined ? {} : { source: opts.source }),
+                ...(opts.maxMeetings === undefined ? {} : { maxMeetings: opts.maxMeetings }),
+                ...(run.locked ? { scope: { crm: [run.account] } } : {}),
+            }, { app }, undefined, meaningLane({ env, messenger: { app }, store: async () => run.store }));
+            const note = (text) => outputFor(leaf).renderer.note(text);
+            for (const { resource, source, reason } of found.skipped)
+                note(`${resource ?? source} not searched: ${reason}`);
+            if (!found.items.length)
+                note("nothing found in what the local store holds");
+            const skips = await historySkipsOf(run.store, found.accounts).catch(() => []);
+            const again = {
+                query: words.join(" "),
+                ...(opts.only === undefined ? {} : { only: opts.only.join(",") }),
+                ...(opts.source === undefined ? {} : { source: opts.source }),
+                ...(opts.exact ? { exact: true } : {}),
+            };
+            return allAnswer("search all", found, { limit, page: opts.page ?? 1, again }, opts.exact === true, skips);
+        });
+    });
+};

package/dist/crm/index.d.ts

@@ -0,0 +1,2 @@
+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";

package/dist/crm/index.js

@@ -0,0 +1 @@
+export { crmStatus, cursorName, parseCrmCursor, syncCrm, } from "./sync.js";