@wirecat/cli-core 0.412.0 → 0.414.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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.
 
+## 0.414.0 — 25.10.2026
+
+### Added
+
+- `AppIdentity.contentLanguages`: ISO 639-1 codes of the languages a CLI's content is in. On a new store the first run pre-ticks the ones search can stem in place of English and the system's language; the person still confirms the shared choice. Unset, nothing changes.
+- Export `publicUrlOf` and `portOf` through `/mcp`, so non-messenger consumers reuse the same HTTP listener option validation as the messenger commands.
+- **A contact saved with an address joins the mail contact of that exact address.** `savePeople` takes an optional
+  `email`; the provider's contact and the mail contact become one person (`same-email`), whichever is saved first.
+  A name never joins anyone, and two identities the owner unlinked stay apart.
+- **The first screen of `tg --help`, `max --help` and `wa --help` points at `account list`.** A row under "Start here" names `<tool> account list`, which lists every profile on this computer without a profile in front, so a reader who does not know their profile names finds them. A tool without `account list` shows no row.
+
+### Fixed
+
+- Generated MCP commands accept a positional argument or its same-named flag alternative once. A single `text` input no longer emits both the argument and `--text`, which made Memo note creation fail. Positional requiredness is retained.
+- Public listener origins refuse embedded credentials before startup diagnostics can expose them.
+- **"Returns" lists the fields of commands whose output has several shapes.** A command's help and the generated `docs/commands.md` showed `message send — ; every field: …` with no fields for every output declared as a union (`message_send`, `store_info`, `chat_group_change` and others; 41 lines in tg-cli's page). The line now lists the fields of every shape, required first, as for any other output.
+
+## 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,137 @@
+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,
+            contentLanguages: entry.app.contentLanguages,
+            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

@@ -25,6 +25,8 @@ export interface FirstRun {
     command: string;
     env: NodeJS.ProcessEnv;
     io: FirstRunIo;
+    /** `AppIdentity.contentLanguages`: ticked on a new store in place of English and the system's language. */
+    contentLanguages?: readonly string[] | undefined;
     /** Every question, as `setup` asks them; otherwise only those no WireCat tool asked yet. */
     all?: boolean;
     /** Where tools are looked for and how one is installed; injected by tests. */
@@ -53,11 +55,12 @@ 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;
     env: NodeJS.ProcessEnv;
+    contentLanguages?: readonly string[] | undefined;
     path: readonly string[];
     headless: boolean;
     readOnlyLock?: string | undefined;

package/dist/cli/first-run.js

@@ -85,17 +85,19 @@ const installerHere = () => {
         return "unknown";
     }
 };
