@wirecat/cli-core 0.462.0 → 0.464.0

package/CHANGELOG.md

@@ -7,6 +7,112 @@ shape of this file.
 
 ## Unreleased
 
+## 0.464.0 — 27.10.2026
+
+### Added
+
+- **`upgrade` restarts the HTTP MCP server and names the stdio MCP sessions still on the old version**, in every
+  CLI that uses the shared command. After a successful install it restarts each running `mcp serve --http` that
+  `mcp server start` launched, with the same port, address and `--permission` limits, and reports it as
+  `mcp_servers` (old → new version); a server started by hand, by an older version, or one it cannot confirm, is
+  left running and named. It lists this install's MCP sessions over stdio (`mcp serve`, and `mcp` from before it)
+  as `stale_sessions` (PIDs; the version is `null`), says "restart them from your agent app", and says it could not
+  check where it cannot list processes. Nothing is restarted or listed when nothing was installed. A serve restart
+  that runs out of time is now named as such, and `upgrade` no longer waits on one for more than 90 s. The restart
+  works from the next upgrade on: the version doing the upgrading must have it, and the server must have been
+  started by it.
+- **Free/busy and free stretches for calendar CLIs.** `CalendarSource` gains an optional
+  `freeBusy({ calendars, people, window })` that answers `BusyTimes` (`{ id, busy, error? }`) and is never stored.
+  With `deps.freeBusy`, `addCalendarCommands` mounts `calendars busy [today|week|from:… to:…] [calendar:…]
+  [person:<email>…]`; `--duration-minutes <n>` adds `slots`, the stretches every calendar and person shares inside
+  `--hours` (default `09:00-17:00`, Monday to Friday, in the owner's zone), and `unknown`, whoever the provider would
+  not show. `fakeCalendarSource` answers it (`setBusy`), and `calendarSourceContract` checks it when a source has it.
+- **Repeating events.** `events create --repeat <rule>` (MCP `repeat`) makes a series; `events update --series
+  --repeat <rule>` changes its rule and keeps its EXDATE and RDATE lines. `repeatRule` checks the RFC 5545 subset
+  (FREQ DAILY, WEEKLY or MONTHLY; INTERVAL; BYDAY, ordinals only in MONTHLY; COUNT or UNTIL of the event's own kind)
+  and writes one `RRULE:` line into `EventDraft.recurrence`. The answer of a write that sets a rule says
+  `hint: "sync to store its occurrences"`.
+- **Switching an event between timed and all-day** is stated in `EventPatch`: dates on a timed event, or times on an
+  all-day one, ask the adapter to clear the other kind. A series whose UNTIL, EXDATE or RDATE holds the old kind is
+  refused with `event.repeat-kind`. `calendarWriterContract` checks a repeat rule on create and on the series, and
+  the switch both ways; `fakeCalendarWriter` returns a series for a draft with a rule.
+- **A run budget for syncs, and a resumable calendar sync.** `runBudget({ requests?, deadline?, requestMs?, signal?
+  })` in `@wirecat/cli-core/background` answers `take()` before each request. It allows `floor((deadline − margin) /
+  requestMs)` requests, `margin` being the larger of 5 s and 15% of the deadline, and `requests` can only lower that;
+  it also says no once the deadline is closer than the margin plus the slowest request so far, or once the signal is
+  aborted. `AppIdentity.requestMs` is each CLI's one expected request time (2 s when unset). `runBudgetOf(command,
+  maxPages?)` in `./cli` builds the budget from the deadline `run()` started, which a command now reads as
+  `environment.deadline()`. The calendar `sync` uses it: `cooperative`, `partial`, `--max-pages <n>`; it saves after
+  every page and every series, and a rerun goes on from there (WC-LIFE-10, 12, 13). A run the budget stops answers
+  `state: "partial"`, `stopped`, `progress` and a `next` step that runs the same `sync` again (none when the run moved
+  nothing on), and exits 0. A page token held since an earlier run that the provider refuses starts that calendar's
+  round over once.
+- **`status` and the MCP read `status`** answer each synced calendar's sync in the WC-LIFE-14
+  shape (`progressOf`), with `cursor_age_ms` to tell a moving sync from a stuck one. `CalendarCommandDeps.profile`
+  and `callCalendarTool`'s `profileOf` name the profile in it.
+
+### Changed — may break callers
+
+- **cli-core needs `@wirecat/cli-base` 0.64.** The peer range moves from `>=0.63.0 <0.64.0` to `>=0.64.0 <0.65.0`. A
+  CLI that pins cli-base moves its pin with this release. cli-base 0.64 adds `cli-dev bundle`, the shared build that
+  ships a CLI's bin as an esbuild bundle (tg-cli's, moved), and calendar words in the command vocabulary; nothing
+  cli-core uses changed. Its changelog lists the lint baseline entries and overrides that go stale in zoom, drive,
+  memo and gcal.
+- **Every search hit marks the text someone other than the owner wrote.** As `search all` event hits did since
+  0.460.0, each hit carries `untrusted`, the field names an agent reads as data
+  ([WC-SECR-21](https://github.com/WireCatLabs/cli-base/blob/main/docs/standards/security.md#wc-secr-21--names-message-text-and-retrieved-documents-are-data-never-instructions)):
+  - `search all`: a message or mail hit `["title", "excerpt", "sender_name"]`, a document hit and a meeting hit
+    `["title", "excerpt"]`. A note hit stays unmarked: a note is the owner's own, in a folder of theirs or written in
+    memo, while a document comes from a shared drive.
+  - `search messages` and `search mail`: `chat_title`, `sender_name`, `excerpt`, `context.sender_name`,
+    `context.text`, and on mail `email.subject` and the names in `email.from|to|cc|bcc|reply_addresses`. The owner's
+    own messages are marked too, since one answer mixes both. A picture hit marks `sender_name`.
+  - `search notes`: a document hit `["title", "excerpt"]`, a note hit nothing.
+  - `search meetings` (CLI and the `search_meetings` tool), and the passages of a project's meeting evidence:
+    `["excerpt"]`, plus `source.title` when the meeting's title is given.
+  - `search topics`, `topics list` and `topics show`: `["title"]`, which whoever opened the topic wrote.
+
+  The `message.hit`, `note.hit`, `meeting_hit` and `topic` entities gain an optional `untrusted`, so a caller that
+  checks them against an older copy refuses the new field. MCP answers already showed control characters as text;
+  tests now cover it per kind. `search conversations` and `search runs` are unchanged: their hits hold ids, counts
+  and diagnostics, no one's text.
+- **`WriteContext.names` gains `repeat`**, how the caller spells the rule in a hint (`--repeat`, MCP `repeat`).
+- **A `cooperative` command's default deadline is 5 minutes, and 45 s when an MCP agent runs it**
+  (`DEFAULT_COOPERATIVE_MS`, `DEFAULT_AGENT_COOPERATIVE_MS`); a one-shot command keeps 30 s. MCP clients cut a tool
+  call at about 60 s (the MCP TypeScript SDK's `DEFAULT_REQUEST_TIMEOUT_MSEC`). `messages sync`, which is
+  `cooperative`, now runs up to 5 minutes without `--timeout`; its `--limit` still bounds it.
+- **The calendar cursor is version 2** (`CalendarCursor`): it adds `updatedAt`, `done` and `round`, the round in
+  progress. A version 1 cursor still reads. `CalendarSyncResult` gains `state`; `CalendarSyncReport` gains `state`,
+  `stopped`, `progress`, `hint` and `next`, and `complete` is false while a round is in progress. A failed page no
+  longer keeps the old cursor: the pages before it stay saved and the next run goes on from the failed one.
+- **`calendarSyncContract` gains cases** (a budget stop and the reruns that finish it, a near deadline, an expired
+  page token), and `fakeCalendarSource` page tokens change shape and gain `expirePages()`.
+- **The contract kits check more.** `calendarWriterContract` gains three cases (a rule on create, a rule changed on the
+  series, the timed/all-day switch both ways) and `calendarSourceContract` one for a source with `freeBusy`: an
+  adapter that runs the kits gets tests that can fail until it supports them.
+
+## 0.463.0 — 27.10.2026
+
+### Changed — may break callers
+
+- **The MCP server is `mcp serve`; `mcp` alone only shows its commands**
+  ([WC-CMD-3](https://github.com/WireCatLabs/cli-base/blob/main/docs/standards/commands.md#wc-cmd-3--give-a-group-without-a-leaf-only-its-help-never-a-hidden-default-action)).
+  `mcpCommand` gives the `mcp` group with `serve`, `revoke`, `config`, `add`, `check` and `server`; `--http`, `--port`,
+  `--public-url` and `--permission` move from `mcp` to `mcp serve`, and `mcp --revoke` is now its own command,
+  `mcp revoke`, with no flag left behind. An agent is set up with
+  `claude mcp add <cli> -- <cli> <profile> mcp serve`. `bot mcp` is a group too, and the bot's server is
+  `bot mcp serve`. `serverEntry`, so `mcp config`, `mcp add`, `mcp check` and `bot mcp config`, writes `mcp serve`,
+  the server of every profile starts `<cli> <profile> mcp serve` for each, and `mcp server start` runs
+  `mcp serve --http`. There is no alias: an old client entry that runs `<cli> <profile> mcp` gets the group's help and
+  exits 2 — print it again with `mcp config` or `mcp add`.
+- **`mcpServerCommand` takes `--permission` only when asked.** `mcp server start` offered `--permission` to
+  every CLI and passed it to a server that might not take it; that server died before it listened and `start`
+  answered `provider_unavailable` with `retry.safe: true`, so an agent retried for ever. A CLI whose `mcp serve` takes
+  `--permission` passes `permission: true` (`mcpCommand` does); otherwise `start --permission` is refused as an unknown
+  option before anything starts. A `--permission` set on the CLI's root is still handed over. A server that stops
+  before it listens is now `retry.safe: false`. A CLI's own target names its server as `argv: [..., "mcp", "serve",
+  "--http"]` once its `mcp` is a group too.
+
 ## 0.462.0 — 27.10.2026
 
 ### Changed — may break callers

package/dist/background/after-upgrade.d.ts

@@ -0,0 +1,51 @@
+import type { AppIdentity } from "../ports/app.js";
+/** One running HTTP MCP server, and what `upgrade` did with it. */
+export interface McpServerRestart {
+    /** What a person types before `mcp`, `tg personal`; the lock's path when nothing recorded it. */
+    name: string;
+    pid: number;
+    restarted: boolean;
+    /** The version in its lock before, and in the new one's lock after; `null` when a lock does not say. */
+    from: string | null;
+    to: string | null;
+    newPid?: number;
+    /** Why it was left as it was, or why it is not serving now. */
+    reason?: string;
+}
+/** The `mcp` sessions over stdin and stdout that an agent app started: only the app can restart them. */
+export interface StaleSessions {
+    checked: boolean;
+    /** `version` is `null`: a process does not say which code it loaded. */
+    sessions: {
+        pid: number;
+        version: string | null;
+    }[];
+    reason?: string;
+}
+export interface ProcessLine {
+    pid: number;
+    /** The command line, word by word; the first is the program. */
+    words: string[];
+}
+/** What the steps after an upgrade ask of the machine. Tests hand one in. */
+export interface AfterUpgradeSystem {
+    platform: NodeJS.Platform;
+    alive: (pid: number) => boolean;
+    carries: (pid: number, marker: string) => boolean;
+    stop: (pid: number) => void;
+    /** Starts `<cli> <argv>` from the installed package, apart from this process, and answers its PID. */
+    spawn: (argv: string[], env: NodeJS.ProcessEnv, log: string) => number;
+    pause: () => Promise<void>;
+    /** This user's processes; `undefined` when this system cannot list them. */
+    processes: () => ProcessLine[] | undefined;
+    /** The folder of the package this process runs from; `undefined` when it does not run from one. */
+    packageRoot: string | undefined;
+}
+/** The nearest package around `script`, when it is `packageName`: a test runner's script belongs to the runner. */
+export declare const packageRootOf: (packageName: string, script: string) => string | undefined;
+export declare const thisSystem: (packageName: string, command: string) => AfterUpgradeSystem;
+/** Restarts each running HTTP MCP server of `app` on the code just installed, as `server restart` does for serve. */
+export declare const restartMcpServers: (app: AppIdentity, env: NodeJS.ProcessEnv, system: AfterUpgradeSystem) => Promise<McpServerRestart[]>;
+/** Whether a command line runs an MCP server over stdio from the package in `root`: not `--http`, not `mcp server …`. */
+export declare const isStdioMcp: (line: string[], root: string, platform?: NodeJS.Platform) => boolean;
+export declare const staleMcpSessions: (system: AfterUpgradeSystem) => StaleSessions;

package/dist/background/after-upgrade.js

@@ -0,0 +1,245 @@
+import { execFileSync, spawn } from "node:child_process";
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, sep } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { resolvePaths } from "@wirecat/cli-base";
+import { httpLaunchFile, mcpHttpMarker, readHttpLaunch, readHttpLock } from "../mcp/http/state.js";
+import { alive, carries } from "./processes.js";
+import { readableLog, tail } from "./units.js";
+// 250 ms apart: 15 s for the old server to stop, 30 s for the new one to listen, as `mcp server start` waits.
+const STOP_LOOKS = 60;
+const START_LOOKS = 120;
+const LOCK_DEPTH = 3;
+/** The nearest package around `script`, when it is `packageName`: a test runner's script belongs to the runner. */
+export const packageRootOf = (packageName, script) => {
+    let dir = dirname(script);
+    for (let up = 0; up < 8; up++) {
+        const manifest = join(dir, "package.json");
+        if (existsSync(manifest)) {
+            try {
+                return JSON.parse(readFileSync(manifest, "utf8")).name === packageName ? dir : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+    return undefined;
+};
+/**
+ * The bin the new `package.json` names, read after the install: the new version may have moved its entry, and the
+ * old process's own path may no longer exist.
+ */
+const binOf = (root, command) => {
+    try {
+        const { bin } = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+        const path = typeof bin === "string" ? bin : bin?.[command];
+        return path && existsSync(join(root, path)) ? join(root, path) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+const words = (line) => [...line.matchAll(/"([^"]*)"|(\S+)/g)].map((match) => match[1] ?? match[2] ?? "");
+const listProcesses = (platform) => {
+    const uid = process.getuid?.();
+    try {
+        if (platform === "linux") {
+            return readdirSync("/proc").flatMap((entry) => {
+                if (!/^\d+$/.test(entry))
+                    return [];
+                try {
+                    if (statSync(`/proc/${entry}`).uid !== uid)
+                        return [];
+                    const line = readFileSync(`/proc/${entry}/cmdline`, "utf8").split("\0");
+                    if (line.at(-1) === "")
+                        line.pop();
+                    return [{ pid: Number(entry), words: line }];
+                }
+                catch {
+                    return [];
+                }
+            });
+        }
+        if (platform === "darwin") {
+            const listed = execFileSync("ps", ["-axww", "-o", "pid=,uid=,command="], { encoding: "utf8", timeout: 5000 });
+            return listed.split("\n").flatMap((line) => {
+                const match = /^\s*(\d+)\s+(\d+)\s+(.*)$/.exec(line);
+                return match && Number(match[2]) === uid ? [{ pid: Number(match[1]), words: words(match[3] ?? "") }] : [];
+            });
+        }
+        if (platform === "win32") {
+            // Without elevation Windows shows the command line of this user's processes only.
+            const listed = execFileSync("powershell.exe", [
+                "-NoProfile",
+                "-NonInteractive",
+                "-Command",
+                "Get-CimInstance Win32_Process -Filter \"Name='node.exe' OR Name='bun.exe'\" | Select-Object ProcessId,CommandLine | ConvertTo-Json -Compress",
+            ], { encoding: "utf8", timeout: 10_000, windowsHide: true }).trim();
+            if (listed === "")
+                return [];
+            const parsed = JSON.parse(listed);
+            return (Array.isArray(parsed) ? parsed : [parsed]).flatMap((one) => one.CommandLine ? [{ pid: one.ProcessId, words: words(one.CommandLine) }] : []);
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+};
+export const thisSystem = (packageName, command) => {
+    const script = process.argv[1];
+    let real;
+    try {
+        real = script ? realpathSync(script) : undefined;
+    }
+    catch { }
+    const packageRoot = real ? packageRootOf(packageName, real) : undefined;
+    return {
+        platform: process.platform,
+        alive,
+        carries,
+        stop: (pid) => process.kill(pid, "SIGTERM"),
+        spawn: (argv, env, log) => {
+            const entry = (packageRoot && binOf(packageRoot, command)) ?? real ?? "";
+            mkdirSync(dirname(log), { recursive: true, mode: 0o700 });
+            const out = openSync(log, "a", 0o600);
+            try {
+                const child = spawn(process.execPath, [entry, ...argv], { detached: true, stdio: ["ignore", out, out], env });
+                child.unref();
+                return child.pid ?? 0;
+            }
+            finally {
+                closeSync(out);
+            }
+        },
+        pause: () => sleep(250),
+        processes: () => listProcesses(process.platform),
+        packageRoot,
+    };
+};
+/** Every HTTP lock under the state folder: each CLI lays them out its own way, a few folders deep at most. */
+const httpLocks = (dir, depth = 0) => {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries.flatMap((entry) => {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory())
+            return depth < LOCK_DEPTH ? httpLocks(path, depth + 1) : [];
+        return entry.isFile() && entry.name.endsWith(".lock") && readHttpLock(path) ? [path] : [];
+    });
+};
+const errorText = (error) => error.code === "EPERM"
+    ? "not allowed to stop it"
+    : error instanceof Error
+        ? error.message
+        : String(error);
+const restartOne = async (envPrefix, lockFile, lock, env, system) => {
+    const launch = readHttpLaunch(httpLaunchFile(lockFile));
+    const name = launch?.invocation ?? lockFile;
+    const from = lock.version ?? null;
+    const left = (reason, rest = {}) => ({
+        name,
+        pid: lock.pid,
+        restarted: false,
+        from,
+        to: null,
+        reason,
+        ...rest,
+    });
+    const marker = mcpHttpMarker(envPrefix);
+    const value = launch?.env[marker];
+    // The marker proves the PID is still the server `mcp server start` launched, not a stranger who got its number.
+    if (!launch || value === undefined || !system.carries(lock.pid, `${marker}=${value}`))
+        return left("it was not started by `mcp server start` on this version, or this system cannot confirm it was — stop it and start it again");
+    try {
+        system.stop(lock.pid);
+    }
+    catch (error) {
+        return left(errorText(error));
+    }
+    for (let look = 0; look < STOP_LOOKS && system.alive(lock.pid); look++)
+        await system.pause();
+    if (system.alive(lock.pid))
+        return left(`asked it to stop, and it still ran after 15 s — \`${name} mcp server status\``);
+    const log = lockFile.replace(/\.lock$/, ".log");
+    const { [`${envPrefix}_TIMEOUT`]: _timeout, ...inherited } = env;
+    let pid;
+    try {
+        pid = system.spawn(launch.argv, { ...inherited, ...launch.env }, log);
+    }
+    catch (error) {
+        return left(`stopped it, and could not start it again: ${errorText(error)} — \`${name} mcp server start\``);
+    }
+    for (let look = 0; look < START_LOOKS; look++) {
+        const now = readHttpLock(lockFile);
+        if (now?.pid === pid && now.listeningAt)
+            return { name, pid: lock.pid, restarted: true, from, to: now.version ?? null, newPid: pid };
+        if (!system.alive(pid)) {
+            const last = readableLog(tail(log, 5)).trim();
+            return left(`stopped it, and the new one exited before it listened${last ? `: ${last}` : ""} — \`${name} mcp server start\``, { newPid: pid });
+        }
+        await system.pause();
+    }
+    return left(`started it again (PID ${pid}), and it was not listening after 30 s — \`${name} mcp server status\``, {
+        newPid: pid,
+    });
+};
+/** Restarts each running HTTP MCP server of `app` on the code just installed, as `server restart` does for serve. */
+export const restartMcpServers = async (app, env, system) => {
+    const state = resolvePaths({ appName: app.appName, prefix: app.envPrefix, env }).state;
+    const done = [];
+    for (const lockFile of httpLocks(state)) {
+        const lock = readHttpLock(lockFile);
+        if (lock && system.alive(lock.pid))
+            done.push(await restartOne(app.envPrefix, lockFile, lock, env, system));
+    }
+    return done;
+};
+// The `mcp` subcommands that are not a server; `mcp` alone was the server before `mcp serve`.
+const NOT_SERVING = new Set(["server", "config", "add", "check", "revoke"]);
+/** Whether a command line runs an MCP server over stdio from the package in `root`: not `--http`, not `mcp server …`. */
+export const isStdioMcp = (line, root, platform = process.platform) => {
+    const at = line.findIndex((word, index) => index > 0 && !word.startsWith("-"));
+    const script = line[at];
+    if (at < 0 || script === undefined || !isAbsolute(script))
+        return false;
+    let path = script;
+    try {
+        path = realpathSync(script);
+    }
+    catch { }
+    const fold = (text) => (platform === "win32" ? text.toLowerCase() : text);
+    if (!fold(path).startsWith(fold(root + sep)) && !fold(script).startsWith(fold(root + sep)))
+        return false;
+    const rest = line.slice(at + 1);
+    if (rest.includes("--http"))
+        return false;
+    const plain = rest.filter((word) => !word.startsWith("-"));
+    const mcp = plain.indexOf("mcp");
+    const leads = plain.slice(0, Math.max(mcp, 0)).filter((word) => word !== "bot");
+    return mcp >= 0 && leads.length <= 1 && !NOT_SERVING.has(plain[mcp + 1] ?? "");
+};
+export const staleMcpSessions = (system) => {
+    const root = system.packageRoot;
+    if (root === undefined)
+        return { checked: false, sessions: [], reason: "this process does not run from an installed package" };
+    const lines = system.processes();
+    if (lines === undefined)
+        return { checked: false, sessions: [], reason: `could not list the processes on ${system.platform}` };
+    return {
+        checked: true,
+        sessions: lines
+            .filter((line) => line.pid !== process.pid && isStdioMcp(line.words, root, system.platform))
+            .map((line) => ({ pid: line.pid, version: null })),
+    };
+};

