@wirecat/cli-core 0.20.0 → 0.263.0

package/dist/cli/reasons.js

@@ -0,0 +1,137 @@
+import { QUERY_REASONS } from "@wirecat/cli-base/query";
+import { defineReasons } from "@wirecat/cli-base/standards";
+const validation = (reason, message) => [reason, "validation_error", message];
+/** The query reasons only message search raises; the shared ones are cli-base's `QUERY_REASONS`. */
+const QUERY = [
+    ["query.aborted", "the search was stopped before it finished"],
+    ["query.conflict", "two parts of the query contradict each other"],
+    ["query.invalid-context", "the context size is out of range"],
+    ["query.invalid-limit", "the limit is out of range"],
+    ["query.invalid-scope", "the query selects no account"],
+    ["query.invalid-size", "a size in the query cannot be read"],
+    ["query.invalid-tag", "a tag in the query is not valid"],
+    ["query.invalid-topic", "a topic in the query is not valid"],
+    ["query.topic-scope", "a topic needs its chat in the query"],
+].map(([reason, message]) => validation(reason, message));
+const OTHERS = [
+    validation("evidence.row-too-large", "one evidence row is over its size limit"),
+    validation("index.not-ready", "the search index is still being built"),
+    validation("input.closed", "the input closed before the answer"),
+    validation("input.required", "the command needs an answer and cannot ask for one"),
+    validation("input.too-large", "the input is over its size limit"),
+    ["meeting-project.stale", "configuration_error", "the meeting's project changed meanwhile"],
+    validation("memory.evidence-required", "a memory needs its evidence"),
+    validation("memory.scope-required", "a memory needs its scope"),
+    validation("name.invalid", "the name is not valid"),
+    validation("output.choose-fields", "at a terminal, --json names the fields it prints"),
+    validation("output.unknown-field", "the answer has no field by that name"),
+    validation("name.taken", "the name is already used"),
+    validation("period.ambiguous", "the period can be read more than one way"),
+    validation("proposal.wrong-state", "the proposal is not in a state that allows this"),
+    validation("ranking.invalid", "the ranking is not valid"),
+    validation("selection.changed", "the stored selection changed meanwhile"),
+    validation("selection.invalid", "the selection is not valid"),
+    ["selection.out-of-scope", "permission_error", "the selection reaches outside what this profile may read"],
+    validation("stemmer.invalid", "the stemmer is not valid for that script"),
+    validation("stemmer.newer", "the stems were built by a newer tool"),
+    validation("stemmer.unknown", "the store asks for stemmers this tool does not know"),
+    validation("tag-review.over-budget", "the tag review is over its budget"),
+    validation("tag-review.required", "the tag needs the owner's review first"),
+    ["tag-review.stale", "configuration_error", "the tag review changed meanwhile"],
+    validation("tag.invalid", "the tag is not valid"),
+    validation("task.closed", "the task is already closed"),
+    validation("task.dependency-cycle", "the task would depend on itself"),
+    ["upgrade.install-failed", "provider_error", "the installer failed; the old version stays"],
+    ["topic.owner-only", "permission_error", "only the owner may use this topic"],
+    ["vocabulary.alias-conflict", "configuration_error", "two vocabulary entries claim one alias"],
+    validation("vocabulary.over-byte-budget", "the vocabulary is over its size budget"),
+    validation("vocabulary.over-entry-budget", "the vocabulary has too many entries"),
+    ["vocabulary.stale", "configuration_error", "the vocabulary changed meanwhile"],
+];
+/** Every reason this package raises; cli-base's own are known to the handler already. */
+export const REASONS = defineReasons([
+    ...QUERY_REASONS,
+    ...[...QUERY, ...OTHERS].map(([reason, code, message]) => ({ reason, code, message, details: [] })),
+]);
+/**
+ * Detail keys an error from this package may carry, until each is registered on its own reason. Not `cause`:
+ * that can hold a provider's or SQLite's raw text.
+ */
+export const DETAILS = [
+    "allowed",
+    "alternative",
+    "arguments",
+    "at",
+    "available",
+    "batch",
+    "budget",
+    "built",
+    "candidates",
+    "chat",
+    "chat_id",
+    "cli",
+    "complete",
+    "emitted_bytes",
+    "exact",
+    "forum",
+    "guide",
+    "hint",
+    "id",
+    "index",
+    "kind",
+    "limit",
+    "limit_source",
+    "max_bytes",
+    "name",
+    "operation_id",
+    "operation_ids",
+    "partial_output",
+    "path",
+    "permission",
+    "person_ids",
+    "previous_chat_id",
+    "profiles",
+    "provider_error",
+    "provider",
+    "recovery",
+    "reference",
+    "remembered",
+    "retry_at",
+    "runtime",
+    "saved",
+    "scheduled_for",
+    "script",
+    "send_id",
+    "sent",
+    "settlement_failed",
+    "span",
+    "sqlite",
+    "stage",
+    "standing",
+    "state",
+    "stderr",
+    "term",
+    "total",
+    "upgraded",
+    "wanted",
+];
+const SHARED = { reasons: REASONS, details: DETAILS };
+const merged = new WeakMap();
+/** The registry every error handler reads — the CLI's, MCP's and the meeting tools' — so none drops an app's keys. */
+export const failureContext = (errors) => {
+    if (!errors)
+        return SHARED;
+    const known = merged.get(errors);
+    if (known)
+        return known;
+    const unnamed = (errors.details ?? []).filter((key) => !/^[a-z][a-z0-9]*(_[a-z0-9]+)*$/.test(key));
+    if (unnamed.length > 0)
+        throw new Error(`error details must be snake_case: ${unnamed.join(", ")}`);
+    const context = {
+        reasons: defineReasons([...REASONS, ...(errors.reasons ?? [])]),
+        details: [...new Set([...DETAILS, ...(errors.details ?? [])])],
+    };
+    merged.set(errors, context);
+    return context;
+};
+//# sourceMappingURL=reasons.js.map

