@aria-cli/tools 1.0.0

package/dist/providers/router.js

@@ -0,0 +1,97 @@
+import { log } from "@aria/types";
+import { resolveSearchProviderEnv } from "./search-provider.js";
+export class SearchProviderRouter {
+    _providers;
+    env;
+    constructor(_providers, env = process.env) {
+        this._providers = _providers;
+        this.env = env;
+    }
+    /**
+     * Resolves the best available search provider.
+     * Priority:
+     * 1. Explicit override via ARIA_SEARCH_PROVIDER env var
+     * 2. Highest-priority available provider (lowest priority number)
+     * @throws {Error} if no providers are available or override is invalid
+     */
+    resolve() {
+        const env = resolveSearchProviderEnv(this.env);
+        // 1. Check for explicit override
+        const override = env.ARIA_SEARCH_PROVIDER;
+        if (override) {
+            const provider = this._providers.find((p) => p.name === override);
+            if (!provider) {
+                throw new Error(`ARIA_SEARCH_PROVIDER override '${override}' not found in provider registry`);
+            }
+            // Verify the overridden provider is actually available (e.g., has API key)
+            if (!provider.isAvailable()) {
+                // Fall through to default priority-based routing
+                log.debug(`[SearchProviderRouter] ARIA_SEARCH_PROVIDER override '${override}' is not available, falling back to priority routing`);
+            }
+            else {
+                return provider;
+            }
+        }
+        // 2. Select first available provider by priority (lower number = higher priority)
+        const sorted = [...this._providers].sort((a, b) => a.priority - b.priority);
+        const available = sorted.find((p) => p.isAvailable());
+        if (!available) {
+            throw new Error("No search providers available. Set at least one API key (BRAVE_API_KEY, TAVILY_API_KEY, etc.)");
+        }
+        return available;
+    }
+    /**
+     * Performs a search with automatic fallback.
+     * Tries providers in priority order (resolved provider first, then others).
+     * Circuit breaker: stops at first successful response.
+     * @throws {AggregateError} if all providers fail
+     */
+    async search(query, options) {
+        if (options?.signal?.aborted) {
+            throw new Error("Search aborted");
+        }
+        const env = resolveSearchProviderEnv(this.env);
+        // Get all available providers sorted by priority
+        const availableProviders = [...this._providers]
+            .filter((p) => p.isAvailable())
+            .sort((a, b) => a.priority - b.priority);
+        if (availableProviders.length === 0) {
+            throw new Error("No search providers available");
+        }
+        // Honor ARIA_SEARCH_PROVIDER override: try the override provider first
+        const override = env.ARIA_SEARCH_PROVIDER;
+        if (override) {
+            const overrideProvider = availableProviders.find((p) => p.name === override);
+            if (overrideProvider) {
+                // Move override provider to front of the list
+                const reordered = [
+                    overrideProvider,
+                    ...availableProviders.filter((p) => p.name !== override),
+                ];
+                availableProviders.length = 0;
+                availableProviders.push(...reordered);
+            }
+        }
+        const errors = [];
+        // Try each provider in order
+        for (const provider of availableProviders) {
+            if (options?.signal?.aborted) {
+                throw new Error("Search aborted");
+            }
+            try {
+                const results = await provider.search(query, options);
+                return results; // Circuit breaker: return on first success
+            }
+            catch (error) {
+                if (options?.signal?.aborted) {
+                    throw error instanceof Error ? error : new Error("Search aborted");
+                }
+                errors.push(error instanceof Error ? error : new Error(`Unknown error from ${provider.name}`));
+                // Continue to next provider
+            }
+        }
+        // All providers failed
+        throw new AggregateError(errors, `All search providers failed (tried ${availableProviders.length} providers)`);
+    }
+}
+//# sourceMappingURL=router.js.map

package/dist/providers/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../../src/providers/router.ts"],"names":[],"mappings":"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"}

package/dist/providers/search-provider.d.ts