package/dist/background/budget.d.ts

@@ -0,0 +1,37 @@
+/** Why a budgeted run stopped asking: its request count is spent, its deadline is close, or it was cancelled. */
+export type BudgetStop = "requests" | "deadline" | "cancelled";
+/** The command's hard limit as `run()` started it: when it ends, and how long it was. */
+export interface Deadline {
+    endsAt: number;
+    ms: number;
+}
+/**
+ * A sync asks it before each request to the source, so the run stops on its own, saves where it is, and says
+ * "run again to continue" instead of being cut by its deadline.
+ */
+export interface RunBudget {
+    /** One more request: `null` when it may go, otherwise why not. Once it says no it keeps saying no. */
+    take(): BudgetStop | null;
+    readonly used: number;
+    /** `null`: no request limit, only the deadline. */
+    readonly limit: number | null;
+    readonly stopped: BudgetStop | null;
+}
+export declare const DEADLINE_MARGIN_MS = 5000;
+export declare const DEADLINE_MARGIN_SHARE = 0.15;
+/** How long one request to a provider is expected to take when the CLI does not say (`AppIdentity.requestMs`). */
+export declare const DEFAULT_REQUEST_MS = 2000;
+export declare const deadlineMargin: (deadline: Deadline) => number;
+/** The requests that fit before the margin: `(deadline − margin) / requestMs`, at least one; none without a deadline. */
+export declare const requestsFor: (deadline: Deadline | undefined, requestMs?: number) => number | null;
+/**
+ * Stops at whichever comes first: the requests that fit the deadline (`requestsFor`), an explicit `requests` lower
+ * than that, the deadline's margin plus the slowest request so far, or the signal.
+ */
+export declare const runBudget: ({ requests, deadline, requestMs, signal, now, }?: {
+    requests?: number;
+    deadline?: Deadline;
+    requestMs?: number;
+    signal?: AbortSignal;
+    now?: () => number;
+}) => RunBudget;