package/dist/cli/reasons.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasons.js","sourceRoot":"","sources":["../../src/cli/reasons.ts"],"names":[],"mappings":"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"}

package/dist/cli/recovery.d.ts

@@ -0,0 +1,8 @@
+import type { ActionableError, RecoveryAction } from "../domain/recovery.js";
+export type { ActionableError, RecoveryAction };
+export declare const withRecovery: (error: {
+    code: string;
+    message: string;
+    [key: string]: unknown;
+}) => ActionableError;
+//# sourceMappingURL=recovery.d.ts.map

package/dist/cli/recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../../src/cli/recovery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAE5E,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,CAAA;AAE/C,eAAO,MAAM,YAAY,UAAW;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,KAAG,eAqE/F,CAAA"}

package/dist/cli/recovery.js

@@ -0,0 +1,70 @@
+export const withRecovery = (error) => {
+    const wait = Number(error.retry_after_ms);
+    const rate = error.code === "rate_limited" || error.status === 429;
+    const actions = [];
+    if (rate) {
+        actions.push({
+            type: "wait",
+            message: "Wait before retrying; do not immediately repeat requests.",
+            ...(Number.isFinite(wait) && wait >= 0 ? { afterMs: wait } : {}),
+        });
+        actions.push({ type: "retry", message: "Resume the unfinished items after the provider's wait." });
+    }
+    else {
+        const setting = typeof error.setting === "string"
+            ? error.setting
+            : error.message.match(/MESSAGING_[A-Z_]+|--(?:max-output-bytes|timeout|max-input-bytes)/)?.[0];
+        if (setting)
+            actions.push({ type: "configure", setting, message: `Check or increase ${setting}, then retry the failed item.` });
+        else if (/already exists/i.test(error.message))
+            actions.push({
+                type: "check",
+                message: "Choose another output folder/name or skip the existing file; it was not overwritten.",
+            });
+        else if (error.code === "ENOSPC")
+            actions.push({ type: "check", message: "Free disk space or choose another output folder before resuming." });
+        else if (error.code === "cancelled")
+            actions.push({ type: "retry", message: "Resume unfinished read items when ready; completed work is retained." });
+        else if (error.limitSource === "local" && /size limit|too.large|exceeds/i.test(error.message))
+            actions.push({
+                type: "check",
+                message: "Split the document or use another reader; local decompression/text budgets remain separate from the configurable file-size budget.",
+            });
+        else if (error.status === 413 || /too.large|exceeds|size limit/i.test(error.message))
+            actions.push({
+                type: "check",
+                message: "Use a smaller file, lower image resolution or split the input; provider limits cannot be raised in local settings.",
+            });
+        else if (error.code === "authentication_error")
+            actions.push({
+                type: "check",
+                message: "Check the selected account/profile and reconnect or sign in before resuming.",
+            });
+        else if (error.code === "permission_error")
+            actions.push({ type: "check", message: "Check the selected profile's permissions and access to this item." });
+        else if (error.code === "timeout" || error.code === "network_error")
+            actions.push({
+                type: "check",
+                message: "Check connectivity and timeout settings, then retry unfinished read operations.",
+            });
+        else if (error.code === "not_found")
+            actions.push({
+                type: "check",
+                message: "Check the item ID or path; it may have been removed or may need downloading again.",
+            });
+        else if (error.code === "outcome_unknown")
+            actions.push({
+                type: "check",
+                message: "Verify whether the operation completed before retrying; replay could duplicate a write.",
+            });
+        else
+            actions.push({ type: "check", message: "Check the reported input or provider error before retrying." });
+        actions.push({ type: "skip", message: "Skip this item and continue independent work." });
+    }
+    return {
+        ...error,
+        retryable: typeof error.retryable === "boolean" ? error.retryable : rate,
+        actions: Array.isArray(error.actions) ? error.actions : actions,
+    };
+};
+//# sourceMappingURL=recovery.js.map

