@wirecat/cli-core 0.424.0 → 0.426.0

package/dist/runs/run-context.d.ts

@@ -0,0 +1,37 @@
+import type { Command } from "commander";
+import type { RunContext } from "./run.js";
+export declare const REDACTED = "[redacted]";
+/** Which coding agent started the process, and its session when the agent names one. Keys as written in run.json. */
+export interface RunAgent {
+    kind: string;
+    session_id: string | null;
+}
+/**
+ * The agent is read from what each one sets in the processes it starts: Claude Code `CLAUDECODE` and
+ * `CLAUDE_CODE_SESSION_ID`, Codex `CODEX_THREAD_ID`, OpenCode `OPENCODE` and `OPENCODE_SESSION_ID`, Gemini CLI
+ * `GEMINI_CLI`, Cursor `CURSOR_AGENT` — the last two give their commands no session id. `AI_AGENT` (Claude Code,
+ * OpenCode) carries a version, `claude-code_2-1-296_agent`, so only the name before it is kept.
+ */
+export declare const agentOf: (env: NodeJS.ProcessEnv) => RunAgent | undefined;
+export interface MaskedArgv {
+    /** The words after the binary, every value that may be content or a secret replaced by `[redacted]`. */
+    argv: string[];
+    /** The first word that names no command where one was expected. */
+    unknownCommand?: string;
+}
+/**
+ * The command line as typed, safe to keep. Command words, flag names and the profile stay; a value stays only when
+ * its shape cannot be somebody's words — a number short of a phone's length, a duration, a date, `true`, one of the
+ * option's declared choices — and its option or argument is not named for content (`--text`, `<phone>`). Anything
+ * else, a positional after `--` or an argument no command declares, is `[redacted]`: a chat is often typed by title.
+ */
+export declare const maskArgv: (program: Command, words: readonly string[]) => MaskedArgv;
+/** A run's context from the parsed program: `max messages list` and its masked words, or the word that named nothing. */
+export declare const runContextOf: ({ bin, command, program, argv, env, }: {
+    bin: string;
+    /** The run's own name, `messages list` or `mcp messages list`; empty when no command was recognised. */
+    command: string;
+    program?: Command;
+    argv?: readonly string[];
+    env: NodeJS.ProcessEnv;
+}) => RunContext;

package/dist/runs/run-context.js