@@ -0,0 +1,36 @@
+export interface SearchOptions {
+    limit?: number;
+    topic?: "general" | "news";
+    domains?: string[];
+    excludeDomains?: string[];
+    timeRange?: "day" | "week" | "month" | "year";
+    signal?: AbortSignal;
+}
+export interface SearchResult {
+    title: string;
+    url: string;
+    content: string;
+    score?: number;
+    publishedDate?: string;
+}
+export interface SearchProviderEnv {
+    ARIA_SEARCH_PROVIDER?: string;
+    BRAVE_API_KEY?: string;
+    FIRECRAWL_API_KEY?: string;
+    EXA_API_KEY?: string;
+    TAVILY_API_KEY?: string;
+    JINA_API_KEY?: string;
+}
+export declare function resolveSearchProviderEnv(env?: SearchProviderEnv | Record<string, string | undefined>): SearchProviderEnv;
+export interface SearchProvider {
+    readonly name: string;
+    readonly requiresApiKey: boolean;
+    readonly priority: number;
+    isAvailable(): boolean;
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+}
+export declare function createProviderAbortSignal(timeoutMs: number, callerSignal?: AbortSignal): {
+    signal: AbortSignal;
+    cleanup: () => void;
+};
+//# sourceMappingURL=search-provider.d.ts.map

package/dist/providers/search-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-provider.d.ts","sourceRoot":"","sources":["../../src/providers/search-provider.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;IAC9C,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,wBAAwB,CACtC,GAAG,GAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACxE,iBAAiB,CASnB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,WAAW,IAAI,OAAO,CAAC;IACvB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CACzE;AAED,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,WAAW,GACzB;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAuB9C"}

package/dist/providers/search-provider.js

@@ -0,0 +1,33 @@
+export function resolveSearchProviderEnv(env = process.env) {
+    return {
+        ARIA_SEARCH_PROVIDER: env.ARIA_SEARCH_PROVIDER,
+        BRAVE_API_KEY: env.BRAVE_API_KEY,
+        FIRECRAWL_API_KEY: env.FIRECRAWL_API_KEY,
+        EXA_API_KEY: env.EXA_API_KEY,
+        TAVILY_API_KEY: env.TAVILY_API_KEY,
+        JINA_API_KEY: env.JINA_API_KEY,
+    };
+}
+export function createProviderAbortSignal(timeoutMs, callerSignal) {
+    const controller = new AbortController();
+    const onCallerAbort = () => controller.abort();
+    if (callerSignal) {
+        if (callerSignal.aborted) {
+            controller.abort();
+        }
+        else {
+            callerSignal.addEventListener("abort", onCallerAbort, { once: true });
+        }
+    }
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            clearTimeout(timeout);
+            if (callerSignal) {
+                callerSignal.removeEventListener("abort", onCallerAbort);
+            }
+        },
+    };
+}
+//# sourceMappingURL=search-provider.js.map

package/dist/providers/search-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-provider.js","sourceRoot":"","sources":["../../src/providers/search-provider.ts"],"names":[],"mappings":"AA0BA,MAAM,UAAU,wBAAwB,CACtC,MAA8D,OAAO,CAAC,GAAG;IAEzE,OAAO;QACL,oBAAoB,EAAE,GAAG,CAAC,oBAAoB;QAC9C,aAAa,EAAE,GAAG,CAAC,aAAa;QAChC,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;QACxC,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,cAAc,EAAE,GAAG,CAAC,cAAc;QAClC,YAAY,EAAE,GAAG,CAAC,YAAY;KAC/B,CAAC;AACJ,CAAC;AAUD,MAAM,UAAU,yBAAyB,CACvC,SAAiB,EACjB,YAA0B;IAE1B,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,aAAa,GAAG,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;IAE/C,IAAI,YAAY,EAAE,CAAC;QACjB,IAAI,YAAY,CAAC,OAAO,EAAE,CAAC;YACzB,UAAU,CAAC,KAAK,EAAE,CAAC;QACrB,CAAC;aAAM,CAAC;YACN,YAAY,CAAC,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;IAEhE,OAAO;QACL,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,OAAO,EAAE,GAAG,EAAE;YACZ,YAAY,CAAC,OAAO,CAAC,CAAC;YACtB,IAAI,YAAY,EAAE,CAAC;gBACjB,YAAY,CAAC,mBAAmB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;YAC3D,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/providers/tavily.d.ts

