@wirecat/cli-core 0.411.0 → 0.413.0

package/dist/entities/index.d.ts

@@ -39,6 +39,7 @@ import { imageEmbedding } from "./image-embedding.js";
 import { inviteLink } from "./invite-link.js";
 import { job } from "./job.js";
 import { joinRequest } from "./join-request.js";
+import { organization, project, reminder } from "./knowledge-lists.js";
 import { botAdmin, botMenuEntry, botProfile, botSeenChat, botTemplate, botWebhook, callRecord, scheduledJob, stickerInventory } from "./list-results.js";
 import { messageEvent, serveSummary, watchedMessage, watchItem } from "./listener.js";
 import { mediaArchive, mediaArchiveCheck, mediaArchiveMove, mediaArchiveTimer } from "./media-archive.js";
@@ -85,7 +86,7 @@ import { topic } from "./topic.js";
  * subset of its fields, never a renamed one. Commands move onto these one by one; until then, a schema
  * is the target, not a description of today's output.
  */
-export { account, accountChange, accountPrivacy, accountPrivacyChange, accountProfile, accountSession, adminReport, agenda, analysisConsent, analysisConsentRevocation, attachment, attachmentBytes, attachmentExtraction, attachmentTextChange, automaticTags, botAdmin, botMenuEntry, botProfile, botSeenChat, botTemplate, botWebhook, cachedChatMetadata, callRecord, chart, chat, chatAdminChange, chatArchive, chatEvent, chatFolderChange, chatFolderOrder, chatFolderRemoval, chatGroupChange, chatInspection, chatInvite, chatInviteChange, chatMembersChange, chatMembersFetch, chatMetadata, chatMetadataRefresh, chatModeration, chatMuting, chatPin, chatRead, chatRemoval, chatRequestChange, chatRules, chatSender, chatStats, chatTracking, chatUnread, contact, contactActivity, contactAlias, contactCheck, contactContext, contactImport, contactLookup, contactNote, contactNoteRemoval, contactPreparation, contactProfile, contactStateChange, contactSync, contactUpdate, conversation, conversationBatch, conversationBatchStatus, conversationBuildResult, conversationChange, conversationDetails, conversationEmbedding, conversationEmbeddingStatus, conversationHit, conversationPreparation, conversationReadiness, counterRefresh, counters, document, documentLink, endedAccountSessions, evidence, evidencePacket, fact, folder, hit, identity, imageEmbedding, inviteLink, job, joinRequest, linkedPerson, mediaArchive, mediaArchiveCheck, mediaArchiveMove, mediaArchiveTimer, meeting, meetingProjectCandidates, meetingSeriesInventory, member, memory, mention, mentionDecision, mentionDetails, mentionDomain, mentionRebuild, message, messageContext, messageCounts, messageDeletion, messageDownload, messageEvent, messageLink, messageLinks, messagePin, messageStar, messageSync, messageTranscript, messageWrite, model, modelKey, note, officialStats, person, place, poll, pollChange, pollVote, ranking, reactionChange, recipient, recipientAdded, recipientChange, recipientOff, recipientRemoved, recordedRun, reference, relationship, removedModelKey, retention, runDetails, runHit, runLocation, savedSearch, scheduledJob, searchHistoryClear, sendAttempt, serveSummary, stickerInventory, storeBackup, storeChatStatus, storeCheck, storeClear, storeCopyRemoval, storeDecrypt, storedModelKey, storeExport, storeGapPlan, storeGapRepair, storeInfo, storeJobCancel, storeJobClear, storeJobDetails, storeJobRetry, storeMigration, storeReindex, storeRepair, storeReset, storeRestore, tagChange, tagging, task, taskCard, taskCategories, taskClosed, taskCreated, taskLinks, taskMerge, taskPair, taskScan, taskSimilar, taskStats, taskUnmerge, topic, trackedChat, trackedChatHistory, watchedMessage, watchItem, };
+export { account, accountChange, accountPrivacy, accountPrivacyChange, accountProfile, accountSession, adminReport, agenda, analysisConsent, analysisConsentRevocation, attachment, attachmentBytes, attachmentExtraction, attachmentTextChange, automaticTags, botAdmin, botMenuEntry, botProfile, botSeenChat, botTemplate, botWebhook, cachedChatMetadata, callRecord, chart, chat, chatAdminChange, chatArchive, chatEvent, chatFolderChange, chatFolderOrder, chatFolderRemoval, chatGroupChange, chatInspection, chatInvite, chatInviteChange, chatMembersChange, chatMembersFetch, chatMetadata, chatMetadataRefresh, chatModeration, chatMuting, chatPin, chatRead, chatRemoval, chatRequestChange, chatRules, chatSender, chatStats, chatTracking, chatUnread, contact, contactActivity, contactAlias, contactCheck, contactContext, contactImport, contactLookup, contactNote, contactNoteRemoval, contactPreparation, contactProfile, contactStateChange, contactSync, contactUpdate, conversation, conversationBatch, conversationBatchStatus, conversationBuildResult, conversationChange, conversationDetails, conversationEmbedding, conversationEmbeddingStatus, conversationHit, conversationPreparation, conversationReadiness, counterRefresh, counters, document, documentLink, endedAccountSessions, evidence, evidencePacket, fact, folder, hit, identity, imageEmbedding, inviteLink, job, joinRequest, linkedPerson, mediaArchive, mediaArchiveCheck, mediaArchiveMove, mediaArchiveTimer, meeting, meetingProjectCandidates, meetingSeriesInventory, member, memory, mention, mentionDecision, mentionDetails, mentionDomain, mentionRebuild, message, messageContext, messageCounts, messageDeletion, messageDownload, messageEvent, messageLink, messageLinks, messagePin, messageStar, messageSync, messageTranscript, messageWrite, model, modelKey, note, officialStats, organization, person, place, poll, pollChange, pollVote, project, ranking, reactionChange, recipient, recipientAdded, recipientChange, recipientOff, recipientRemoved, recordedRun, reference, relationship, reminder, removedModelKey, retention, runDetails, runHit, runLocation, savedSearch, scheduledJob, searchHistoryClear, sendAttempt, serveSummary, stickerInventory, storeBackup, storeChatStatus, storeCheck, storeClear, storeCopyRemoval, storeDecrypt, storedModelKey, storeExport, storeGapPlan, storeGapRepair, storeInfo, storeJobCancel, storeJobClear, storeJobDetails, storeJobRetry, storeMigration, storeReindex, storeRepair, storeReset, storeRestore, tagChange, tagging, task, taskCard, taskCategories, taskClosed, taskCreated, taskLinks, taskMerge, taskPair, taskScan, taskSimilar, taskStats, taskUnmerge, topic, trackedChat, trackedChatHistory, watchedMessage, watchItem, };
 export declare const ENTITIES: {
     readonly meeting_ingestion: v.StrictObjectSchema<{
         readonly meetings: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
@@ -4742,6 +4743,33 @@ export declare const ENTITIES: {
         readonly account: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
         readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
     }, undefined>;
+    readonly organization: v.StrictObjectSchema<{
+        readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+        readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
+        readonly kind: v.PicklistSchema<["company", "team", "family", "community"], undefined>;
+        readonly name: v.StringSchema<undefined>;
+        readonly scope: v.PicklistSchema<["personal", "work"], undefined>;
+        readonly created_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+    }, undefined>;
+    readonly project: v.StrictObjectSchema<{
+        readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+        readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
+        readonly key: v.StringSchema<undefined>;
+        readonly name: v.StringSchema<undefined>;
+        readonly type: v.PicklistSchema<["work", "client", "personal", "oss", "other"], undefined>;
+        readonly organization_id: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+        readonly scope: v.PicklistSchema<["personal", "work"], undefined>;
+        readonly created_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+    }, undefined>;
+    readonly reminder: v.StrictObjectSchema<{
+        readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+        readonly task: v.StringSchema<undefined>;
+        readonly due_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+        readonly timezone: v.StringSchema<undefined>;
+        readonly state: v.PicklistSchema<["pending", "leased", "delivered", "cancelled"], undefined>;
+        readonly revision: v.NumberSchema<undefined>;
+        readonly receipt: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>;
     readonly bot_profile: v.StrictObjectSchema<{
         readonly name: v.StringSchema<undefined>;
         readonly token: v.StringSchema<undefined>;

package/dist/entities/index.js

@@ -41,6 +41,7 @@ import { imageEmbedding } from "./image-embedding.js";
 import { inviteLink } from "./invite-link.js";
 import { job } from "./job.js";
 import { joinRequest } from "./join-request.js";
+import { organization, project, reminder } from "./knowledge-lists.js";
 import { botAdmin, botMenuEntry, botProfile, botSeenChat, botTemplate, botWebhook, callRecord, scheduledJob, stickerInventory, } from "./list-results.js";
 import { messageEvent, serveSummary, watchedMessage, watchItem } from "./listener.js";
 import { mediaArchive, mediaArchiveCheck, mediaArchiveMove, mediaArchiveTimer } from "./media-archive.js";
@@ -91,7 +92,7 @@ import { topic } from "./topic.js";
  * subset of its fields, never a renamed one. Commands move onto these one by one; until then, a schema
  * is the target, not a description of today's output.
  */
-export { account, accountChange, accountPrivacy, accountPrivacyChange, accountProfile, accountSession, adminReport, agenda, analysisConsent, analysisConsentRevocation, attachment, attachmentBytes, attachmentExtraction, attachmentTextChange, automaticTags, botAdmin, botMenuEntry, botProfile, botSeenChat, botTemplate, botWebhook, cachedChatMetadata, callRecord, chart, chat, chatAdminChange, chatArchive, chatEvent, chatFolderChange, chatFolderOrder, chatFolderRemoval, chatGroupChange, chatInspection, chatInvite, chatInviteChange, chatMembersChange, chatMembersFetch, chatMetadata, chatMetadataRefresh, chatModeration, chatMuting, chatPin, chatRead, chatRemoval, chatRequestChange, chatRules, chatSender, chatStats, chatTracking, chatUnread, contact, contactActivity, contactAlias, contactCheck, contactContext, contactImport, contactLookup, contactNote, contactNoteRemoval, contactPreparation, contactProfile, contactStateChange, contactSync, contactUpdate, conversation, conversationBatch, conversationBatchStatus, conversationBuildResult, conversationChange, conversationDetails, conversationEmbedding, conversationEmbeddingStatus, conversationHit, conversationPreparation, conversationReadiness, counterRefresh, counters, document, documentLink, endedAccountSessions, evidence, evidencePacket, fact, folder, hit, identity, imageEmbedding, inviteLink, job, joinRequest, linkedPerson, mediaArchive, mediaArchiveCheck, mediaArchiveMove, mediaArchiveTimer, meeting, meetingProjectCandidates, meetingSeriesInventory, member, memory, mention, mentionDecision, mentionDetails, mentionDomain, mentionRebuild, message, messageContext, messageCounts, messageDeletion, messageDownload, messageEvent, messageLink, messageLinks, messagePin, messageStar, messageSync, messageTranscript, messageWrite, model, modelKey, note, officialStats, person, place, poll, pollChange, pollVote, ranking, reactionChange, recipient, recipientAdded, recipientChange, recipientOff, recipientRemoved, recordedRun, reference, relationship, removedModelKey, retention, runDetails, runHit, runLocation, savedSearch, scheduledJob, searchHistoryClear, sendAttempt, serveSummary, stickerInventory, storeBackup, storeChatStatus, storeCheck, storeClear, storeCopyRemoval, storeDecrypt, storedModelKey, storeExport, storeGapPlan, storeGapRepair, storeInfo, storeJobCancel, storeJobClear, storeJobDetails, storeJobRetry, storeMigration, storeReindex, storeRepair, storeReset, storeRestore, tagChange, tagging, task, taskCard, taskCategories, taskClosed, taskCreated, taskLinks, taskMerge, taskPair, taskScan, taskSimilar, taskStats, taskUnmerge, topic, trackedChat, trackedChatHistory, watchedMessage, watchItem, };
+export { account, accountChange, accountPrivacy, accountPrivacyChange, accountProfile, accountSession, adminReport, agenda, analysisConsent, analysisConsentRevocation, attachment, attachmentBytes, attachmentExtraction, attachmentTextChange, automaticTags, botAdmin, botMenuEntry, botProfile, botSeenChat, botTemplate, botWebhook, cachedChatMetadata, callRecord, chart, chat, chatAdminChange, chatArchive, chatEvent, chatFolderChange, chatFolderOrder, chatFolderRemoval, chatGroupChange, chatInspection, chatInvite, chatInviteChange, chatMembersChange, chatMembersFetch, chatMetadata, chatMetadataRefresh, chatModeration, chatMuting, chatPin, chatRead, chatRemoval, chatRequestChange, chatRules, chatSender, chatStats, chatTracking, chatUnread, contact, contactActivity, contactAlias, contactCheck, contactContext, contactImport, contactLookup, contactNote, contactNoteRemoval, contactPreparation, contactProfile, contactStateChange, contactSync, contactUpdate, conversation, conversationBatch, conversationBatchStatus, conversationBuildResult, conversationChange, conversationDetails, conversationEmbedding, conversationEmbeddingStatus, conversationHit, conversationPreparation, conversationReadiness, counterRefresh, counters, document, documentLink, endedAccountSessions, evidence, evidencePacket, fact, folder, hit, identity, imageEmbedding, inviteLink, job, joinRequest, linkedPerson, mediaArchive, mediaArchiveCheck, mediaArchiveMove, mediaArchiveTimer, meeting, meetingProjectCandidates, meetingSeriesInventory, member, memory, mention, mentionDecision, mentionDetails, mentionDomain, mentionRebuild, message, messageContext, messageCounts, messageDeletion, messageDownload, messageEvent, messageLink, messageLinks, messagePin, messageStar, messageSync, messageTranscript, messageWrite, model, modelKey, note, officialStats, organization, person, place, poll, pollChange, pollVote, project, ranking, reactionChange, recipient, recipientAdded, recipientChange, recipientOff, recipientRemoved, recordedRun, reference, relationship, reminder, removedModelKey, retention, runDetails, runHit, runLocation, savedSearch, scheduledJob, searchHistoryClear, sendAttempt, serveSummary, stickerInventory, storeBackup, storeChatStatus, storeCheck, storeClear, storeCopyRemoval, storeDecrypt, storedModelKey, storeExport, storeGapPlan, storeGapRepair, storeInfo, storeJobCancel, storeJobClear, storeJobDetails, storeJobRetry, storeMigration, storeReindex, storeRepair, storeReset, storeRestore, tagChange, tagging, task, taskCard, taskCategories, taskClosed, taskCreated, taskLinks, taskMerge, taskPair, taskScan, taskSimilar, taskStats, taskUnmerge, topic, trackedChat, trackedChatHistory, watchedMessage, watchItem, };
 export const ENTITIES = {
     sync_progress: syncProgress,
     ...MEETING_RESULT_ENTITIES,
@@ -167,6 +168,9 @@ export const ENTITIES = {
     account_privacy: accountPrivacy,
     account_privacy_change: accountPrivacyChange,
     account_profile: accountProfile,
+    organization,
+    project,
+    reminder,
     bot_profile: botProfile,
     bot_template: botTemplate,
     bot_seen_chat: botSeenChat,

package/dist/entities/knowledge-lists.d.ts

@@ -0,0 +1,28 @@
+import * as v from "valibot";
+export declare const organization: v.StrictObjectSchema<{
+    readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
+    readonly kind: v.PicklistSchema<["company", "team", "family", "community"], undefined>;
+    readonly name: v.StringSchema<undefined>;
+    readonly scope: v.PicklistSchema<["personal", "work"], undefined>;
+    readonly created_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+}, undefined>;
+export declare const project: v.StrictObjectSchema<{
+    readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
+    readonly key: v.StringSchema<undefined>;
+    readonly name: v.StringSchema<undefined>;
+    readonly type: v.PicklistSchema<["work", "client", "personal", "oss", "other"], undefined>;
+    readonly organization_id: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+    readonly scope: v.PicklistSchema<["personal", "work"], undefined>;
+    readonly created_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+}, undefined>;
+export declare const reminder: v.StrictObjectSchema<{
+    readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly task: v.StringSchema<undefined>;
+    readonly due_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+    readonly timezone: v.StringSchema<undefined>;
+    readonly state: v.PicklistSchema<["pending", "leased", "delivered", "cancelled"], undefined>;
+    readonly revision: v.NumberSchema<undefined>;
+    readonly receipt: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;

package/dist/entities/knowledge-lists.js

@@ -0,0 +1,29 @@
+import * as v from "valibot";
+import { id, reference, text, time } from "./fields.js";
+export const organization = v.strictObject({
+    id,
+    ref: reference,
+    kind: v.picklist(["company", "team", "family", "community"]),
+    name: text,
+    scope: v.picklist(["personal", "work"]),
+    created_at: time,
+});
+export const project = v.strictObject({
+    id,
+    ref: reference,
+    key: text,
+    name: text,
+    type: v.picklist(["work", "client", "personal", "oss", "other"]),
+    organization_id: v.nullable(id),
+    scope: v.picklist(["personal", "work"]),
+    created_at: time,
+});
+export const reminder = v.strictObject({
+    id,
+    task: text,
+    due_at: time,
+    timezone: text,
+    state: v.picklist(["pending", "leased", "delivered", "cancelled"]),
+    revision: v.number(),
+    receipt: v.nullable(text),
+});

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/index.d.ts

@@ -8,6 +8,7 @@ export { parseMarkdownSpans } from "./domain/markdown-spans.js";
 export type { MessageLink, MessagePermalink } from "./domain/message-link.js";
 export type * from "./domain/models.js";
 export { countedPoll } from "./domain/polls.js";
+export { isKind, KINDS, type Kind, kindIn, kindOf, PROVIDERS, type ProviderEntry, providerNamed, providers, UNKNOWN_PROVIDER, useProviders, } from "./domain/providers.js";
 export type { RankingGraphEvidence, RankingGraphLink } from "./domain/rankings-graph.js";
 export type { RankingComponent, RankingInput, RankingMeasure, RankingOptions, RankingTarget, RankingWeights, ScorePreset, } from "./domain/rankings-options.js";
 export { rankingOptions } from "./domain/rankings-options.js";

package/dist/index.js

@@ -5,6 +5,7 @@ export { formatLocator, isLocator, parseLocator } from "./domain/locator.js";
 export { parseMarkdown } from "./domain/markdown.js";
 export { parseMarkdownSpans } from "./domain/markdown-spans.js";
 export { countedPoll } from "./domain/polls.js";
+export { isKind, KINDS, kindIn, kindOf, PROVIDERS, providerNamed, providers, UNKNOWN_PROVIDER, useProviders, } from "./domain/providers.js";
 export { rankingOptions } from "./domain/rankings-options.js";
 export { canonicalReference, formatReference, parseReference } from "./domain/references.js";
 export { normalizeTag, TAG_TYPES } from "./domain/tags.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";

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 {};