@wirecat/cli-core 0.564.0 → 0.566.0

package/dist/constants/index.d.ts

@@ -0,0 +1,83 @@
+import * as v from "valibot";
+import type { AppSource, OAuthClient } from "../oauth/provider.js";
+/** cli-core's layer, read after cli-base's and before the tool's. */
+export declare const CORE_CONSTANTS: import("url").URL;
+/** What cli-base's and cli-core's layers hold; a tool extends it with `v.object({ ...constantsSchema.entries, … })`. */
+export declare const constantsSchema: v.ObjectSchema<{
+    readonly google: v.ObjectSchema<{
+        readonly app: v.ObjectSchema<{
+            readonly client_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.NonEmptyAction<string, undefined>, v.TransformAction<string, string>]>;
+            readonly client_secret: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TransformAction<string, string>]>, undefined>;
+        }, undefined>;
+    }, undefined>;
+    readonly microsoft: v.ObjectSchema<{
+        readonly app: v.ObjectSchema<{
+            readonly client_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.NonEmptyAction<string, undefined>]>;
+        }, undefined>;
+    }, undefined>;
+}, undefined>;
+export type Constants = v.InferOutput<typeof constantsSchema>;
+/**
+ * The packaged constants, base → core → the tool's `constants.json` when given, read once per process for each tool
+ * layer. A tool with constants of its own passes its layer and a schema built on `constantsSchema`; the first call for
+ * a layer decides its schema.
+ */
+export declare const constants: <TSchema extends v.GenericSchema<unknown, Constants> = typeof constantsSchema>(toolLayer?: URL, schema?: TSchema) => v.InferOutput<TSchema>;
+export interface AppOptions {
+    env: NodeJS.ProcessEnv;
+    /** The tool's environment prefix: `GCAL` with provider `google` reads `GCAL_GOOGLE_CLIENT_ID` and `_SECRET`. */
+    prefix: string;
+    /** `--client-id`. A secret for it comes from `<PREFIX>_<PROVIDER>_CLIENT_SECRET`. */
+    clientId?: string | undefined;
+    /** The account's config key `<provider>.client_id`. A config file never holds the secret: it comes from the env. */
+    configClientId?: string | undefined;
+}
+export interface OAuthAppOptions extends AppOptions {
+    /** `google`, `microsoft`, `zoom`: names the env variables, upper-cased. */
+    provider: string;
+    /** WireCat's app from the constants; an empty or missing id means WireCat has none for this provider. */
+    wirecat?: {
+        client_id?: string | undefined;
+        client_secret?: string | undefined;
+    } | undefined;
+}
+export interface OAuthApp {
+    client: OAuthClient & {
+        source: AppSource;
+    };
+    source: AppSource;
+}
+/**
+ * The app a sign-in uses, first match wins (WC-SECR-25): `--client-id`, `<PREFIX>_<PROVIDER>_CLIENT_ID`, the account's
+ * `<provider>.client_id`, WireCat's app. A secret without any of the first three ids is a `configuration_error`.
+ * Undefined when nothing names an app and WireCat has none.
+ */
+export declare const oauthApp: (options: OAuthAppOptions) => OAuthApp | undefined;
+export interface GoogleAppOptions extends AppOptions {
+    /** The owner's Desktop client JSON, `--client-file`; it must be private to the owner. */
+    clientFile?: string | undefined;
+    platform?: NodeJS.Platform;
+    /** The tool's own constants, when its layer overrides the app. */
+    constants?: Constants;
+}
+/**
+ * The Google Desktop app a sign-in uses: `--client-file`, then `oauthApp`'s order. Google treats a Desktop app's
+ * secret as public (https://developers.google.com/identity/protocols/oauth2/native-app), so WireCat's ships, obscured,
+ * in cli-core's constants.
+ */
+export declare const googleApp: (options: GoogleAppOptions) => OAuthApp;
+/** WireCat's Microsoft app is a public client: it has an id and no secret. */
+export declare const microsoftApp: (options: AppOptions & {
+    constants?: Constants;
+}) => OAuthApp;
+export interface OAuthClientReport {
+    client: "wirecat" | "own" | null;
+    source: AppSource | null;
+    /** Why there is no app, when `client` is null. */
+    reason?: string;
+}
+/** `doctor`'s `oauth_client` for one provider: the app a new sign-in would use; doctor reads no keyring. */
+export declare const oauthClientReport: (app: {
+    source?: AppSource | undefined;
+} | undefined, reason?: string) => OAuthClientReport;
+export type { AppSource };