@@ -0,0 +1,11 @@
+import type { SearchProvider, SearchOptions, SearchResult, SearchProviderEnv } from "./search-provider.js";
+export declare class TavilySearchProvider implements SearchProvider {
+    private readonly env;
+    readonly name = "tavily";
+    readonly requiresApiKey = true;
+    readonly priority = 4;
+    constructor(env?: SearchProviderEnv | Record<string, string | undefined>);
+    isAvailable(): boolean;
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+}
+//# sourceMappingURL=tavily.d.ts.map

package/dist/providers/tavily.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tavily.d.ts","sourceRoot":"","sources":["../../src/providers/tavily.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACb,YAAY,EACZ,iBAAiB,EAClB,MAAM,sBAAsB,CAAC;AAG9B,qBAAa,oBAAqB,YAAW,cAAc;IAMvD,OAAO,CAAC,QAAQ,CAAC,GAAG;IALtB,QAAQ,CAAC,IAAI,YAAY;IACzB,QAAQ,CAAC,cAAc,QAAQ;IAC/B,QAAQ,CAAC,QAAQ,KAAK;gBAGH,GAAG,GAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe;IAG5F,WAAW,IAAI,OAAO;IAKhB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;CAmD9E"}

package/dist/providers/tavily.js

@@ -0,0 +1,55 @@
+import { createProviderAbortSignal, resolveSearchProviderEnv } from "./search-provider.js";
+export class TavilySearchProvider {
+    env;
+    name = "tavily";
+    requiresApiKey = true;
+    priority = 4;
+    constructor(env = process.env) {
+        this.env = env;
+    }
+    isAvailable() {
+        const apiKey = resolveSearchProviderEnv(this.env).TAVILY_API_KEY;
+        return Boolean(apiKey && apiKey.trim().length > 0);
+    }
+    async search(query, options) {
+        const apiKey = resolveSearchProviderEnv(this.env).TAVILY_API_KEY;
+        if (!apiKey) {
+            throw new Error("TAVILY_API_KEY environment variable is not set");
+        }
+        const limit = options?.limit ?? 5;
+        const body = {
+            api_key: apiKey,
+            query,
+            max_results: limit,
+            ...(options?.topic && { topic: options.topic }),
+            ...(options?.domains && { include_domains: options.domains }),
+            ...(options?.excludeDomains && { exclude_domains: options.excludeDomains }),
+        };
+        const { signal, cleanup } = createProviderAbortSignal(30_000, options?.signal);
+        try {
+            const response = await fetch("https://api.tavily.com/search", {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(body),
+                signal,
+            });
+            if (!response.ok) {
+                throw new Error(`Tavily Search API error: ${response.status} ${response.statusText}`);
+            }
+            const json = await response.json();
+            const results = (json.results || []);
+            return results.map((r) => ({
+                title: r.title,
+                url: r.url,
+                content: r.content,
+                score: r.score,
+            }));
+        }
+        finally {
+            cleanup();
+        }
+    }
+}
+//# sourceMappingURL=tavily.js.map

package/dist/providers/tavily.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tavily.js","sourceRoot":"","sources":["../../src/providers/tavily.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,yBAAyB,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAE3F,MAAM,OAAO,oBAAoB;IAMZ;IALV,IAAI,GAAG,QAAQ,CAAC;IAChB,cAAc,GAAG,IAAI,CAAC;IACtB,QAAQ,GAAG,CAAC,CAAC;IAEtB,YACmB,MAA8D,OAAO,CAAC,GAAG;QAAzE,QAAG,GAAH,GAAG,CAAsE;IACzF,CAAC;IAEJ,WAAW;QACT,MAAM,MAAM,GAAG,wBAAwB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC;QACjE,OAAO,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACrD,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,OAAuB;QACjD,MAAM,MAAM,GAAG,wBAAwB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC;QACjE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACpE,CAAC;QAED,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,CAAC,CAAC;QAElC,MAAM,IAAI,GAAG;YACX,OAAO,EAAE,MAAM;YACf,KAAK;YACL,WAAW,EAAE,KAAK;YAClB,GAAG,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;YAC/C,GAAG,CAAC,OAAO,EAAE,OAAO,IAAI,EAAE,eAAe,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;YAC7D,GAAG,CAAC,OAAO,EAAE,cAAc,IAAI,EAAE,eAAe,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC;SAC5E,CAAC;QAEF,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,yBAAyB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAE/E,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,+BAA+B,EAAE;gBAC5D,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,cAAc,EAAE,kBAAkB;iBACnC;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;gBAC1B,MAAM;aACP,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,IAAI,KAAK,CAAC,4BAA4B,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;YACxF,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnC,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAKjC,CAAC;YAEH,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBACzB,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,GAAG,EAAE,CAAC,CAAC,GAAG;gBACV,OAAO,EAAE,CAAC,CAAC,OAAO;gBAClB,KAAK,EAAE,CAAC,CAAC,KAAK;aACf,CAAC,CAAC,CAAC;QACN,CAAC;gBAAS,CAAC;YACT,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;CACF"}