package/dist/cli/recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.js","sourceRoot":"","sources":["../../src/cli/recovery.ts"],"names":[],"mappings":"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"}

package/dist/cli/registry-keys.d.ts

@@ -0,0 +1,8 @@
+import { type AppIdentity } from "./app.js";
+/**
+ * Combot's key for CAS, where the owner keeps one: the keyring account `registries:cas` under the
+ * app's own service, `<PREFIX>_CAS_API_KEY`, or a 0600 file — as the AI providers' keys are. CAS
+ * answers without one for now; never printed, never in an error.
+ */
+export declare const casKey: (app: AppIdentity, env?: NodeJS.ProcessEnv) => string | undefined;
+//# sourceMappingURL=registry-keys.d.ts.map

package/dist/cli/registry-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-keys.d.ts","sourceRoot":"","sources":["../../src/cli/registry-keys.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,WAAW,EAAW,MAAM,UAAU,CAAA;AAEpD;;;;GAIG;AACH,eAAO,MAAM,MAAM,QAAS,WAAW,QAAO,MAAM,CAAC,UAAU,KAAiB,MAAM,GAAG,SAUxF,CAAA"}

package/dist/cli/registry-keys.js

@@ -0,0 +1,19 @@
+import { Credentials, pathsAreOverridden, resolvePaths } from "@wirecat/cli-base";
+import { envName } from "./app.js";
+/**
+ * Combot's key for CAS, where the owner keeps one: the keyring account `registries:cas` under the
+ * app's own service, `<PREFIX>_CAS_API_KEY`, or a 0600 file — as the AI providers' keys are. CAS
+ * answers without one for now; never printed, never in an error.
+ */
+export const casKey = (app, env = process.env) => {
+    const where = { appName: app.appName, prefix: app.envPrefix, env };
+    return new Credentials({
+        configDir: resolvePaths(where).config,
+        service: app.appName,
+        envVar: envName(app, "CAS_API_KEY"),
+        isolated: pathsAreOverridden(where),
+        env,
+        warn: (message) => process.stderr.write(`${message}\n`),
+    }).read("registries:cas")?.secret;
+};
+//# sourceMappingURL=registry-keys.js.map