package/dist/background/budget.js

@@ -0,0 +1,48 @@
+export const DEADLINE_MARGIN_MS = 5_000;
+export const DEADLINE_MARGIN_SHARE = 0.15;
+/** How long one request to a provider is expected to take when the CLI does not say (`AppIdentity.requestMs`). */
+export const DEFAULT_REQUEST_MS = 2_000;
+export const deadlineMargin = (deadline) => Math.max(DEADLINE_MARGIN_MS, deadline.ms * DEADLINE_MARGIN_SHARE);
+/** The requests that fit before the margin: `(deadline − margin) / requestMs`, at least one; none without a deadline. */
+export const requestsFor = (deadline, requestMs = DEFAULT_REQUEST_MS) => deadline === undefined ? null : Math.max(1, Math.floor((deadline.ms - deadlineMargin(deadline)) / requestMs));
+/**
+ * Stops at whichever comes first: the requests that fit the deadline (`requestsFor`), an explicit `requests` lower
+ * than that, the deadline's margin plus the slowest request so far, or the signal.
+ */
+export const runBudget = ({ requests, deadline, requestMs, signal, now = Date.now, } = {}) => {
+    const fits = requestsFor(deadline, requestMs);
+    const limit = fits === null ? (requests ?? null) : Math.min(fits, requests ?? fits);
+    const margin = deadline ? deadlineMargin(deadline) : 0;
+    let used = 0;
+    let stopped = null;
+    let last;
+    // A request may page inside the source, so the gap between two asks is the honest measure of one.
+    let slowest = 0;
+    return {
+        take() {
+            if (stopped)
+                return stopped;
+            const at = now();
+            if (last !== undefined)
+                slowest = Math.max(slowest, at - last);
+            if (signal?.aborted)
+                stopped = "cancelled";
+            else if (limit !== null && used >= limit)
+                stopped = "requests";
+            else if (deadline && at + margin + slowest >= deadline.endsAt)
+                stopped = "deadline";
+            if (stopped)
+                return stopped;
+            used += 1;
+            last = at;
+            return null;
+        },
+        get used() {
+            return used;
+        },
+        limit,
+        get stopped() {
+            return stopped;
+        },
+    };
+};

