skillex 0.3.1 → 0.4.0

package/dist/direct-github.js

@@ -0,0 +1,177 @@
+/**
+ * Direct-GitHub install path. Parallels the catalog install path but reads
+ * `skill.json` (or `SKILL.md` frontmatter) directly from a GitHub
+ * repository, allowing users to install skills that are not yet published
+ * in any catalog source.
+ */
+import { buildRawGitHubUrl } from "./catalog.js";
+import { confirmAction } from "./confirm.js";
+import { downloadSkillFiles, writeDownloadedManifest, } from "./downloader.js";
+import { fetchOptionalJson, fetchOptionalText } from "./http.js";
+import { parseSkillFrontmatter } from "./skill.js";
+import * as path from "node:path";
+import { CliError, InstallError } from "./types.js";
+/** Refs in `owner/repo[@ref]` form must match this character set. */
+const ALLOWED_REF_PATTERN = /^[A-Za-z0-9_.\-/]+$/;
+/**
+ * Parses a direct GitHub install reference in `owner/repo[@ref]` format.
+ *
+ * The ref segment (when present) MUST match `^[A-Za-z0-9_.\-/]+$`. Empty
+ * refs (e.g. `owner/repo@`) and refs containing whitespace, newlines, or
+ * shell metacharacters are rejected with `CliError("INVALID_DIRECT_REF")`
+ * rather than silently defaulting to `main`.
+ *
+ * @param input - User-supplied install argument.
+ * @returns Parsed direct GitHub reference or `null` when the value is not a direct ref.
+ * @throws {CliError} When the value looks like a direct ref but the ref portion is invalid.
+ */
+export function parseDirectGitHubRef(input) {
+    if (!input || input.startsWith("http://") || input.startsWith("https://")) {
+        return null;
+    }
+    const trimmed = input.trim();
+    // Detect "owner/repo[@maybeRef]" shape. The ref capture is greedy so we can
+    // validate exactly what the user typed (including empty values after `@`).
+    const shape = trimmed.match(/^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(@.*)?$/);
+    if (!shape) {
+        return null;
+    }
+    const owner = shape[1];
+    const repo = shape[2];
+    const refSuffix = shape[3]; // e.g. "@v1.0.0" or "@" or undefined
+    let ref = "main";
+    if (refSuffix !== undefined) {
+        const rawRef = refSuffix.slice(1); // drop leading "@"
+        if (rawRef.length === 0) {
+            throw new CliError(`Invalid direct install ref: empty ref after "@" in "${trimmed}". Use owner/repo or owner/repo@<branch|tag>.`, "INVALID_DIRECT_REF");
+        }
+        if (!ALLOWED_REF_PATTERN.test(rawRef)) {
+            throw new CliError(`Invalid direct install ref: "${rawRef}" contains disallowed characters. Allowed: letters, digits, "_", ".", "-", "/".`, "INVALID_DIRECT_REF");
+        }
+        ref = rawRef;
+    }
+    return { owner, repo, ref };
+}
+/**
+ * Parses a `github:owner/repo@ref` source string from the lockfile back into a
+ * `DirectGitHubRef`.
+ */
+export function parseGitHubSource(source) {
+    if (!source.startsWith("github:")) {
+        return null;
+    }
+    const withoutPrefix = source.slice("github:".length);
+    const separatorIndex = withoutPrefix.lastIndexOf("@");
+    if (separatorIndex <= 0) {
+        return null;
+    }
+    return parseDirectGitHubRef(`${withoutPrefix.slice(0, separatorIndex)}@${withoutPrefix.slice(separatorIndex + 1)}`);
+}
+/**
+ * Fetches the manifest for a direct-install skill, falling back to SKILL.md
+ * frontmatter when no `skill.json` is present at the repository root.
+ */
+export async function fetchDirectGitHubSkill(reference) {
+    const repoId = `${reference.owner}/${reference.repo}`;
+    const manifestUrl = buildRawGitHubUrl(repoId, reference.ref, "skill.json");
+    const manifest = await fetchOptionalJson(manifestUrl, {
+        headers: { Accept: "application/json" },
+    });
+    if (manifest) {
+        return {
+            repo: repoId,
+            ref: reference.ref,
+            source: `github:${repoId}@${reference.ref}`,
+            manifest: normalizeDirectManifest(manifest, reference),
+        };
+    }
+    const skillMarkdown = await fetchOptionalText(buildRawGitHubUrl(repoId, reference.ref, "SKILL.md"), {
+        headers: { Accept: "text/plain" },
+    });
+    if (!skillMarkdown) {
+        throw new InstallError(`No skill.json or SKILL.md found at ${repoId}@${reference.ref}.`, "DIRECT_SKILL_NOT_FOUND");
+    }
+    const frontmatter = parseSkillFrontmatter(skillMarkdown);
+    return {
+        repo: repoId,
+        ref: reference.ref,
+        source: `github:${repoId}@${reference.ref}`,
+        manifest: {
+            id: normalizeRepoSkillId(reference.repo),
+            name: frontmatter.name || toTitleCase(reference.repo),
+            version: "0.1.0",
+            description: frontmatter.description || `Skill installed directly from ${repoId}.`,
+            author: reference.owner,
+            tags: [],
+            compatibility: [],
+            entry: "SKILL.md",
+            path: "",
+            files: ["SKILL.md"],
+        },
+    };
+}
+/**
+ * Downloads the resolved direct-install skill into the managed skills store.
+ */
+export async function downloadDirectGitHubSkill(skill, skillsDirPath) {
+    const skillTargetDir = path.join(skillsDirPath, skill.manifest.id);
+    await downloadSkillFiles({
+        repo: skill.repo,
+        ref: skill.ref,
+        skillRelPath: skill.manifest.path,
+        files: skill.manifest.files,
+        targetDir: skillTargetDir,
+    });
+    const downloaded = {
+        ...skill.manifest,
+        source: {
+            repo: skill.repo,
+            ref: skill.ref,
+            path: skill.manifest.path,
+        },
+    };
+    await writeDownloadedManifest(skillTargetDir, downloaded);
+}
+/**
+ * Promotes a partial direct-install manifest into a fully-typed `SkillManifest`,
+ * providing safe defaults for missing fields.
+ */
+export function normalizeDirectManifest(manifest, reference) {
+    return {
+        id: manifest.id || normalizeRepoSkillId(reference.repo),
+        name: manifest.name || toTitleCase(reference.repo),
+        version: manifest.version || "0.1.0",
+        description: manifest.description || `Skill installed directly from ${reference.owner}/${reference.repo}.`,
+        author: manifest.author || reference.owner,
+        tags: Array.isArray(manifest.tags) ? manifest.tags : [],
+        compatibility: Array.isArray(manifest.compatibility) ? manifest.compatibility : [],
+        entry: manifest.entry || "SKILL.md",
+        path: manifest.path || "",
+        files: Array.isArray(manifest.files) && manifest.files.length > 0 ? manifest.files : [manifest.entry || "SKILL.md"],
+        ...(manifest.scripts ? { scripts: manifest.scripts } : {}),
+    };
+}
+/**
+ * Prompts the user to confirm a direct GitHub install (skipped when the
+ * caller passes `trust: true`). Throws `InstallError` with code
+ * `INSTALL_CANCELLED` on rejection.
+ */
+export async function confirmDirectInstall(skillRef, options) {
+    const warning = `Warning: ${skillRef} will be installed directly from GitHub and has not been verified by the active catalog.`;
+    (options.warn || console.error)(warning);
+    const confirm = options.confirm || (() => confirmAction("Continue with the direct install?"));
+    const accepted = await confirm();
+    if (!accepted) {
+        throw new InstallError("Direct install cancelled by user.", "INSTALL_CANCELLED");
+    }
+}
+function normalizeRepoSkillId(repo) {
+    return repo.trim().toLowerCase();
+}
+function toTitleCase(skillId) {
+    return skillId
+        .split("-")
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(" ");
+}