package/dist/cli/registry-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-keys.js","sourceRoot":"","sources":["../../src/cli/registry-keys.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AACjF,OAAO,EAAoB,OAAO,EAAE,MAAM,UAAU,CAAA;AAEpD;;;;GAIG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,GAAgB,EAAE,GAAG,GAAsB,OAAO,CAAC,GAAG,EAAsB,EAAE;IACnG,MAAM,KAAK,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,SAAS,EAAE,GAAG,EAAE,CAAA;IAClE,OAAO,IAAI,WAAW,CAAC;QACrB,SAAS,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,MAAM;QACrC,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,aAAa,CAAC;QACnC,QAAQ,EAAE,kBAAkB,CAAC,KAAK,CAAC;QACnC,GAAG;QACH,IAAI,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC;KACxD,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;AACnC,CAAC,CAAA"}

package/dist/cli/result-fields.d.ts

@@ -0,0 +1,4 @@
+export declare const fieldsOf: (value: string) => string[];
+/** An item answer keeps its `next`, `missing` and `meta`; only the item is cut down. */
+export declare const projectFields: (value: unknown, fields: readonly string[]) => unknown;
+//# sourceMappingURL=result-fields.d.ts.map

package/dist/cli/result-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-fields.d.ts","sourceRoot":"","sources":["../../src/cli/result-fields.ts"],"names":[],"mappings":"AAiBA,eAAO,MAAM,QAAQ,UAAW,MAAM,KAAG,MAAM,EAAsC,CAAA;AAKrF,wFAAwF;AACxF,eAAO,MAAM,aAAa,UAAW,OAAO,UAAU,SAAS,MAAM,EAAE,KAAG,OAKzE,CAAA"}

package/dist/cli/result-fields.js

@@ -0,0 +1,23 @@
+import { CliError, fieldsOf as coreFieldsOf, projectFields as coreProjectFields } from "@wirecat/cli-base";
+/** cli-base keeps `operation_id` and `send_id`; this package's results still say `operationId` and `sendId`. */
+const CORRELATION = ["operationId", "sendId"];
+const named = (work) => {
+    try {
+        return work();
+    }
+    catch (error) {
+        if (error instanceof CliError && error.code === "validation_error")
+            throw new CliError("validation_error", "--json takes comma-separated field paths, for example --json=id,text", {
+                param: "--json",
+            });
+        throw error;
+    }
+};
+export const fieldsOf = (value) => named(() => coreFieldsOf(value));
+const isItemAnswer = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && "item" in value && "meta" in value;
+/** An item answer keeps its `next`, `missing` and `meta`; only the item is cut down. */
+export const projectFields = (value, fields) => {
+    const kept = [...fields, ...CORRELATION.filter((name) => !fields.includes(name))];
+    return named(() => isItemAnswer(value) ? { ...value, item: coreProjectFields(value.item, kept) } : coreProjectFields(value, kept));
+};
+//# sourceMappingURL=result-fields.js.map

