@wirecat/cli-core 0.20.0 → 0.263.0

package/dist/sends/journal.d.ts

@@ -0,0 +1,91 @@
+import type { LogRecord } from "@wirecat/cli-base/standards";
+import type { AppIdentity } from "../cli/app.js";
+import type { Id } from "../domain/models.js";
+/** `reserved` holds a place under the hourly limit while the write is on its way; its outcome follows. */
+export type SendOutcome = "sent" | "outcome_unknown" | "refused" | "failed" | "reserved";
+/** Absent in the journal means a message: that is every line written before reactions were guarded. */
+export type SendKind = "message" | "reaction" | "edit" | "forward" | "pin" | "read" | "delete" | "chat" | "account";
+/** What a `chat` entry did. Never a title, a description or a link — only which action. */
+export type ChatAction = "create" | "join" | "leave" | "delete" | "clear" | "members.add" | "members.remove" | "admins.add" | "admins.remove" | "update" | "settings" | "requests.accept" | "requests.decline" | "link.reset" | "link.create" | "link.revoke" | "link.update" | "forum-upgrade" | "forum-enable" | "topic-create" | "topic-edit" | "topic-delete" | "topic-close" | "topic-reopen" | "topic-pin" | "topic-unpin" | "topic-order" | "topic-hide" | "topic-unhide";
+/** What an `account` entry changed. Never the value it changed it to — no name, number or title. */
+export type AccountAction = "contact-add" | "contact-remove" | "contact-import" | "contact-rename" | "contact-block" | "contact-unblock" | "profile" | "folder-create" | "folder-update" | "folder-delete" | "folder-order" | "folder-join" | "sessions-end" | "chat-mute" | "privacy";
+/** One attempt to send. **Never the text** — only its length. */
+export interface SendEntry {
+    at: string;
+    profile: string;
+    /** `null` when a join or a creation was refused before there was a chat, and for a change to the account itself. */
+    chatId: Id | null;
+    outcome: SendOutcome;
+    kind?: SendKind;
+    action?: ChatAction | AccountAction;
+    /** How many people a `chat` entry added or removed. */
+    people?: number;
+    messageId?: Id;
+    /** The command a write belongs to, where it named one: `polls.create` sets a poll apart from a message. */
+    key?: string;
+    /** How many messages a `delete` entry named — each one counts toward the hourly limit. */
+    count?: number;
+    forEveryone?: boolean;
+    /**
+     * The client-side identity of one logical send — Telegram's `random_id`, MAX's `cid` — as a
+     * string: Telegram's is 64-bit. A retry repeats it, and the provider delivers one message for both.
+     */
+    sendId?: string;
+    /**
+     * One write's id — in its answer, on each of its lines here and in its run events. A send's is its
+     * `sendId`. Absent on lines written before writes had one.
+     */
+    operationId?: string;
+    parentOperationId?: string;
+    /** The message a reply answers. */
+    replyTo?: Id;
+    threadId?: Id;
+    /** The identity a message was sent as, when not the account itself by default. */
+    sendAs?: Id;
+    resultChatId?: Id;
+    length?: number;
+    /** What was attached, by kind and size — never a file name. */
+    attachments?: {
+        kind: "photo" | "file" | "video" | "voice";
+        bytes: number;
+    }[];
+    /** When the provider will send it; it counts toward the limit of that hour, not of the hour it was queued. */
+    scheduledFor?: string;
+    /** Whether a pin told the members. */
+    notify?: boolean;
+    /** What sent it when no command did: `rule:<id>` for an auto-reply. */
+    origin?: string;
+    /** Pairs an outcome with the `reserved` line it settles. */
+    reservation?: string;
+    errorCode?: string;
+}
+/**
+ * `<state dir>/sends/<profile>.jsonl` — beside `runs`, never in the cache directory, so that
+ * clearing a cache cannot erase what was sent in the owner's name.
+ */
+export declare const sendsPathFor: (app: AppIdentity, profile: string, env?: NodeJS.ProcessEnv) => string;
+/**
+ * One log record per line (cli-base's `LogRecord`): the entry's `at` is the record's `time`, the rest
+ * its `attributes`, and the run that wrote it its `runId`. A refusal or a failure is a `warn`.
+ */
+export declare class SendJournal {
+    #private;
+    readonly path: string;
+    /** Who writes: the program's name and version. Only a reader may leave it out. */
+    private readonly resource;
+    constructor(path: string, 
+    /** Who writes: the program's name and version. Only a reader may leave it out. */
+    resource?: LogRecord["resource"]);
+    /**
+     * Runs `body` with the journal to itself, across processes: two sends at the limit must not both
+     * read "one left". A lock file opened with `wx`, because `flock` is not there on Windows.
+     */
+    locked<T>(body: () => T): T;
+    append(entry: SendEntry): void;
+    /**
+     * Oldest first, each reservation folded into its outcome; one with no outcome yet is in flight,
+     * or its process died. A line that does not parse is skipped: a torn last write must not block sending.
+     */
+    entries(): SendEntry[];
+}
+//# sourceMappingURL=journal.d.ts.map