package/dist/doctor.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Workspace and environment health checks.
+ *
+ * Used by both the CLI `skillex doctor` command and the Web UI's Doctor
+ * panel. Returns a structured `DoctorReport` so callers can render however
+ * they want (CLI text, JSON, Vue components).
+ */
+import type { ProjectOptions } from "./types.js";
+/** Status indicator for a single doctor check. */
+export type DoctorStatus = "pass" | "warn" | "fail";
+/** A single named health check result. */
+export interface DoctorCheck {
+    name: string;
+    status: DoctorStatus;
+    message: string;
+    hint?: string | undefined;
+}
+/** Aggregate report shape returned by `runDoctorChecks`. */
+export interface DoctorReport {
+    scope: "local" | "global";
+    stateDir: string;
+    checks: DoctorCheck[];
+    /** True when at least one check has status `"fail"`. */
+    hasFailures: boolean;
+}
+/**
+ * Runs the canonical six health checks and returns a structured report.
+ * No I/O beyond reading the lockfile, an HTTP HEAD probe to api.github.com,
+ * and a peek at the catalog cache directory.
+ */
+export declare function runDoctorChecks(options?: ProjectOptions): Promise<DoctorReport>;

package/dist/doctor.js

@@ -0,0 +1,172 @@
+/**
+ * Workspace and environment health checks.
+ *
+ * Used by both the CLI `skillex doctor` command and the Web UI's Doctor
+ * panel. Returns a structured `DoctorReport` so callers can render however
+ * they want (CLI text, JSON, Vue components).
+ */
+import * as path from "node:path";
+import { listAdapters } from "./adapters.js";
+import { computeCatalogCacheKey, readCatalogCache } from "./catalog.js";
+import { DEFAULT_INSTALL_SCOPE, getScopedStatePaths } from "./config.js";
+import { getInstalledSkills, resolveProjectSource, } from "./install.js";
+/**
+ * Runs the canonical six health checks and returns a structured report.
+ * No I/O beyond reading the lockfile, an HTTP HEAD probe to api.github.com,
+ * and a peek at the catalog cache directory.
+ */
+export async function runDoctorChecks(options = {}) {
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    const statePaths = getScopedStatePaths(cwd, {
+        scope: options.scope ?? DEFAULT_INSTALL_SCOPE,
+        baseDir: options.agentSkillsDir,
+    });
+    const opts = { ...options, cwd };
+    const checks = [];
+    // 1. Lockfile
+    const state = await getInstalledSkills(opts);
+    if (state) {
+        checks.push({
+            name: "lockfile",
+            status: "pass",
+            message: `Lockfile present at ${statePaths.lockfilePath}`,
+        });
+    }
+    else {
+        checks.push({
+            name: "lockfile",
+            status: "fail",
+            message: "No lockfile found",
+            hint: statePaths.scope === "global"
+                ? "Run: skillex init --global --adapter <id>"
+                : "Run: skillex init",
+        });
+    }
+    // 2. Source(s)
+    if ((state?.sources?.length ?? 0) > 0) {
+        const repos = state.sources.map((s) => `${s.repo}@${s.ref}`).join(", ");
+        checks.push({ name: "source", status: "pass", message: `Sources configured: ${repos}` });
+    }
+    else {
+        checks.push({
+            name: "source",
+            status: "fail",
+            message: "No catalog source configured",
+            hint: "Run: skillex source add <owner/repo>",
+        });
+    }
+    // 3. Adapter
+    const hasAdapter = Boolean(state?.adapters?.active || (state?.adapters?.detected?.length ?? 0) > 0);
+    if (hasAdapter) {
+        const adapter = state?.adapters?.active ?? state?.adapters?.detected?.[0];
+        checks.push({ name: "adapter", status: "pass", message: `Active: ${adapter}` });
+    }
+    else {
+        checks.push({
+            name: "adapter",
+            status: "fail",
+            message: "No adapter detected",
+            hint: `Use --adapter <id>. Available: ${listAdapters().map((a) => a.id).join(", ")}`,
+        });
+    }
+    // 4. GitHub reachable
+    try {
+        const response = await fetch("https://api.github.com", {
+            method: "HEAD",
+            headers: { "User-Agent": "skillex" },
+            signal: AbortSignal.timeout(5000),
+        });
+        if (response.status < 500) {
+            checks.push({ name: "github", status: "pass", message: "GitHub API is reachable" });
+        }
+        else {
+            checks.push({
+                name: "github",
+                status: "fail",
+                message: `GitHub returned a server error (status ${response.status})`,
+                hint: "Try again in a moment.",
+            });
+        }
+    }
+    catch (error) {
+        const cause = error?.cause?.code
+            ?? error?.code
+            ?? null;
+        const message = error instanceof Error ? error.message : String(error);
+        if (cause === "EAI_AGAIN" || cause === "ENOTFOUND") {
+            checks.push({
+                name: "github",
+                status: "fail",
+                message: "DNS lookup failed for api.github.com",
+                hint: `Check your network or DNS resolver. (${message})`,
+            });
+        }
+        else if (cause === "ECONNREFUSED") {
+            checks.push({
+                name: "github",
+                status: "fail",
+                message: "Connection refused by api.github.com",
+                hint: `Check your firewall or proxy. (${message})`,
+            });
+        }
+        else if (cause === "CERT_HAS_EXPIRED" || cause === "UNABLE_TO_VERIFY_LEAF_SIGNATURE") {
+            checks.push({
+                name: "github",
+                status: "fail",
+                message: "TLS handshake failed",
+                hint: `Check the system clock or any TLS-intercepting proxy. (${message})`,
+            });
+        }
+        else if (cause === "ETIMEDOUT" || error?.name === "TimeoutError") {
+            checks.push({
+                name: "github",
+                status: "fail",
+                message: "Connection to api.github.com timed out",
+                hint: `Check your network connectivity. (${message})`,
+            });
+        }
+        else {
+            checks.push({
+                name: "github",
+                status: "fail",
+                message: "GitHub API is unreachable",
+                hint: `Check your internet connection or proxy settings. (${message})`,
+            });
+        }
+    }
+    // 5. GitHub token (warning only — never fails)
+    const token = process.env.GITHUB_TOKEN;
+    checks.push({
+        name: "token",
+        status: "pass",
+        message: token
+            ? "GitHub token set (authenticated — 5,000 req/hr)"
+            : "No GitHub token (unauthenticated — 60 req/hr)",
+    });
+    // 6. Cache
+    const cacheDir = path.join(statePaths.stateDir, ".cache");
+    if ((state?.sources?.length ?? 0) > 0) {
+        const source = await resolveProjectSource(opts);
+        const cacheKey = computeCatalogCacheKey(source);
+        const cached = await readCatalogCache(cacheDir, cacheKey);
+        if (cached) {
+            checks.push({ name: "cache", status: "pass", message: "Catalog cache is fresh" });
+        }
+        else {
+            checks.push({
+                name: "cache",
+                status: "pass",
+                message: "No cached catalog (will fetch on next command)",
+            });
+        }
+    }
+    else {
+        checks.push({ name: "cache", status: "pass", message: "Cache not checked (no source configured)" });
+    }
+    return {
+        scope: statePaths.scope,
+        stateDir: statePaths.stateDir,
+        checks,
+        hasFailures: checks.some((c) => c.status === "fail"),
+    };
+}