package/dist/cli/result-fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-fields.js","sourceRoot":"","sources":["../../src/cli/result-fields.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,QAAQ,IAAI,YAAY,EAAE,aAAa,IAAI,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAE1G,gHAAgH;AAChH,MAAM,WAAW,GAAG,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAA;AAE7C,MAAM,KAAK,GAAG,CAAI,IAAa,EAAK,EAAE;IACpC,IAAI,CAAC;QACH,OAAO,IAAI,EAAE,CAAA;IACf,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,QAAQ,IAAI,KAAK,CAAC,IAAI,KAAK,kBAAkB;YAChE,MAAM,IAAI,QAAQ,CAAC,kBAAkB,EAAE,sEAAsE,EAAE;gBAC7G,KAAK,EAAE,QAAQ;aAChB,CAAC,CAAA;QACJ,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,KAAa,EAAY,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAA;AAErF,MAAM,YAAY,GAAG,CAAC,KAAc,EAA8B,EAAE,CAClE,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,MAAM,IAAI,KAAK,IAAI,MAAM,IAAI,KAAK,CAAA;AAE5G,wFAAwF;AACxF,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,KAAc,EAAE,MAAyB,EAAW,EAAE;IAClF,MAAM,IAAI,GAAG,CAAC,GAAG,MAAM,EAAE,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACjF,OAAO,KAAK,CAAC,GAAG,EAAE,CAChB,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,iBAAiB,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,iBAAiB,CAAC,KAAK,EAAE,IAAI,CAAC,CAC/G,CAAA;AACH,CAAC,CAAA"}

package/dist/cli/runs/command.d.ts

@@ -0,0 +1,5 @@
+import { Command } from "commander";
+import type { AppIdentity } from "../app.js";
+/** Reading the log is not itself worth recording, so **nothing here starts a run**. */
+export declare const runsCommand: (app: AppIdentity) => Command;
+//# sourceMappingURL=command.d.ts.map

package/dist/cli/runs/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../src/cli/runs/command.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAA;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAM5C,uFAAuF;AACvF,eAAO,MAAM,WAAW,QAAS,WAAW,KAAG,OA0E9C,CAAA"}

package/dist/cli/runs/command.js

@@ -0,0 +1,75 @@
+import { CliError } from "@wirecat/cli-base";
+import { Command, Option } from "commander";
+import { environmentOf, outputFor } from "../context.js";
+import { positiveCount, renderPage } from "../paging.js";
+import { findRun, listRuns, readEvents, runsDirFor } from "./run.js";
+import { searchRuns } from "./search.js";
+/** Reading the log is not itself worth recording, so **nothing here starts a run**. */
+export const runsCommand = (app) => {
+    const command = new Command("runs").description("recorded runs — what this tool did, and when");
+    const dir = (from) => runsDirFor(app, environmentOf(from).env ?? process.env);
+    const runOrRefuse = (from, id) => {
+        const found = findRun(dir(from), id);
+        if (!found)
+            throw new CliError("not_found", `no recorded run "${id}" — \`${app.command} runs list\` shows them`);
+        return found;
+    };
+    command
+        .command("list")
+        .description("recorded runs, newest first")
+        .option("--limit <n>", "how many to show", positiveCount("--limit"), 20)
+        .action(function () {
+        const { limit } = this.opts();
+        const output = outputFor(this);
+        const { renderer } = output;
+        const runs = listRuns(dir(this), { atLeast: limit + 1 });
+        renderPage({ ...output, settings: { page: 1, limit, all: false } }, { items: runs.slice(0, limit), hasMore: runs.length > limit }, undefined, () => "more recorded runs — increase `--limit` to show them");
+        if (runs.length === 0)
+            renderer.note("nothing recorded — a run is kept with `--record`, or when it fails");
+    });
+    command
+        .command("show")
+        .argument("<run-id>", `an id from \`${app.command} runs list\``)
+        .description("one run: what it was, how it ended and what went wrong; -v for every event")
+        .action(function (id) {
+        const { renderer } = outputFor(this);
+        const found = runOrRefuse(this, id);
+        const events = readEvents(found.dir).map(readable);
+        const all = (this.optsWithGlobals().verbose ?? 0) > 0;
+        const shown = all ? events : events.filter(notable);
+        renderer.result({ ...found.metadata, directory: found.dir, eventCount: events.length, events: shown });
+        if (shown.length < events.length)
+            renderer.note(`${events.length - shown.length} more events — \`${app.command} runs show ${id} -v\` shows them all`);
+    });
+    command
+        .command("search")
+        .description("search recorded diagnostic metadata and events; no message contents")
+        .argument("[query]", "case-insensitive literal diagnostic text")
+        .addOption(new Option("--status <status>", "run outcome").choices(["success", "failed", "partial", "running"]))
+        .option("--error-code <code>", "one stable error code")
+        .option("--operation <name>", "one operation, such as messages.download")
+        .option("--profile <name>", "one recorded profile")
+        .option("--since-time <time>", "runs starting on or after an ISO time or 2h / 1d ago")
+        .option("--limit <n>", "matches per page, at most 100", positiveCount("--limit"), 20)
+        .option("--page <n>", "result page", positiveCount("--page"), 1)
+        .action(function (query) {
+        outputFor(this).renderer.result(searchRuns(dir(this), {
+            ...this.opts(),
+            since: this.opts().sinceTime,
+            ...(query === undefined ? {} : { query }),
+        }));
+    });
+    command
+        .command("path")
+        .argument("<run-id>", `an id from \`${app.command} runs list\``)
+        .description("the directory holding one run")
+        .action(function (id) {
+        outputFor(this).renderer.result({ path: runOrRefuse(this, id).dir });
+    });
+    return command;
+};
+/** What went wrong, and nothing that went right. */
+const notable = (event) => event.outcome === "error" || event.event === "warning" || event.event === "crash";
+/** Drops what the logger puts on every line and `show` already prints once above the events. */
+const readable = ({ level, runId, command, profile, ...event }) => event;
+//# sourceMappingURL=command.js.map