package/dist/background/index.d.ts

@@ -1,3 +1,4 @@
+export { type BudgetStop, DEADLINE_MARGIN_MS, DEADLINE_MARGIN_SHARE, DEFAULT_REQUEST_MS, type Deadline, deadlineMargin, type RunBudget, requestsFor, runBudget, } from "./budget.js";
 export { type Checkpoint, checkpointPath, clearCheckpoint, type Progress, progressLine, progressOf, readCheckpoint, saveCheckpoint, } from "./checkpoints.js";
 export type { DailyArchiveTimer, DailyArchiveTimerInput } from "./daily-archive-timer.js";
 export { dailyArchiveTimer, manageDailyArchiveTimer } from "./daily-archive-timer.js";

package/dist/background/index.js

@@ -1,3 +1,4 @@
+export { DEADLINE_MARGIN_MS, DEADLINE_MARGIN_SHARE, DEFAULT_REQUEST_MS, deadlineMargin, requestsFor, runBudget, } from "./budget.js";
 export { checkpointPath, clearCheckpoint, progressLine, progressOf, readCheckpoint, saveCheckpoint, } from "./checkpoints.js";
 export { dailyArchiveTimer, manageDailyArchiveTimer } from "./daily-archive-timer.js";
 export { holdLock, lockPath, readLock, releaseLock, servingProfiles, takeLock } from "./lock.js";