package/dist/downloader.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared file-download helper used by both the catalog install path and the
+ * direct-GitHub install path. Centralizes the per-file fetch loop and the
+ * manifest write so retry / timeout / etag changes only have to land in
+ * one place.
+ */
+import type { SkillManifest } from "./types.js";
+/**
+ * A skill manifest plus the resolved remote source it was downloaded from.
+ * Persisted into `<skillTargetDir>/skill.json` so subsequent updates know
+ * where to fetch from.
+ */
+export interface DownloadedSkillManifest extends SkillManifest {
+    source: {
+        repo: string;
+        ref: string;
+        path: string;
+    };
+}
+/**
+ * Downloads every file declared in a skill manifest into `targetDir`. The
+ * helper wipes the target directory beforehand to ensure a clean install
+ * even when a previous version had different files.
+ *
+ * @param args.repo - GitHub repository in `owner/repo` form.
+ * @param args.ref - Branch, tag, or commit SHA.
+ * @param args.skillRelPath - Path of the skill inside the repository (may be empty).
+ * @param args.files - File list relative to `skillRelPath`.
+ * @param args.targetDir - Local directory that will receive the files.
+ */
+export declare function downloadSkillFiles(args: {
+    repo: string;
+    ref: string;
+    skillRelPath: string;
+    files: string[];
+    targetDir: string;
+}): Promise<void>;
+/**
+ * Persists the downloaded manifest (with resolved source) into the skill's
+ * target directory.
+ */
+export declare function writeDownloadedManifest(skillTargetDir: string, manifest: DownloadedSkillManifest): Promise<void>;