package/dist/cli/runs/command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../../../src/cli/runs/command.ts"],"names":[],"mappings":"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"}

package/dist/cli/runs/events.d.ts

@@ -0,0 +1,61 @@
+/**
+ * One operation against the messenger, as both sinks see it: `--trace` renders it, a recorded run
+ * writes it as a line of JSON.
+ *
+ * ⚠ **Nothing here may carry content.** An operation name, an id, a count, a duration and an error
+ * code are safe. A chat title, a name, a message body, a phone number or a token are not — not
+ * truncated and not hashed. The adapter builds `ids` and `counts` from fields it names, never by
+ * copying a request, and never from what the person typed: a typed chat is often a title.
+ */
+export interface RequestEvent {
+    event: "request" | "response";
+    /** Ours, not the messenger's: `messages.send`. */
+    operation: string;
+    /** A frame protocol's own numbering (max-cli's personal protocol); an HTTP API says `status` instead. */
+    opcode?: number;
+    seq?: number;
+    status?: number;
+    /** The size of what went out or came back. */
+    bytes?: number;
+    ids?: Record<string, string>;
+    /** How many things, per field: `{ messages: 3 }`. */
+    counts?: Record<string, number>;
+    durationMs?: number;
+    outcome?: "ok" | "error";
+    /** cli-base's code — `timeout`, `provider_error`. Never the message: a messenger quotes our payload. */
+    errorCode?: string;
+    /** The messenger's own name for a refusal, when it is shaped like one (`providerErrorKey`). */
+    providerError?: string;
+}
+/** Something the client noticed and went on without. A code, never the sentence. */
+export interface WarningEvent {
+    event: "warning";
+    code: string;
+    operation?: string;
+    /** Field paths and types for an answer of an unexpected shape — built without the values. */
+    detail?: string;
+}
+/** A read answered locally, without asking the messenger, and why. */
+export interface CacheEvent {
+    event: "cache";
+    operation: string;
+    reason: string;
+    ids?: Record<string, string>;
+    counts?: Record<string, number>;
+    /** How old the kept answer was. */
+    ageMs?: number;
+}
+export type DiagnosticEvent = RequestEvent | CacheEvent | WarningEvent;
+export type EventSink = (event: DiagnosticEvent) => void;
+/** `FLOOD_WAIT`, `PEER_ID_INVALID`, `login.token` — or nothing. A sentence is dropped, not trimmed. */
+export declare const providerErrorKey: (value: unknown) => string | undefined;
+/**
+ * The line a person reads. `→` is what we asked, `←` what came back.
+ *
+ * ```text
+ * → messages.list    chat 777
+ * ← messages.list    chat 777  118ms  3 messages
+ * ```
+ */
+export declare const renderEvent: (event: DiagnosticEvent) => string;
+//# sourceMappingURL=events.d.ts.map

