skillex 0.3.1 → 0.4.0

package/dist/http.js

@@ -1,25 +1,72 @@
 /**
  * HTTP fetch utilities with GitHub API support.
  *
- * Automatically attaches GitHub headers and, when `GITHUB_TOKEN` is set in
- * the environment, an `Authorization: Bearer` header to raise the API rate
- * limit from 60 to 5,000 requests per hour.
+ * Automatically attaches a default 30-second timeout, a `User-Agent`, and a
+ * GitHub `Accept` header. When `GITHUB_TOKEN` is set in the environment, an
+ * `Authorization: Bearer` header is attached **only for GitHub hosts** so the
+ * token does not leak to third-party `--catalog-url` targets.
+ *
+ * HTTP errors raise typed `HttpError` instances with codes that distinguish
+ * timeouts, rate limits, auth failures, and server errors.
  */
 import { debug } from "./output.js";
+import { HttpError } from "./types.js";
+let defaultHttpTimeoutMs = 30_000;
+/**
+ * Overrides the default HTTP timeout (in milliseconds) used when callers do
+ * not pass their own `init.signal`. Primarily for tests; production callers
+ * should rely on the default.
+ *
+ * @param ms - Positive integer in milliseconds.
+ */
+export function setDefaultHttpTimeoutMs(ms) {
+    if (!Number.isFinite(ms) || ms <= 0) {
+        throw new RangeError(`Invalid HTTP timeout: ${ms}`);
+    }
+    defaultHttpTimeoutMs = Math.floor(ms);
+}
+/**
+ * Returns the current default HTTP timeout in milliseconds.
+ */
+export function getDefaultHttpTimeoutMs() {
+    return defaultHttpTimeoutMs;
+}
+/**
+ * Hostnames that are considered GitHub-owned for the purpose of attaching the
+ * `Authorization: Bearer ${GITHUB_TOKEN}` header.
+ */
+const GITHUB_HOSTS = new Set(["api.github.com", "raw.githubusercontent.com"]);
+/**
+ * Returns `true` when the URL targets a GitHub-owned host (api or raw mirrors,
+ * including any `*.githubusercontent.com` subdomain).
+ */
+export function isGitHubHost(url) {
+    try {
+        const parsed = new URL(url);
+        if (GITHUB_HOSTS.has(parsed.hostname)) {
+            return true;
+        }
+        if (parsed.hostname.endsWith(".githubusercontent.com")) {
+            return true;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Fetches a JSON document and parses it with default Skillex headers.
  *
  * @param url - Target URL.
  * @param init - Fetch init overrides.
  * @returns Parsed JSON payload.
- * @throws {Error} With an actionable message on HTTP errors.
+ * @throws {HttpError} On non-2xx responses or timeouts.
  */
 export async function fetchJson(url, init = {}) {
-    debug(`GET ${url}`);
-    const response = await fetch(url, withDefaultHeaders(init));
-    debug(`${response.status} ${url}`);
+    const response = await fetchWithDefaults(url, init);
     if (!response.ok) {
-        throw new Error(buildHttpErrorMessage(url, response.status));
+        throw await buildHttpError(url, response);
     }
     return (await response.json());
 }
@@ -29,14 +76,12 @@ export async function fetchJson(url, init = {}) {
  * @param url - Target URL.
  * @param init - Fetch init overrides.
  * @returns Response text body.
- * @throws {Error} With an actionable message on HTTP errors.
+ * @throws {HttpError} On non-2xx responses or timeouts.
  */
 export async function fetchText(url, init = {}) {
-    debug(`GET ${url}`);
-    const response = await fetch(url, withDefaultHeaders(init));
-    debug(`${response.status} ${url}`);
+    const response = await fetchWithDefaults(url, init);
     if (!response.ok) {
-        throw new Error(buildHttpErrorMessage(url, response.status));
+        throw await buildHttpError(url, response);
     }
     return response.text();
 }
@@ -46,17 +91,15 @@ export async function fetchText(url, init = {}) {
  * @param url - Target URL.
  * @param init - Fetch init overrides.
  * @returns Response text body or `null` for HTTP 404.
- * @throws {Error} With an actionable message on non-404 HTTP errors.
+ * @throws {HttpError} On non-404 non-2xx responses or timeouts.
  */
 export async function fetchOptionalText(url, init = {}) {
-    debug(`GET ${url}`);
-    const response = await fetch(url, withDefaultHeaders(init));
-    debug(`${response.status} ${url}`);
+    const response = await fetchWithDefaults(url, init);
     if (response.status === 404) {
         return null;
     }
     if (!response.ok) {
-        throw new Error(buildHttpErrorMessage(url, response.status));
+        throw await buildHttpError(url, response);
     }
     return response.text();
 }
@@ -66,28 +109,44 @@ export async function fetchOptionalText(url, init = {}) {
  * @param url - Target URL.
  * @param init - Fetch init overrides.
  * @returns Parsed JSON payload or `null` for HTTP 404.
- * @throws {Error} With an actionable message on non-404 HTTP errors.
+ * @throws {HttpError} On non-404 non-2xx responses or timeouts.
  */
 export async function fetchOptionalJson(url, init = {}) {
-    debug(`GET ${url}`);
-    const response = await fetch(url, withDefaultHeaders(init));
-    debug(`${response.status} ${url}`);
+    const response = await fetchWithDefaults(url, init);
     if (response.status === 404) {
         return null;
     }
     if (!response.ok) {
-        throw new Error(buildHttpErrorMessage(url, response.status));
+        throw await buildHttpError(url, response);
     }
     return (await response.json());
 }
+/**
+ * Performs a `fetch` with default headers and a default abort timeout. Wraps
+ * abort errors into a typed `HttpError` with code `HTTP_TIMEOUT`.
+ */
+async function fetchWithDefaults(url, init) {
+    debug(`GET ${url}`);
+    const { merged, attachedTimeout } = withDefaultHeaders(url, init);
+    try {
+        const response = await fetch(url, merged);
+        debug(`${response.status} ${url}`);
+        return response;
+    }
+    catch (error) {
+        if (error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError")) {
+            const timeout = attachedTimeout ?? defaultHttpTimeoutMs;
+            throw new HttpError(`Request timed out after ${timeout}ms: ${url}`, "HTTP_TIMEOUT", { url });
+        }
+        throw error;
+    }
+}
 /**
  * Applies default HTTP headers expected by GitHub-hosted catalog requests.
- * Attaches `Authorization: Bearer` when `GITHUB_TOKEN` is set in the environment.
- *
- * @param init - User-supplied fetch options.
- * @returns Fetch options with default headers merged in.
+ * Attaches `Authorization: Bearer` only when `GITHUB_TOKEN` is set AND the
+ * target host is GitHub-owned.
  */
-function withDefaultHeaders(init) {
+function withDefaultHeaders(url, init) {
     const headers = new Headers(init.headers || {});
     if (!headers.has("User-Agent")) {
         headers.set("User-Agent", "skillex");
@@ -97,27 +156,69 @@ function withDefaultHeaders(init) {
     }
     const token = process.env.GITHUB_TOKEN;
     if (token && !headers.has("Authorization")) {
-        headers.set("Authorization", `Bearer ${token}`);
-        debug("Using GITHUB_TOKEN for authentication");
+        if (isGitHubHost(url)) {
+            headers.set("Authorization", `Bearer ${token}`);
+            debug("Using GITHUB_TOKEN for authentication");
+        }
+        else {
+            debug(`GITHUB_TOKEN suppressed: non-GitHub host (${safeHost(url)})`);
+        }
+    }
+    let attachedTimeout = null;
+    let signal = init.signal;
+    if (signal === undefined || signal === null) {
+        attachedTimeout = defaultHttpTimeoutMs;
+        signal = AbortSignal.timeout(defaultHttpTimeoutMs);
+    }
+    const merged = {
+        ...init,
+        headers,
+        signal,
+    };
+    return { merged, attachedTimeout };
+}
+function safeHost(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return "<invalid-url>";
     }
-    return { ...init, headers };
 }
 /**
- * Builds a human-readable, actionable error message for HTTP failures.
- *
- * @param url - The URL that failed.
- * @param status - HTTP response status code.
- * @returns Descriptive error message.
+ * Builds a typed `HttpError` for a non-2xx response, splitting 403 into
+ * rate-limit vs auth based on `X-RateLimit-Remaining`.
  */
-function buildHttpErrorMessage(url, status) {
-    if (status === 403) {
-        return "GitHub API rate limit exceeded or access denied. Set the GITHUB_TOKEN environment variable to authenticate.";
+async function buildHttpError(url, response) {
+    const status = response.status;
+    if (status === 403 || status === 401) {
+        const remainingHeader = response.headers.get("x-ratelimit-remaining");
+        const isRateLimited = status === 403 && remainingHeader !== null && remainingHeader.trim() === "0";
+        if (isRateLimited) {
+            const reset = response.headers.get("x-ratelimit-reset");
+            const resetHint = reset ? buildResetHint(reset) : "Set GITHUB_TOKEN to raise the limit.";
+            return new HttpError(`GitHub API rate limit exceeded. ${resetHint}`, "HTTP_RATE_LIMIT", { status, url });
+        }
+        return new HttpError("GitHub API authentication failed. Check that GITHUB_TOKEN is valid and has access.", "HTTP_AUTH_FAILED", { status, url });
     }
     if (status === 404) {
-        return `Repository or file not found. Check that --repo is correct and the repository is public. (${url})`;
+        return new HttpError(`Repository or file not found. Check that --repo is correct and the repository is public. (${url})`, "HTTP_NOT_FOUND", { status, url });
     }
     if (status >= 500) {
-        return `GitHub API returned a server error (${status}). Try again in a moment.`;
+        return new HttpError(`GitHub API returned a server error (${status}). Try again in a moment.`, "HTTP_SERVER_ERROR", { status, url });
+    }
+    return new HttpError(`Failed to fetch ${url} (HTTP ${status})`, "HTTP_ERROR", { status, url });
+}
+function buildResetHint(resetEpoch) {
+    const epoch = Number(resetEpoch);
+    if (!Number.isFinite(epoch)) {
+        return "Set GITHUB_TOKEN to raise the limit.";
+    }
+    const resetDate = new Date(epoch * 1000);
+    const seconds = Math.max(0, Math.round((resetDate.getTime() - Date.now()) / 1000));
+    if (seconds < 60) {
+        return `Resets in ${seconds}s. Set GITHUB_TOKEN to raise the limit.`;
     }
-    return `Failed to fetch ${url} (HTTP ${status})`;
+    const minutes = Math.round(seconds / 60);
+    return `Resets in ~${minutes}m. Set GITHUB_TOKEN to raise the limit.`;
 }

package/dist/install.d.ts

@@ -1,4 +1,26 @@
-import type { AggregatedCatalogData, CatalogLoader, CatalogSource, DirectGitHubRef, InitProjectResult, InstallSkillsResult, LockfileSource, LockfileState, ProjectOptions, RemoveSkillsResult, SkillDownloader, SyncCommandResult, UpdateInstalledSkillsResult } from "./types.js";
+/**
+ * Install / update / remove orchestration for catalog and direct-GitHub skills.
+ *
+ * Historically this module owned every install-related concern. Lockfile
+ * shape, direct-GitHub install, auto-sync, and the shared file downloader
+ * have been extracted into focused modules. This file now contains only
+ * orchestration and re-exports the moved symbols so existing imports keep
+ * working until callers migrate to the canonical paths.
+ *
+ * Re-export shim → canonical module mapping:
+ * - lockfile shape and source-list helpers      → ./lockfile.js
+ * - direct GitHub parsing / fetch / download    → ./direct-github.js
+ * - auto-sync orchestration                     → ./auto-sync.js
+ * - shared per-file download helper             → ./downloader.js
+ */
+import type { AggregatedCatalogData, CatalogLoader, CatalogSource, InitProjectResult, InstallSkillsResult, LockfileSource, LockfileState, ProjectOptions, RemoveSkillsResult, SkillDownloader, SyncCommandResult, UpdateInstalledSkillsResult } from "./types.js";
+export { createBaseLockfile, dedupeSources, getLockfileSources, normalizeLockfile, normalizeSyncHistory, parseCatalogSource, PLACEHOLDER_REPOS, toLockfileSource, } from "./lockfile.js";
+export { confirmDirectInstall, downloadDirectGitHubSkill, fetchDirectGitHubSkill, normalizeDirectManifest, parseDirectGitHubRef, parseGitHubSource, } from "./direct-github.js";
+export type { DirectInstallPayload } from "./direct-github.js";
+export { maybeAutoSync, maybeSyncAfterRemove, resolveSyncAdapterIds, } from "./auto-sync.js";
+export type { SyncFn } from "./auto-sync.js";
+export { downloadSkillFiles, writeDownloadedManifest, } from "./downloader.js";
+export type { DownloadedSkillManifest } from "./downloader.js";
 interface InstallOptions extends ProjectOptions {
     catalogLoader?: CatalogLoader;
     downloader?: SkillDownloader;
@@ -105,11 +127,3 @@ export declare function removeProjectSource(repo: string, options?: ProjectOptio
  * @returns Normalized source list.
  */
 export declare function listProjectSources(options?: ProjectOptions): Promise<LockfileSource[]>;
-/**
- * Parses a direct GitHub install reference in `owner/repo[@ref]` format.
- *
- * @param input - User-supplied install argument.
- * @returns Parsed direct GitHub reference or `null` when the value is not a direct ref.
- */
-export declare function parseDirectGitHubRef(input: string): DirectGitHubRef | null;
-export {};