package/dist/calendar/busy.d.ts

@@ -0,0 +1,68 @@
+import type { EventStore, StoredCalendar } from "../meetings/index.js";
+import type { CalendarSource, SyncWindow } from "./source.js";
+export declare const BUSY_QUERY_HELP = "\nWords, any order:\n  today | week            today, or today and the next six days, in your time zone\n  from:<date> to:<date>   from the start of one day through the end of another (or a time with a zone)\n  calendar:<id>           one of the account's calendars, by its id or the provider's id; repeat for more\n  person:<email>          someone else, by email address; repeat for more\nWithout a time word: this week. Without calendar:, every calendar that syncs.";
+export interface BusyQuery {
+    window: SyncWindow;
+    calendars: StoredCalendar[];
+    people: string[];
+}
+export declare const busyQuery: (words: readonly string[], context: {
+    store: EventStore;
+    accountId: number;
+    zone: string;
+    now: number;
+}) => Promise<BusyQuery>;
+export interface WorkingHours {
+    /** Minutes after local midnight. */
+    start: number;
+    end: number;
+}
+export declare const workingHoursOf: (text: string) => WorkingHours;
+/**
+ * The stretches of at least `minutes` inside working hours on weekdays, after `now`, that no busy time touches.
+ * A stretch is returned whole; the caller picks where in it to put the meeting.
+ */
+export declare const freeSlots: (busy: readonly SyncWindow[], window: SyncWindow, options: {
+    minutes: number;
+    hours: WorkingHours;
+    zone: string;
+    now: number;
+}) => SyncWindow[];
+/**
+ * `calendars busy`: the provider's busy times for the query, and with `slot` the free stretches every calendar and
+ * person shares. Nothing is stored, and a person appears only by the address the caller gave.
+ */
+export declare const busyAnswer: (source: CalendarSource, query: BusyQuery, options: {
+    zone: string;
+    now: number;
+    slot?: {
+        minutes: number;
+        hours: WorkingHours;
+    };
+}) => Promise<{
+    start: string;
+    end: string;
+    timezone: string;
+    calendars: ({
+        id: string;
+        calendar: string;
+        busy: {
+            start: string;
+            end: string;
+        }[];
+        error?: string | undefined;
+    } | {
+        id: string;
+        person: string;
+        busy: {
+            start: string;
+            end: string;
+        }[];
+        error?: string | undefined;
+    })[];
+    slots?: {
+        start: string;
+        end: string;
+    }[] | undefined;
+    unknown?: string[] | undefined;
+}>;