-const askLanguages = async ({ command, env, io }) => {
+const suggested = (env, contentLanguages) => {
+    const own = LANGUAGES.filter(({ code }) => contentLanguages?.includes(code));
+    const system = systemLanguage(env);
+    return (own.length ? own : LANGUAGES.filter(({ code }) => code === "en" || code === system)).map(({ name }) => name);
+};
+const askLanguages = async ({ command, env, io, contentLanguages }) => {
     const store = await openStore({ env });
     let rebuild = false;
     try {
         const saved = (await store.searchIndex.stemmers()) ?? undefined;
         // A store already in use keeps the languages it was built with, so Enter changes nothing (RISK-1612).
         const inUse = saved !== undefined || (await store.accounts.accounts()).length > 0;
-        const system = systemLanguage(env);
-        const ticked = inUse
-            ? languagesOf(saved ?? DEFAULT_STEMMERS)
-            : LANGUAGES.filter(({ code }) => code === "en" || code === system).map(({ name }) => name);
+        const ticked = inUse ? languagesOf(saved ?? DEFAULT_STEMMERS) : suggested(env, contentLanguages);
         const numbers = ticked.map((name) => LANGUAGES.findIndex((one) => one.name === name) + 1);
         io.say("Languages you write and speak — search finds every form of their words, and spellings speech mangles:");
         LANGUAGES.forEach(({ name, label }, at) => {
@@ -203,7 +205,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;
@@ -213,6 +215,7 @@ export const setupAtStart = async (start) => {
     await askSetupQuestions({
         command: start.command,
         env: start.env,
+        contentLanguages: start.contentLanguages,
         all: start.path[0] === "setup",
         io: {
             ask: (prompt) => readSecret(prompt, { input, echo: true }),

package/dist/cli/help/command-help.js

@@ -100,16 +100,19 @@ const call = (command) => [
     ...commandPathOf(command),
     ...command.registeredArguments.map((one) => (one.required ? `<${one.name()}>` : `[${one.name()}]`)),
 ].join(" ");
+const fieldsOf = (schema) => {
+    const variants = schema.anyOf;
+    if (variants)
+        return variants.flatMap(fieldsOf);
+    const required = schema.required ?? [];
+    return [...required, ...Object.keys(schema.properties ?? {})];
+};
 const returnsOf = (command) => {
     const output = metaOf(command).output;
     const { item, coverage } = outputOf(command);
     if (!output || coverage !== "declared-entity")
         return short(command.summary() || command.description()) || "not declared";
-    const required = item.required ?? [];
-    const fields = [
-        ...required,
-        ...Object.keys(item.properties ?? {}).filter((name) => !required.includes(name)),
-    ];
+    const fields = [...new Set(fieldsOf(item))];
     const noun = (output.view ? `${output.entity} ${output.view}` : output.entity).replaceAll("_", " ");
     const more = fields.length > 8 ? `, and ${fields.length - 8} more` : "";
     const root = rootOf(command);

package/dist/cli/help/first-screen.js

@@ -64,6 +64,9 @@ const pointers = (program, cli, start, profile) => {
     ].filter((row) => row !== undefined);
     const rows = [
         ...(start ? [["Start here:", start, profile ? "(any profile name works)" : ""]] : []),
+        ...(has("account list")
+            ? [["", `${cli} account list`, "your profiles and their logged-in accounts"]]
+            : []),
         ...next.map(([command = "", does = ""], at) => [at === 0 ? "Next:" : "", command, does]),
         ...(has("skill show") ? [["For agents:", `${cli} skill show`, "rules and the discovery loop"]] : []),
     ];

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/cli/program.js

@@ -267,6 +267,7 @@ const runOnce = async (argv, definition, options) => {
         await setupAtStart({
             command,
             env: commandEnv,
+            contentLanguages: definition.app.contentLanguages,
             path,
             headless,
             readOnlyLock: lock,

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/http/public-url.js

@@ -14,6 +14,8 @@ export const publicUrlOf = (given, { missing, reaches }) => {
     catch {
         throw new CliError("validation_error", `--public-url is not an address: ${EXAMPLE}`);
     }
+    if (url.username || url.password)
+        throw new CliError("validation_error", "--public-url must not contain login credentials");
     const local = url.protocol === "http:" && ["localhost", "127.0.0.1"].includes(url.hostname);
     if (url.protocol !== "https:" && !local)
         throw new CliError("validation_error", `--public-url must be https — ${reaches} through it`);

package/dist/mcp/agent.js

@@ -111,7 +111,10 @@ const fieldsOf = (info, { omit = [], offline = false, stdin }) => {
         const long = longOf(option);
         if (!long || option.mcp === false)
             continue;
-        fields.push(optionField(option, long, longs.has(`--no-${long.slice(2)}`)));
+        const field = optionField(option, long, longs.has(`--no-${long.slice(2)}`));
+        // A positional and its flag alternative share one MCP input; emitting both supplies the value twice.
+        if (!fields.some((existing) => existing.name === field.name))
+            fields.push(field);
     }
     if (offline && info.effects?.remote === "read" && info.offline !== false)
         fields.push(OFFLINE);

package/dist/mcp/index.d.ts

@@ -1,3 +1,4 @@
+export { portOf, publicUrlOf } from "../http/public-url.js";
 export { type AgentAnswer, type AgentContext, type AgentProgram, type AgentTool, type CatalogueOptions, type CommandAvailability, runCommandForAgent, toolsFromCommands, } from "./agent.js";
 export { type BotServerOptions, createBotServer, type RunBotCommand } from "./bot/server.js";
 export { revokeAll } from "./http/oauth.js";

package/dist/mcp/index.js

@@ -1,4 +1,5 @@
 // Apart from the `cli` entry, so a CLI loads the MCP SDK and zod only when it serves MCP.
+export { portOf, publicUrlOf } from "../http/public-url.js";
 export { runCommandForAgent, toolsFromCommands, } from "./agent.js";
 export { createBotServer } from "./bot/server.js";
 export { revokeAll } from "./http/oauth.js";

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";