@@ -0,0 +1,148 @@
+import { isContentKey } from "@wirecat/cli-base/standards";
+export const REDACTED = "[redacted]";
+/**
+ * The agent is read from what each one sets in the processes it starts: Claude Code `CLAUDECODE` and
+ * `CLAUDE_CODE_SESSION_ID`, Codex `CODEX_THREAD_ID`, OpenCode `OPENCODE` and `OPENCODE_SESSION_ID`, Gemini CLI
+ * `GEMINI_CLI`, Cursor `CURSOR_AGENT` — the last two give their commands no session id. `AI_AGENT` (Claude Code,
+ * OpenCode) carries a version, `claude-code_2-1-296_agent`, so only the name before it is kept.
+ */
+export const agentOf = (env) => {
+    const named = env.AI_AGENT?.trim().split("_")[0];
+    const kind = (named && plainWord(named) ? named.toLowerCase() : undefined) ??
+        (env.CLAUDECODE ? "claude-code" : undefined) ??
+        (env.CODEX_THREAD_ID || env.CODEX_SESSION_ID || env.CODEX_SANDBOX ? "codex" : undefined) ??
+        (env.GEMINI_CLI ? "gemini-cli" : undefined) ??
+        (env.OPENCODE ? "opencode" : undefined) ??
+        (env.CURSOR_AGENT ? "cursor" : undefined);
+    if (!kind)
+        return undefined;
+    const session = sessionOf(kind, env);
+    return { kind, session_id: session && SESSION.test(session) ? session : null };
+};
+const SESSION = /^[A-Za-z0-9._:-]{1,128}$/;
+const sessionOf = (kind, env) => {
+    const value = kind === "claude-code"
+        ? env.CLAUDE_CODE_SESSION_ID
+        : kind === "codex"
+            ? env.CODEX_THREAD_ID
+            : kind === "opencode"
+                ? env.OPENCODE_SESSION_ID
+                : undefined;
+    return value?.trim() || undefined;
+};
+const plainWord = (word) => /^[A-Za-z][A-Za-z0-9.-]{0,39}$/.test(word);
+/**
+ * The command line as typed, safe to keep. Command words, flag names and the profile stay; a value stays only when
+ * its shape cannot be somebody's words — a number short of a phone's length, a duration, a date, `true`, one of the
+ * option's declared choices — and its option or argument is not named for content (`--text`, `<phone>`). Anything
+ * else, a positional after `--` or an argument no command declares, is `[redacted]`: a chat is often typed by title.
+ */
+export const maskArgv = (program, words) => {
+    const argv = [];
+    let unknownCommand;
+    let current = program;
+    let positional = 0;
+    let profileSeen = false;
+    let lost = false;
+    const optionFor = (flag) => {
+        for (let at = current; at; at = at.parent) {
+            const found = at.options.find((option) => option.long === flag || option.short === flag);
+            if (found)
+                return found;
+        }
+        return undefined;
+    };
+    for (let at = 0; at < words.length; at++) {
+        const word = words[at];
+        if (word === "--") {
+            argv.push("--");
+            for (let after = at + 1; after < words.length; after++)
+                argv.push(REDACTED);
+            break;
+        }
+        if (word.startsWith("-") && word.length > 1 && !NUMBER.test(word)) {
+            const equals = word.indexOf("=");
+            const flag = equals > 0 ? word.slice(0, equals) : word;
+            if (!/^--?[A-Za-z0-9][A-Za-z0-9-]*$/.test(flag)) {
+                argv.push(REDACTED);
+                continue;
+            }
+            const option = optionFor(flag);
+            const name = option?.attributeName() ?? flag.replace(/^-+/, "");
+            if (equals > 0) {
+                argv.push(`${flag}=${maskedValue(name, word.slice(equals + 1), option?.argChoices)}`);
+                continue;
+            }
+            argv.push(flag);
+            if (!option || !(option.required || option.optional))
+                continue;
+            const takes = (next) => next !== undefined && (option.required || !next.startsWith("-") || NUMBER.test(next));
+            if (takes(words[at + 1])) {
+                at += 1;
+                argv.push(maskedValue(name, words[at], option.argChoices));
+                while (option.variadic && words[at + 1] !== undefined && !words[at + 1].startsWith("-")) {
+                    at += 1;
+                    argv.push(maskedValue(name, words[at], option.argChoices));
+                }
+            }
+            continue;
+        }
+        if (!lost && positional === 0) {
+            const sub = current.commands.find((one) => one.name() === word || one.aliases().includes(word));
+            if (sub) {
+                argv.push(word);
+                current = sub;
+                continue;
+            }
+            if (current === program && !profileSeen) {
+                profileSeen = true;
+                argv.push(PROFILE.test(word) ? word : REDACTED);
+                continue;
+            }
+            if (current.commands.length > 0 && current.registeredArguments.length === 0) {
+                lost = true;
+                unknownCommand = commandLike(word);
+                argv.push(unknownCommand);
+                continue;
+            }
+        }
+        const declared = lost ? undefined : current.registeredArguments;
+        const argument = declared?.[Math.min(positional, declared.length - 1)];
+        positional += 1;
+        argv.push(argument ? maskedValue(argument.name(), word, argument.argChoices) : REDACTED);
+    }
+    return { argv, ...(unknownCommand === undefined ? {} : { unknownCommand }) };
+};
+const NUMBER = /^-?\d+(\.\d+)?$/;
+const PROFILE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** A mistyped command word is kept so the typo can be seen; anything shaped like a sentence or an address is not. */
+const commandLike = (word) => (/^[a-z][a-z0-9-]{0,31}$/i.test(word) ? word : REDACTED);
+const maskedValue = (name, value, choices) => {
+    if (isContentKey(name))
+        return REDACTED;
+    if (name === "profile")
+        return PROFILE.test(value) ? value : REDACTED;
+    if (name === "json" || name === "fields")
+        return /^[a-z0-9_.,]{1,200}$/.test(value) ? value : REDACTED;
+    if (choices?.includes(value))
+        return value;
+    return safeShape(value) ? value : REDACTED;
+};
+// A positive run of eleven or more digits can be a phone number written without its "+"; ids that long are negative
+// (chats and channels) and stay.
+const safeShape = (value) => (NUMBER.test(value) && !/^\d{11,}$/.test(value)) ||
+    /^\d+(ms|s|m|h|d|w)$/.test(value) ||
+    /^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/.test(value) ||
+    value === "true" ||
+    value === "false";
+/** A run's context from the parsed program: `max messages list` and its masked words, or the word that named nothing. */
+export const runContextOf = ({ bin, command, program, argv, env, }) => {
+    const masked = program && argv ? maskArgv(program, argv) : undefined;
+    const agent = agentOf(env);
+    return {
+        cliCommand: command ? `${bin} ${command}` : bin,
+        ...(masked ? { argv: masked.argv } : {}),
+        ...(masked?.unknownCommand === undefined ? {} : { unknownCommand: masked.unknownCommand }),
+        ...(agent ? { agent } : {}),
+    };
+};