package/dist/cli/runs/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/cli/runs/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,SAAS,GAAG,UAAU,CAAA;IAC7B,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAA;IACjB,yGAAyG;IACzG,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,IAAI,GAAG,OAAO,CAAA;IACxB,wGAAwG;IACxG,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,+FAA+F;IAC/F,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,oFAAoF;AACpF,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,SAAS,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,sEAAsE;AACtE,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,OAAO,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,mCAAmC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,UAAU,GAAG,YAAY,CAAA;AAEtE,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAA;AAExD,uGAAuG;AACvG,eAAO,MAAM,gBAAgB,UAAW,OAAO,KAAG,MAAM,GAAG,SACoC,CAAA;AAE/F;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,UAAW,eAAe,KAAG,MA2BpD,CAAA"}

package/dist/cli/runs/events.js

@@ -0,0 +1,52 @@
+/** `FLOOD_WAIT`, `PEER_ID_INVALID`, `login.token` — or nothing. A sentence is dropped, not trimmed. */
+export const providerErrorKey = (value) => typeof value === "string" && /^[A-Za-z][A-Za-z0-9._-]{0,63}$/.test(value) ? value : undefined;
+/**
+ * The line a person reads. `→` is what we asked, `←` what came back.
+ *
+ * ```text
+ * → messages.list    chat 777
+ * ← messages.list    chat 777  118ms  3 messages
+ * ```
+ */
+export const renderEvent = (event) => {
+    if (event.event === "warning") {
+        return [`${MARK.warning} ${(event.operation ?? "").padEnd(16)} ${event.code}`, event.detail]
+            .filter(Boolean)
+            .join("  ");
+    }
+    const parts = [];
+    if (event.event === "cache") {
+        parts.push(event.reason);
+        if (event.ageMs !== undefined)
+            parts.push(`cached ${age(event.ageMs)}`);
+    }
+    else {
+        if (event.opcode !== undefined)
+            parts.push(`op ${event.opcode}`, `seq ${event.seq}`);
+        if (event.status !== undefined)
+            parts.push(`${event.status}`);
+    }
+    if (event.ids)
+        for (const [name, value] of Object.entries(event.ids))
+            parts.push(`${name} ${value}`);
+    if (event.event !== "cache") {
+        if (event.durationMs !== undefined)
+            parts.push(`${event.durationMs}ms`);
+        if (event.bytes !== undefined)
+            parts.push(size(event.bytes));
+    }
+    if (event.counts)
+        for (const [field, count] of Object.entries(event.counts))
+            parts.push(`${count} ${field}`);
+    if (event.event !== "cache") {
+        if (event.errorCode)
+            parts.push(event.errorCode);
+        if (event.providerError)
+            parts.push(event.providerError);
+    }
+    return `${MARK[event.event]} ${event.operation.padEnd(16)} ${parts.join("  ")}`.trimEnd();
+};
+const MARK = { request: "→", response: "←", cache: "•", warning: "!" };
+const age = (ms) => (ms < 1000 ? `${ms}ms` : `${Math.round(ms / 1000)}s`);
+const size = (bytes) => (bytes < 1000 ? `${bytes} B` : `${(bytes / 1000).toFixed(1)} kB`);
+//# sourceMappingURL=events.js.map

package/dist/cli/runs/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/cli/runs/events.ts"],"names":[],"mappings":"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"}

package/dist/cli/runs/recording.d.ts

