@wirecat/cli-core 0.596.0 → 0.598.0

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

package/dist/domain/crm.d.ts

@@ -52,9 +52,20 @@ export interface CrmItem {
     updatedAt?: number | null;
     /** The CRM's own page for it, http or https. */
     url?: string | null;
-    /** What the CRM sends that has no column, such as custom fields with their labels; never a secret. */
+    /** The CRM user it is assigned to, by the user's id: never a contact's. */
+    assignee?: string | null;
+    /**
+     * What the CRM sends that has no column; never a secret. Its own fields' values are here by code as `CrmValue`,
+     * which the deal's `provider_metadata` answers.
+     */
     metadata?: Record<string, unknown>;
 }
+/** One of the CRM's own fields' values: its label, and for a list field the option's label and `option_id`. */
+export interface CrmValue {
+    label: string | null;
+    value: unknown;
+    option_id?: string | string[];
+}
 /**
  * A CRM contact: it becomes an identity of the CRM's provider, `<account>/contact/<id>`, joined to a person by exact
  * email only. A CRM user, such as a deal's owner, is not a contact: its ids are another sequence (`<account>/user/<id>`).
@@ -72,6 +83,23 @@ export interface CrmOrganization {
     url?: string | null;
     metadata?: Record<string, unknown>;
 }
+/** One of a CRM account's own fields on a kind: what the code a row's `metadata` is keyed by means. */
+export interface CrmField {
+    /** The CRM's key for it, unique in its kind. */
+    code: string;
+    /** Its title in the CRM; null when the CRM gives none. */
+    label: string | null;
+    /** The CRM's own word for its type, such as `string` or `enumeration`. */
+    type: string;
+    multiple: boolean;
+    /** Whether the CRM can filter a list by it. */
+    filterable: boolean;
+    /** A list field's options in the CRM's order; absent on any other field. */
+    options?: {
+        id: string;
+        label: string;
+    }[];
+}
 export interface CrmRecords {
     deal: CrmItem;
     lead: CrmItem;

package/dist/entities/deal.d.ts

@@ -33,6 +33,14 @@ export declare const deal: v.StrictObjectSchema<{
         readonly account: v.StringSchema<undefined>;
     }, undefined>, undefined>;
     readonly external_id: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** A CRM copy's assignee, the identity `<account>/user/<id>`. */
+    readonly assignee: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** A CRM copy's own fields by code; a list field's value is its option's label, `option_id` its id. */
+    readonly provider_metadata: v.RecordSchema<v.StringSchema<undefined>, v.StrictObjectSchema<{
+        readonly label: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly value: v.UnknownSchema;
+        readonly option_id: v.OptionalSchema<v.UnionSchema<[v.StringSchema<undefined>, v.ArraySchema<v.StringSchema<undefined>, undefined>], undefined>, undefined>;
+    }, undefined>, undefined>;
     readonly people: v.ArraySchema<v.StrictObjectSchema<{
         readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
         readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
@@ -86,6 +94,14 @@ export declare const lead: v.StrictObjectSchema<{
         readonly account: v.StringSchema<undefined>;
     }, undefined>, undefined>;
     readonly external_id: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** A CRM copy's assignee, the identity `<account>/user/<id>`. */
+    readonly assignee: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** A CRM copy's own fields by code; a list field's value is its option's label, `option_id` its id. */
+    readonly provider_metadata: v.RecordSchema<v.StringSchema<undefined>, v.StrictObjectSchema<{
+        readonly label: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly value: v.UnknownSchema;
+        readonly option_id: v.OptionalSchema<v.UnionSchema<[v.StringSchema<undefined>, v.ArraySchema<v.StringSchema<undefined>, undefined>], undefined>, undefined>;
+    }, undefined>, undefined>;
     readonly people: v.ArraySchema<v.StrictObjectSchema<{
         readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
         readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;

package/dist/entities/deal.js

@@ -32,6 +32,14 @@ export const deal = v.strictObject({
     /** The CRM account it is a copy from; `null` for the owner's own. */
     account: crmAccount,
     external_id: nullableText,
+    /** A CRM copy's assignee, the identity `<account>/user/<id>`. */
+    assignee: nullableText,
+    /** A CRM copy's own fields by code; a list field's value is its option's label, `option_id` its id. */
+    provider_metadata: v.record(v.string(), v.strictObject({
+        label: v.nullable(v.string()),
+        value: v.unknown(),
+        option_id: v.optional(v.union([v.string(), v.array(v.string())])),
+    })),
     people: v.array(v.strictObject({ ...party.entries, role: v.picklist(["owner", "contact", "decision-maker"]) })),
     author: v.strictObject({
         type: v.picklist(["person", "bot"]),

package/dist/entities/index.d.ts

@@ -262,6 +262,12 @@ export declare const ENTITIES: {
             readonly account: v.StringSchema<undefined>;
         }, undefined>, undefined>;
         readonly external_id: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly assignee: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly provider_metadata: v.RecordSchema<v.StringSchema<undefined>, v.StrictObjectSchema<{
+            readonly label: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly value: v.UnknownSchema;
+            readonly option_id: v.OptionalSchema<v.UnionSchema<[v.StringSchema<undefined>, v.ArraySchema<v.StringSchema<undefined>, undefined>], undefined>, undefined>;
+        }, undefined>, undefined>;
         readonly people: v.ArraySchema<v.StrictObjectSchema<{
             readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
             readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
@@ -311,6 +317,12 @@ export declare const ENTITIES: {
             readonly account: v.StringSchema<undefined>;
         }, undefined>, undefined>;
         readonly external_id: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly assignee: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly provider_metadata: v.RecordSchema<v.StringSchema<undefined>, v.StrictObjectSchema<{
+            readonly label: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly value: v.UnknownSchema;
+            readonly option_id: v.OptionalSchema<v.UnionSchema<[v.StringSchema<undefined>, v.ArraySchema<v.StringSchema<undefined>, undefined>], undefined>, undefined>;
+        }, undefined>, undefined>;
         readonly people: v.ArraySchema<v.StrictObjectSchema<{
             readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
             readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;

package/dist/errors/reasons.js

@@ -215,6 +215,10 @@ const OTHERS = [
     validation("crm.stage-unknown", "a CRM item stands in a stage the store does not hold; it was not kept"),
     validation("crm.item-invalid", "a CRM item has a field the store refuses, such as a currency it does not keep"),
     validation("crm.pipeline-required", "the CRM has more than one pipeline of the kind; the write names one"),
+    validation("field.unknown", "no custom field of the kind has that code or label; `fields list` lists them"),
+    validation("field.ambiguous", "more than one custom field has that label; name one by its code"),
+    validation("field.unknown-option", "the list field has no option with that id or label"),
+    validation("field.unknown-kind", "fields are listed for deals, leads, people and organizations only"),
     validation("crm.write-unsupported", "the CRM does not take this write, or does not recognise a repeated one"),
     validation("crm.unlisted-held", "a list of every id would mark most of a kind deleted; nothing was, until --rescan"),
     validation("order.duplicate", "the shop's order with this number is already stored; change its status instead"),

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { bareCheck, type CheckWords, checkWords } from "./domain/checks.js";
 export type { CounterField, CounterObservation, CounterObservations, CounterState } from "./domain/counters.js";
 export { COUNTER_FIELDS, counterValue, observedCounters } from "./domain/counters.js";
-export { CRM_KINDS, type CrmItem, type CrmKind, type CrmOrganization, type CrmPerson, type CrmPipeline, type CrmRecords, type CrmStage, isItemKind, } from "./domain/crm.js";
+export { CRM_KINDS, type CrmField, type CrmItem, type CrmKind, type CrmOrganization, type CrmPerson, type CrmPipeline, type CrmRecords, type CrmStage, type CrmValue, isItemKind, } from "./domain/crm.js";
 export { DEAL_KINDS, DEAL_ROLES, DEAL_STATUSES, type DealKind, type DealRole, type DealStatus, STAGE_OUTCOMES, type StageOutcome, } from "./domain/deals.js";
 export { FINANCE_REVIEWS, type FinanceReview, INVOICE_DIRECTIONS, INVOICE_STATUSES, type InvoiceDirection, type InvoiceStatus, MONEY_DIRECTIONS, type MoneyDirection, } from "./domain/finance.js";
 export { type FormattedText, type HtmlFormatting, type MarkdownFormatting, type TextSpan, validateFormattedText, } from "./domain/formatting.js";

package/dist/kit/index.d.ts

@@ -2,5 +2,6 @@ export { ARGV_LOG, argvLogSetup } from "./argv-log.js";
 export { type ContractCase, type ContractOptions, contractCases, OPTIONAL_METHODS } from "./contract.js";
 export { type FakeAdapter, fakeAdapter } from "./fake.js";
 export { type McpStdio, type McpStdioStreams, type McpToolResult, mcpOverStdio } from "./mcp-stdio.js";
+export { neverAnswers, type RunScopeCase, type RunScopeOptions, runScopeCases } from "./run-scope.js";
 export { type SearchRecipes, searchRecipes, seedSearchRecipes } from "./search-recipes.js";
 export { BUSY_PAGE, contractSeed, digitIds, type IdKind, type IdMaker, type Seed, wordIds } from "./seed.js";

package/dist/kit/index.js

@@ -2,5 +2,6 @@ export { ARGV_LOG, argvLogSetup } from "./argv-log.js";
 export { contractCases, OPTIONAL_METHODS } from "./contract.js";
 export { fakeAdapter } from "./fake.js";
 export { mcpOverStdio } from "./mcp-stdio.js";
+export { neverAnswers, runScopeCases } from "./run-scope.js";
 export { searchRecipes, seedSearchRecipes } from "./search-recipes.js";
 export { BUSY_PAGE, contractSeed, digitIds, wordIds } from "./seed.js";

package/dist/kit/run-scope.d.ts

@@ -0,0 +1,34 @@
+import { type ProgramDefinition, type RunOptions } from "../cli/program.js";
+export interface RunScopeCase {
+    name: string;
+    /** Throws an `AssertionError` when the command does not run inside cli-core's run. */
+    run(): Promise<void>;
+}
+export interface RunScopeOptions {
+    /** The CLI's own program definition, as its `run()` hands it to cli-core. */
+    definition: ProgramDefinition;
+    /**
+     * The words that run each remote command to success against the answering fake, by command path:
+     * `{ "comments show": ["personal", "comments", "show", "c1"] }`. A write whose level is `ask` needs a profile that
+     * allows it, or its refusal fails the case.
+     */
+    commands: Record<string, readonly string[]>;
+    /** Remote commands left out, each with its reason: one that listens until stopped, one that asks npm. */
+    skip?: Record<string, string>;
+    /** What `run()` gets beside the streams: the keyring, and the fake that answers every request. */
+    answering: () => RunOptions;
+    /** The same, with a fake that takes every request and never settles it, `neverAnswers` for an HTTP service. */
+    silent: () => RunOptions;
+    /** The `--timeout` a silent run gets; 100 ms. */
+    timeoutMs?: number;
+}
+/** A `fetch` that never settles, not even on abort: only the run's own deadline can end the command. */
+export declare const neverAnswers: typeof fetch;
+/**
+ * Cases that each remote command runs inside cli-core's run — `baseContext(command, resolveSettings).run(body)` — and
+ * not beside it, so `--record` keeps a run named after the command (WC-LIFE-15); and that `--timeout` ends it when
+ * its service never answers, a write as `outcome_unknown` (WC-LIFE-5, WC-LIFE-9). The recorded case is the one that
+ * catches a command beside the run: `run()`'s own deadline still ends such a command on time. The first case fails
+ * on a remote command with no words and no skip.
+ */
+export declare const runScopeCases: (options: RunScopeOptions) => RunScopeCase[];

package/dist/kit/run-scope.js

@@ -0,0 +1,112 @@
+import assert from "node:assert/strict";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { metaOf } from "@wirecat/cli-base/commands";
+import { createProgram, run } from "../cli/program.js";
+import { findRun, runsDirFor } from "../runs/run.js";
+/** A `fetch` that never settles, not even on abort: only the run's own deadline can end the command. */
+export const neverAnswers = (() => new Promise(() => { }));
+const GRACE_MS = 2000;
+const remoteCommands = (program, path = []) => program.commands.flatMap((command) => {
+    const at = [...path, command.name()];
+    if (command.commands.length > 0)
+        return remoteCommands(command, at);
+    const meta = metaOf(command);
+    const remote = meta.effects?.remote;
+    return remote && remote !== "none" ? [{ path: at.join(" "), remote, partial: meta.partial === true }] : [];
+});
+const within = async (ms, what, body) => {
+    let timer;
+    const late = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new assert.AssertionError({ message: what })), ms);
+        timer.unref();
+    });
+    try {
+        return await Promise.race([body, late]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+const parsed = (text) => {
+    try {
+        return JSON.parse(text.trim());
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Cases that each remote command runs inside cli-core's run — `baseContext(command, resolveSettings).run(body)` — and
+ * not beside it, so `--record` keeps a run named after the command (WC-LIFE-15); and that `--timeout` ends it when
+ * its service never answers, a write as `outcome_unknown` (WC-LIFE-5, WC-LIFE-9). The recorded case is the one that
+ * catches a command beside the run: `run()`'s own deadline still ends such a command on time. The first case fails
+ * on a remote command with no words and no skip.
+ */
+export const runScopeCases = (options) => {
+    const { definition, commands, skip = {}, timeoutMs = 100 } = options;
+    const { app } = definition;
+    const cli = async (argv, given) => {
+        const out = [];
+        const err = [];
+        const env = {
+            ...process.env,
+            ...given.env,
+            [`${app.envPrefix}_STATE_DIR`]: mkdtempSync(join(tmpdir(), "run-scope-")),
+        };
+        const code = await run(argv, definition, {
+            ...given,
+            env,
+            tty: false,
+            streams: { data: (text) => out.push(text), diagnostic: (text) => err.push(text) },
+        });
+        return { code, out: out.join(""), err: err.join(""), env };
+    };
+    const machine = (words) => words.some((word) => word === "--json" || word.startsWith("--json=")) ? [...words] : [...words, "--json"];
+    const recordedCase = (path, words) => ({
+        name: `${path} runs in a recorded run named after it`,
+        run: async () => {
+            const ran = await within(GRACE_MS, `${path} did not end against the answering fake`, (async () => cli(["--record", ...machine(words)], options.answering()))());
+            assert.equal(ran.code, 0, `${path} must succeed against the answering fake; it exited ${ran.code}: ${ran.err}`);
+            const runId = parsed(ran.out)?.meta?.run_id;
+            assert.equal(typeof runId, "string", `${path} answered without meta.run_id`);
+            assert.doesNotMatch(String(runId), /-process-/, `${path} answered outside a run of its own: ${runId}`);
+            const kept = findRun(runsDirFor(app, ran.env), String(runId));
+            assert.ok(kept, `--record kept no run ${runId} for ${path}`);
+            assert.equal(kept.metadata.command, path, `the run of ${path} is named ${kept.metadata.command}`);
+        },
+    });
+    const timeoutCase = ({ path, remote, partial }, words) => {
+        const expected = remote === "write" ? "outcome_unknown" : "timeout";
+        return {
+            name: `${path} ends in ${expected}${partial ? " or a partial answer" : ""} at --timeout when the service never answers`,
+            run: async () => {
+                const ran = await within(timeoutMs + GRACE_MS, `${path} was still running ${GRACE_MS} ms after its --timeout ${timeoutMs}ms`, cli(["--timeout", `${timeoutMs}ms`, ...machine(words)], options.silent()));
+                const answered = parsed(ran.out)?.meta?.complete;
+                if (partial && ran.code === 0 && answered === false)
+                    return;
+                const code = parsed(ran.err)?.error?.code;
+                assert.equal(code, expected, `${path} against a silent service ended in ${String(code)}: ${ran.out}${ran.err}`);
+            },
+        };
+    };
+    const remote = remoteCommands(createProgram(definition));
+    const coverage = {
+        name: "every remote command has its words or a reason to skip it",
+        run: async () => {
+            const missing = remote.map(({ path }) => path).filter((path) => !(path in commands) && !(path in skip));
+            assert.deepEqual(missing, [], `remote commands with no words in \`commands\` and no reason in \`skip\``);
+            const known = new Set(remote.map(({ path }) => path));
+            const stray = [...Object.keys(commands), ...Object.keys(skip)].filter((path) => !known.has(path));
+            assert.deepEqual(stray, [], "paths in `commands` or `skip` that are not remote commands of this program");
+        },
+    };
+    return [
+        coverage,
+        ...remote.flatMap((one) => {
+            const words = commands[one.path];
+            return words ? [recordedCase(one.path, words), timeoutCase(one, words)] : [];
+        }),
+    ];
+};

package/dist/mcp/app-server.js

@@ -124,8 +124,13 @@ export const serveAppOverStdio = async (command, context, options) => {
     });
     const ended = await new Promise((resolve) => {
         wire.ended.then(() => resolve("input"));
-        if (own)
-            signal?.addEventListener("abort", () => resolve("stopped"), { once: true });
+        if (own) {
+            // A stop that came before this line fires no abort event.
+            if (signal?.aborted)
+                resolve("stopped");
+            else
+                signal?.addEventListener("abort", () => resolve("stopped"), { once: true });
+        }
         else {
             process.once("SIGINT", () => resolve("stopped"));
             process.once("SIGTERM", () => resolve("stopped"));

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

@@ -11,6 +11,11 @@ export interface MeetingCommandDeps {
     importHelp?: string;
     writeFile?: (path: string, content: string) => Promise<void>;
     write: (value: unknown, format: "json" | "jsonl" | "text") => void;
+    /**
+     * Runs a command that reaches the account inside cli-core's run, so it is recorded and ended by `--timeout`:
+     * `inCommandRun` from `@wirecat/cli-core/cli`. Required, since this module cannot reach the run itself.
+     */
+    inRun: <T>(command: Command, body: () => Promise<T>) => Promise<T>;
     now?: () => number;
 }
 export { addMeetingPassageCommand, createMeetingPassageCommand, type MeetingPassageFlags, meetingPassageRequest, } from "./passage.js";

package/dist/meetings/cli/index.js

@@ -121,14 +121,15 @@ const addMeetingCommandsDefinition = (program, deps) => {
         .option("--since-time <time>", "fetch meetings starting at or after this ISO 8601 date or time", date)
         .option("--lookback-days <days>", "revisit recent occurrences for late transcripts (0–31)", lookbackDays, 0)
         .action(async (opts, command) => {
-        if (!deps.source)
+        const source = deps.source;
+        if (!source)
             throw new MeetingError("configuration_error", "meeting source is unavailable");
-        print(await pull(deps.source, deps.store, {
+        await deps.inRun(command, async () => print(await pull(source, deps.store, {
             accountId: deps.accountId,
             since: opts.sinceTime === undefined ? undefined : new Date(opts.sinceTime).toISOString(),
             now: deps.now?.(),
             lookbackMs: opts.lookbackDays * 86400000,
-        }), command);
+        }), command));
     });
     const importCommand = annotate(group.command("import"), {
         effects: LOCAL_WRITE,