package/dist/sends/journal.d.ts.map

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

package/dist/sends/journal.js

@@ -0,0 +1,89 @@
+import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { resolvePaths } from "@wirecat/cli-base";
+import { currentRun } from "../cli/runs/scope.js";
+import { withFileLock } from "./file-lock.js";
+/**
+ * `<state dir>/sends/<profile>.jsonl` — beside `runs`, never in the cache directory, so that
+ * clearing a cache cannot erase what was sent in the owner's name.
+ */
+export const sendsPathFor = (app, profile, env = process.env) => join(resolvePaths({ appName: app.appName, prefix: app.envPrefix, env }).state, "sends", `${profile}.jsonl`);
+/**
+ * One log record per line (cli-base's `LogRecord`): the entry's `at` is the record's `time`, the rest
+ * its `attributes`, and the run that wrote it its `runId`. A refusal or a failure is a `warn`.
+ */
+export class SendJournal {
+    path;
+    resource;
+    constructor(path, 
+    /** Who writes: the program's name and version. Only a reader may leave it out. */
+    resource = { service: "unknown", version: "unknown" }) {
+        this.path = path;
+        this.resource = resource;
+    }
+    /**
+     * Runs `body` with the journal to itself, across processes: two sends at the limit must not both
+     * read "one left". A lock file opened with `wx`, because `flock` is not there on Windows.
+     */
+    locked(body) {
+        return withFileLock(this.path, "the send journal", body);
+    }
+    append(entry) {
+        const { at, ...attributes } = entry;
+        const { runId, command } = currentRun();
+        const record = {
+            time: at,
+            severity: entry.outcome === "sent" || entry.outcome === "reserved" ? "info" : "warn",
+            body: entry.kind ?? "message",
+            run_id: runId,
+            command,
+            attributes,
+            resource: this.resource,
+        };
+        mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+        appendFileSync(this.path, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+    }
+    /**
+     * Oldest first, each reservation folded into its outcome; one with no outcome yet is in flight,
+     * or its process died. A line that does not parse is skipped: a torn last write must not block sending.
+     */
+    entries() {
+        const lines = this.#lines();
+        const settled = new Set(lines.filter((entry) => entry.outcome !== "reserved").map((entry) => entry.reservation));
+        return lines
+            .filter((entry) => entry.outcome !== "reserved" || !settled.has(entry.reservation))
+            .map(({ reservation, ...entry }) => (entry.outcome === "reserved" ? { ...entry, reservation } : entry))
+            .map(withSendId);
+    }
+    #lines() {
+        let text;
+        try {
+            text = readFileSync(this.path, "utf8");
+        }
+        catch {
+            return [];
+        }
+        return text
+            .split("\n")
+            .filter((line) => line.trim() !== "")
+            .flatMap((line) => {
+            try {
+                return [entryOf(JSON.parse(line))];
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+}
+/**
+ * The guard counts every line toward the hourly limit, so a line written before the journal held
+ * records — flat, with `at` — still counts.
+ */
+const entryOf = (line) => "attributes" in line ? { at: line.time, ...line.attributes } : line;
+/** max-cli wrote the send identity as a number called `cid` before it was shared; read both. */
+const withSendId = (entry) => {
+    const { cid, ...rest } = entry;
+    return cid === undefined || rest.sendId !== undefined ? rest : { ...rest, sendId: String(cid) };
+};
+//# sourceMappingURL=journal.js.map

package/dist/sends/journal.js.map

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

package/dist/sends/pace.d.ts

@@ -0,0 +1,33 @@
+import type { AppIdentity } from "../cli/app.js";
+/** How fast one profile may ask its messenger, counted across every process using it. */
+export interface PaceRate {
+    /** 0 turns pacing off. */
+    perMinute: number;
+    /** Calls that may go at once before the rest are spaced. */
+    burst: number;
+}
+/** One call a second after a burst of 20: what a single `messages sync` already did with its 1 s page pause. */
+export declare const DEFAULT_PACE: PaceRate;
+/** `<state dir>/pace/<profile>.json`, beside `flood/`. */
+export declare const pacePathFor: (app: AppIdentity, profile: string, env?: NodeJS.ProcessEnv) => string;
+/**
+ * One request pace per profile, shared through a file so two commands, a background job and `serve` count
+ * against the same allowance. A generic cell-rate algorithm: `tat` is when the allowance is back to empty; a
+ * call may go once `tat - burst × interval` has passed, and moves `tat` one interval on.
+ */
+export declare class Pacer {
+    readonly path: string;
+    private readonly rate;
+    private readonly now;
+    constructor(path: string, rate: PaceRate, now?: () => number);
+    get interval(): number;
+    /** When this call may go; reserved at once, so the next caller in any process lines up behind it. */
+    reserve(): number;
+    /** The messenger asked every caller to wait: nothing goes before `now + waitMs`, in any process. */
+    holdFor(waitMs: number): void;
+    /** The owner's `flood clear`: every process may go again at once. */
+    reset(): void;
+    private read;
+    private write;
+}
+//# sourceMappingURL=pace.d.ts.map

package/dist/sends/pace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pace.d.ts","sourceRoot":"","sources":["../../src/sends/pace.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAGhD,yFAAyF;AACzF,MAAM,WAAW,QAAQ;IACvB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAA;CACd;AAED,gHAAgH;AAChH,eAAO,MAAM,YAAY,EAAE,QAAuC,CAAA;AAElE,0DAA0D;AAC1D,eAAO,MAAM,WAAW,QAAS,WAAW,WAAW,MAAM,QAAO,MAAM,CAAC,UAAU,KAAiB,MACK,CAAA;AAE3G;;;;GAIG;AACH,qBAAa,KAAK;IAEd,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAHtB,YACW,IAAI,EAAE,MAAM,EACJ,IAAI,EAAE,QAAQ,EACd,GAAG,GAAE,MAAM,MAAiB,EAC3C;IAEJ,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,qGAAqG;IACrG,OAAO,IAAI,MAAM,CAQhB;IAED,oGAAoG;IACpG,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAM5B;IAED,qEAAqE;IACrE,KAAK,IAAI,IAAI,CAEZ;IAED,OAAO,CAAC,IAAI;IASZ,OAAO,CAAC,KAAK;CAKd"}

package/dist/sends/pace.js

@@ -0,0 +1,65 @@
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolvePaths } from "@wirecat/cli-base";
+import { withFileLock } from "./file-lock.js";
+/** One call a second after a burst of 20: what a single `messages sync` already did with its 1 s page pause. */
+export const DEFAULT_PACE = { perMinute: 60, burst: 20 };
+/** `<state dir>/pace/<profile>.json`, beside `flood/`. */
+export const pacePathFor = (app, profile, env = process.env) => join(resolvePaths({ appName: app.appName, prefix: app.envPrefix, env }).state, "pace", `${profile}.json`);
+/**
+ * One request pace per profile, shared through a file so two commands, a background job and `serve` count
+ * against the same allowance. A generic cell-rate algorithm: `tat` is when the allowance is back to empty; a
+ * call may go once `tat - burst × interval` has passed, and moves `tat` one interval on.
+ */
+export class Pacer {
+    path;
+    rate;
+    now;
+    constructor(path, rate, now = Date.now) {
+        this.path = path;
+        this.rate = rate;
+        this.now = now;
+    }
+    get interval() {
+        return this.rate.perMinute > 0 ? 60_000 / this.rate.perMinute : 0;
+    }
+    /** When this call may go; reserved at once, so the next caller in any process lines up behind it. */
+    reserve() {
+        const now = this.now();
+        if (this.interval === 0)
+            return now;
+        return withFileLock(this.path, "the request pace", () => {
+            const tat = Math.max(this.read(), now);
+            this.write(tat + this.interval);
+            return Math.max(now, tat - this.rate.burst * this.interval);
+        });
+    }
+    /** The messenger asked every caller to wait: nothing goes before `now + waitMs`, in any process. */
+    holdFor(waitMs) {
+        if (this.interval === 0)
+            return;
+        withFileLock(this.path, "the request pace", () => {
+            const hold = this.now() + waitMs + this.rate.burst * this.interval;
+            this.write(Math.max(this.read(), hold));
+        });
+    }
+    /** The owner's `flood clear`: every process may go again at once. */
+    reset() {
+        withFileLock(this.path, "the request pace", () => this.write(0));
+    }
+    read() {
+        try {
+            const tat = Number(JSON.parse(readFileSync(this.path, "utf8")).tat);
+            return Number.isFinite(tat) ? tat : 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    write(tat) {
+        const temporary = `${this.path}.${process.pid}.tmp`;
+        writeFileSync(temporary, JSON.stringify({ tat }), { mode: 0o600 });
+        renameSync(temporary, this.path);
+    }
+}
+//# sourceMappingURL=pace.js.map

package/dist/sends/pace.js.map

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

package/dist/sends/permissions.d.ts

@@ -0,0 +1,62 @@
+import type { SendKind } from "./journal.js";
+/**
+ * What a profile may be allowed to do (max-cli `CLI-37`, `NEED-251`). One name per thing the owner would
+ * recognise, so `sessions` — which logs the owner out of their phone — never rides along with
+ * adding a contact. There is no `*`: "everything" is not setting `allow` at all, and a wildcard
+ * would switch on `delete` without anyone naming it.
+ */
+export declare const PERMISSIONS: readonly ["send", "forward", "reaction", "edit", "pin", "read", "delete", "groups", "contacts", "profile", "folders", "sessions"];
+export type Permission = (typeof PERMISSIONS)[number];
+export declare const permissionFor: (kind: SendKind, action?: string) => Permission;
+/** What a profile may do with one command path — the standard's "Permissions". */
+export declare const LEVELS: readonly ["deny", "readonly", "ask", "allow"];
+export type Level = (typeof LEVELS)[number];
+/** A command path, dotted: `messages`, `messages.delete`, `chats.members.remove`. */
+export type PermissionKey = string;
+/** Deleting has its own word for "yes": the flag a person has to mean, not a habit (max-cli `NEED-238`). */
+export declare const skipFlagFor: (key: string) => "--allow-dangerous" | "--yes";
+/** Only what cannot be undone asks; the tool is meant to work without questions (owner, NEED-460). */
+export declare const DEFAULT_PERMISSIONS: Readonly<Record<PermissionKey, Level>>;
+/** The resources at the top of the command tree, which `readOnly` and `allow` turn read-only as a whole. */
+export declare const RESOURCES: readonly ["messages", "reactions", "polls", "topics", "chats", "contacts", "account", "bot", "conversations", "tags", "search", "searches", "tasks", "replies", "attachments", "stats", "store", "metadata"];
+/** The command path an old `allow` word stood for, as one key — what an MCP tool's `permission` is checked against. */
+export declare const keyOfWord: (word: Permission) => PermissionKey;
+/** `bot` translates a bot's `readOnly` and `allow`, which only ever covered the bot. */
+export declare const fromOldSettings: (readOnly: boolean, allow: readonly Permission[] | undefined, { bot }?: {
+    bot?: boolean;
+}) => Record<PermissionKey, Level>;
+/**
+ * Layers come nearest first. A key a nearer layer sets hides that key and every key under it in the
+ * farther layers, so a profile's `messages: readonly` is not undone by `messages.delete: allow` in
+ * `defaults` — the nearest section wins, as it does for every other setting (NEED-573).
+ */
+export declare const layerPermissions: (layers: readonly [string, Readonly<Record<PermissionKey, Level>> | undefined][]) => {
+    levels: Record<string, "allow" | "ask" | "deny" | "readonly">;
+    sources: Record<string, string>;
+};
+/**
+ * The most specific key the owner set wins. A built-in default (`DEFAULT_PERMISSIONS`) only ever
+ * tightens: against a broader key of the owner's, the stricter of the two holds — so
+ * `messages: readonly` still stops a deletion, and `messages: allow` does not drop its question.
+ * A path nothing names is allowed.
+ */
+export declare const levelFor: (permissions: Readonly<Record<PermissionKey, Level>>, key: PermissionKey, defaults?: Readonly<Record<PermissionKey, Level>>) => {
+    level: Level;
+    key: PermissionKey | null;
+};
+/** The command path a guarded write belongs to, when the caller did not name it. */
+export declare const keyForWrite: (kind: SendKind, action?: string) => PermissionKey;
+/** Every key a write is checked against that a command path may not spell out. */
+export declare const WRITE_KEYS: readonly PermissionKey[];
+/** Statistics and searches moved; a profile still naming the old paths must be migrated before they run. */
+export declare const assertStatsPermissionsCurrent: (path: readonly string[], permissions: Readonly<Record<string, Level>>) => void;
+export declare const readKeysForCommand: (path: readonly string[]) => PermissionKey[];
+/**
+ * The key a command path is checked against: `null` for housekeeping, which no level stops, and
+ * `undefined` for a path this package does not know — a CLI's own command, which its CLI maps.
+ */
+export declare const keyForCommand: (path: readonly string[]) => PermissionKey | null | undefined;
+/** Startup overrides are a nearer layer than the saved profile, and never write that profile. */
+export declare const permissionOverrides: (entries?: readonly string[]) => Record<PermissionKey, Level>;
+export declare const assertRetentionEvidenceRead: (permissions: Readonly<Record<string, Level>>) => void;
+//# sourceMappingURL=permissions.d.ts.map

package/dist/sends/permissions.d.ts.map

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