package/dist/quip/desktop-session.d.ts

@@ -0,0 +1,70 @@
+export interface QuipDocumentSummary {
+    threadId: string;
+    title: string;
+    link: string;
+    updatedUsec: number;
+    createdUsec: number;
+}
+export interface QuipDocumentListResult {
+    documents: QuipDocumentSummary[];
+}
+export interface QuipDocumentDetail {
+    threadId: string;
+    title: string;
+    link: string;
+    markdown: string;
+    updatedUsec: number;
+    createdUsec: number;
+    authorId: string;
+}
+export interface QuipCreateResult {
+    threadId: string;
+    title: string;
+    link: string;
+}
+export interface QuipCommentView {
+    id: string;
+    authorId: string;
+    authorName: string;
+    text: string;
+    createdUsec: number;
+}
+export interface QuipCommentResult {
+    threadId: string;
+    commentId: string;
+}
+export interface QuipCommentListResult {
+    threadId: string;
+    comments: QuipCommentView[];
+}
+export interface QuipDesktopClient {
+    getUserId(): string;
+    listRecentDocuments(input: {
+        limit?: number;
+    }): Promise<QuipDocumentListResult>;
+    searchDocuments(input: {
+        query: string;
+        limit?: number;
+    }): Promise<QuipDocumentListResult>;
+    readDocument(input: {
+        threadId: string;
+    }): Promise<QuipDocumentDetail>;
+    createDocument(input: {
+        title: string;
+        content: string;
+        format?: "markdown" | "html";
+        folderId?: string;
+    }): Promise<QuipCreateResult>;
+    addComment(input: {
+        threadId: string;
+        content: string;
+    }): Promise<QuipCommentResult>;
+    listComments(input: {
+        threadId: string;
+    }): Promise<QuipCommentListResult>;
+    close(): Promise<void>;
+}
+export declare function createQuipDesktopClient(options?: {
+    bootstrapTimeoutMs?: number;
+}): Promise<QuipDesktopClient>;
+//# sourceMappingURL=desktop-session.d.ts.map

package/dist/quip/desktop-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop-session.d.ts","sourceRoot":"","sources":["../../src/quip/desktop-session.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,mBAAmB,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAID,MAAM,WAAW,iBAAiB;IAChC,SAAS,IAAI,MAAM,CAAC;IAEpB,mBAAmB,CAAC,KAAK,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAEhF,eAAe,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAE3F,YAAY,CAAC,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAEvE,cAAc,CAAC,KAAK,EAAE;QACpB,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;QAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAE9B,UAAU,CAAC,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAErF,YAAY,CAAC,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAE1E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AA6KD,wBAAsB,uBAAuB,CAAC,OAAO,CAAC,EAAE;IACtD,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAoL7B"}

package/dist/quip/desktop-session.js