package/dist/constants/index.js

@@ -0,0 +1,77 @@
+import { BASE_CONSTANTS, baseConstantsSchema, CliError, loadConstants } from "@wirecat/cli-base";
+import * as v from "valibot";
+import { readClientFile } from "../oauth/client-file.js";
+import { reveal } from "./obscure.js";
+/** cli-core's layer, read after cli-base's and before the tool's. */
+export const CORE_CONSTANTS = new URL("../../constants.json", import.meta.url);
+/** What cli-base's and cli-core's layers hold; a tool extends it with `v.object({ ...constantsSchema.entries, … })`. */
+export const constantsSchema = v.object({
+    ...baseConstantsSchema.entries,
+    google: v.object({
+        app: v.object({
+            client_id: v.pipe(v.string(), v.nonEmpty(), v.transform(reveal)),
+            client_secret: v.optional(v.pipe(v.string(), v.transform(reveal))),
+        }),
+    }),
+    microsoft: v.object({ app: v.object({ client_id: v.pipe(v.string(), v.nonEmpty()) }) }),
+});
+const loaded = new Map();
+/**
+ * The packaged constants, base → core → the tool's `constants.json` when given, read once per process for each tool
+ * layer. A tool with constants of its own passes its layer and a schema built on `constantsSchema`; the first call for
+ * a layer decides its schema.
+ */
+export const constants = (toolLayer, schema) => {
+    const key = toolLayer?.href ?? "";
+    if (!loaded.has(key)) {
+        const layers = toolLayer ? [BASE_CONSTANTS, CORE_CONSTANTS, toolLayer] : [BASE_CONSTANTS, CORE_CONSTANTS];
+        loaded.set(key, loadConstants(layers, schema ?? constantsSchema));
+    }
+    return loaded.get(key);
+};
+/**
+ * The app a sign-in uses, first match wins (WC-SECR-25): `--client-id`, `<PREFIX>_<PROVIDER>_CLIENT_ID`, the account's
+ * `<provider>.client_id`, WireCat's app. A secret without any of the first three ids is a `configuration_error`.
+ * Undefined when nothing names an app and WireCat has none.
+ */
+export const oauthApp = (options) => {
+    const { env, prefix, provider } = options;
+    const name = `${prefix}_${provider.toUpperCase()}_CLIENT`;
+    const clientSecret = env[`${name}_SECRET`];
+    const own = [
+        [options.clientId, "flag"],
+        [env[`${name}_ID`], "env"],
+        [options.configClientId, "config"],
+    ];
+    const [clientId, source] = own.find(([id]) => id) ?? [];
+    if (clientId && source)
+        return app({ clientId, ...(clientSecret ? { clientSecret } : {}) }, source);
+    if (clientSecret)
+        throw new CliError("configuration_error", `${name}_SECRET is set without a client id; set ${name}_ID too, or unset it to use WireCat's app`, { reason: "sign-in.secret-without-id" });
+    const wirecat = options.wirecat;
+    if (!wirecat?.client_id)
+        return undefined;
+    return app({ clientId: wirecat.client_id, ...(wirecat.client_secret ? { clientSecret: wirecat.client_secret } : {}) }, "constants");
+};
+const app = (client, source) => ({ client: { ...client, source }, source });
+/**
+ * The Google Desktop app a sign-in uses: `--client-file`, then `oauthApp`'s order. Google treats a Desktop app's
+ * secret as public (https://developers.google.com/identity/protocols/oauth2/native-app), so WireCat's ships, obscured,
+ * in cli-core's constants.
+ */
+export const googleApp = (options) => {
+    const { clientFile, platform } = options;
+    if (clientFile)
+        return app(readClientFile(clientFile, platform ? { platform } : {}), "flag");
+    const wirecat = (options.constants ?? constants()).google.app;
+    return oauthApp({ ...options, provider: "google", wirecat });
+};
+/** WireCat's Microsoft app is a public client: it has an id and no secret. */
+export const microsoftApp = (options) => {
+    const wirecat = (options.constants ?? constants()).microsoft.app;
+    return oauthApp({ ...options, provider: "microsoft", wirecat });
+};
+/** `doctor`'s `oauth_client` for one provider: the app a new sign-in would use; doctor reads no keyring. */
+export const oauthClientReport = (app, reason) => app?.source
+    ? { client: app.source === "constants" ? "wirecat" : "own", source: app.source }
+    : { client: null, source: null, ...(reason ? { reason } : {}) };

