@eightstate/escli 0.5.0

package/dist/services/docs.js

@@ -0,0 +1,303 @@
+import { readFileSync } from 'node:fs';
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ErrorCode } from '@eightstate/contracts/errors';
+import { ExitCodes } from '@eightstate/contracts/exit-codes';
+import { EscliError } from '../lib/escli-error.js';
+import { callWithRetry } from './credentials.js';
+const CONTEXT7_API = 'https://context7.com/api';
+const SEARCH_TTL_SECONDS = 86_400;
+const RESOLVE_TTL_SECONDS = 604_800;
+const DOCS_TTL_SECONDS = 86_400;
+const DEFAULT_TIMEOUT_MS = 30_000;
+export async function searchDocs(options) {
+    const name = options.libraryName;
+    const query = options.query || name;
+    const limit = options.limit || 10;
+    const cacheKey = `search:${name.toLowerCase()}:${query.toLowerCase()}`;
+    if (!options.refresh) {
+        const cached = await cacheRead('search', cacheKey);
+        if (cached)
+            return searchData(cached, limit, true);
+    }
+    const payload = await docsRequestJson(searchUrl(name, query));
+    await cacheWrite('search', cacheKey, payload, SEARCH_TTL_SECONDS);
+    return searchData(payload, limit, false);
+}
+export async function getDocs(options) {
+    const resolveKey = `resolve:${options.libraryName.toLowerCase()}:${options.query.toLowerCase()}`;
+    let libraryId;
+    if (!options.refresh) {
+        const cached = await cacheRead('resolve', resolveKey);
+        libraryId = cached?.id;
+    }
+    if (!libraryId) {
+        const payload = await docsRequestJson(searchUrl(options.libraryName, options.query));
+        const results = payload.results ?? [];
+        const pick = results.find((result) => result.state === 'finalized') ?? results[0];
+        if (!pick?.id) {
+            throw new EscliError(`no results for: ${options.libraryName}`, {
+                code: ErrorCode.DocsNoResults,
+                exitCode: ExitCodes.NotFound,
+            });
+        }
+        libraryId = pick.id;
+        await cacheWrite('resolve', resolveKey, { id: libraryId, name: options.libraryName }, RESOLVE_TTL_SECONDS);
+    }
+    const docs = await fetchDocs({ ...options, libraryId });
+    return { ...docs, operation: 'get' };
+}
+export async function fetchDocs(options) {
+    const cacheKey = `docs:${options.libraryId}:${options.query}:${options.tokens ?? 'undefined'}:${options.page ?? 'undefined'}:${options.topic ?? 'undefined'}`;
+    if (!options.refresh) {
+        const cached = await cacheRead('docs', cacheKey);
+        if (cached)
+            return docsData(cached.body ?? '', options.libraryId, options.query, true, 'fetch');
+    }
+    const response = await docsRequestText(contextUrl(options));
+    await cacheWrite('docs', cacheKey, { body: response }, DOCS_TTL_SECONDS);
+    return docsData(response, options.libraryId, options.query, false, 'fetch');
+}
+function searchData(payload, limit, cached) {
+    const results = (payload.results ?? []).slice(0, limit);
+    return { operation: 'search', cached, results, count: results.length };
+}
+function docsData(body, libraryId, query, cached, operation) {
+    return { operation, cached, library_id: libraryId, query, content: body };
+}
+async function docsRequestJson(url) {
+    const text = await docsRequestText(url);
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new EscliError(`invalid JSON response: ${error instanceof Error ? error.message : String(error)}`, {
+            code: ErrorCode.GateInvalidResponse,
+            exitCode: ExitCodes.Error,
+            details: text,
+        });
+    }
+}
+async function docsRequestText(url) {
+    const explicitKey = process.env.CONTEXT7_API_KEY;
+    if (explicitKey)
+        return requestText(url, { apiKey: explicitKey, fingerprint: explicitKey.slice(-8) }, timeoutMs());
+    try {
+        const response = await callWithRetry('context7', (key) => requestText(url, key, timeoutMs()));
+        if (response !== null)
+            return response;
+    }
+    catch (error) {
+        if (!(error instanceof Error && error.name === 'ServiceCallError'))
+            throw error;
+    }
+    return requestText(url, undefined, timeoutMs());
+}
+async function requestText(url, key, requestTimeoutMs) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), requestTimeoutMs);
+    try {
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: requestHeaders(key?.apiKey),
+            redirect: 'follow',
+            signal: controller.signal,
+        });
+        if (key?.apiKey)
+            await reportContext7Key(key, response.status, response.headers);
+        const text = await response.text();
+        if (!response.ok)
+            throw httpStatusError(response.status, formatHttpError(response.status, text, url), text);
+        return text;
+    }
+    catch (error) {
+        if (isHttpStatusError(error))
+            throw mapHttpStatusError(error);
+        throw mapNetworkError(error);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function requestHeaders(apiKey) {
+    const headers = { 'user-agent': 'escli-docs/1.0', 'x-context7-source': 'cli' };
+    if (apiKey)
+        headers.authorization = `Bearer ${apiKey}`;
+    return headers;
+}
+async function reportContext7Key(key, status, headers) {
+    const token = resolveCliTokenForReport();
+    if (!token)
+        return;
+    const body = { service: 'context7', fingerprint: key.fingerprint, status };
+    const remaining = numericHeader(headers, 'ratelimit-remaining');
+    const limit = numericHeader(headers, 'ratelimit-limit');
+    const reset = headers.get('ratelimit-reset');
+    const tier = headers.get('context7-quota-tier');
+    if (remaining !== undefined)
+        body.remaining = remaining;
+    if (limit !== undefined)
+        body.limit = limit;
+    if (reset)
+        body.reset = reset;
+    if (tier)
+        body.tier = tier;
+    try {
+        await fetch(`${gateUrl()}/api/keys/report`, {
+            method: 'POST',
+            headers: { 'authorization': `Bearer ${token}`, 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+    }
+    catch {
+        // reporting failures are intentionally swallowed; the Context7
+        // result is the user-facing payload and remains authoritative.
+    }
+}
+function numericHeader(headers, name) {
+    const value = headers.get(name);
+    if (!value)
+        return undefined;
+    const number = Number(value);
+    return Number.isFinite(number) ? number : undefined;
+}
+function resolveCliTokenForReport() {
+    try {
+        const config = JSON.parse(readFileSync(join(configDir(), 'config.json'), 'utf8'));
+        const activeProfile = stringValue(config.active_profile) ?? 'default';
+        const profiles = recordValue(config.profiles);
+        return stringValue(recordValue(profiles?.[activeProfile])?.cli_token);
+    }
+    catch {
+        return undefined;
+    }
+}
+function searchUrl(libraryName, query) {
+    const url = new URL(`${context7BaseUrl()}/v2/libs/search`);
+    url.searchParams.set('libraryName', libraryName);
+    url.searchParams.set('query', query);
+    return url.toString();
+}
+function contextUrl(options) {
+    const url = new URL(`${context7BaseUrl()}/v2/context`);
+    url.searchParams.set('libraryId', options.libraryId);
+    url.searchParams.set('query', options.query);
+    url.searchParams.set('type', 'txt');
+    if (options.tokens)
+        url.searchParams.set('tokens', String(options.tokens));
+    if (options.page)
+        url.searchParams.set('page', String(options.page));
+    if (options.topic)
+        url.searchParams.set('topic', options.topic);
+    return url.toString();
+}
+function context7BaseUrl() {
+    if ((typeof __ESCLI_TEST__ === 'undefined' || __ESCLI_TEST__) && process.env.ESCLI_TEST_CONTEXT7_URL)
+        return process.env.ESCLI_TEST_CONTEXT7_URL;
+    return CONTEXT7_API;
+}
+function timeoutMs() {
+    if (typeof __ESCLI_TEST__ === 'undefined' || __ESCLI_TEST__) {
+        const value = Number(process.env.ESCLI_DOCS_TIMEOUT_MS);
+        if (Number.isFinite(value) && value > 0)
+            return Math.trunc(value);
+    }
+    return DEFAULT_TIMEOUT_MS;
+}
+async function cacheRead(layer, key) {
+    const path = cachePath(layer, key);
+    try {
+        const data = JSON.parse(await readFile(path, 'utf8'));
+        const expiresAt = typeof data.expires_at === 'number' ? data.expires_at : 0;
+        if (Date.now() / 1000 > expiresAt) {
+            await unlink(path).catch(() => undefined);
+            return undefined;
+        }
+        return data.payload;
+    }
+    catch {
+        await unlink(path).catch(() => undefined);
+        return undefined;
+    }
+}
+async function cacheWrite(layer, key, payload, ttlSeconds) {
+    const path = cachePath(layer, key);
+    const createdAt = Date.now() / 1000;
+    await mkdir(join(path, '..'), { recursive: true });
+    await writeFile(path, JSON.stringify({ created_at: createdAt, expires_at: createdAt + ttlSeconds, payload }));
+}
+function cachePath(layer, key) {
+    const hash = createHash('sha256').update(key).digest('hex');
+    return join(cacheDir(), layer, `${hash}.json`);
+}
+function cacheDir() {
+    return process.env.ESCLI_CACHE_DIR ?? join(homedir(), '.escli', 'cache');
+}
+function configDir() {
+    return process.env.ESCLI_CONFIG_DIR ?? join(homedir(), '.escli');
+}
+function gateUrl() {
+    return process.env.ESCLI_GATE_URL ?? 'https://internal.eightstate.co';
+}
+function httpStatusError(status, message, details) {
+    const error = new Error(message);
+    error.status = status;
+    error.details = details;
+    return error;
+}
+function isHttpStatusError(error) {
+    return error instanceof Error && typeof error.status === 'number';
+}
+function mapHttpStatusError(error) {
+    const status = error.status;
+    const message = error.message;
+    if (status === 401)
+        return new EscliError(message, { code: ErrorCode.ApiUnauthorized, exitCode: ExitCodes.Auth, details: error.details });
+    if (status === 403)
+        return new EscliError(message, { code: ErrorCode.ApiForbidden, exitCode: ExitCodes.Auth, details: error.details });
+    if (status === 404)
+        return new EscliError(message.startsWith('library not found:') ? message : 'library not found', { code: ErrorCode.DocsLibraryNotFound, exitCode: ExitCodes.NotFound, details: error.details });
+    if (status === 429)
+        return new EscliError(message, { code: ErrorCode.ApiRateLimited, exitCode: ExitCodes.Transient, details: error.details });
+    if (status >= 500)
+        return new EscliError(message, { code: ErrorCode.ServiceUnavailable, exitCode: ExitCodes.Transient, details: error.details });
+    return new EscliError(message, { code: ErrorCode.DocsFetchFailed, details: error.details });
+}
+function mapNetworkError(error) {
+    const isAbort = error instanceof Error && error.name === 'AbortError';
+    return new EscliError(isAbort ? 'network error: request timed out' : `network error: ${error instanceof Error ? error.message : String(error)}`, {
+        code: isAbort ? ErrorCode.NetworkTimeout : ErrorCode.NetworkError,
+        exitCode: ExitCodes.Transient,
+        details: error instanceof Error ? error.message : error,
+    });
+}
+function formatHttpError(status, body, url) {
+    if (status === 404 && url.includes('/v2/context')) {
+        const parsed = new URL(url);
+        return `library not found: ${parsed.searchParams.get('libraryId') ?? ''}`;
+    }
+    const parsedBody = parseMaybeJson(body);
+    const extracted = extractErrorMessage(parsedBody) ?? (typeof parsedBody === 'string' ? parsedBody : undefined);
+    return extracted ? `API error (${status}): ${extracted}` : `API error (${status})`;
+}
+function parseMaybeJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+function extractErrorMessage(body) {
+    const root = recordValue(body);
+    return stringValue(root?.error) ?? stringValue(root?.message) ?? stringValue(recordValue(root?.error)?.message);
+}
+function recordValue(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function stringValue(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+//# sourceMappingURL=docs.js.map

package/dist/services/fetch.js

@@ -0,0 +1,197 @@
+import { randomUUID } from 'node:crypto';
+import { ErrorCode } from '@eightstate/contracts/errors';
+import { ExitCodes } from '@eightstate/contracts/exit-codes';
+import { EscliError } from '../lib/escli-error.js';
+import { callWithRetry } from './credentials.js';
+const REST_ENDPOINT = 'https://api.parallel.ai/v1';
+const MCP_ENDPOINT = 'https://search.parallel.ai/mcp';
+const DEFAULT_TIMEOUT_MS = 60_000;
+export async function fetchUrls(options) {
+    const started = Date.now();
+    const payload = await fetchPayload(options);
+    const results = normalizeResults(recordValue(payload)?.results);
+    return {
+        elapsed_seconds: roundElapsed((Date.now() - started) / 1000),
+        results,
+        count: results.length,
+    };
+}
+async function fetchPayload(options) {
+    const explicitKey = process.env.PARALLEL_API_KEY;
+    if (explicitKey)
+        return restExtract(options, { apiKey: explicitKey, fingerprint: 'env' });
+    try {
+        const response = await callWithRetry('parallel', (key) => restExtract(options, key));
+        if (response !== null)
+            return response;
+    }
+    catch (error) {
+        if (!(error instanceof Error && error.name === 'ServiceCallError'))
+            throw error;
+    }
+    return mcpFetch(options);
+}
+async function restExtract(options, key) {
+    const body = { urls: options.urls };
+    if (options.objective)
+        body.objective = options.objective;
+    if (options.full)
+        body.full_content = true;
+    const response = await requestText(`${parallelBaseUrl()}/v1/extract`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'x-api-key': key.apiKey },
+        body: JSON.stringify(body),
+        timeoutMs: timeoutMs(options.timeoutSeconds),
+    });
+    return parseJsonResponse(response);
+}
+async function mcpFetch(options) {
+    const args = { urls: options.urls, session_id: randomUUID().replaceAll('-', '') };
+    if (options.objective)
+        args.objective = options.objective;
+    if (options.full)
+        args.full_content = true;
+    const response = await requestText(parallelMcpUrl(), {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream' },
+        body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'web_fetch', arguments: args } }),
+        timeoutMs: timeoutMs(options.timeoutSeconds),
+    });
+    const data = recordValue(parseJsonResponse(response));
+    const error = recordValue(data?.error);
+    if (error)
+        throw new EscliError(stringValue(error.message) ?? 'MCP error', { code: ErrorCode.FetchFailed });
+    const result = recordValue(data?.result);
+    const content = arrayValue(result?.content);
+    for (const item of content) {
+        const record = recordValue(item);
+        if (record?.type === 'text' && typeof record.text === 'string')
+            return parseJsonResponse(record.text);
+    }
+    return result ?? data;
+}
+async function requestText(url, options) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
+    try {
+        const response = await fetch(url, {
+            method: options.method,
+            headers: options.headers,
+            body: options.body,
+            redirect: 'follow',
+            signal: controller.signal,
+        });
+        const text = await response.text();
+        if (!response.ok)
+            throw httpStatusError(response.status, formatHttpError(response.status, text), text);
+        return text;
+    }
+    catch (error) {
+        if (isHttpStatusError(error))
+            throw mapHttpStatusError(error);
+        throw mapNetworkError(error);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function parseJsonResponse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new EscliError(`invalid JSON response: ${error instanceof Error ? error.message : String(error)}`, {
+            code: ErrorCode.JsonInvalid,
+            exitCode: ExitCodes.Error,
+            details: text,
+        });
+    }
+}
+function normalizeResults(results) {
+    if (!Array.isArray(results))
+        return [];
+    return results
+        .map((item) => recordValue(item))
+        .filter((item) => Boolean(item))
+        .map((item) => ({
+        ...(typeof item.title === 'string' || item.title === null ? { title: item.title } : {}),
+        url: String(item.url ?? ''),
+        excerpts: Array.isArray(item.excerpts) ? item.excerpts.map(String) : [],
+        ...(item.full_content === null || typeof item.full_content === 'string' ? { full_content: item.full_content } : {}),
+        ...(item.publish_date === null || typeof item.publish_date === 'string' ? { publish_date: item.publish_date } : {}),
+    }));
+}
+function parallelBaseUrl() {
+    if ((typeof __ESCLI_TEST__ === 'undefined' || __ESCLI_TEST__) && process.env.ESCLI_TEST_PARALLEL_URL)
+        return process.env.ESCLI_TEST_PARALLEL_URL;
+    return REST_ENDPOINT.replace(/\/v1$/u, '');
+}
+function parallelMcpUrl() {
+    if ((typeof __ESCLI_TEST__ === 'undefined' || __ESCLI_TEST__) && process.env.ESCLI_TEST_PARALLEL_URL)
+        return `${process.env.ESCLI_TEST_PARALLEL_URL}/mcp`;
+    return MCP_ENDPOINT;
+}
+function timeoutMs(timeoutSeconds) {
+    const seconds = timeoutSeconds ?? DEFAULT_TIMEOUT_MS / 1000;
+    return Math.max(1, seconds) * 1000;
+}
+function roundElapsed(seconds) {
+    return Math.round(seconds * 10) / 10;
+}
+function httpStatusError(status, message, details) {
+    const error = new Error(message);
+    error.status = status;
+    error.details = details;
+    return error;
+}
+function isHttpStatusError(error) {
+    return error instanceof Error && typeof error.status === 'number';
+}
+function mapHttpStatusError(error) {
+    const status = error.status;
+    if (status === 401)
+        return new EscliError(error.message, { code: ErrorCode.ApiUnauthorized, details: error.details });
+    if (status === 403)
+        return new EscliError(error.message, { code: ErrorCode.ApiForbidden, details: error.details });
+    if (status === 404)
+        return new EscliError(error.message, { code: ErrorCode.FileNotFound, details: error.details });
+    if (status === 429)
+        return new EscliError(error.message, { code: ErrorCode.ApiRateLimited, details: error.details });
+    if (status >= 500)
+        return new EscliError(error.message, { code: ErrorCode.ServiceUnavailable, details: error.details });
+    return new EscliError(error.message, { code: ErrorCode.FetchFailed, details: error.details });
+}
+function mapNetworkError(error) {
+    const isAbort = error instanceof Error && error.name === 'AbortError';
+    return new EscliError(isAbort ? 'network error: request timed out' : `network error: ${error instanceof Error ? error.message : String(error)}`, {
+        code: isAbort ? ErrorCode.NetworkTimeout : ErrorCode.NetworkError,
+        details: error instanceof Error ? error.message : error,
+    });
+}
+function formatHttpError(status, body) {
+    const parsed = parseMaybeJson(body);
+    const extracted = extractErrorMessage(parsed) ?? (typeof parsed === 'string' ? parsed : undefined);
+    return extracted ? `API error (${status}): ${extracted}` : `API error (${status})`;
+}
+function parseMaybeJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+function extractErrorMessage(body) {
+    const root = recordValue(body);
+    return stringValue(root?.error) ?? stringValue(root?.message) ?? stringValue(recordValue(root?.error)?.message);
+}
+function arrayValue(value) {
+    return Array.isArray(value) ? value : [];
+}
+function recordValue(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function stringValue(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+//# sourceMappingURL=fetch.js.map