package/dist/downloader.js

@@ -0,0 +1,41 @@
+/**
+ * Shared file-download helper used by both the catalog install path and the
+ * direct-GitHub install path. Centralizes the per-file fetch loop and the
+ * manifest write so retry / timeout / etag changes only have to land in
+ * one place.
+ */
+import * as path from "node:path";
+import { buildRawGitHubUrl } from "./catalog.js";
+import { ensureDir, removePath, writeJson, writeText } from "./fs.js";
+import { fetchText } from "./http.js";
+/**
+ * Downloads every file declared in a skill manifest into `targetDir`. The
+ * helper wipes the target directory beforehand to ensure a clean install
+ * even when a previous version had different files.
+ *
+ * @param args.repo - GitHub repository in `owner/repo` form.
+ * @param args.ref - Branch, tag, or commit SHA.
+ * @param args.skillRelPath - Path of the skill inside the repository (may be empty).
+ * @param args.files - File list relative to `skillRelPath`.
+ * @param args.targetDir - Local directory that will receive the files.
+ */
+export async function downloadSkillFiles(args) {
+    await removePath(args.targetDir);
+    await ensureDir(args.targetDir);
+    await Promise.all(args.files.map(async (relativePath) => {
+        const remotePath = args.skillRelPath
+            ? path.posix.join(args.skillRelPath, relativePath)
+            : relativePath;
+        const rawUrl = buildRawGitHubUrl(args.repo, args.ref, remotePath);
+        const content = await fetchText(rawUrl, { headers: { Accept: "text/plain" } });
+        const localPath = path.join(args.targetDir, relativePath);
+        await writeText(localPath, content);
+    }));
+}
+/**
+ * Persists the downloaded manifest (with resolved source) into the skill's
+ * target directory.
+ */
+export async function writeDownloadedManifest(skillTargetDir, manifest) {
+    await writeJson(path.join(skillTargetDir, "skill.json"), manifest);
+}