@@ -0,0 +1,51 @@
+import { type RenderFormat, type Streams } from "@wirecat/cli-base";
+import type { AppIdentity } from "../app.js";
+import { type EventSink } from "./events.js";
+export interface RecordingOptions {
+    app: AppIdentity;
+    /** As typed, without the arguments: `chats list`. It names the run directory. */
+    command: string;
+    profile: string;
+    record: boolean;
+    /** Keep the run if it fails, even though `record` is off. */
+    keepFailed: boolean;
+    trace: boolean;
+    /** Diagnostics follow the data stream: text for a person, one JSON object per line otherwise. */
+    format: RenderFormat;
+    streams?: Streams;
+    env?: NodeJS.ProcessEnv;
+    runsDir?: string;
+    keepDays?: number;
+    now?: () => Date;
+}
+/**
+ * Runs one command with the diagnostics turned on, and **finalizes on every path**.
+ *
+ * `--trace` shows each event as it happens and keeps nothing, `--record` keeps it and shows
+ * nothing. It is a wrapper rather than three lines in each command because the failure it prevents
+ * is the quiet one: a run directory left saying `running` because the command threw on the way out.
+ */
+export declare const recorded: <T>(options: RecordingOptions, body: (events: EventSink) => Promise<T>) => Promise<T>;
+export interface Recording {
+    /** Given now, before the run is kept or not, so whatever the command writes can name it. */
+    runId: string;
+    events: EventSink;
+    succeed: (answer?: unknown) => Promise<void>;
+    /** Marks the error as dealt with, so the program's last catch does not keep it a second time. */
+    fail: (error: unknown) => Promise<void>;
+}
+/** `recorded` in two halves, for a caller that starts a run before its command and ends it after (max-cli's `max bot`). */
+export declare const startRecording: (options: RecordingOptions) => Recording;
+export declare const wasSettled: (error: unknown) => boolean;
+/**
+ * Where a crash happened, not what it said: the class and up to ten frames as `function file:line`,
+ * paths cut to what follows `dist/` or `src/`. **Never `message`** — it can hold whatever the
+ * failing line was handling.
+ */
+export declare const crashOf: (error: unknown) => {
+    event: "crash";
+    errorName: string;
+    frames: string[];
+};
+export declare const partialOutcome: (answer: unknown) => import("./run.js").RunMetadata["partial"];
+//# sourceMappingURL=recording.d.ts.map

package/dist/cli/runs/recording.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recording.d.ts","sourceRoot":"","sources":["../../../src/cli/runs/recording.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,YAAY,EAAE,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAA;AACnF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAE5C,OAAO,EAAwB,KAAK,SAAS,EAAiC,MAAM,aAAa,CAAA;AAIjG,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,WAAW,CAAA;IAChB,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,OAAO,CAAA;IACf,6DAA6D;IAC7D,UAAU,EAAE,OAAO,CAAA;IACnB,KAAK,EAAE,OAAO,CAAA;IACd,iGAAiG;IACjG,MAAM,EAAE,YAAY,CAAA;IACpB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CACjB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,GAAU,CAAC,WAAW,gBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,CAAC,CAY/G,CAAA;AAED,MAAM,WAAW,SAAS;IACxB,4FAA4F;IAC5F,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,SAAS,CAAA;IACjB,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5C,iGAAiG;IACjG,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACxC;AAED,2HAA2H;AAC3H,eAAO,MAAM,cAAc,YAAa,gBAAgB,KAAG,SA6D1D,CAAA;AAKD,eAAO,MAAM,UAAU,UAAW,OAAO,KAAG,OAA4E,CAAA;AAqBxH;;;;GAIG;AACH,eAAO,MAAM,OAAO,UAAW,OAAO,KAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAc7F,CAAA;AAED,eAAO,MAAM,cAAc,WAAY,OAAO,KAAG,OAAO,UAAU,EAAE,WAAW,CAAC,SAAS,CAyBxF,CAAA"}