@wirecat/cli-core 0.412.0 → 0.413.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ Notable changes to `@wirecat/cli-core` (`@wirecat/cli-messaging` up to 0.261.0,
 minor version may break callers, and says how under "Changed — may break callers". `pnpm docs:check` checks the
 shape of this file.
 
+## Unreleased
+
+## 0.413.0 — 25.10.2026
+
+### Added
+
+- **`startCli`, one entry-point call for a CLI that builds its own program** (from `@wirecat/cli-core/cli`). It does what drive, zm and memo wire by hand in `src/bin/`: the crash catch, cancellation on SIGINT and SIGTERM, a quiet exit 0 on a closed pipe, the SQLite swap, the first-run questions (`entry.atStart`), the consent prompt (`entry.ask`) and the browser (`entry.openBrowser`). The program and its failure report stay the CLI's own. Nothing changes for a CLI that keeps its own wiring.
+- **Sign-in module `@wirecat/cli-core/oauth`** (available from cli-core 0.413.0). A CLI declares its provider (URLs, client, loopback or relay redirect) and gets authorization code with PKCE S256 (state check, timeout, cancel, paste fallback), refresh and revoke over plain `fetch`, and a `tokenKeeper` whose refresh takes a lock per keyring entry shared by every process, so two processes refreshing at once send one request. `credentialStorage` sits on cli-base's `Credentials`; `standardCodec` writes new entries as `oauth:<provider>:<profile>`, and `driveSessionCodec` and `zoomTokenCodec` read and write drive's and zm's existing entries unchanged, so nobody signs in again.
+- **`gatherProjectEvidence` caps each linked chat per invocation.** A linked chat returns at most `max(20, floor(maxItems / (linked chats read + 1)))` new items per run (50 for one chat at the default 100 items, 20 from four chats up); the rest stays in the checkpoint for the next `--cursor` run, which gives it a fresh share. Every linked chat still gets its first page before any chat gets a second. Each `linkedChats` entry now has `items` (new items it returned in this run) and `capped` (it hit the limit and has more to read). Before, one busy chat could fill the whole run. Checkpoints stay version 1, and old ones still resume.
+
+### Fixed
+
+- **A file lock no longer fails with "no such file" when another writer releases at the same moment** (available from cli-core 0.413.0). The releaser removes the empty marker folder; an acquirer that had just created it now creates it again instead of throwing `ENOENT`. `acquireLock`, the archive writer lease and the sign-in module's refresh lock all use it.
+- **The 0.412.0 notes for the provider registry, unknown providers and the `events` kind say "available from cli-core 0.413.0"; they shipped in 0.412.0.** The release folded them in from `main`'s head. Nothing else in those entries changes.
 
 ## 0.412.0 — 24.10.2026
 

package/dist/cli/entry.d.ts

@@ -0,0 +1,59 @@
+import { type ChildProcess, type SpawnOptions } from "node:child_process";
+import type { ErrorReason } from "@wirecat/cli-base/standards";
+import type { Command } from "commander";
+import { type AppIdentity } from "../ports/app.js";
+/** What `startCli` hands the CLI's own program: the process, wired once. */
+export interface EntryContext {
+    /** `process.argv` without the runtime and the script. */
+    args: string[];
+    env: NodeJS.ProcessEnv;
+    /** Whether stdout is a terminal. */
+    tty: boolean;
+    /** Aborted on SIGINT, SIGTERM and a closed or failing stdout. */
+    signal: AbortSignal;
+    /** The first-run questions, before the command acts: call it from a `preAction` hook with the action command. */
+    atStart: (command: Command) => Promise<void>;
+    /** A yes/no question on stderr; false without asking when there is no terminal, under CI, `--json`, `--jsonl` or `--no-input`. */
+    ask: (question: string, command?: Command) => Promise<boolean>;
+    /** Opens the URL in the system browser, or in `browser` when given; never waits for the browser to close. */
+    openBrowser: (url: string, browser?: string) => Promise<void>;
+    /** True once a reader closed the output (`| head`): nothing more reaches the terminal. */
+    outputClosed: () => boolean;
+}
+/** The parts of the process `startCli` touches, replaced in tests. */
+export interface EntryIo {
+    argv: readonly string[];
+    env: NodeJS.ProcessEnv;
+    platform: NodeJS.Platform;
+    stdin: NodeJS.ReadableStream & {
+        isTTY?: boolean;
+    };
+    stdout: NodeJS.WritableStream & {
+        isTTY?: boolean;
+    };
+    stderr: NodeJS.WritableStream & {
+        isTTY?: boolean;
+    };
+    signals: Pick<NodeJS.Process, "on" | "off">;
+    setExitCode: (code: number) => void;
+    spawn: (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
+}
+export interface CliEntry {
+    app: AppIdentity;
+    /** Builds and runs the CLI's program; a returned number is the exit code, nothing keeps the one already set. */
+    run: (entry: EntryContext) => Promise<number | undefined>;
+    /** Says a failure the program threw, once, and gives its exit code. */
+    fail: (error: unknown, entry: EntryContext) => number;
+    /** Whether a crash may print the human form; stdout being a terminal when left out. */
+    interactive?: (args: readonly string[], tty: boolean) => boolean;
+    reasons?: readonly ErrorReason[];
+    /** Swap a system SQLite that cannot hold the store before anything runs (`ensureSqlite`). */
+    sqlite?: boolean;
+    io?: Partial<EntryIo>;
+}
+/**
+ * The entry point of a CLI that builds its own commander program: crash catch, cancellation, a quiet end on a closed
+ * pipe, the first-run questions, the consent prompt and the browser. It sets `process.exitCode` and never exits, so
+ * output still flushes.
+ */
+export declare const startCli: (entry: CliEntry) => Promise<void>;

package/dist/cli/entry.js

@@ -0,0 +1,136 @@
+import { spawn } from "node:child_process";
+import { CliError, catchCrashes } from "@wirecat/cli-base";
+import { readOnlyLockOf } from "../ports/app.js";
+import { ensureSqlite } from "../sqlite-runtime.js";
+import { readSecret } from "../terminal/prompt.js";
+import { commandPathOf } from "./command-contract.js";
+import { setupAtStart } from "./first-run.js";
+const processIo = () => ({
+    argv: process.argv,
+    env: process.env,
+    platform: process.platform,
+    stdin: process.stdin,
+    stdout: process.stdout,
+    stderr: process.stderr,
+    signals: process,
+    setExitCode: (code) => {
+        process.exitCode = code;
+    },
+    spawn,
+});
+/**
+ * The entry point of a CLI that builds its own commander program: crash catch, cancellation, a quiet end on a closed
+ * pipe, the first-run questions, the consent prompt and the browser. It sets `process.exitCode` and never exits, so
+ * output still flushes.
+ */
+export const startCli = async (entry) => {
+    const io = { ...processIo(), ...entry.io };
+    const args = io.argv.slice(2);
+    const tty = io.stdout.isTTY === true;
+    const release = catchCrashes({
+        cli: entry.app.command,
+        interactive: entry.interactive?.(args, tty) ?? tty,
+        ...(entry.reasons ? { reasons: entry.reasons } : {}),
+        target: io.signals,
+    });
+    const controller = new AbortController();
+    let closed = false;
+    let unwritable = false;
+    const interrupted = (signal) => () => controller.abort(new CliError("cancelled", `command interrupted by ${signal}`, { reason: signal, retryable: false }));
+    const sigint = interrupted("SIGINT");
+    const sigterm = interrupted("SIGTERM");
+    const outputFailed = (error) => {
+        if (error.code === "EPIPE") {
+            closed = true;
+            controller.abort(new CliError("cancelled", "output pipe closed", { retryable: false }));
+        }
+        else {
+            unwritable = true;
+            controller.abort(new CliError("configuration_error", "could not write command output"));
+        }
+    };
+    const headless = (command) => {
+        const flags = command?.optsWithGlobals() ?? {};
+        return Boolean(flags.json || flags.jsonl || flags.input === false || io.env.CI) || !tty;
+    };
+    const context = {
+        args,
+        env: io.env,
+        tty,
+        signal: controller.signal,
+        atStart: (command) => setupAtStart({
+            command: entry.app.command,
+            env: io.env,
+            path: commandPathOf(command),
+            headless: headless(command),
+            readOnlyLock: readOnlyLockOf(entry.app, io.env),
+            input: io.stdin,
+        }),
+        ask: async (question, command) => {
+            if (headless(command) || io.stdin.isTTY !== true)
+                return false;
+            const answer = await readSecret(`${question} [y/N] `, {
+                input: io.stdin,
+                output: io.stderr,
+                echo: true,
+                signal: controller.signal,
+            });
+            return /^(y|yes)$/i.test(answer.trim());
+        },
+        openBrowser: (url, browser) => openBrowser(io, url, browser),
+        outputClosed: () => closed,
+    };
+    let code;
+    try {
+        if (entry.sqlite)
+            await ensureSqlite();
+        io.signals.on("SIGINT", sigint).on("SIGTERM", sigterm);
+        io.stdout.on("error", outputFailed);
+        io.stderr.on("error", outputFailed);
+        const returned = await entry.run(context);
+        if (typeof returned === "number")
+            code = returned;
+    }
+    catch (error) {
+        code = commanderExit(error) ?? entry.fail(error, context);
+    }
+    finally {
+        io.signals.off("SIGINT", sigint).off("SIGTERM", sigterm);
+        release();
+    }
+    // The listeners stay: output still flushing after the command can meet the closed pipe too.
+    if (closed)
+        io.setExitCode(0);
+    else if (unwritable)
+        io.setExitCode(3);
+    else if (code !== undefined)
+        io.setExitCode(code);
+};
+/** Help and the version were printed already; help for a missing command is a usage mistake, as in `run()`. */
+const commanderExit = (error) => {
+    if (!(error instanceof Error))
+        return undefined;
+    const { code, exitCode } = error;
+    if (typeof code !== "string" || !code.startsWith("commander.") || typeof exitCode !== "number")
+        return undefined;
+    if (exitCode === 0)
+        return 0;
+    return code === "commander.help" ? 2 : undefined;
+};
+const openBrowser = (io, url, browser) => {
+    const [command, prefix] = browser !== undefined
+        ? [browser, []]
+        : io.platform === "darwin"
+            ? ["open", []]
+            : io.platform === "win32"
+                ? ["rundll32.exe", ["url.dll,FileProtocolHandler"]]
+                : ["xdg-open", []];
+    return new Promise((resolve, reject) => {
+        const child = io.spawn(command, [...prefix, url], { detached: true, stdio: "ignore", windowsHide: true });
+        child.once("error", () => reject(new CliError("configuration_error", `could not start ${command} — open the printed URL in a browser`)));
+        child.once("spawn", () => {
+            child.unref();
+            resolve();
+        });
+    });
+};

package/dist/cli/first-run.d.ts

@@ -53,7 +53,7 @@ export declare const askSetupQuestions: (run: FirstRun) => Promise<Question[]>;
 /**
  * The first-run step a tool runs before each command: asks when `asksAtStart` says so, and lets the command run
  * whatever happens to the questions. `setup` asks all three again, since a refusal sends the owner there.
- * A tool that builds its own program (zm, memo, drive) calls this with its command path.
+ * A tool that builds its own program gets it from `startCli` as `entry.atStart`.
  */
 export declare const setupAtStart: (start: {
     command: string;

package/dist/cli/first-run.js

@@ -203,7 +203,7 @@ export const askSetupQuestions = async (run) => {
 /**
  * The first-run step a tool runs before each command: asks when `asksAtStart` says so, and lets the command run
  * whatever happens to the questions. `setup` asks all three again, since a refusal sends the owner there.
- * A tool that builds its own program (zm, memo, drive) calls this with its command path.
+ * A tool that builds its own program gets it from `startCli` as `entry.atStart`.
  */
 export const setupAtStart = async (start) => {
     const input = start.input ?? process.stdin;

package/dist/cli/index.d.ts

@@ -59,6 +59,7 @@ export { type Closeable, withDeadline } from "./deadline.js";
 export { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 export { DISCOVERY_DESCRIPTIONS } from "./discovery-descriptions.js";
 export { changesAuthority, changesAuthorityAt, changesAuthorityNow, destroysNothing, FETCH, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, REMOTE_READ, REMOTE_WRITE, reachesOtherService, refuseUnderReadOnly, } from "./effects.js";
+export { type CliEntry, type EntryContext, type EntryIo, startCli } from "./entry.js";
 export { type AnswerOutput, answerSchema, type Body, type ItemBody, isBody, itemAnswer, itemOf, jsonlRecords, judgedAnswer, type ListBody, type ListInput, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
 export { askSetupQuestions, asksAtStart, type FirstRun, type FirstRunIo, LANGUAGES, setupAtStart, systemLanguage, } from "./first-run.js";

package/dist/cli/index.js

@@ -52,6 +52,7 @@ export { withDeadline } from "./deadline.js";
 export { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 export { DISCOVERY_DESCRIPTIONS } from "./discovery-descriptions.js";
 export { changesAuthority, changesAuthorityAt, changesAuthorityNow, destroysNothing, FETCH, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, REMOTE_READ, REMOTE_WRITE, reachesOtherService, refuseUnderReadOnly, } from "./effects.js";
+export { startCli } from "./entry.js";
 export { answerSchema, isBody, itemAnswer, itemOf, jsonlRecords, judgedAnswer, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
 export { askSetupQuestions, asksAtStart, LANGUAGES, setupAtStart, systemLanguage, } from "./first-run.js";

package/dist/errors/reasons.js

@@ -15,6 +15,21 @@ const QUERY = [
     ["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 SIGN_IN = [
+    ["oauth.declined", "authentication_error", "the provider's consent was declined"],
+    ["oauth.timeout", "timeout", "the sign-in was not finished in time"],
+    ["oauth.mismatch", "authentication_error", "the pasted sign-in result belongs to another sign-in"],
+    ["oauth.missing", "authentication_error", "this profile is not signed in"],
+    ["oauth.locked", "provider_unavailable", "another process holds this sign-in's lock"],
+    ["oauth.no-response", "outcome_unknown", "the token request did not finish"],
+    ["oauth.unavailable", "provider_unavailable", "the provider's token endpoint is unavailable"],
+    ["oauth.expired", "authentication_error", "the provider refused the saved sign-in; sign in again"],
+    ["oauth.invalid-response", "invalid_response", "the provider's token response could not be used"],
+    ["oauth.failed", "authentication_error", "the provider returned no offline refresh token"],
+    ["oauth.revoke-failed", "outcome_unknown", "the provider did not confirm the revoke"],
+    ["oauth.invalid", "authentication_error", "the saved sign-in cannot be read"],
+    ["oauth.not-saved", "configuration_error", "the sign-in cannot be saved or read where it is kept"],
+];
 const OTHERS = [
     ["model.offline", "permission_error", "downloading a model needs the network; --offline was requested"],
     [
@@ -105,7 +120,7 @@ export const INPUT_FIELD_REASONS = defineReasons([
 export const REASONS = defineReasons([
     ...QUERY_REASONS,
     ...INPUT_FIELD_REASONS,
-    ...[...QUERY, ...OTHERS].map(([reason, code, message]) => ({
+    ...[...QUERY, ...SIGN_IN, ...OTHERS].map(([reason, code, message]) => ({
         reason,
         code,
         message,

package/dist/files/native-writer-lease.js

@@ -22,15 +22,26 @@ export const nativeWriterLeaseStore = (layout) => {
             const root = await realpath(destination);
             signal?.throwIfAborted();
             const folder = join(root, markerDirectory);
-            await mkdir(folder, { recursive: true });
-            if ((await lstat(folder)).isSymbolicLink())
-                throw new CliError("validation_error", "archive lock directory must not be a symlink");
-            await inspection.recover(root, { apply: true, signal });
-            signal?.throwIfAborted();
             const owner = { version: 1, pid: process.pid, host: hostname(), nonce: randomUUID() };
             const name = `${owner.pid}-${owner.nonce}.json`;
             const path = join(folder, name);
-            const file = await open(path, "wx", 0o600);
+            // Another writer removes the folder once it is empty, so it can vanish before our marker is in it.
+            const marker = async (attempt = 1) => {
+                await mkdir(folder, { recursive: true });
+                try {
+                    if ((await lstat(folder)).isSymbolicLink())
+                        throw new CliError("validation_error", "archive lock directory must not be a symlink");
+                    await inspection.recover(root, { apply: true, signal });
+                    signal?.throwIfAborted();
+                    return await open(path, "wx", 0o600);
+                }
+                catch (error) {
+                    if (attempt < 5 && missingLeaseFile(error))
+                        return marker(attempt + 1);
+                    throw error;
+                }
+            };
+            const file = await marker();
             let retained = false;
             let identity;
             try {

package/dist/oauth/authorize.d.ts

@@ -0,0 +1,21 @@
+import type { OAuthProvider } from "./provider.js";
+export interface AuthorizeOptions {
+    provider: OAuthProvider;
+    scopes: readonly string[];
+    openBrowser: (url: string) => Promise<void>;
+    showUrl?: (url: string) => void;
+    /** The redirected URL, or its query, pasted when the browser cannot reach this machine's loopback. */
+    readPaste?: (signal: AbortSignal) => Promise<string>;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface Authorization {
+    code: string;
+    redirectUri: string;
+    codeVerifier: string;
+}
+/**
+ * Authorization code with PKCE S256 for an installed app: a loopback listener on 127.0.0.1, a `state` check, a
+ * timeout, cancel and a paste fallback. Answers the code without exchanging it.
+ */
+export declare const authorize: (options: AuthorizeOptions) => Promise<Authorization>;

package/dist/oauth/authorize.js

@@ -0,0 +1,130 @@
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { CliError, isCliError } from "@wirecat/cli-base";
+const DEFAULT_TIMEOUT_MS = 300_000;
+const pkce = () => {
+    const codeVerifier = randomBytes(48).toString("base64url");
+    return { codeVerifier, codeChallenge: createHash("sha256").update(codeVerifier).digest("base64url") };
+};
+const queryOf = (text) => {
+    const trimmed = text.trim();
+    const start = trimmed.indexOf("?");
+    return new URLSearchParams(start >= 0 ? trimmed.slice(start + 1).split("#")[0] : trimmed);
+};
+/**
+ * Authorization code with PKCE S256 for an installed app: a loopback listener on 127.0.0.1, a `state` check, a
+ * timeout, cancel and a paste fallback. Answers the code without exchanging it.
+ */
+export const authorize = async (options) => {
+    const { provider } = options;
+    const cancelled = () => isCliError(options.signal?.reason)
+        ? options.signal.reason
+        : new CliError("cancelled", `${provider.name} sign-in was cancelled`);
+    if (options.signal?.aborted)
+        throw cancelled();
+    const { codeVerifier, codeChallenge } = pkce();
+    const paste = new AbortController();
+    let state = "";
+    let settled = false;
+    let accept = () => { };
+    let fail = () => { };
+    const code = new Promise((resolve, reject) => {
+        accept = (value) => {
+            settled = true;
+            resolve(value);
+        };
+        fail = (error) => {
+            settled = true;
+            reject(error);
+        };
+    });
+    void code.catch(() => { });
+    const settle = (query) => {
+        const value = query.get("code");
+        if (value)
+            accept(value);
+        else
+            fail(new CliError("authentication_error", `${provider.name} sign-in was declined`, { reason: "oauth.declined" }));
+    };
+    const server = createServer((request, response) => {
+        let url;
+        try {
+            url = new URL(request.url ?? "/", "http://127.0.0.1");
+        }
+        catch {
+            response.writeHead(400).end();
+            return;
+        }
+        if (request.method !== "GET" || url.pathname !== "/callback") {
+            response.writeHead(404).end();
+            return;
+        }
+        if (settled || !state || url.searchParams.get("state") !== state) {
+            response.writeHead(400).end("This sign-in link does not belong to the waiting sign-in");
+            return;
+        }
+        if (!url.searchParams.get("code") && !url.searchParams.get("error")) {
+            response.writeHead(400).end("Missing sign-in result");
+            return;
+        }
+        response.end("Sign-in received; you can close this tab");
+        settle(url.searchParams);
+    });
+    const onAbort = () => fail(cancelled());
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    const timer = setTimeout(() => fail(new CliError("timeout", `${provider.name} sign-in timed out`, { reason: "oauth.timeout" })), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    try {
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(0, "127.0.0.1", resolve);
+        });
+        const address = server.address();
+        if (!address || typeof address === "string")
+            throw new CliError("configuration_error", "could not start the local sign-in listener");
+        const random = randomBytes(32).toString("base64url");
+        const relay = provider.redirect.kind === "relay";
+        state = relay ? `${address.port}.${random}` : random;
+        const redirectUri = provider.redirect.kind === "relay" ? provider.redirect.url : `http://127.0.0.1:${address.port}/callback`;
+        const url = new URL(provider.authorizeUrl);
+        for (const [key, value] of Object.entries({
+            ...provider.authorizeParams,
+            response_type: "code",
+            client_id: provider.client.clientId,
+            redirect_uri: redirectUri,
+            ...(options.scopes.length ? { scope: options.scopes.join(" ") } : {}),
+            state,
+            code_challenge: codeChallenge,
+            code_challenge_method: "S256",
+        }))
+            url.searchParams.set(key, value);
+        options.showUrl?.(url.toString());
+        options
+            .readPaste?.(paste.signal)
+            .then((text) => {
+            if (settled)
+                return;
+            const query = queryOf(text);
+            if (query.get("state") !== state || (!query.get("code") && !query.get("error")))
+                fail(new CliError("authentication_error", "the pasted sign-in result does not match this sign-in", {
+                    reason: "oauth.mismatch",
+                }));
+            else
+                settle(query);
+        })
+            .catch(() => { });
+        void Promise.resolve()
+            .then(() => options.openBrowser(url.toString()))
+            .catch(() => {
+            if (!options.readPaste && !options.showUrl)
+                fail(new CliError("configuration_error", "could not open the browser, and no sign-in link can be shown"));
+        });
+        return { code: await code, redirectUri, codeVerifier };
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", onAbort);
+        paste.abort();
+        server.closeAllConnections();
+        await new Promise((resolve) => server.close(() => resolve()));
+    }
+};

package/dist/oauth/index.d.ts

@@ -0,0 +1,5 @@
+export { type Authorization, type AuthorizeOptions, authorize } from "./authorize.js";
+export { type SignInOptions, type TokenKeeper, type TokenKeeperOptions, tokenKeeper } from "./keeper.js";
+export type { ExchangeContext, OAuthClient, OAuthProvider, RequestContext, TokenSet } from "./provider.js";
+export { requestTokens, revokeToken, TOKEN_LOG_ALLOW, TOKEN_LOG_EVENT } from "./requests.js";
+export { type CredentialStorageOptions, credentialStorage, driveSessionCodec, type EncodeInput, oauthAccount, type StoredTokens, standardCodec, type TokenCodec, type TokenStorage, zoomTokenCodec, } from "./storage.js";

package/dist/oauth/index.js

@@ -0,0 +1,4 @@
+export { authorize } from "./authorize.js";
+export { tokenKeeper } from "./keeper.js";
+export { requestTokens, revokeToken, TOKEN_LOG_ALLOW, TOKEN_LOG_EVENT } from "./requests.js";
+export { credentialStorage, driveSessionCodec, oauthAccount, standardCodec, zoomTokenCodec, } from "./storage.js";

package/dist/oauth/keeper.d.ts

@@ -0,0 +1,41 @@
+import { type CredentialSource, type Logger } from "@wirecat/cli-base";
+import { type AuthorizeOptions } from "./authorize.js";
+import type { OAuthProvider, TokenSet } from "./provider.js";
+import type { TokenStorage } from "./storage.js";
+export interface TokenKeeperOptions {
+    provider: OAuthProvider;
+    storage: TokenStorage;
+    /** The CLI's config directory: the keyring entry varies with it, so the lock must too. */
+    lockDir: string;
+    fetch: typeof fetch;
+    /** `drive personal session start`: named in every failure that needs a new sign-in. */
+    signInCommand: string;
+    now?: () => number;
+    signal?: AbortSignal;
+    log?: Logger;
+    /** Longer than one token request's 30 s limit, so a live refresher finishes first. Real time, not `now`. */
+    lockWaitMs?: number;
+    lockRetryMs?: number;
+    /** An access token expiring later than this from now is used as is. */
+    freshForMs?: number;
+}
+export type SignInOptions = Omit<AuthorizeOptions, "provider" | "signal"> & {
+    /** Runs before anything is saved; it may refuse the account or add fields to the entry (drive's `principal`). */
+    accept?: (tokens: TokenSet) => Promise<Record<string, unknown> | undefined> | Record<string, unknown> | undefined;
+};
+export interface TokenKeeper {
+    accessToken(): Promise<string>;
+    tokens(): Promise<TokenSet>;
+    signIn(options: SignInOptions): Promise<{
+        scopes: string[];
+    }>;
+    /** Saves tokens a CLI got by a flow of its own, under the same lock. */
+    save(tokens: TokenSet, extra?: Record<string, unknown>): Promise<void>;
+    signOut(options?: {
+        revoke?: boolean;
+    }): Promise<{
+        revoked: boolean;
+        removed: CredentialSource[];
+    }>;
+}
+export declare const tokenKeeper: (options: TokenKeeperOptions) => TokenKeeper;

package/dist/oauth/keeper.js

@@ -0,0 +1,136 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { CliError, isCliError } from "@wirecat/cli-base";
+import { acquireLock } from "../files/index.js";
+import { authorize } from "./authorize.js";
+import { requestTokens, revokeToken, TOKEN_LOG_EVENT } from "./requests.js";
+const inFlight = new Map();
+export const tokenKeeper = (options) => {
+    const { provider, storage, signal, log } = options;
+    const now = options.now ?? Date.now;
+    const fresh = (tokens) => Boolean(tokens.accessToken) &&
+        tokens.expiresAt !== undefined &&
+        tokens.expiresAt > now() + (options.freshForMs ?? 60_000);
+    const lockPath = join(options.lockDir, `oauth-${createHash("sha256").update(storage.key).digest("hex").slice(0, 16)}.lock`);
+    const clientOf = (stored) => {
+        const saved = stored?.client;
+        if (!saved || saved.clientSecret || saved.clientId !== provider.client.clientId)
+            return saved ?? provider.client;
+        return provider.client;
+    };
+    const context = (client, previous) => ({
+        fetch: options.fetch,
+        client,
+        now,
+        signInCommand: options.signInCommand,
+        ...(signal ? { signal } : {}),
+        ...(log ? { log } : {}),
+        ...(previous ? { previous } : {}),
+    });
+    const exchange = (params, ctx) => provider.exchange ? provider.exchange(params, ctx) : requestTokens(provider, params, ctx);
+    const notSignedIn = () => new CliError("authentication_error", `not signed in to ${provider.name}; run ${options.signInCommand}`, {
+        reason: "oauth.missing",
+    });
+    const busy = (error) => isCliError(error) && error.details.reason === "file.locked";
+    const acquire = async () => {
+        const started = performance.now();
+        let waiting = false;
+        for (;;) {
+            try {
+                return await acquireLock(lockPath, signal ? { signal } : {});
+            }
+            catch (error) {
+                if (!busy(error))
+                    throw error;
+                if (!waiting) {
+                    waiting = true;
+                    log?.info({
+                        event: TOKEN_LOG_EVENT,
+                        provider: provider.id,
+                        operation: "lock",
+                        outcome: "waiting",
+                        pid: process.pid,
+                    });
+                }
+                if (performance.now() - started > (options.lockWaitMs ?? 45_000))
+                    throw new CliError("provider_unavailable", `another process holds this ${provider.name} sign-in; retry`, {
+                        reason: "oauth.locked",
+                        retryable: true,
+                    });
+                await delay(options.lockRetryMs ?? 50, undefined, signal ? { signal } : {}).catch(() => {
+                    throw new CliError("cancelled", `${provider.name} sign-in was cancelled`);
+                });
+            }
+        }
+    };
+    const locked = async (work) => {
+        const lock = await acquire();
+        try {
+            return await work();
+        }
+        finally {
+            await lock.release().catch(() => { });
+        }
+    };
+    const shared = (work) => {
+        const running = inFlight.get(lockPath);
+        if (running)
+            return running;
+        const started = locked(work).finally(() => inFlight.delete(lockPath));
+        inFlight.set(lockPath, started);
+        return started;
+    };
+    const tokens = async () => {
+        const seen = storage.read();
+        if (!seen)
+            throw notSignedIn();
+        if (fresh(seen.tokens))
+            return seen.tokens;
+        return shared(async () => {
+            const current = storage.read();
+            if (!current)
+                throw notSignedIn();
+            // Another process refreshed while this one waited for the lock: its result is the one to use.
+            if (fresh(current.tokens) || current.tokens.refreshToken !== seen.tokens.refreshToken)
+                return current.tokens;
+            const client = clientOf(current);
+            const refreshed = await exchange({ grant_type: "refresh_token", refresh_token: current.tokens.refreshToken }, context(client, current.tokens));
+            storage.write({ tokens: refreshed, client });
+            return refreshed;
+        });
+    };
+    return {
+        tokens,
+        accessToken: async () => {
+            const current = await tokens();
+            if (!current.accessToken)
+                throw notSignedIn();
+            return current.accessToken;
+        },
+        signIn: async ({ accept, ...authorizeOptions }) => {
+            storage.probe();
+            const authorization = await authorize({ ...authorizeOptions, provider, ...(signal ? { signal } : {}) });
+            const client = provider.client;
+            const received = await exchange({
+                grant_type: "authorization_code",
+                code: authorization.code,
+                redirect_uri: authorization.redirectUri,
+                code_verifier: authorization.codeVerifier,
+            }, context(client));
+            const extra = (await accept?.(received)) ?? undefined;
+            await locked(async () => storage.write({ tokens: received, client, ...(extra ? { extra } : {}) }));
+            return { scopes: received.scopes };
+        },
+        save: (saved, extra) => locked(async () => storage.write({ tokens: saved, client: clientOf(storage.read()), ...(extra ? { extra } : {}) })),
+        signOut: ({ revoke = false } = {}) => locked(async () => {
+            const current = storage.read();
+            let revoked = false;
+            if (revoke && current) {
+                await revokeToken(provider, current.tokens, context(clientOf(current)));
+                revoked = true;
+            }
+            return { revoked, removed: storage.remove() };
+        }),
+    };
+};

package/dist/oauth/provider.d.ts

@@ -0,0 +1,54 @@
+import type { Logger } from "@wirecat/cli-base";
+/** The app identity a provider issued; an installed app's secret is public, not account access. */
+export interface OAuthClient {
+    clientId: string;
+    clientSecret?: string;
+}
+export interface TokenSet {
+    accessToken?: string;
+    refreshToken: string;
+    /** UTC milliseconds; unknown means "refresh before use". */
+    expiresAt?: number;
+    scopes: string[];
+    tokenType?: string;
+}
+export interface RequestContext {
+    fetch: typeof fetch;
+    client: OAuthClient;
+    now: () => number;
+    signal?: AbortSignal;
+    log?: Logger;
+    /** The command that signs in again, named in every failure that needs it. */
+    signInCommand: string;
+}
+export interface ExchangeContext extends RequestContext {
+    /** The tokens being refreshed; absent for the first exchange. */
+    previous?: TokenSet;
+}
+/**
+ * A provider as a CLI declares it. cli-core holds no provider's URLs or ids; every step may be replaced, and the
+ * keeper still holds the lock and the storage around it.
+ */
+export interface OAuthProvider {
+    /** A short word, part of new keyring account names: `google`, `zoom`. */
+    id: string;
+    /** The name people know, used in messages: `Google`. */
+    name: string;
+    authorizeUrl: string;
+    tokenUrl: string;
+    revokeUrl?: string;
+    client: OAuthClient;
+    /**
+     * `loopback` sends the browser to `http://127.0.0.1:<port>/callback`. `relay` sends it to a fixed page that
+     * forwards to the loopback port, which it reads from `state` (`<port>.<random>`).
+     */
+    redirect: {
+        kind: "loopback";
+    } | {
+        kind: "relay";
+        url: string;
+    };
+    authorizeParams?: Record<string, string>;
+    exchange?: (params: Record<string, string>, context: ExchangeContext) => Promise<TokenSet>;
+    revoke?: (tokens: TokenSet, context: RequestContext) => Promise<void>;
+}

package/dist/oauth/provider.js

@@ -0,0 +1 @@
+export {};

package/dist/oauth/requests.d.ts

@@ -0,0 +1,11 @@
+import type { ExchangeContext, OAuthProvider, RequestContext, TokenSet } from "./provider.js";
+export declare const TOKEN_LOG_EVENT = "oauth.token";
+/** The keys the module's log records carry, for a run log's `allow`; names only, never a token. */
+export declare const TOKEN_LOG_ALLOW: readonly ["provider", "operation", "outcome", "status", "rotated", "pid"];
+/**
+ * The token endpoint, form-encoded, for both grants. Nothing from the request or the response reaches a message or
+ * a log record: both carry codes and tokens.
+ */
+export declare const requestTokens: (provider: OAuthProvider, params: Record<string, string>, context: ExchangeContext) => Promise<TokenSet>;
+/** Revokes the refresh token at `revokeUrl`. A provider without one, or with another method, declares `revoke`. */
+export declare const revokeToken: (provider: OAuthProvider, tokens: TokenSet, context: RequestContext) => Promise<void>;

package/dist/oauth/requests.js

@@ -0,0 +1,129 @@
+import { CliError, isCliError } from "@wirecat/cli-base";
+const REQUEST_LIMIT_MS = 30_000;
+export const TOKEN_LOG_EVENT = "oauth.token";
+/** The keys the module's log records carry, for a run log's `allow`; names only, never a token. */
+export const TOKEN_LOG_ALLOW = ["provider", "operation", "outcome", "status", "rotated", "pid"];
+const object = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error("not an object");
+    return value;
+};
+const requestSignal = (signal) => signal ? AbortSignal.any([signal, AbortSignal.timeout(REQUEST_LIMIT_MS)]) : AbortSignal.timeout(REQUEST_LIMIT_MS);
+const cancelledBy = (signal) => {
+    if (!signal?.aborted)
+        return;
+    throw isCliError(signal.reason) ? signal.reason : new CliError("cancelled", "sign-in was cancelled");
+};
+const post = async (url, body, context) => {
+    cancelledBy(context.signal);
+    try {
+        return await context.fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+            body,
+            signal: requestSignal(context.signal),
+            redirect: "error",
+        });
+    }
+    catch {
+        cancelledBy(context.signal);
+        return undefined;
+    }
+};
+const clientFields = ({ client }) => ({
+    client_id: client.clientId,
+    ...(client.clientSecret ? { client_secret: client.clientSecret } : {}),
+});
+/**
+ * The token endpoint, form-encoded, for both grants. Nothing from the request or the response reaches a message or
+ * a log record: both carry codes and tokens.
+ */
+export const requestTokens = async (provider, params, context) => {
+    const operation = params.grant_type ?? "unknown";
+    const record = (level, fields) => context.log?.[level]({ event: TOKEN_LOG_EVENT, provider: provider.id, operation, pid: process.pid, ...fields });
+    const again = `run ${context.signInCommand} again`;
+    const response = await post(provider.tokenUrl, new URLSearchParams({ ...params, ...clientFields(context) }), context);
+    if (!response) {
+        record("warn", { outcome: "no_response" });
+        throw new CliError("outcome_unknown", `${provider.name} token request did not finish; ${again} if it keeps failing`, {
+            reason: "oauth.no-response",
+        });
+    }
+    if (!response.ok) {
+        record("warn", { outcome: "rejected", status: response.status });
+        if (response.status === 429 || response.status >= 500)
+            throw new CliError("provider_unavailable", `${provider.name} token request failed (HTTP ${response.status})`, {
+                status: response.status,
+                retryable: true,
+                reason: "oauth.unavailable",
+            });
+        throw new CliError("authentication_error", `${provider.name} sign-in was refused (HTTP ${response.status}); ${again}`, {
+            status: response.status,
+            reason: "oauth.expired",
+        });
+    }
+    let body;
+    try {
+        body = object(await response.json());
+    }
+    catch {
+        record("error", { outcome: "unreadable_response", status: response.status });
+        throw new CliError("invalid_response", `${provider.name} returned an unreadable token response; ${again}`, {
+            reason: "oauth.invalid-response",
+        });
+    }
+    const previous = context.previous;
+    const refreshToken = typeof body.refresh_token === "string" && body.refresh_token ? body.refresh_token : previous?.refreshToken;
+    const expiresIn = body.expires_in;
+    if (typeof body.access_token !== "string" ||
+        !body.access_token ||
+        (expiresIn !== undefined && (typeof expiresIn !== "number" || !Number.isFinite(expiresIn) || expiresIn <= 0)) ||
+        (body.scope !== undefined && typeof body.scope !== "string") ||
+        (body.token_type !== undefined && typeof body.token_type !== "string")) {
+        record("error", { outcome: "invalid_response", status: response.status });
+        throw new CliError("invalid_response", `${provider.name} returned an invalid token response; ${again}`, {
+            reason: "oauth.invalid-response",
+        });
+    }
+    if (!refreshToken) {
+        record("error", { outcome: "no_refresh_token", status: response.status });
+        throw new CliError("authentication_error", `${provider.name} returned no offline refresh token; ${again}`, {
+            reason: "oauth.failed",
+        });
+    }
+    const scopes = typeof body.scope === "string" ? body.scope.split(/\s+/).filter(Boolean) : (previous?.scopes ?? []);
+    const tokenType = typeof body.token_type === "string" ? body.token_type : previous?.tokenType;
+    record("info", {
+        outcome: "received",
+        status: response.status,
+        ...(previous ? { rotated: refreshToken !== previous.refreshToken } : {}),
+    });
+    return {
+        accessToken: body.access_token,
+        refreshToken,
+        ...(typeof expiresIn === "number" ? { expiresAt: context.now() + expiresIn * 1000 } : {}),
+        scopes,
+        ...(tokenType ? { tokenType } : {}),
+    };
+};
+/** Revokes the refresh token at `revokeUrl`. A provider without one, or with another method, declares `revoke`. */
+export const revokeToken = async (provider, tokens, context) => {
+    if (provider.revoke)
+        return provider.revoke(tokens, context);
+    if (!provider.revokeUrl)
+        throw new CliError("validation_error", `${provider.name} declares no way to revoke a sign-in`);
+    const response = await post(provider.revokeUrl, new URLSearchParams({ token: tokens.refreshToken, ...clientFields(context) }), context);
+    context.log?.[response?.ok ? "info" : "warn"]({
+        event: TOKEN_LOG_EVENT,
+        provider: provider.id,
+        operation: "revoke",
+        pid: process.pid,
+        outcome: response?.ok ? "revoked" : response ? "rejected" : "no_response",
+        ...(response ? { status: response.status } : {}),
+    });
+    if (!response?.ok)
+        throw new CliError("outcome_unknown", `${provider.name} did not confirm the revoke`, {
+            reason: "oauth.revoke-failed",
+            ...(response ? { status: response.status } : {}),
+        });
+};

package/dist/oauth/storage.d.ts

@@ -0,0 +1,48 @@
+import { type CredentialSource, type CredentialsOptions } from "@wirecat/cli-base";
+import type { OAuthClient, TokenSet } from "./provider.js";
+export interface StoredTokens {
+    tokens: TokenSet;
+    /** The app the entry was signed in with, when the entry records it; refresh must use that one. */
+    client?: OAuthClient;
+}
+export interface EncodeInput {
+    tokens: TokenSet;
+    client: OAuthClient;
+    /** The entry as stored before, so fields the codec does not own survive a write. */
+    previous?: string;
+    /** Fields a CLI adds at sign-in, such as drive's `principal`. */
+    extra?: Record<string, unknown>;
+}
+/** Every failure throws a fixed message: a parser's message would quote the secret. */
+export interface TokenCodec {
+    decode(raw: string): StoredTokens;
+    encode(input: EncodeInput): string;
+}
+export interface TokenStorage {
+    /** Names the entry across processes; the lock is keyed by it. */
+    readonly key: string;
+    /** Throws when the entry cannot be saved, so a sign-in fails before the browser, not after consent. */
+    probe(): void;
+    read(): StoredTokens | undefined;
+    write(input: Omit<EncodeInput, "previous">): void;
+    remove(): CredentialSource[];
+}
+export declare const oauthAccount: (providerId: string, profile: string) => string;
+/** The entry every new sign-in writes: account `oauth:<provider>:<profile>` under the CLI's own service. */
+export declare const standardCodec: (providerId: string) => TokenCodec;
+/**
+ * drive's entry as drive-cli writes it today: `{principal, clientId, clientSecret?, tokens: {access_token,
+ * refresh_token, expiry_date, scope, token_type, …}}`. A write keeps every field it does not own.
+ */
+export declare const driveSessionCodec: TokenCodec;
+/** zm's entry as zoom-cli writes it today: `{accessToken, refreshToken, expiresAt, scopes}`, all four required. */
+export declare const zoomTokenCodec: TokenCodec;
+export interface CredentialStorageOptions {
+    /** What the CLI passes `Credentials` today; the same options address the same entry. */
+    credentials: CredentialsOptions;
+    account: string;
+    /** Older accounts read when `account` is empty; a hit is copied to `account` and left in place. */
+    legacyAccounts?: readonly string[];
+    codec: TokenCodec;
+}
+export declare const credentialStorage: (options: CredentialStorageOptions) => TokenStorage;

package/dist/oauth/storage.js

@@ -0,0 +1,197 @@
+import { CliError, Credentials, keyringService, } from "@wirecat/cli-base";
+const invalid = () => new CliError("authentication_error", "the saved sign-in cannot be read; sign in again", { reason: "oauth.invalid" });
+const parse = (raw) => {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw invalid();
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw invalid();
+    return value;
+};
+const text = (value) => (typeof value === "string" && value ? value : undefined);
+const finite = (value) => typeof value === "number" && Number.isFinite(value) ? value : undefined;
+const previousOf = (raw) => {
+    if (raw === undefined)
+        return {};
+    try {
+        return parse(raw);
+    }
+    catch {
+        return {};
+    }
+};
+const defined = (value) => Object.fromEntries(Object.entries(value).filter(([, field]) => field !== undefined));
+export const oauthAccount = (providerId, profile) => {
+    if (!profile.trim())
+        throw new CliError("validation_error", "name a profile: a sign-in always belongs to one");
+    return `oauth:${providerId}:${profile}`;
+};
+/** The entry every new sign-in writes: account `oauth:<provider>:<profile>` under the CLI's own service. */
+export const standardCodec = (providerId) => ({
+    decode: (raw) => {
+        const value = parse(raw);
+        const refreshToken = text(value.refreshToken);
+        const clientId = text(value.clientId);
+        if (value.version !== 1 || value.provider !== providerId || !refreshToken || !clientId)
+            throw invalid();
+        if (!Array.isArray(value.scopes) || !value.scopes.every((scope) => typeof scope === "string"))
+            throw invalid();
+        return {
+            client: { clientId },
+            tokens: defined({
+                accessToken: text(value.accessToken),
+                refreshToken,
+                expiresAt: finite(value.expiresAt),
+                scopes: value.scopes,
+                tokenType: text(value.tokenType),
+            }),
+        };
+    },
+    encode: ({ tokens, client, previous, extra }) => JSON.stringify(defined({
+        ...previousOf(previous),
+        ...extra,
+        version: 1,
+        provider: providerId,
+        clientId: client.clientId,
+        accessToken: tokens.accessToken,
+        refreshToken: tokens.refreshToken,
+        expiresAt: tokens.expiresAt,
+        scopes: tokens.scopes,
+        tokenType: tokens.tokenType,
+    })),
+});
+/**
+ * drive's entry as drive-cli writes it today: `{principal, clientId, clientSecret?, tokens: {access_token,
+ * refresh_token, expiry_date, scope, token_type, …}}`. A write keeps every field it does not own.
+ */
+export const driveSessionCodec = {
+    decode: (raw) => {
+        const value = parse(raw);
+        const tokens = value.tokens;
+        if (typeof tokens !== "object" || tokens === null || Array.isArray(tokens))
+            throw invalid();
+        const fields = tokens;
+        const refreshToken = text(fields.refresh_token);
+        const clientId = text(value.clientId);
+        if (!refreshToken || !clientId || typeof value.principal !== "string")
+            throw invalid();
+        return {
+            client: defined({ clientId, clientSecret: text(value.clientSecret) }),
+            tokens: defined({
+                accessToken: text(fields.access_token),
+                refreshToken,
+                expiresAt: finite(fields.expiry_date),
+                scopes: typeof fields.scope === "string" ? fields.scope.split(/\s+/).filter(Boolean) : [],
+                tokenType: text(fields.token_type),
+            }),
+        };
+    },
+    encode: ({ tokens, client, previous, extra }) => {
+        const before = previousOf(previous);
+        const oldTokens = typeof before.tokens === "object" && before.tokens !== null ? before.tokens : {};
+        const session = {
+            ...before,
+            ...extra,
+            clientId: client.clientId,
+            ...(client.clientSecret ? { clientSecret: client.clientSecret } : {}),
+            tokens: defined({
+                ...oldTokens,
+                access_token: tokens.accessToken,
+                refresh_token: tokens.refreshToken,
+                expiry_date: tokens.expiresAt,
+                ...(tokens.scopes.length ? { scope: tokens.scopes.join(" ") } : {}),
+                token_type: tokens.tokenType,
+            }),
+        };
+        if (typeof session.principal !== "string")
+            throw new CliError("configuration_error", "drive's sign-in entry needs the account's principal");
+        return JSON.stringify(session);
+    },
+};
+/** zm's entry as zoom-cli writes it today: `{accessToken, refreshToken, expiresAt, scopes}`, all four required. */
+export const zoomTokenCodec = {
+    decode: (raw) => {
+        const value = parse(raw);
+        const accessToken = text(value.accessToken);
+        const refreshToken = text(value.refreshToken);
+        const expiresAt = finite(value.expiresAt);
+        if (!accessToken || !refreshToken || expiresAt === undefined)
+            throw invalid();
+        if (!Array.isArray(value.scopes) || !value.scopes.every((scope) => typeof scope === "string"))
+            throw invalid();
+        return { tokens: { accessToken, refreshToken, expiresAt, scopes: value.scopes } };
+    },
+    encode: ({ tokens }) => {
+        if (!tokens.accessToken)
+            throw new CliError("invalid_response", "zm's sign-in entry needs an access token");
+        return JSON.stringify({
+            accessToken: tokens.accessToken,
+            refreshToken: tokens.refreshToken,
+            expiresAt: tokens.expiresAt ?? 0,
+            scopes: tokens.scopes,
+        });
+    },
+};
+const keyringFailure = () => new CliError("configuration_error", "could not reach the saved sign-in; use an available keyring or file storage", {
+    reason: "oauth.not-saved",
+});
+export const credentialStorage = (options) => {
+    if (!options.credentials.keyring)
+        throw new CliError("configuration_error", "a sign-in store needs its keyring passed in, never a default");
+    const credentials = new Credentials(options.credentials);
+    const { account, codec } = options;
+    const service = keyringService(options.credentials.service, options.credentials.configDir, options.credentials.isolated);
+    const raw = (name) => {
+        try {
+            return credentials.read(name)?.secret;
+        }
+        catch {
+            throw keyringFailure();
+        }
+    };
+    const save = (value) => {
+        try {
+            credentials.write(account, value);
+        }
+        catch {
+            throw keyringFailure();
+        }
+    };
+    const current = () => {
+        const own = raw(account);
+        if (own !== undefined)
+            return own;
+        for (const legacy of options.legacyAccounts ?? []) {
+            const found = raw(legacy);
+            if (found === undefined)
+                continue;
+            codec.decode(found);
+            save(found);
+            return found;
+        }
+        return undefined;
+    };
+    return {
+        key: `${service}\u0000${account}`,
+        probe: () => {
+            raw(account);
+        },
+        read: () => {
+            const value = current();
+            return value === undefined ? undefined : codec.decode(value);
+        },
+        write: (input) => save(codec.encode({ ...input, previous: raw(account) })),
+        remove: () => {
+            try {
+                return credentials.remove(account);
+            }
+            catch {
+                throw keyringFailure();
+            }
+        },
+    };
+};

package/dist/services/project-gathering.d.ts

@@ -77,6 +77,8 @@ export declare const gatherProjectEvidence: (ports: ProjectGatheringPorts, reque
         source: number | null;
         lane: string | null;
         state: "in-scope" | "out-of-scope" | "unavailable";
+        items: number;
+        capped: boolean;
     }[];
     fetch: {
         state: ProjectFetchState;

package/dist/services/project-gathering.js

@@ -5,6 +5,7 @@ import { excerpt } from "./excerpt.js";
 import { attachNeighbours, documentMatches, } from "./project-gathering-around.js";
 import { decodeCheckpoint, encodeCheckpoint, projectGatheringRequest, projectUnits, seenKey, } from "./project-gathering-request.js";
 const terminal = new Set(["done", "unavailable", "failed"]);
+const PAGE = 20;
 const CONTEXTS = ["person-only", "sender", "linked-chat", "project"];
 const contextOf = (lane) => lane.kinds.includes("linked-chat")
     ? "linked-chat"
@@ -84,6 +85,12 @@ export const gatherProjectEvidence = async (ports, request) => {
     const oversized = new Map();
     let stopped = null;
     const open = (u) => !terminal.has(u.state) && u.state !== "read-limited";
+    const linkedLanes = new Set(plan.linkedChats.flatMap((c) => (c.lane === null ? [] : [c.lane])));
+    // One even share per linked chat plus one for the word and sender lanes, so one busy chat cannot fill a run; never
+    // below a page, so every chat still gets its whole first page.
+    const linkedLimit = Math.max(PAGE, Math.floor(plan.budgets.maxItems / (linkedLanes.size + 1)));
+    const linkedTaken = new Map();
+    const capped = new Set();
     /** Records another lane finding a reference this run already returned; true when it had. */
     const again = (ref, lane) => {
         const known = byRef.get(ref);
@@ -133,11 +140,13 @@ export const gatherProjectEvidence = async (ports, request) => {
         byRef.set(item.ref, entry);
         items.push(entry);
         usage.items++;
+        if (linkedLanes.has(lane.id))
+            linkedTaken.set(lane.id, (linkedTaken.get(lane.id) ?? 0) + 1);
     };
     // A resumed run starts at its shallowest open unit: below it no unit is due, and an empty round would end the run.
     const shallowest = progress.reduce((low, u) => (open(u) ? Math.min(low, u.pages) : low), Number.POSITIVE_INFINITY);
     for (let round = shallowest; !stopped; round++) {
-        const due = progress.flatMap((u, index) => (open(u) && u.pages <= round ? [index] : []));
+        const due = progress.flatMap((u, index) => open(u) && u.pages <= round && !capped.has(units[index]?.lane.id ?? "") ? [index] : []);
         if (!due.length)
             break;
         for (const index of due) {
@@ -145,6 +154,11 @@ export const gatherProjectEvidence = async (ports, request) => {
             if (!unit || !state)
                 continue;
             signal?.throwIfAborted();
+            const room = linkedLanes.has(unit.lane.id) ? linkedLimit - (linkedTaken.get(unit.lane.id) ?? 0) : PAGE;
+            if (room <= 0) {
+                capped.add(unit.lane.id);
+                continue;
+            }
             stopped =
                 usage.reads >= plan.budgets.maxReads
                     ? "reads"
@@ -187,7 +201,7 @@ export const gatherProjectEvidence = async (ports, request) => {
                 }
             };
             try {
-                let page = await readPage(Math.min(plan.budgets.maxPageBytes, plan.budgets.maxReadBytes - usage.readBytes), 20);
+                let page = await readPage(Math.min(plan.budgets.maxPageBytes, plan.budgets.maxReadBytes - usage.readBytes), Math.min(PAGE, room));
                 // A large record another lane already returned is not read again; its page already moves past it.
                 const big = page.oversized && !again(page.oversized.ref, unit.lane) ? page.oversized : undefined;
                 if (big && big.bytes <= CONTEXT_MAX_READ_BYTES) {
@@ -288,6 +302,8 @@ export const gatherProjectEvidence = async (ports, request) => {
                 : units.every((unit, index) => unit.lane.id !== lane || progress[index]?.state === "unavailable")
                     ? "unavailable"
                     : "in-scope",
+            items: lane === null ? 0 : (linkedTaken.get(lane) ?? 0),
+            capped: lane !== null && capped.has(lane),
         })),
         fetch: fetched.map((f, index) => ({ source: index, ...f })),
         index: indexed,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.412.0",
+  "version": "0.413.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",
@@ -128,6 +128,10 @@
     "./update": {
       "types": "./dist/update/index.d.ts",
       "default": "./dist/update/index.js"
+    },
+    "./oauth": {
+      "types": "./dist/oauth/index.d.ts",
+      "default": "./dist/oauth/index.js"
     }
   },
   "scripts": {