package/dist/fs.d.ts

@@ -1,4 +1,14 @@
 import type { CreateSymlinkResult } from "./types.js";
+/** Optional safety constraints for `createSymlink`. */
+export interface CreateSymlinkOptions {
+    /**
+     * When provided, the resolved symlink target MUST be inside this directory.
+     * Anything outside (including paths that escape via `..`) is rejected with
+     * a `ValidationError`. Use this to confine adapter symlinks to the
+     * managed skills store.
+     */
+    allowedRoot?: string | undefined;
+}
 /**
  * Checks whether a file or directory exists.
  *
@@ -58,11 +68,21 @@ export declare function copyPath(sourcePath: string, targetPath: string): Promis
 /**
  * Creates a relative symlink and reports whether the caller should fall back to copy mode.
  *
+ * When `options.allowedRoot` is set, the resolved target MUST be inside it; targets
+ * outside the root raise `ValidationError("SYMLINK_TARGET_UNSAFE")` and no link is
+ * written. This prevents a tampered lockfile from pointing adapter symlinks at
+ * arbitrary filesystem locations.
+ *
  * @param targetPath - Absolute path the link should point to.
  * @param linkPath - Absolute path of the symlink to create.
+ * @param options - Optional safety constraints.
  * @returns Symlink creation result.
  */
