@wirecat/cli-core 0.564.0 → 0.565.0

package/dist/calendar/testing/answers.js

@@ -1,6 +1,8 @@
+import { Command } from "commander";
 import * as v from "valibot";
 import { answerEntitySchema } from "../../cli/answer-entity.js";
-import { snakeKeys } from "../../cli/envelope.js";
+import { provide } from "../../cli/context.js";
+import { addCalendarCommands } from "../cli/index.js";
 const commandAt = (root, argv) => {
     let at = root;
     for (const word of argv) {
@@ -11,28 +13,97 @@ const commandAt = (root, argv) => {
     }
     return at;
 };
-/**
- * Parses what a shared calendar command handed its host against the command's entity, as a host prints it: keys in
- * snake_case, a list's items one by one, a search's hits each with the search's `untrusted`, and no `next`. A `meta`
- * goes into the host's envelope, never into the item.
- */
-export const checkCalendarAnswer = (root, argv, value) => {
+/** Each item of a printed calendar answer, parsed against the command's declared entity. */
+export const checkCalendarAnswer = (root, argv, envelope) => {
     const command = commandAt(root, argv);
     const schema = answerEntitySchema(command);
     if (!schema)
         throw new Error(`${argv.join(" ")} declares no answer entity`);
-    const { next: _next, meta: _meta, ...body } = snakeKeys(value);
-    const marker = body.untrusted
-        ?.filter((field) => field.startsWith("hits."))
-        .map((field) => field.slice("hits.".length));
-    const items = Array.isArray(body.items)
-        ? body.items
-        : Array.isArray(body.hits)
-            ? body.hits.map((hit) => ({ ...hit, untrusted: marker }))
-            : [body];
-    for (const item of items) {
+    const body = envelope;
+    for (const item of body.items ?? [body.item]) {
         const parsed = v.safeParse(schema, item);
         if (!parsed.success)
             throw new Error(`${argv.join(" ")}: ${parsed.issues.map((issue) => `${v.getDotPath(issue) ?? ""} ${issue.message}`).join("; ")}`);
     }
 };
+export const CALENDAR_TEST_APP = {
+    command: "gcal",
+    appName: "gcal-cli",
+    envPrefix: "GCAL",
+    description: "synthetic",
+    version: "1.0.0",
+};
+/**
+ * The shared calendar commands on a bare program over `run`, as an app mounts them, printing to captured streams. A
+ * test of the commands themselves; an app's own tests go through its `run()`.
+ */
+export const calendarTestProgram = (run, options = {}) => {
+    const stderr = [];
+    const opened = [];
+    let data = "";
+    const build = (tty = false) => {
+        const root = new Command("gcal")
+            .exitOverride()
+            .configureOutput({ writeErr: () => undefined, writeOut: () => undefined })
+            .option("--json")
+            .option("--jsonl")
+            .option("--offline")
+            .option("--full")
+            .option("--timeout <duration>")
+            .option("--yes")
+            .option("--dry-run");
+        addCalendarCommands(root, {
+            app: CALENDAR_TEST_APP,
+            open: async (_command, access) => {
+                opened.push(access);
+                return run;
+            },
+            now: () => Date.now(),
+            timezone: "UTC",
+            // A help example names a file; no test writes into the working folder.
+            readFile: async () => "",
+            writeFile: async () => undefined,
+            ...options,
+        });
+        provide(root, {
+            streams: {
+                data: (text) => {
+                    data += text;
+                },
+                diagnostic: (text) => {
+                    stderr.push(text);
+                },
+            },
+            tty,
+        });
+        return root;
+    };
+    const root = build();
+    const cli = async (...args) => {
+        const fresh = build();
+        data = "";
+        const dashes = args.indexOf("--");
+        const argv = args.includes("--json")
+            ? args
+            : dashes < 0
+                ? [...args, "--json"]
+                : [...args.slice(0, dashes), "--json", ...args.slice(dashes)];
+        await fresh.parseAsync(argv, { from: "user" });
+        if (!data.trim())
+            throw new Error(`${args.join(" ")} printed nothing`);
+        const envelope = JSON.parse(data);
+        // A --dry-run preview answers what would happen, not the command's entity.
+        if (!args.includes("--dry-run"))
+            checkCalendarAnswer(fresh, args, envelope);
+        // The run's own facts differ every run; a test compares the rest.
+        const { item, meta, ...rest } = envelope;
+        const { run_id: _run, duration_ms: _duration, ...facts } = meta;
+        return { ...(item ?? {}), ...rest, meta: facts };
+    };
+    const text = async (...args) => {
+        data = "";
+        await build(true).parseAsync(args, { from: "user" });
+        return data;
+    };
+    return { root, cli, text, stderr, opened };
+};

package/dist/calendar/testing/writer.d.ts

@@ -25,4 +25,5 @@ export interface FakeCalendarWriter extends CalendarWriter {
 }
 export declare const fakeCalendarWriter: (options?: {
     provider?: string;
+    now?: () => number;
 }) => FakeCalendarWriter;

package/dist/calendar/testing/writer.js

@@ -1,7 +1,9 @@
 import { CliError } from "@wirecat/cli-base";
 import { calendarConflict } from "../writer.js";
 export const fakeCalendarWriter = (options = {}) => {
+    const now = options.now ?? Date.now;
     const calendars = new Map();
+    const made = new Map();
     const calls = [];
     let version = 0;
     let lose = false;
@@ -89,8 +91,12 @@ export const fakeCalendarWriter = (options = {}) => {
                 participants: [],
             });
             of(calendar.externalId).set(id, entry);
+            made.set(id, now());
             return answer(entry);
         },
+        async quickAdded(calendar, since) {
+            return [...of(calendar.externalId).values()].filter((one) => (made.get(one.externalId) ?? -1) >= since);
+        },
         /** Keeps one event per UID on a calendar: a UID sent again replaces the event under the same id. */
         async importEvent(calendar, event) {
             const held = [...of(calendar.externalId).values()].find((one) => one.icalUid === event.uid);

package/dist/calendar/writer.d.ts

@@ -67,11 +67,16 @@ export interface CalendarWriter {
     }): Promise<EntryInput>;
     /**
      * Optional: the provider makes an event from one line of text, reading its date, time and place its own way. The
-     * provider picks the id, so a retry after `outcome_unknown` may make a second event.
+     * provider picks the id, so a retry after `outcome_unknown` first asks `quickAdded`.
      */
     quickAdd?(calendar: StoredCalendar, text: string, options: {
         notify: boolean;
     }): Promise<EntryInput>;
+    /**
+     * With `quickAdd`: the events this account made on `calendar` at or after `since` (epoch ms), so a retry of a quick
+     * add whose answer was lost finds the event instead of making a second one.
+     */
+    quickAdded?(calendar: StoredCalendar, since: number): Promise<EntryInput[]>;
     /**
      * Optional: adds a private copy of an event read from an iCalendar file, under its own UID, as Google's
      * `events.import`. The provider mails nobody. Sending the same UID again goes to the provider again; what it does

package/dist/calendar/writes.d.ts

@@ -86,10 +86,12 @@ export declare const createEvent: (context: WriteContext, calendarReference: str
 }>;
 /**
  * An event the provider makes from one line of text, as Google's quickAdd. Nobody is mailed unless `notify` says so:
- * the attendees are known only once the provider has read the text.
+ * the attendees are known only once the provider has read the text. The provider picks the event's id, so a retry
+ * with the `id` a lost attempt named first looks for the event that attempt made.
  */
 export declare const createEventFromText: (context: WriteContext, calendarReference: string, text: string, options?: {
     notify?: boolean;
+    id?: string;
 }) => Promise<{
     operation_id: string;
     event: string | null;

package/dist/calendar/writes.js

@@ -165,9 +165,38 @@ export const createEvent = async (context, calendarReference, fields, options =
 };
 /** The longest line `createEventFromText` sends; a quick add is one sentence, not a description. */
 const TEXT_MAX = 1000;
+/** How far the provider's clock may run behind this computer's when a retry looks for what a lost quick add made. */
+const CLOCK_SKEW_MS = 120_000;
+const TIME_DIGITS = 9;
+/**
+ * A quick add's id: `q`, which no hex create id has, then when it was sent, so a retry knows from when to look for the
+ * event it may have made.
+ */
+const quickId = (at) => `q${at.toString(32).padStart(TIME_DIGITS, "0")}${newEventId()}`;
+const QUICK_ID = new RegExp(`^q[a-v0-9]{${TIME_DIGITS}}[a-f0-9]{32}$`, "u");
+const sentAt = (id) => Number.parseInt(id.slice(1, 1 + TIME_DIGITS), 32);
+const wordsOf = (text) => text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
+/**
+ * What a lost quick add made: an event this account made on the calendar since the attempt, whose title's every word
+ * is in the line. The provider builds the title from the line's own words.
+ */
+const lostQuickAdd = async (context, calendar, line, id) => {
+    const quickAdded = context.writes.writer.quickAdded;
+    if (!quickAdded)
+        throw new CliError("validation_error", `this provider cannot find a lost quick add; leave out ${context.names.id}`, {
+            param: context.names.id,
+        });
+    const words = new Set(wordsOf(line));
+    const found = (await quickAdded.call(context.writes.writer, calendar, sentAt(id) - CLOCK_SKEW_MS)).filter((entry) => entry.status !== "cancelled" && wordsOf(entry.title ?? "").every((word) => words.has(word)));
+    if (found.length > 1)
+        throw new CliError("validation_error", `${found.length} events made since that attempt could be the one it added; look with events list ` +
+            "changed_at>=today and add it again only if none is", { reason: "event.quick-add-ambiguous", operation_id: id, retryable: false });
+    return found[0];
+};
 /**
  * An event the provider makes from one line of text, as Google's quickAdd. Nobody is mailed unless `notify` says so:
- * the attendees are known only once the provider has read the text.
+ * the attendees are known only once the provider has read the text. The provider picks the event's id, so a retry
+ * with the `id` a lost attempt named first looks for the event that attempt made.
  */
 export const createEventFromText = async (context, calendarReference, text, options = {}) => {
     const quickAdd = context.writes.writer.quickAdd;
@@ -178,29 +207,22 @@ export const createEventFromText = async (context, calendarReference, text, opti
         throw new CliError("validation_error", "the text is empty: say what, when and where");
     if (line.length > TEXT_MAX || /[\r\n]/u.test(line))
         throw new CliError("validation_error", `the text is one line of at most ${TEXT_MAX} characters`);
+    if (options.id !== undefined && !QUICK_ID.test(options.id))
+        throw new CliError("validation_error", `${context.names.id} is the id a quick add's outcome_unknown named`, {
+            param: context.names.id,
+        });
     const calendar = writable(await calendarIn(context.store, context.accountId, calendarReference));
+    const lost = options.id === undefined ? undefined : await lostQuickAdd(context, calendar, line, options.id);
     const notify = options.notify ?? false;
-    const guard = writeGuard(context, keysFor(context, "quick-add", notify));
-    const id = newEventId();
+    const id = lost ? options.id : quickId(context.now);
     let entry;
-    try {
-        entry = await guardedWrite(guard, { chatId: null, kind: "edit", key: COMMAND_KEY["quick-add"], operationId: id, sendId: id, notify }, () => quickAdd.call(context.writes.writer, calendar, line, { notify }));
-    }
-    catch (error) {
-        if (isCliError(error) && error.code === "outcome_unknown")
-            throw new CliError("outcome_unknown", `${error.message} — the provider may have made the event, and a create from text cannot be retried safely: ` +
-                "sync, then look with events list changed_at>=today before adding it again", { ...error.details, operation_id: id, retryable: false });
-        throw error;
-    }
-    let saved;
-    try {
-        ;
-        [saved] = await context.store.saveEntries(calendar.id, [entry], context.now);
-    }
-    catch (error) {
-        throw new CliError(isCliError(error) ? error.code : "invalid_response", `the provider made event ${entry.externalId}, but the local store did not save it ` +
-            `(${error instanceof Error ? error.message : String(error)}); sync to store it — do not create it again`, { ...(isCliError(error) ? error.details : {}), operation_id: id, id: entry.externalId, retryable: false });
+    if (lost)
+        entry = lost;
+    else {
+        const guard = writeGuard(context, keysFor(context, "quick-add", notify));
+        entry = await retryable(context, id, () => guardedWrite(guard, { chatId: null, kind: "edit", key: COMMAND_KEY["quick-add"], operationId: id, sendId: id, notify }, () => quickAdd.call(context.writes.writer, calendar, line, { notify })));
     }
+    const [saved] = await savedAfterCreate(context, id, () => context.store.saveEntries(calendar.id, [entry], context.now));
     return answerOf(id, saved, (entry.recurrence?.length ?? 0) > 0);
 };
 /** The most events one import sends: a file of more is refused before anything goes. */

package/dist/cli/config-command.js

@@ -56,7 +56,7 @@ export const configCommand = (app, config, { permissionKey = config.permissions,
                     ...(declared ? { default: declared.default, description: declared.description } : {}),
                 };
             }),
-            store_settings: await storeSettings(env),
+            store_settings: (await storeSettings(env)).filter(({ setting }) => offersStoreSetting(app, setting)),
         }));
         for (const issue of [
             ...(settings.configIssues ?? []),

package/dist/cli/config-issues.d.ts

@@ -76,11 +76,13 @@ export declare const issueMessage: (issues: readonly ConfigIssue[], doctor?: str
  * `knownPermissions` (from `knownPermissionKeys`), each saved permission key outside it is an issue too, in every
  * section.
  */
-export declare const checkConfigText: <T extends v.GenericSchema>(text: string, { file, tool, schema, knownPermissions, }: {
+export declare const checkConfigText: <T extends v.GenericSchema>(text: string, { file, tool, schema, knownPermissions, repair, }: {
     file: string;
     tool: string;
     schema: T;
     knownPermissions?: ReadonlySet<string>;
+    /** `false` for a CLI with its own `config` that has no `repair`: no fix then names one. */
+    repair?: boolean;
 }) => {
     issues: ConfigIssue[];
     config: v.InferOutput<T> | undefined;

package/dist/cli/config-issues.js

@@ -317,12 +317,12 @@ export const issueMessage = (issues, doctor = "doctor") => {
  * `knownPermissions` (from `knownPermissionKeys`), each saved permission key outside it is an issue too, in every
  * section.
  */
-export const checkConfigText = (text, { file, tool, schema, knownPermissions, }) => {
+export const checkConfigText = (text, { file, tool, schema, knownPermissions, repair = true, }) => {
     const parsed = parseConfigText(text, file);
     if ("issue" in parsed) {
         const issue = publicIssue(parsed.issue);
         // Offered only where it would work, so the desktop never shows a Repair button that fails.
-        if (repairConfigText(text).state === "repaired")
+        if (repair && repairConfigText(text).state === "repaired")
             issue.fix = `${tool} config repair`;
         return { issues: [issue], config: undefined };
     }

package/dist/cli/contract-evidence.d.ts

@@ -15,7 +15,7 @@ export declare const contractEvidence: (root: Command, { fields, errors }?: Cont
     field_only: string[];
     reasons: readonly {
         reason: string;
-        code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
+        code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "conflict" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
         message: string;
         details: string[];
         step?: string | undefined;

package/dist/cli/early-refusal.d.ts

@@ -22,7 +22,8 @@ export declare const refuseWriteBeforeConnecting: (action: Command, { app, env,
  * A command of a CLI that declares its own keys (`commandPermissions`), refused by its key before anything connects:
  * `deny` stops it, `readonly` stops a write, and the read-only lock stops a write to the service. `ask` is left to
  * the write guard, which can put the question. A saved or `--permission` key that names no command stops every keyed
- * command; housekeeping still runs, so `config unset` can remove it.
+ * command; housekeeping still runs, so `config unset` can remove it. Under the lock a non-messenger CLI still previews
+ * a `--dry-run`, which sends nothing (WC-PERM-12); a messenger's preview stays refused (SEC-65).
  */
 export declare const refuseByCommandPermissions: (action: Command, permissions: CommandPermissions, { app, env, dryRun, resolve }: {
     app: AppIdentity;

package/dist/cli/early-refusal.js

@@ -79,7 +79,8 @@ export const refuseWriteBeforeConnecting = (action, { app, env, dryRun, resolve
  * A command of a CLI that declares its own keys (`commandPermissions`), refused by its key before anything connects:
  * `deny` stops it, `readonly` stops a write, and the read-only lock stops a write to the service. `ask` is left to
  * the write guard, which can put the question. A saved or `--permission` key that names no command stops every keyed
- * command; housekeeping still runs, so `config unset` can remove it.
+ * command; housekeeping still runs, so `config unset` can remove it. Under the lock a non-messenger CLI still previews
+ * a `--dry-run`, which sends nothing (WC-PERM-12); a messenger's preview stays refused (SEC-65).
  */
 export const refuseByCommandPermissions = (action, permissions, { app, env, dryRun, resolve }) => {
     const key = permissions.keyOf(commandPathOf(action));
@@ -87,7 +88,8 @@ export const refuseByCommandPermissions = (action, permissions, { app, env, dryR
         return;
     const { effects } = metaOf(action);
     const lock = readOnlyLockOf(app, env);
-    if (lock && effects?.remote === "write")
+    const preview = dryRun && app.messenger === false;
+    if (lock && effects?.remote === "write" && !preview)
         throw readOnlyRefusal(lock, `run ${commandPathOf(action).join(" ")}`);
     const flags = action.optsWithGlobals();
     const overrides = environmentOf(action).agent?.overrides ?? [];

package/dist/cli/entry.d.ts

@@ -16,8 +16,12 @@ export interface EntryContext {
     atStart: (command: Command) => Promise<void>;
     /** A yes/no question on stderr; false without asking when there is no terminal, under CI, `--json`, `--jsonl` or `--no-input`. */
     ask: (question: string, command?: Command) => Promise<boolean>;
-    /** Opens the URL in the system browser, or in `browser` when given; never waits for the browser to close. */
-    openBrowser: (url: string, browser?: string) => Promise<void>;
+    /**
+     * Opens the URL in the system browser, or in `browser` when given; never waits for the browser to close. Does nothing
+     * where nobody can use a browser (WC-CMD-15): under CI, `--json`, `--jsonl`, `--no-input`, or with no terminal.
+     * The caller prints the URL either way.
+     */
+    openBrowser: (url: string, browser?: string, command?: Command) => Promise<void>;
     /** True once a reader closed the output (`| head`): nothing more reaches the terminal. */
     outputClosed: () => boolean;
 }

package/dist/cli/entry.js

@@ -88,7 +88,10 @@ export const startCli = async (entry) => {
             });
             return /^(y|yes)$/i.test(answer.trim());
         },
-        openBrowser: (url, browser) => openBrowser(url, browser, io),
+        openBrowser: async (url, browser, command) => {
+            if (!headless(command))
+                await openBrowser(url, browser, io);
+        },
         outputClosed: () => closed,
     };
     let code;

package/dist/cli/envelope.d.ts

@@ -89,7 +89,7 @@ export declare const answerSchema: (item?: v.GenericSchema) => v.UnionSchema<[v.
         readonly accounts: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>, undefined>;
         readonly complete: v.BooleanSchema<undefined>;
         readonly issues: v.OptionalSchema<v.ArraySchema<v.StrictObjectSchema<{
-            readonly code: v.PicklistSchema<readonly ["validation_error", "configuration_error", "authentication_error", "permission_error", "not_found", "confirmation_required", "rate_limited", "timeout", "network_error", "provider_error", "provider_unavailable", "invalid_response", "outcome_unknown", "cancelled"], undefined>;
+            readonly code: v.PicklistSchema<readonly ["validation_error", "configuration_error", "authentication_error", "permission_error", "not_found", "confirmation_required", "rate_limited", "timeout", "network_error", "provider_error", "provider_unavailable", "invalid_response", "outcome_unknown", "conflict", "cancelled"], undefined>;
             readonly reason: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "dotted lower-case words, such as `page.next`">]>, undefined>;
             readonly source: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>;
         }, undefined>, undefined>, undefined>;
@@ -144,7 +144,7 @@ export declare const answerSchema: (item?: v.GenericSchema) => v.UnionSchema<[v.
         readonly accounts: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>, undefined>;
         readonly complete: v.BooleanSchema<undefined>;
         readonly issues: v.OptionalSchema<v.ArraySchema<v.StrictObjectSchema<{
-            readonly code: v.PicklistSchema<readonly ["validation_error", "configuration_error", "authentication_error", "permission_error", "not_found", "confirmation_required", "rate_limited", "timeout", "network_error", "provider_error", "provider_unavailable", "invalid_response", "outcome_unknown", "cancelled"], undefined>;
+            readonly code: v.PicklistSchema<readonly ["validation_error", "configuration_error", "authentication_error", "permission_error", "not_found", "confirmation_required", "rate_limited", "timeout", "network_error", "provider_error", "provider_unavailable", "invalid_response", "outcome_unknown", "conflict", "cancelled"], undefined>;
             readonly reason: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "dotted lower-case words, such as `page.next`">]>, undefined>;
             readonly source: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>;
         }, undefined>, undefined>, undefined>;

package/dist/cli/index.d.ts

@@ -45,6 +45,7 @@ export { type AgentPolicy, type AgentTask, type EvaluationResult, evaluateAgent,
 export { answerEntity } from "./answer-entity.js";
 export { type AppDoctorOptions, appDoctorReport } from "./app-doctor-command.js";
 export type { AppMcpOptions } from "./app-mcp-command.js";
+export { actorOf } from "./author.js";
 export type { ApiCommandInput, ApiCommands } from "./bot/api.js";
 export { apiFlagOf, apiJson, apiOptionKey, apiPlainJson, checkApiBody, checkApiParameter, parseApiJson, readApiBody, } from "./bot/api-input.js";
 export { prepareRpcApiBody, type RpcApiBody } from "./bot/api-rpc.js";

package/dist/cli/index.js

@@ -39,6 +39,7 @@ export { liftOptionsAfterDashes } from "./after-dashes.js";
 export { evaluateAgent, } from "./agent-evaluation.js";
 export { answerEntity } from "./answer-entity.js";
 export { appDoctorReport } from "./app-doctor-command.js";
+export { actorOf } from "./author.js";
 export { apiFlagOf, apiJson, apiOptionKey, apiPlainJson, checkApiBody, checkApiParameter, parseApiJson, readApiBody, } from "./bot/api-input.js";
 export { prepareRpcApiBody } from "./bot/api-rpc.js";
 export { botContext, botWords } from "./bot/context.js";

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/permission-keys.d.ts

@@ -14,12 +14,14 @@ export interface CommandPermissions {
     extra: readonly PermissionKey[];
     /** cli-core's built-in levels and the CLI's own; they only ever tighten. */
     defaults: Readonly<Record<PermissionKey, Level>>;
+    /** The other keys a command's real run checks, so its `--dry-run` preview shows each: gcal's `api.calendar.*`. */
+    alsoChecks?: (path: readonly string[]) => readonly PermissionKey[];
 }
 /** Either way of naming a program's keys: a messenger's per-command mapping, or a declared CLI's own. */
 export type PermissionKeySource = PermissionKeyOf | CommandPermissions;
 /** A command's own path is its key; the commands that look after the tool have none. */
 export declare const commandPathKey: (path: readonly string[]) => PermissionKey | null;
-export declare const commandPermissions: ({ keyOf, extra, defaults, }?: Partial<CommandPermissions>) => CommandPermissions;
+export declare const commandPermissions: ({ keyOf, extra, defaults, alsoChecks, }?: Partial<CommandPermissions>) => CommandPermissions;
 /**
  * The keys `permissions` may name: every command of the program, every write key, and each of their
  * parents. A key outside it is a typo that would otherwise do nothing (BUG-137).

package/dist/cli/permission-keys.js

@@ -16,10 +16,11 @@ const HOUSEKEEPING = new Set([
 ]);
 /** A command's own path is its key; the commands that look after the tool have none. */
 export const commandPathKey = (path) => path[0] === undefined || HOUSEKEEPING.has(path[0]) ? null : path.join(".");
-export const commandPermissions = ({ keyOf = commandPathKey, extra = [], defaults = {}, } = {}) => ({
+export const commandPermissions = ({ keyOf = commandPathKey, extra = [], defaults = {}, alsoChecks, } = {}) => ({
     keyOf,
     extra: [AUTHORITY_KEY, ...extra],
     defaults: { ...DEFAULT_PERMISSIONS, ...defaults },
+    ...(alsoChecks ? { alsoChecks } : {}),
 });
 const pathOf = (command) => {
     const words = [];

package/dist/cli/preview.d.ts

@@ -10,6 +10,10 @@ export declare const preview: (command: Command, settings: Pick<Settings, "permi
     permission?: {
         key: PermissionKey | null;
         level: string;
+        also?: {
+            key: PermissionKey;
+            level: string;
+        }[];
     } | undefined;
     validation: {
         arguments: string;
@@ -42,12 +46,20 @@ export declare const preview: (command: Command, settings: Pick<Settings, "permi
 export declare const previewBody: (command: Command, permission: {
     key: PermissionKey | null;
     level: string;
+    also?: {
+        key: PermissionKey;
+        level: string;
+    }[];
 } | undefined, messenger: boolean) => {
     preview: boolean;
     path: string[];
     permission?: {
         key: PermissionKey | null;
         level: string;
+        also?: {
+            key: PermissionKey;
+            level: string;
+        }[];
     } | undefined;
     validation: {
         arguments: string;

package/dist/cli/preview.js

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

package/dist/cli/settings.d.ts

@@ -42,6 +42,8 @@ export interface SettingsExtension<T extends object = Record<never, never>> {
      * `--permission` then take any command path, which the program checks against its commands.
      */
     permissions?: CommandPermissions;
+    /** `false` for a CLI with its own `config` that has no `repair`: no config issue then names one. */
+    configRepair?: boolean;
 }
 export interface SettingsExtensionContext {
     flags: GlobalFlags;

package/dist/cli/settings.js

@@ -102,6 +102,8 @@ export const MESSENGER_ONLY_SETTINGS = [
     "history_group_days",
     "history_group_members_max",
     "read_other_bots",
+    "speech_model",
+    "picture_search",
 ];
 /** One program, one version: whether to look for a newer one is not a per-profile matter. */
 const SHARED_DEFAULTS_ONLY = {
@@ -259,7 +261,12 @@ export const settingsFor = (app, extension = {}) => {
             return { config: { profiles: {} }, issues: [read.issue] };
         if (read.text === undefined)
             return { config: { profiles: {} }, issues: [] };
-        const { config, issues } = checkConfigText(read.text, { file: path, tool: app.command, schema: readSchema });
+        const { config, issues } = checkConfigText(read.text, {
+            file: path,
+            tool: app.command,
+            schema: readSchema,
+            repair: extension.configRepair !== false,
+        });
         return { config: (config ?? { profiles: {} }), issues };
     };
     /**

package/dist/errors/reasons.js

@@ -31,6 +31,18 @@ const SIGN_IN = [
     ["oauth.not-saved", "configuration_error", "the sign-in cannot be saved or read where it is kept"],
     ["sign-in.client-file-open", "configuration_error", "other users of this computer can read the client file"],
     ["sign-in.client-file-invalid", "configuration_error", "the file is not a Desktop app OAuth client JSON"],
+    ["oauth.scope-missing", "permission_error", "the sign-in lacks a permission this command needs"],
+    ["sign-in.client-rejected", "configuration_error", "the provider rejected the OAuth client"],
+];
+/** Reasons every CLI over a provider's API raises alike: gcal and drive today. */
+const PROVIDER_API = [
+    ["offline.refused", "permission_error", "this command needs the provider; --offline was given"],
+    validation("api.unknown-method", "the provider has no method by this name"),
+    ["api.disabled", "configuration_error", "the provider's API is turned off for this OAuth project"],
+    ["provider.usage-limit", "rate_limited", "the account's usage limit at the provider is reached; wait, do not retry"],
+    ["file.not-found", "not_found", "the file named, or its folder, does not exist"],
+    validation("file.not-a-file", "the path names a folder or another thing that is not a file"),
+    ["file.denied", "permission_error", "the file cannot be opened: permission denied"],
 ];
 const OTHERS = [
     ["query.time-limit", "timeout", "the search took longer than its time limit; the query itself is valid"],
@@ -87,6 +99,7 @@ const OTHERS = [
     validation("event.repeat-split", "the series cannot be split at this occurrence, or was split there already"),
     validation("event.repeat-count", "a COUNT series is split only with a rule for its new part"),
     validation("event.unmovable", "the provider keeps this kind of event on its calendar"),
+    validation("event.quick-add-ambiguous", "more than one event could be the one a lost quick add made"),
     validation("event.text-with-fields", "--text takes the whole event from its line, so no field option goes with it"),
     validation("calendar.ambiguous", "two or more calendars have this name; name one by its id"),
     validation("export.too-many", "the query finds more events than one export writes"),
@@ -258,7 +271,7 @@ export const INPUT_FIELD_REASONS = defineReasons([
 export const REASONS = defineReasons([
     ...QUERY_REASONS,
     ...INPUT_FIELD_REASONS,
-    ...[...QUERY, ...SIGN_IN, ...OTHERS].map(([reason, code, message]) => ({
+    ...[...QUERY, ...SIGN_IN, ...PROVIDER_API, ...OTHERS].map(([reason, code, message]) => ({
         reason,
         code,
         message,

package/dist/mcp/meeting-preparation.d.ts

@@ -28,7 +28,7 @@ export declare const callMeetingPreparationTool: (read: MeetingPreparationReader
     }[];
     structuredContent: {
         error: {
-            code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
+            code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "conflict" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
             reason: string;
             message: string;
             param?: string | undefined;

package/dist/mcp/meeting-project-candidates.d.ts

@@ -23,7 +23,7 @@ export declare const callMeetingProjectCandidatesTool: (read: StoredMeetingProje
     }[];
     structuredContent: {
         error: {
-            code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
+            code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "conflict" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
             reason: string;
             message: string;
             param?: string | undefined;

package/dist/mcp/meeting-series-inventory.d.ts

@@ -23,7 +23,7 @@ export declare const callMeetingSeriesInventoryTool: (read: MeetingSeriesInvento
     }[];
     structuredContent: {
         error: {
-            code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
+            code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "conflict" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
             reason: string;
             message: string;
             param?: string | undefined;