package/dist/runs/run.d.ts

@@ -1,10 +1,13 @@
 import { type Logger } from "@wirecat/cli-base";
 import type { AppIdentity } from "../ports/app.js";
+import type { RunError } from "./error-detail.js";
+import type { RunAgent } from "./run-context.js";
 export type RunStatus = "success" | "failed" | "partial";
 /**
- * What a run was, and how it ended. **It never says what was read or sent** — a command, a profile
- * and a count, and the `errorCode` a script branches on rather than the sentence a person reads,
- * because a messenger's refusal can quote the payload back.
+ * What a run was, and how it ended. **It never says what was read or sent** — a command, a profile,
+ * a count, the arguments with every value that may be content masked, and the `errorCode` a script
+ * branches on. The sentence a person reads is kept only in `error`, masked, because a messenger's
+ * refusal can quote the payload back.
  */
 export interface RunMetadata {
     runId: string;
@@ -44,7 +47,19 @@ export interface RunMetadata {
     codes?: string[];
     /** The caller's trace: the MCP client's, or the schedule's or job's that started it. */
     traceId?: string;
+    /** The whole command with the program's name, `max messages list`; `command` stays the run's short name. */
+    cliCommand?: string;
+    /** The words after the program's name, every value that may be content or a secret `[redacted]` (`maskArgv`). */
+    argv?: string[];
+    /** The word that named no command, when that is why the run failed. */
+    unknownCommand?: string;
+    /** The coding agent that started it, when one did. */
+    agent?: RunAgent;
+    /** How a failed run failed (`errorDetailOf`). */
+    error?: RunError;
 }
+/** Who started a run and with what, known before it starts. */
+export type RunContext = Pick<RunMetadata, "cliCommand" | "argv" | "unknownCommand" | "agent">;
 export interface StartRunOptions {
     runsDir: string;
     command: string;
@@ -60,6 +75,7 @@ export interface StartRunOptions {
     startedAt?: Date;
     /** The caller's trace, written on every record as `trace_id`. */
     traceId?: string;
+    context?: RunContext;
     /** The log file could not be opened or written; the run goes on unrecorded from here. */
     onError?: (error: Error) => void;
 }

package/dist/runs/run.js

@@ -74,6 +74,7 @@ export const startRun = (options) => {
         platform: process.platform,
         arch: process.arch,
         ...(options.traceId === undefined ? {} : { traceId: options.traceId }),
+        ...options.context,
     };
     writeRunFile(dir, metadata);
     let finished = false;

package/dist/store/exports.d.ts

@@ -32,6 +32,7 @@ export { OTHER_SOURCES, type OtherSource, type SourceMention } from "./sqlite/me
 export { MENTION_QUERY, MENTION_STATUSES, type MentionDecision, type MentionStatus, type MentionsRebuild, type MentionsState, type StoredMention, type StoredPlace, } from "./sqlite/mentions.js";
 export { drainNoteIndex, noteIndexState, resetNoteIndex } from "./sqlite/note-index.js";
 export type { Link as ThingLink } from "./sqlite/notes.js";
+export { openSqlite } from "./sqlite/open.js";
 export type { PersonPreparationRead, PreparationFact, PreparationNote, PreparationTask, } from "./sqlite/person-preparation.js";
 export { savedPhoneCountries, saveStorePhoneCountries } from "./sqlite/phone-countries.js";
 export type { PrivateContact, PrivateContactNote } from "./sqlite/private-people.js";
@@ -46,6 +47,7 @@ export { fillSearchIndex, resetSearchIndex, searchIndexState } from "./sqlite/se
 export type { SearchCommand, SearchRecord, StoredSearch } from "./sqlite/searches.js";
 export { type StemsState, savedStemmers, stemmerCache, stemmersOrigin, stemsState, } from "./sqlite/stems.js";
 export { fillStems, resetStems } from "./sqlite/stems-fill.js";
+export { rowCounts, storeContents } from "./sqlite/store-contents.js";
 export type { StoredTag, TagFilter, TagTarget, TaskTagTarget } from "./sqlite/tags.js";
 export { savedTaskCategories } from "./sqlite/task-category-settings.js";
 export { DEFAULT_AGENT_CLOSE, savedAgentClose } from "./sqlite/task-close.js";

package/dist/store/exports.js

@@ -11,12 +11,14 @@ export { involvementStoreOver } from "./sqlite/involvements.js";
 export { OTHER_SOURCES } from "./sqlite/mention-sources.js";
 export { MENTION_QUERY, MENTION_STATUSES, } from "./sqlite/mentions.js";
 export { drainNoteIndex, noteIndexState, resetNoteIndex } from "./sqlite/note-index.js";
+export { openSqlite } from "./sqlite/open.js";
 export { savedPhoneCountries, saveStorePhoneCountries } from "./sqlite/phone-countries.js";
 export { queryFilter } from "./sqlite/query-filter.js";
 export { AGENDA_COLUMNS } from "./sqlite/reads.js";
 export { fillSearchIndex, resetSearchIndex, searchIndexState } from "./sqlite/search-index.js";
 export { savedStemmers, stemmerCache, stemmersOrigin, stemsState, } from "./sqlite/stems.js";
 export { fillStems, resetStems } from "./sqlite/stems-fill.js";
+export { rowCounts, storeContents } from "./sqlite/store-contents.js";
 export { savedTaskCategories } from "./sqlite/task-category-settings.js";
 export { DEFAULT_AGENT_CLOSE, savedAgentClose } from "./sqlite/task-close.js";
 export { DEFAULT_FIRST_PASS_PER_CHAT, firstPassPerChatOf, savedFirstPassPerChat } from "./sqlite/task-first-pass.js";

package/dist/store/sqlite/store-contents.d.ts

@@ -0,0 +1,47 @@
+import type { CacheDatabase } from "../driver.js";
+/** The tables `store info` counts; a file from before a table's migration simply lacks it. */
+export declare const COUNTED_TABLES: readonly ["accounts", "chats", "messages", "emails", "documents", "meetings", "events", "attachments", "identities"];
+export declare const hasTable: (database: CacheDatabase, table: string) => boolean;
+export declare const rowCounts: (database: CacheDatabase) => Partial<Record<(typeof COUNTED_TABLES)[number], number>>;
+/**
+ * What the store holds, grouped, over every account in it. Plain `count(*) … GROUP BY` on indexed
+ * columns only: `dbstat` would give sizes per table but reads every page of the file.
+ */
+export declare const storeContents: (database: CacheDatabase) => {
+    byProvider: {
+        accounts: number;
+        provider: string;
+        chats: number;
+        documents: number;
+        emails: number;
+        meetings: number;
+        messages: number;
+    }[];
+    byChatKind: {
+        provider: string;
+        kind: string;
+        chats: number;
+        messages: number;
+    }[];
+    byAccount: {
+        provider: string;
+        accountId: number;
+        name: string | null;
+        chats: number;
+        documents: number;
+        emails: number;
+        meetings: number;
+        messages: number;
+    }[];
+    byYear: {
+        provider: string;
+        year: number;
+        messages: number;
+    }[];
+    byAttachmentKind: {
+        type: string;
+        kind: string;
+        count: number;
+        bytes: number;
+    }[];
+} | undefined;

package/dist/store/sqlite/store-contents.js

@@ -0,0 +1,104 @@
+/** The tables `store info` counts; a file from before a table's migration simply lacks it. */
+export const COUNTED_TABLES = [
+    "accounts",
+    "chats",
+    "messages",
+    "emails",
+    "documents",
+    "meetings",
+    "events",
+    "attachments",
+    "identities",
+];
+/** Tables whose rows belong to one account, so they can be counted per account and per provider. */
+const PER_ACCOUNT = ["chats", "messages", "emails", "documents", "meetings"];
+export const hasTable = (database, table) => database.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(table) !== undefined;
+export const rowCounts = (database) => Object.fromEntries(COUNTED_TABLES.filter((table) => hasTable(database, table)).map((table) => [
+    table,
+    Number(database.prepare(`SELECT count(*) AS n FROM ${table}`).get()?.n ?? 0),
+]));
+const zero = () => ({ chats: 0, messages: 0, emails: 0, documents: 0, meetings: 0 });
+/**
+ * What the store holds, grouped, over every account in it. Plain `count(*) … GROUP BY` on indexed
+ * columns only: `dbstat` would give sizes per table but reads every page of the file.
+ */
+export const storeContents = (database) => {
+    if (!hasTable(database, "accounts"))
+        return undefined;
+    const accounts = database.prepare("SELECT id, provider, name FROM accounts ORDER BY provider, id").all();
+    const perAccount = new Map(accounts.map((row) => [Number(row.id), zero()]));
+    for (const table of PER_ACCOUNT.filter((one) => hasTable(database, one))) {
+        for (const row of database.prepare(`SELECT account_id, count(*) AS n FROM ${table} GROUP BY account_id`).all()) {
+            const counts = perAccount.get(Number(row.account_id));
+            if (counts)
+                counts[table] = Number(row.n);
+        }
+    }
+    const providerOf = new Map(accounts.map((row) => [Number(row.id), String(row.provider)]));
+    const byProvider = new Map();
+    for (const [account, counts] of perAccount) {
+        const provider = providerOf.get(account);
+        const into = byProvider.get(provider) ?? { accounts: 0, ...zero() };
+        into.accounts++;
+        for (const table of PER_ACCOUNT)
+            into[table] += counts[table];
+        byProvider.set(provider, into);
+    }
+    const byYear = new Map();
+    if (hasTable(database, "messages")) {
+        // UTC years: the store keeps `sent_at` as epoch milliseconds and the machine's zone is not the owner's.
+        const rows = database
+            .prepare(`SELECT account_id, CAST(strftime('%Y', sent_at / 1000, 'unixepoch') AS INTEGER) AS year, count(*) AS n
+         FROM messages GROUP BY account_id, year`)
+            .all();
+        for (const row of rows) {
+            const provider = providerOf.get(Number(row.account_id)) ?? "unknown";
+            const key = `${provider}\u0000${row.year}`;
+            const into = byYear.get(key) ?? { provider, year: Number(row.year), messages: 0 };
+            into.messages += Number(row.n);
+            byYear.set(key, into);
+        }
+    }
+    const byChatKind = hasTable(database, "chats")
+        ? database
+            .prepare(`SELECT a.provider, c.kind, count(*) AS chats, coalesce(sum(m.n), 0) AS messages
+           FROM chats c
+           JOIN accounts a ON a.id = c.account_id
+           LEFT JOIN (SELECT chat_id, count(*) AS n FROM messages GROUP BY chat_id) m ON m.chat_id = c.id
+           GROUP BY a.provider, c.kind
+           ORDER BY a.provider, c.kind`)
+            .all()
+            .map((row) => ({
+            provider: String(row.provider),
+            kind: String(row.kind),
+            chats: Number(row.chats),
+            messages: Number(row.messages),
+        }))
+        : [];
+    const byAttachmentKind = hasTable(database, "attachments")
+        ? database
+            .prepare(`SELECT attachable_type, kind, count(*) AS n, coalesce(sum(size), 0) AS bytes
+           FROM attachments GROUP BY attachable_type, kind ORDER BY attachable_type, kind`)
+            .all()
+            .map((row) => ({
+            type: String(row.attachable_type),
+            kind: String(row.kind),
+            count: Number(row.n),
+            bytes: Number(row.bytes),
+        }))
+        : [];
+    return {
+        byProvider: [...byProvider]
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([provider, counts]) => ({ provider, ...counts })),
+        byChatKind,
+        byAccount: accounts.map((row) => ({
+            provider: String(row.provider),
+            accountId: Number(row.id),
+            name: row.name === null ? null : String(row.name),
+            ...perAccount.get(Number(row.id)),
+        })),
+        byYear: [...byYear.values()].sort((a, b) => a.provider.localeCompare(b.provider) || a.year - b.year),
+        byAttachmentKind,
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.424.0",
+  "version": "0.426.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",