-export declare function createSymlink(targetPath: string, linkPath: string): Promise<CreateSymlinkResult>;
+export declare function createSymlink(targetPath: string, linkPath: string, options?: CreateSymlinkOptions): Promise<CreateSymlinkResult>;
+/**
+ * Returns `true` when `candidate` resolves to a path inside `root` (or equals `root`).
+ */
+export declare function isPathInside(candidate: string, root: string): boolean;
 /**
  * Removes a symlink without following it.
  *

package/dist/fs.js

@@ -103,12 +103,24 @@ export async function copyPath(sourcePath, targetPath) {
 /**
  * Creates a relative symlink and reports whether the caller should fall back to copy mode.
  *
+ * When `options.allowedRoot` is set, the resolved target MUST be inside it; targets
+ * outside the root raise `ValidationError("SYMLINK_TARGET_UNSAFE")` and no link is
+ * written. This prevents a tampered lockfile from pointing adapter symlinks at
+ * arbitrary filesystem locations.
+ *
  * @param targetPath - Absolute path the link should point to.
  * @param linkPath - Absolute path of the symlink to create.
+ * @param options - Optional safety constraints.
  * @returns Symlink creation result.
  */
-export async function createSymlink(targetPath, linkPath) {
+export async function createSymlink(targetPath, linkPath, options = {}) {
     const absoluteTarget = path.resolve(targetPath);
+    if (options.allowedRoot) {
+        const allowedRoot = path.resolve(options.allowedRoot);
+        if (!isPathInside(absoluteTarget, allowedRoot)) {
+            throw new ValidationError(`Refusing to symlink outside the managed root: target=${absoluteTarget} root=${allowedRoot}`, "SYMLINK_TARGET_UNSAFE");
+        }
+    }
     const relativeTarget = path.relative(path.dirname(linkPath), absoluteTarget) || ".";
     await ensureDir(path.dirname(linkPath));
     await removePath(linkPath);
@@ -135,6 +147,21 @@ export async function createSymlink(targetPath, linkPath) {
         throw error;
     }
 }
+/**
+ * Returns `true` when `candidate` resolves to a path inside `root` (or equals `root`).
+ */
+export function isPathInside(candidate, root) {
+    const candidateAbs = path.resolve(candidate);
+    const rootAbs = path.resolve(root);
+    if (candidateAbs === rootAbs) {
+        return true;
+    }
+    const rel = path.relative(rootAbs, candidateAbs);
+    if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) {
+        return false;
+    }
+    return true;
+}
 /**
  * Removes a symlink without following it.
  *
@@ -184,14 +211,14 @@ export async function readSymlink(linkPath) {
  */
 export function assertSafeRelativePath(relativePath) {
     if (!relativePath || relativePath.includes("\0")) {
-        throw new ValidationError(`Caminho invalido: "${relativePath}"`);
+        throw new ValidationError(`Invalid path: "${relativePath}"`);
     }
     const normalized = path.posix.normalize(relativePath);
     if (normalized.startsWith("../") ||
         normalized === ".." ||
         path.isAbsolute(relativePath) ||
         normalized.startsWith("/")) {
-        throw new ValidationError(`Caminho inseguro detectado: "${relativePath}"`);
+        throw new ValidationError(`Unsafe path detected: "${relativePath}"`);
     }
     return normalized;
 }

package/dist/http.d.ts

@@ -1,17 +1,38 @@
 /**
  * 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.
+ */
+/**
+ * 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 declare function setDefaultHttpTimeoutMs(ms: number): void;
+/**
+ * Returns the current default HTTP timeout in milliseconds.
+ */
+export declare function getDefaultHttpTimeoutMs(): number;
+/**
+ * Returns `true` when the URL targets a GitHub-owned host (api or raw mirrors,
+ * including any `*.githubusercontent.com` subdomain).
  */
+export declare function isGitHubHost(url: string): boolean;
 /**
  * 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 declare function fetchJson<T>(url: string, init?: RequestInit): Promise<T>;
 /**
@@ -20,7 +41,7 @@ export declare function fetchJson<T>(url: string, init?: RequestInit): Promise<T
  * @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 declare function fetchText(url: string, init?: RequestInit): Promise<string>;
 /**
@@ -29,7 +50,7 @@ export declare function fetchText(url: string, init?: RequestInit): Promise<stri
  * @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 declare function fetchOptionalText(url: string, init?: RequestInit): Promise<string | null>;
 /**
@@ -38,6 +59,6 @@ export declare function fetchOptionalText(url: string, init?: RequestInit): Prom
  * @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 declare function fetchOptionalJson<T>(url: string, init?: RequestInit): Promise<T | null>;