package/dist/constants/obscure.d.ts

@@ -0,0 +1 @@
+export declare const reveal: (obscured: string) => string;

package/dist/constants/obscure.js

@@ -0,0 +1,9 @@
+import { createDecipheriv } from "node:crypto";
+// Not protection: anyone holding the package can reveal these. It keeps secret scanners and a casual read from
+// treating WireCat's public Desktop app as a leaked credential, as rclone does for its own app.
+const KEY = Buffer.from("d43012779aa2dded3e98092a3dbcf5d8980c564172f5ce0a5fd0574e5f740339", "hex");
+export const reveal = (obscured) => {
+    const bytes = Buffer.from(obscured, "base64url");
+    const decipher = createDecipheriv("aes-256-ctr", KEY, bytes.subarray(0, 16));
+    return Buffer.concat([decipher.update(bytes.subarray(16)), decipher.final()]).toString("utf8");
+};

package/dist/errors/reasons.js

@@ -31,6 +31,19 @@ const SIGN_IN = [
     ["oauth.not-saved", "configuration_error", "the sign-in cannot be saved or read where it is kept"],
     ["sign-in.client-file-open", "configuration_error", "other users of this computer can read the client file"],
     ["sign-in.client-file-invalid", "configuration_error", "the file is not a Desktop app OAuth client JSON"],
+    ["oauth.scope-missing", "permission_error", "the sign-in lacks a permission this command needs"],
+    ["sign-in.client-rejected", "configuration_error", "the provider rejected the OAuth client"],
+    ["sign-in.secret-without-id", "configuration_error", "an OAuth client secret is set without its client id"],
+];
+/** Reasons every CLI over a provider's API raises alike: gcal and drive today. */
+const PROVIDER_API = [
+    ["offline.refused", "permission_error", "this command needs the provider; --offline was given"],
+    validation("api.unknown-method", "the provider has no method by this name"),
+    ["api.disabled", "configuration_error", "the provider's API is turned off for this OAuth project"],
+    ["provider.usage-limit", "rate_limited", "the account's usage limit at the provider is reached; wait, do not retry"],
+    ["file.not-found", "not_found", "the file named, or its folder, does not exist"],
+    validation("file.not-a-file", "the path names a folder or another thing that is not a file"),
+    ["file.denied", "permission_error", "the file cannot be opened: permission denied"],
 ];
 const OTHERS = [
     ["query.time-limit", "timeout", "the search took longer than its time limit; the query itself is valid"],
@@ -87,6 +100,7 @@ const OTHERS = [
     validation("event.repeat-split", "the series cannot be split at this occurrence, or was split there already"),
     validation("event.repeat-count", "a COUNT series is split only with a rule for its new part"),
     validation("event.unmovable", "the provider keeps this kind of event on its calendar"),
+    validation("event.quick-add-ambiguous", "more than one event could be the one a lost quick add made"),
     validation("event.text-with-fields", "--text takes the whole event from its line, so no field option goes with it"),
     validation("calendar.ambiguous", "two or more calendars have this name; name one by its id"),
     validation("export.too-many", "the query finds more events than one export writes"),
@@ -258,7 +272,7 @@ export const INPUT_FIELD_REASONS = defineReasons([
 export const REASONS = defineReasons([
     ...QUERY_REASONS,
     ...INPUT_FIELD_REASONS,
-    ...[...QUERY, ...SIGN_IN, ...OTHERS].map(([reason, code, message]) => ({
+    ...[...QUERY, ...SIGN_IN, ...PROVIDER_API, ...OTHERS].map(([reason, code, message]) => ({
         reason,
         code,
         message,

package/dist/mcp/meeting-preparation.d.ts

@@ -28,7 +28,7 @@ export declare const callMeetingPreparationTool: (read: MeetingPreparationReader
     }[];
     structuredContent: {
         error: {
-            code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
+            code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "conflict" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
             reason: string;
             message: string;
             param?: string | undefined;

package/dist/mcp/meeting-project-candidates.d.ts

@@ -23,7 +23,7 @@ export declare const callMeetingProjectCandidatesTool: (read: StoredMeetingProje
     }[];
     structuredContent: {
         error: {
-            code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
+            code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "conflict" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
             reason: string;
             message: string;
             param?: string | undefined;

package/dist/mcp/meeting-series-inventory.d.ts

@@ -23,7 +23,7 @@ export declare const callMeetingSeriesInventoryTool: (read: MeetingSeriesInvento
     }[];
     structuredContent: {
         error: {
-            code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
+            code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "conflict" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
             reason: string;
             message: string;
             param?: string | undefined;

package/dist/meetings/mcp/passage.d.ts

@@ -57,7 +57,7 @@ export declare const callMeetingPassageTool: (read: MeetingPassageReader, input:
     }[];
     structuredContent: {
         error: {
-            code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
+            code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "conflict" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
             reason: string;
             message: string;
             param?: string | undefined;

package/dist/meetings/mcp/project-evidence.d.ts

@@ -51,7 +51,7 @@ export declare const callMeetingProjectEvidenceTool: (read: MeetingProjectDiscov
     }[];
     structuredContent: {
         error: {
-            code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
+            code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "conflict" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
             reason: string;
             message: string;
             param?: string | undefined;

package/dist/meetings/mcp/search.d.ts

@@ -94,7 +94,7 @@ export declare const callMeetingSearchTool: (search: MeetingHitSearch, input: un
     }[];
     structuredContent: {
         error: {
-            code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
+            code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "conflict" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
             reason: string;
             message: string;
             param?: string | undefined;

package/dist/oauth/index.d.ts

@@ -1,6 +1,6 @@
 export { type Authorization, type AuthorizeOptions, authorize } from "./authorize.js";
 export { type ClientFileOptions, readClientFile } from "./client-file.js";
 export { type SignInOptions, type TokenKeeper, type TokenKeeperOptions, type TokensOptions, tokenKeeper, } from "./keeper.js";
-export type { ExchangeContext, OAuthClient, OAuthProvider, RequestContext, TokenSet } from "./provider.js";
+export type { AppSource, 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/provider.d.ts

@@ -3,7 +3,12 @@ import type { Logger } from "@wirecat/cli-base";
 export interface OAuthClient {
     clientId: string;
     clientSecret?: string;
+    /** Where the sign-in found the app (WC-SECR-25); saved with the entry, so `doctor` reports the app it used. */
+    source?: AppSource;
 }
+/** `flag`: `--client-file` or `--client-id`; `env`: `<TOOL>_<PROVIDER>_CLIENT_ID`; `config`: the account's
+ * `<provider>.client_id`; `constants`: WireCat's app. */
+export type AppSource = "flag" | "env" | "config" | "constants";
 export interface TokenSet {
     accessToken?: string;
     refreshToken: string;

package/dist/oauth/storage.js

@@ -40,8 +40,9 @@ export const standardCodec = (providerId) => ({
             throw invalid();
         if (!Array.isArray(value.scopes) || !value.scopes.every((scope) => typeof scope === "string"))
             throw invalid();
+        const source = text(value.clientSource);
         return {
-            client: { clientId },
+            client: defined({ clientId, clientSecret: text(value.clientSecret), source }),
             tokens: defined({
                 accessToken: text(value.accessToken),
                 refreshToken,
@@ -57,6 +58,10 @@ export const standardCodec = (providerId) => ({
         version: 1,
         provider: providerId,
         clientId: client.clientId,
+        // Only WireCat's secret, which is public: a later release may ship another default app, and a refresh needs
+        // the secret of the app that signed in. An owner's own secret stays where the owner keeps it.
+        clientSecret: client.source === "constants" ? client.clientSecret : undefined,
+        clientSource: client.source,
         accessToken: tokens.accessToken,
         refreshToken: tokens.refreshToken,
         expiresAt: tokens.expiresAt,
@@ -80,7 +85,11 @@ export const driveSessionCodec = {
         if (!refreshToken || !clientId || typeof value.principal !== "string")
             throw invalid();
         return {
-            client: defined({ clientId, clientSecret: text(value.clientSecret) }),
+            client: defined({
+                clientId,
+                clientSecret: text(value.clientSecret),
+                source: text(value.clientSource),
+            }),
             tokens: defined({
                 accessToken: text(fields.access_token),
                 refreshToken,
@@ -98,6 +107,7 @@ export const driveSessionCodec = {
             ...extra,
             clientId: client.clientId,
             ...(client.clientSecret ? { clientSecret: client.clientSecret } : {}),
+            ...(client.source ? { clientSource: client.source } : {}),
             tokens: defined({
                 ...oldTokens,
                 access_token: tokens.accessToken,

package/dist/services/metadata.d.ts

@@ -27,7 +27,7 @@ export declare const metadataService: (deps: ServiceDeps) => {
             source?: undefined;
             chatId: string;
             error: {
-                code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
+                code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "conflict" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
                 message: string;
             };
         })[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.564.0",
+  "version": "0.566.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",
@@ -19,6 +19,7 @@
   "packageManager": "pnpm@11.28.8",
   "files": [
     "dist",
+    "constants.json",
     "parity.json",
     "skills",
     "README.md",
@@ -166,6 +167,10 @@
     "./oauth": {
       "types": "./dist/oauth/index.d.ts",
       "default": "./dist/oauth/index.js"
+    },
+    "./constants": {
+      "types": "./dist/constants/index.d.ts",
+      "default": "./dist/constants/index.js"
     }
   },
   "scripts": {
@@ -253,7 +258,7 @@
     "@types/node": "^22.20.5",
     "@types/pngjs": "6.0.5",
     "@vitest/coverage-v8": "^5.0.5",
-    "@wirecat/cli-base": "0.75.0",
+    "@wirecat/cli-base": "0.77.1",
     "@wirecat/cli-core-legacy-tags": "npm:@wirecat/cli-core@0.414.0",
     "commander": "15.0.0",
     "cspell": "10.4.0",
@@ -273,7 +278,7 @@
   },
   "peerDependencies": {
     "@napi-rs/canvas": ">=0.1.69 <2",
-    "@wirecat/cli-base": ">=0.75.0 <0.76.0",
+    "@wirecat/cli-base": ">=0.76.0 <0.78.0",
     "commander": ">=15"
   },
   "bin": {