@wirecat/cli-core 0.391.0 → 0.392.0

package/dist/cli/messenger/messages-delete-command.js

@@ -11,7 +11,10 @@ import { messengerContext } from "./context.js";
  * The guard asks first at the default level, `ask`; `--allow-dangerous` is the yes. For everyone only
  * with `--for-everyone` (max-cli `NEED-239`), and never for an agent (NEED-1423).
  */
-export const deleteCommand = (messenger) => annotate(new Command("delete"), { effects: REMOTE_WRITE })
+export const deleteCommand = (messenger) => annotate(new Command("delete"), {
+    examples: [`${messenger.app.command} personal messages delete "Book club" 101`],
+    effects: REMOTE_WRITE,
+})
     .description("delete messages for you only; with --for-everyone, for everyone in the chat")
     .argument("<chat>", messenger.chatArgument)
     .argument("<messages...>", `the message ids, by spaces or commas, at most ${DELETE_AT_ONCE}`)

package/dist/cli/messenger/messages-edit-command.js

@@ -8,7 +8,10 @@ import { afterWrite, writtenAnswer } from "./message-writes.js";
 import { HTML_HELP } from "./messages-send-command.js";
 import { readAll } from "./stdin.js";
 export const editCommand = (messenger) => {
-    const edit = annotate(new Command("edit"), { effects: REMOTE_WRITE })
+    const edit = annotate(new Command("edit"), {
+        examples: [`${messenger.app.command} personal messages edit "Book club" 101 "The meeting starts at 11."`],
+        effects: REMOTE_WRITE,
+    })
         .description("change the text of your own message; the other side may have read it already")
         .argument("<chat>", messenger.chatArgument)
         .argument("<message>", "the id of your own message")

package/dist/cli/messenger/messages-evidence-command.js

@@ -6,7 +6,10 @@ import { renderAnswer } from "../envelope.js";
 import { positiveCount } from "../paging.js";
 import { messengerContext } from "./context.js";
 import { evidenceAnswer } from "./message-answers.js";
-export const evidenceCommand = (messenger) => annotate(new Command("evidence"), { effects: LOCAL_READ })
+export const evidenceCommand = (messenger) => annotate(new Command("evidence"), {
+    examples: [`${messenger.app.command} personal messages evidence "Book club" --limit 10`],
+    effects: LOCAL_READ,
+})
     .description("a bounded evidence packet from stored messages, newest first")
     .argument("<chat>", messenger.chatArgument)
     .option("--limit <n>", "how many, 1–100", positiveCount("--limit"))

package/dist/cli/messenger/messages-forward-command.js

@@ -6,7 +6,10 @@ import { renderAnswer } from "../envelope.js";
 import { messengerContext } from "./context.js";
 import { afterWrite, writtenAnswer } from "./message-writes.js";
 export const forwardCommand = (messenger) => {
-    const forward = annotate(new Command("forward"), { effects: REMOTE_WRITE })
+    const forward = annotate(new Command("forward"), {
+        examples: [`${messenger.app.command} personal messages forward "Book club" 101 --to "Project room"`],
+        effects: REMOTE_WRITE,
+    })
         .description("forward one message to another chat")
         .argument("<chat>", `the chat the message is in: ${messenger.chatArgument}`)
         .argument("<message>", "the message id")

package/dist/cli/messenger/messages-link-command.js

@@ -4,7 +4,10 @@ import { REMOTE_READ } from "../effects.js";
 import { itemOf, renderAnswer } from "../envelope.js";
 import { messengerContext } from "./context.js";
 export const messageLinkCommand = (messenger) => {
-    const command = annotate(new Command("link"), { effects: REMOTE_READ })
+    const command = annotate(new Command("link"), {
+        examples: [`${messenger.app.command} personal messages link "Book club" 101`],
+        effects: REMOTE_READ,
+    })
         .description("a message permalink when supported, and its account-scoped locator")
         .argument("<chat>", `${messenger.chatArgument}; or a msg: locator, with no message id after it`)
         .argument("[message]", "the message id")

package/dist/cli/messenger/messages-scheduled-command.js

@@ -8,7 +8,10 @@ import { messengerContext } from "./context.js";
 import { messageItems, selfOf, viewOf } from "./message-items.js";
 /** Where to look after a scheduled send ended without an answer: repeating it would schedule a second one. */
 export const scheduledCommand = (messenger) => {
-    const command = annotate(new Command("scheduled"), { effects: REMOTE_READ })
+    const command = annotate(new Command("scheduled"), {
+        examples: [`${messenger.app.command} personal messages scheduled "Book club"`],
+        effects: REMOTE_READ,
+    })
         .description("messages waiting to be sent later in a chat, soonest first; cancel one in the app")
         .argument("<chat>", messenger.chatArgument)
         .action(async function (chat) {

package/dist/cli/messenger/messages-send-command.js

@@ -16,7 +16,10 @@ import { readAll } from "./stdin.js";
  */
 export const HTML_HELP = "the text is HTML: <b>, <i>, <a href>, <code>";
 export const sendCommand = (messenger) => {
-    const send = annotate(new Command("send"), { effects: REMOTE_WRITE })
+    const send = annotate(new Command("send"), {
+        examples: [`${messenger.app.command} personal messages send "Book club" "The meeting starts at 10."`],
+        effects: REMOTE_WRITE,
+    })
         .description("send a text message; without [text], the text is read from stdin")
         .argument("<chat>", messenger.chatArgument)
         .argument("[text]", "the message");

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

@@ -2,9 +2,9 @@ import { Command } from "commander";
 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/messenger/transcribe-command.js

@@ -8,7 +8,10 @@ import { messengerContext } from "./context.js";
 import { heardAnswer } from "./message-answers.js";
 import { keepRefreshedRefs } from "./refreshed-refs.js";
 /** `messages transcribe`: a voice message as text, by the messenger or by a model on this machine. */
-export const transcribeSubcommand = (messages, messenger) => annotate(messages.command("transcribe"), { effects: REMOTE_READ })
+export const transcribeSubcommand = (messages, messenger) => annotate(messages.command("transcribe"), {
+    examples: [`${messenger.app.command} personal messages transcribe "Book club" 101`],
+    effects: REMOTE_READ,
+})
     .description(`a voice message as text — by ${messenger.name ?? messenger.app.command} where it can, else by a model on this machine`)
     .argument("<chat>", messenger.chatArgument)
     .argument("<message>", "the id of a voice message")

package/dist/domain/providers.js

@@ -6,6 +6,8 @@ export const PROVIDERS = [
     { name: "telegram-bot", kind: "messages", aliases: ["tg-bot"] },
     { name: "max", kind: "messages", aliases: [] },
     { name: "max-bot", kind: "messages", aliases: [] },
+    { name: "whatsapp", kind: "messages", aliases: ["wa"] },
+    { name: "whatsapp-bot", kind: "messages", aliases: ["wa-bot"] },
     { name: "email", kind: "mail", aliases: [] },
     { name: "notes", kind: "notes", aliases: [] },
     { name: "zoom", kind: "meetings", aliases: [] },

package/dist/{mcp/http/node.d.ts → http/listen.d.ts}

@@ -4,13 +4,14 @@ export interface Listening {
     url: URL;
     close(): Promise<void>;
 }
-/** Larger bodies are refused unread: the port faces the internet, and MCP requests are small JSON. */
+/** Larger bodies are refused unread: the port faces the internet. MCP requests are small JSON. */
 export declare const MAX_BODY: number;
 /**
  * Binds `host` only — never every interface: the public address is the owner's tunnel.
  * `close` ends open streams too, so the process can exit.
  */
-export declare const listen: (handle: Handle, { host, port }: {
+export declare const listen: (handle: Handle, { host, port, maxBody }: {
     host: string;
     port: number;
+    maxBody?: number;
 }) => Promise<Listening>;

package/dist/{mcp/http/node.js → http/listen.js}

@@ -1,6 +1,6 @@
 import { createServer } from "node:http";
 import { Readable } from "node:stream";
-/** Larger bodies are refused unread: the port faces the internet, and MCP requests are small JSON. */
+/** Larger bodies are refused unread: the port faces the internet. MCP requests are small JSON. */
 export const MAX_BODY = 4 * 1024 * 1024;
 class TooLarge extends Error {
 }
@@ -21,7 +21,7 @@ const readBody = (incoming, limit) => new Promise((resolve, reject) => {
     incoming.once("end", () => resolve(Buffer.concat(chunks)));
     incoming.once("error", reject);
 });
-const toRequest = async (incoming, origin) => {
+const toRequest = async (incoming, origin, maxBody) => {
     const headers = new Headers();
     for (const [name, value] of Object.entries(incoming.headers)) {
         if (Array.isArray(value))
@@ -31,7 +31,7 @@ const toRequest = async (incoming, origin) => {
             headers.set(name, value);
     }
     const method = incoming.method ?? "GET";
-    const body = method === "GET" || method === "HEAD" ? undefined : await readBody(incoming, MAX_BODY);
+    const body = method === "GET" || method === "HEAD" ? undefined : await readBody(incoming, maxBody);
     if (body)
         headers.set("content-length", String(body.length));
     return new Request(new URL(incoming.url ?? "/", origin), { method, headers, ...(body ? { body } : {}) });
@@ -48,9 +48,9 @@ const send = async (response, outgoing) => {
  * Binds `host` only — never every interface: the public address is the owner's tunnel.
  * `close` ends open streams too, so the process can exit.
  */
-export const listen = (handle, { host, port }) => new Promise((resolve, reject) => {
+export const listen = (handle, { host, port, maxBody = MAX_BODY }) => new Promise((resolve, reject) => {
     const server = createServer((incoming, outgoing) => {
-        toRequest(incoming, `http://${host}`)
+        toRequest(incoming, `http://${host}`, maxBody)
             .then(handle)
             .then((response) => send(response, outgoing))
             .catch((error) => {

package/dist/http/public-url.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The tunnel's address a public listener is reached at, checked one way for every command that opens
+ * one. `missing` says what needs it; `reaches` who calls through it, for the https refusal.
+ */
+export declare const publicUrlOf: (given: string | undefined, { missing, reaches }: {
+    missing: string;
+    reaches: string;
+}) => URL;
+/** A local port from `--port`, or the command's own default. */
+export declare const portOf: (given: string | undefined, fallback: number) => number;

package/dist/http/public-url.js

@@ -0,0 +1,32 @@
+import { CliError } from "@wirecat/cli-base";
+const EXAMPLE = "--public-url https://<name>.ts.net";
+/**
+ * The tunnel's address a public listener is reached at, checked one way for every command that opens
+ * one. `missing` says what needs it; `reaches` who calls through it, for the https refusal.
+ */
+export const publicUrlOf = (given, { missing, reaches }) => {
+    if (!given)
+        throw new CliError("configuration_error", `${missing} needs the tunnel's address: ${EXAMPLE}`);
+    let url;
+    try {
+        url = new URL(given);
+    }
+    catch {
+        throw new CliError("validation_error", `--public-url is not an address: ${EXAMPLE}`);
+    }
+    const local = url.protocol === "http:" && ["localhost", "127.0.0.1"].includes(url.hostname);
+    if (url.protocol !== "https:" && !local)
+        throw new CliError("validation_error", `--public-url must be https — ${reaches} through it`);
+    if (url.pathname !== "/" || url.search || url.hash)
+        throw new CliError("validation_error", `--public-url is the tunnel's address only, without a path: ${EXAMPLE}`);
+    return url;
+};
+/** A local port from `--port`, or the command's own default. */
+export const portOf = (given, fallback) => {
+    if (given === undefined)
+        return fallback;
+    const port = Number(given);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new CliError("validation_error", "--port takes 1–65535");
+    return port;
+};

package/dist/mcp/http/serve.d.ts

@@ -1,5 +1,5 @@
 import { type McpServer } from "@modelcontextprotocol/server";
-import { type Listening } from "./node.js";
+import { type Listening } from "../../http/listen.js";
 export declare const MCP_PATH = "/mcp";
 export interface HttpOptions {
     /** The tunnel's address, as the browser apps reach it — `https://name.ts.net`. */

package/dist/mcp/http/serve.js

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { createMcpHandler, getOAuthProtectedResourceMetadataUrl, hostHeaderValidationResponse, isLegacyRequest, oauthMetadataResponse, requireBearerAuth, WebStandardStreamableHTTPServerTransport, } from "@modelcontextprotocol/server";
-import { listen } from "./node.js";
+import { listen } from "../../http/listen.js";
 import { ownerLogin } from "./oauth.js";
 export const MCP_PATH = "/mcp";
 const LOCAL = ["localhost", "127.0.0.1"];

package/dist/store/sqlite/lucene-fields.d.ts

@@ -29,8 +29,13 @@ export interface Corpus {
     item: string;
     thread: string;
 }
-/** A voice note's transcript is its attachment's text, written by speech recognition (`speech:<model>`). */
-export declare const SPEECH = "coalesce(att.extractor,'') LIKE 'speech:%'";
+/**
+ * A voice note's transcript is its attachment's text, whoever wrote it: speech recognition (`speech:<model>`) or an
+ * agent, which writes the text of a voice attachment as `agent`. The voice attachment is the one
+ * `intoVoiceAttachment` picks.
+ */
+export declare const speech: (alias: string) => string;
+export declare const SPEECH: string;
 export declare const quoted: (value: string) => string;
 /** A leaf's words as an FTS5 match: a phrase, or with `~N` its words at most N apart, in any order. */
 export declare const ftsMatch: (node: ResolvedPredicate) => string;

package/dist/store/sqlite/lucene-fields.js

@@ -12,8 +12,13 @@ import { STEM_SEPARATOR } from "../../search/stem.js";
 import { normalize } from "../normalize.js";
 import { linkMatch } from "./mention-links.js";
 import { valueMatch } from "./phone-countries.js";
-/** A voice note's transcript is its attachment's text, written by speech recognition (`speech:<model>`). */
-export const SPEECH = "coalesce(att.extractor,'') LIKE 'speech:%'";
+/**
+ * A voice note's transcript is its attachment's text, whoever wrote it: speech recognition (`speech:<model>`) or an
+ * agent, which writes the text of a voice attachment as `agent`. The voice attachment is the one
+ * `intoVoiceAttachment` picks.
+ */
+export const speech = (alias) => `(coalesce(${alias}.extractor,'') LIKE 'speech:%' OR ${alias}.kind IN ('voice','video_note') OR coalesce(${alias}.mime,'')='audio/ogg')`;
+export const SPEECH = speech("att");
 export const quoted = (value) => `"${value.replaceAll('"', '""')}"`;
 /** A leaf's words as an FTS5 match: a phrase, or with `~N` its words at most N apart, in any order. */
 export const ftsMatch = (node) => {

package/dist/store/sqlite/mention-drain.js

@@ -1,6 +1,7 @@
 import { findMentions, MENTION_KINDS, MENTION_VERSIONS, oneTrackedLinkPerSite, telegramTarget, } from "../../domain/mentions.js";
 import { findNames, findUnknownNames, nameIndex } from "../../domain/person-names.js";
 import { createStemmer } from "../../search/stem.js";
+import { speech } from "./lucene-fields.js";
 import { storePhoneCountries } from "./phone-countries.js";
 import { placeOf } from "./place-key.js";
 /** Mentions a store write finds before it commits: an older binary may have queued thousands. */
@@ -98,10 +99,10 @@ export const SOURCES = {
     attachment: {
         count: "SELECT count(*) AS n FROM attachments a JOIN messages m ON m.id = a.attachable_id " +
             "WHERE a.attachable_type = 'message' AND a.text IS NOT NULL AND a.text <> '' AND m.deleted_at IS NULL",
-        page: "SELECT a.id, a.text, CASE WHEN coalesce(a.extractor, '') LIKE 'speech:%' THEN 'transcript' ELSE 'file_text' END AS field, " +
+        page: `SELECT a.id, a.text, CASE WHEN ${speech("a")} THEN 'transcript' ELSE 'file_text' END AS field, ` +
             "m.chat_id FROM attachments a JOIN messages m ON m.id = a.attachable_id WHERE a.id > ? AND a.attachable_type = 'message' " +
             "AND a.text IS NOT NULL AND a.text <> '' AND m.deleted_at IS NULL ORDER BY a.id LIMIT ?",
-        one: "SELECT a.text, CASE WHEN coalesce(a.extractor, '') LIKE 'speech:%' THEN 'transcript' ELSE 'file_text' END AS field, " +
+        one: `SELECT a.text, CASE WHEN ${speech("a")} THEN 'transcript' ELSE 'file_text' END AS field, ` +
             "m.chat_id FROM attachments a JOIN messages m ON m.id = a.attachable_id WHERE a.id = ? AND a.attachable_type = 'message' " +
             "AND a.text IS NOT NULL AND m.deleted_at IS NULL",
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.391.0",
+  "version": "0.392.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",