@@ -0,0 +1,318 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const QUIP_API_BASE = "https://platform.quip.com/1";
+const DEFAULT_BOOTSTRAP_TIMEOUT_MS = 30_000;
+// ── HTML → Markdown conversion (regex-based, no deps) ───────────────
+function htmlToMarkdown(html) {
+    let md = html;
+    // Block elements first
+    md = md.replace(/<h1[^>]*>([\s\S]*?)<\/h1>/gi, "\n# $1\n");
+    md = md.replace(/<h2[^>]*>([\s\S]*?)<\/h2>/gi, "\n## $1\n");
+    md = md.replace(/<h3[^>]*>([\s\S]*?)<\/h3>/gi, "\n### $1\n");
+    md = md.replace(/<h4[^>]*>([\s\S]*?)<\/h4>/gi, "\n#### $1\n");
+    md = md.replace(/<br\s*\/?>/gi, "\n");
+    md = md.replace(/<\/p>/gi, "\n\n");
+    md = md.replace(/<p[^>]*>/gi, "");
+    md = md.replace(/<li[^>]*>([\s\S]*?)<\/li>/gi, "- $1\n");
+    md = md.replace(/<\/?(ul|ol)[^>]*>/gi, "\n");
+    md = md.replace(/<blockquote[^>]*>([\s\S]*?)<\/blockquote>/gi, (_, content) => content
+        .split("\n")
+        .map((line) => `> ${line}`)
+        .join("\n"));
+    md = md.replace(/<pre[^>]*>([\s\S]*?)<\/pre>/gi, "\n```\n$1\n```\n");
+    md = md.replace(/<code[^>]*>([\s\S]*?)<\/code>/gi, "`$1`");
+    // Inline formatting
+    md = md.replace(/<(b|strong)[^>]*>([\s\S]*?)<\/\1>/gi, "**$2**");
+    md = md.replace(/<(i|em)[^>]*>([\s\S]*?)<\/\1>/gi, "*$2*");
+    md = md.replace(/<(s|del|strike)[^>]*>([\s\S]*?)<\/\1>/gi, "~~$2~~");
+    md = md.replace(/<a\s+href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi, "[$2]($1)");
+    // Strip remaining tags
+    md = md.replace(/<[^>]+>/g, "");
+    // Decode common HTML entities
+    md = md.replace(/&amp;/g, "&");
+    md = md.replace(/&lt;/g, "<");
+    md = md.replace(/&gt;/g, ">");
+    md = md.replace(/&quot;/g, '"');
+    md = md.replace(/&#39;/g, "'");
+    md = md.replace(/&nbsp;/g, " ");
+    // Collapse excessive blank lines
+    md = md.replace(/\n{3,}/g, "\n\n");
+    return md.trim();
+}
+async function extractKeychainDesktopToken() {
+    try {
+        // Use python3 to parse the bplist from Keychain — macOS ships python3
+        // and plutil requires a temp file; python3 one-liner is cleaner.
+        const { stdout } = await execFileAsync("python3", [
+            "-c",
+            `
+import subprocess, plistlib, sys
+from datetime import datetime, timedelta
+try:
+    raw = subprocess.check_output([
+        'security', 'find-generic-password', '-s', 'Quip', '-a', 'MultiAccount', '-g'
+    ], stderr=subprocess.STDOUT).decode()
+    import re
+    hex_match = re.search(r'password: 0x([0-9A-Fa-f]+)', raw)
+    if not hex_match:
+        sys.exit(1)
+    data = bytes.fromhex(hex_match.group(1))
+    plist = plistlib.loads(data)
+    import json
+    for uid, info in plist.get('accounts', {}).items():
+        exp = info.get('session_expiration', 0)
+        exp_date = datetime(2001, 1, 1) + timedelta(seconds=exp)
+        if exp_date > datetime.now():
+            json.dump({"token": info["session_id"], "userId": uid}, sys.stdout)
+            sys.exit(0)
+    sys.exit(1)
+except:
+    sys.exit(1)
+`.trim(),
+        ]);
+        const parsed = JSON.parse(stdout.trim());
+        if (parsed.token && parsed.userId) {
+            return parsed;
+        }
+    }
+    catch {
+        // Keychain extraction failed — fall through
+    }
+    return null;
+}
+async function extractManualKeychainToken() {
+    try {
+        const { stdout } = await execFileAsync("security", [
+            "find-generic-password",
+            "-a",
+            "aria",
+            "-s",
+            "quip-token",
+            "-w",
+        ]);
+        const token = stdout.trim();
+        return token || null;
+    }
+    catch {
+        return null;
+    }
+}
+async function extractPlaywrightToken(timeoutMs) {
+    const playwright = await import("playwright");
+    const browser = await playwright.chromium.launch({ headless: true });
+    try {
+        const context = await browser.newContext();
+        const page = await context.newPage();
+        const tokenPromise = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                page.off("request", handleRequest);
+                reject(new Error("Timed out waiting for Quip API token via Playwright."));
+            }, timeoutMs);
+            const handleRequest = (request) => {
+                const url = request.url();
+                if (!url.includes("platform.quip.com"))
+                    return;
+                const authHeader = request.headers()["authorization"];
+                if (!authHeader?.startsWith("Bearer "))
+                    return;
+                clearTimeout(timer);
+                page.off("request", handleRequest);
+                resolve(authHeader.slice(7));
+            };
+            page.on("request", handleRequest);
+        });
+        await page.goto("https://quip.com", {
+            waitUntil: "domcontentloaded",
+            timeout: timeoutMs,
+        });
+        const token = await tokenPromise;
+        // Get user ID from /users/current
+        const resp = await context.request.get(`${QUIP_API_BASE}/users/current`, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        const userData = (await resp.json());
+        const userId = typeof userData.id === "string" ? userData.id : "unknown";
+        await page.close().catch(() => undefined);
+        await context.close().catch(() => undefined);
+        await browser.close().catch(() => undefined);
+        return { token, userId };
+    }
+    catch (error) {
+        await browser.close().catch(() => undefined);
+        throw error;
+    }
+}
+// ── Thread/document helpers ─────────────────────────────────────────
+function toDocumentSummary(thread) {
+    return {
+        threadId: typeof thread.id === "string" ? thread.id : "",
+        title: typeof thread.title === "string" ? thread.title : "",
+        link: typeof thread.link === "string" ? thread.link : "",
+        updatedUsec: typeof thread.updated_usec === "number" ? thread.updated_usec : 0,
+        createdUsec: typeof thread.created_usec === "number" ? thread.created_usec : 0,
+    };
+}
+// ── Client factory ──────────────────────────────────────────────────
+export async function createQuipDesktopClient(options) {
+    const timeoutMs = options?.bootstrapTimeoutMs ?? DEFAULT_BOOTSTRAP_TIMEOUT_MS;
+    // Priority 1: Keychain desktop token (auto from Quip desktop app)
+    let keychainResult = await extractKeychainDesktopToken();
+    // Priority 2: Playwright web session (SSO handles auth)
+    if (!keychainResult) {
+        try {
+            keychainResult = await extractPlaywrightToken(timeoutMs);
+        }
+        catch {
+            // Playwright extraction failed — fall through
+        }
+    }
+    // Priority 3: Manual keychain token
+    let token;
+    let userId;
+    if (keychainResult) {
+        token = keychainResult.token;
+        userId = keychainResult.userId;
+    }
+    else {
+        const manualToken = await extractManualKeychainToken();
+        if (!manualToken) {
+            throw new Error("No Quip token available. Install the Quip desktop app, or add a manual token:\n" +
+                '  security add-generic-password -a aria -s quip-token -w "<token>"\n' +
+                "Get a token from https://quip.com/dev/token");
+        }
+        token = manualToken;
+        userId = "unknown";
+    }
+    // Verify token and resolve userId if unknown
+    const invokeApi = async (method, endpoint, body) => {
+        const url = `${QUIP_API_BASE}${endpoint}`;
+        const headers = {
+            Authorization: `Bearer ${token}`,
+        };
+        const fetchOptions = { method, headers };
+        if (body) {
+            headers["Content-Type"] = "application/x-www-form-urlencoded";
+            fetchOptions.body = new URLSearchParams(Object.entries(body).map(([k, v]) => [k, String(v)])).toString();
+        }
+        const resp = await fetch(url, fetchOptions);
+        const text = await resp.text();
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            throw new Error(`Quip API ${endpoint} returned non-JSON (HTTP ${resp.status}).`);
+        }
+        if (!resp.ok) {
+            const errorCode = typeof json.error_code === "number" ? json.error_code : resp.status;
+            const errorMsg = typeof json.error_description === "string" ? json.error_description : `HTTP ${resp.status}`;
+            throw new Error(`Quip API ${endpoint} failed (${errorCode}): ${errorMsg}`);
+        }
+        return json;
+    };
+    // Resolve userId on first use if unknown
+    if (userId === "unknown") {
+        const user = await invokeApi("GET", "/users/current");
+        userId = typeof user.id === "string" ? user.id : "unknown";
+    }
+    return {
+        getUserId: () => userId,
+        listRecentDocuments: async ({ limit = 20 }) => {
+            const data = await invokeApi("GET", `/threads/recent?count=${Math.min(limit, 50)}`);
+            const threads = Array.isArray(data)
+                ? data
+                : typeof data === "object" && data !== null
+                    ? Object.values(data)
+                    : [];
+            const documents = [];
+            for (const entry of threads) {
+                if (!entry || typeof entry !== "object")
+                    continue;
+                const thread = "thread" in entry
+                    ? entry.thread
+                    : entry;
+                documents.push(toDocumentSummary(thread));
+            }
+            return { documents: documents.slice(0, limit) };
+        },
+        searchDocuments: async ({ query, limit = 20 }) => {
+            const params = new URLSearchParams({ query, count: String(Math.min(limit, 50)) });
+            const data = await invokeApi("GET", `/threads/search?${params}`);
+            const threads = Array.isArray(data)
+                ? data
+                : typeof data === "object" && data !== null
+                    ? Object.values(data)
+                    : [];
+            const documents = [];
+            for (const entry of threads) {
+                if (!entry || typeof entry !== "object")
+                    continue;
+                const thread = "thread" in entry
+                    ? entry.thread
+                    : entry;
+                documents.push(toDocumentSummary(thread));
+            }
+            return { documents: documents.slice(0, limit) };
+        },
+        readDocument: async ({ threadId }) => {
+            const data = await invokeApi("GET", `/threads/${threadId}`);
+            const thread = typeof data.thread === "object" && data.thread !== null
+                ? data.thread
+                : data;
+            const rawHtml = typeof data.html === "string" ? data.html : "";
+            return {
+                threadId: typeof thread.id === "string" ? thread.id : threadId,
+                title: typeof thread.title === "string" ? thread.title : "",
+                link: typeof thread.link === "string" ? thread.link : "",
+                markdown: htmlToMarkdown(rawHtml),
+                updatedUsec: typeof thread.updated_usec === "number" ? thread.updated_usec : 0,
+                createdUsec: typeof thread.created_usec === "number" ? thread.created_usec : 0,
+                authorId: typeof thread.author_id === "string" ? thread.author_id : "",
+            };
+        },
+        createDocument: async ({ title, content, format = "markdown", folderId }) => {
+            const body = { title, content, format };
+            if (folderId)
+                body.member_ids = folderId;
+            const data = await invokeApi("POST", "/threads/new-document", body);
+            const thread = typeof data.thread === "object" && data.thread !== null
+                ? data.thread
+                : data;
+            return {
+                threadId: typeof thread.id === "string" ? thread.id : "",
+                title: typeof thread.title === "string" ? thread.title : title,
+                link: typeof thread.link === "string" ? thread.link : "",
+            };
+        },
+        addComment: async ({ threadId, content }) => {
+            const data = await invokeApi("POST", "/messages/new", {
+                thread_id: threadId,
+                content,
+            });
+            return {
+                threadId,
+                commentId: typeof data.id === "string" ? data.id : "",
+            };
+        },
+        listComments: async ({ threadId }) => {
+            const data = await invokeApi("GET", `/messages/${threadId}`);
+            const rawMessages = Array.isArray(data) ? data : [];
+            const comments = rawMessages
+                .filter((m) => !!m && typeof m === "object")
+                .map((m) => ({
+                id: typeof m.id === "string" ? m.id : "",
+                authorId: typeof m.author_id === "string" ? m.author_id : "",
+                authorName: typeof m.author_name === "string" ? m.author_name : "",
+                text: typeof m.text === "string" ? m.text : "",
+                createdUsec: typeof m.created_usec === "number" ? m.created_usec : 0,
+            }));
+            return { threadId, comments };
+        },
+        close: async () => {
+            // No persistent resources to clean up (unlike Slack which keeps a browser open).
+            // Token-based client is stateless.
+        },
+    };
+}
+//# sourceMappingURL=desktop-session.js.map