@sanity/ailf 0.1.6 → 0.1.7

package/dist/adapters/api-client/build-request.d.ts

@@ -0,0 +1,75 @@
+/**
+ * api-client/build-request.ts — Build a PipelineRequest from local state.
+ *
+ * Translates the user's local `.ailf/tasks/` directory and resolved CLI
+ * config into a `PipelineRequest` payload ready for the API. Reuses the
+ * existing `RepoTaskSource` adapter for YAML parsing — no duplicated
+ * parsing logic.
+ *
+ * The built request is validated against `PipelineRequestSchema` before
+ * return (fail-fast on malformed payloads).
+ *
+ * @see packages/core/src/schemas/pipeline-request.ts — shared schema
+ * @see packages/eval/src/adapters/task-sources/repo-task-source.ts
+ */
+import { type PipelineRequest } from "../../_vendor/ailf-core/index.d.ts";
+/** Options for building a remote pipeline request. */
+export interface BuildRequestOptions {
+    /** Path to .ailf/tasks/ directory. */
+    tasksDir: string;
+    /** Resolved CLI config for mode, scoping, and source overrides. */
+    config: RemoteConfigSlice;
+}
+/**
+ * Subset of ResolvedConfig fields needed for building a remote request.
+ * Defined as a standalone interface so the build function doesn't depend
+ * on the full ResolvedConfig type (keeps the api-client adapter decoupled).
+ */
+export interface RemoteConfigSlice {
+    mode?: string;
+    debug?: {
+        enabled?: boolean;
+        firstN?: number;
+        pattern?: string;
+        sample?: number;
+    };
+    areas?: string[];
+    tasks?: string[];
+    changedDocs?: string[];
+    source?: string;
+    compareEnabled?: boolean;
+    compareThreshold?: number;
+    publishEnabled?: boolean;
+    publishTag?: string;
+    concurrency?: number;
+    datasetOverride?: string;
+    projectIdOverride?: string;
+    perspectiveOverride?: string;
+    graderReplications?: number;
+    gapAnalysisEnabled?: boolean;
+    readinessEnabled?: boolean;
+    discoveryReportEnabled?: boolean;
+}
+/**
+ * Build a PipelineRequest from local tasks and config.
+ *
+ * 1. Loads tasks via RepoTaskSource (validates via Zod automatically)
+ * 2. Applies filter options (areas, task IDs) from config
+ * 3. Maps tasks to inline format
+ * 4. Builds the full PipelineRequest
+ * 5. Validates against PipelineRequestSchema
+ *
+ * Throws on validation errors (from RepoTaskSource or PipelineRequestSchema).
+ */
+export declare function buildRemoteRequest(options: BuildRequestOptions): Promise<{
+    request: PipelineRequest;
+    taskCount: number;
+}>;
+/**
+ * Find the tasks directory, trying in order:
+ * 1. Explicit path (from --repo-tasks-path)
+ * 2. .ailf/tasks/ relative to rootDir
+ *
+ * Returns the resolved path or throws if not found.
+ */
+export declare function resolveTasksDir(rootDir: string, explicitPath?: string): string;

package/dist/adapters/api-client/build-request.js

@@ -0,0 +1,176 @@
+/**
+ * api-client/build-request.ts — Build a PipelineRequest from local state.
+ *
+ * Translates the user's local `.ailf/tasks/` directory and resolved CLI
+ * config into a `PipelineRequest` payload ready for the API. Reuses the
+ * existing `RepoTaskSource` adapter for YAML parsing — no duplicated
+ * parsing logic.
+ *
+ * The built request is validated against `PipelineRequestSchema` before
+ * return (fail-fast on malformed payloads).
+ *
+ * @see packages/core/src/schemas/pipeline-request.ts — shared schema
+ * @see packages/eval/src/adapters/task-sources/repo-task-source.ts
+ */
+import { existsSync } from "fs";
+import { resolve } from "path";
+import { PipelineRequestSchema, } from "../../_vendor/ailf-core/index.js";
+import { RepoTaskSource } from "../task-sources/repo-task-source.js";
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Build a PipelineRequest from local tasks and config.
+ *
+ * 1. Loads tasks via RepoTaskSource (validates via Zod automatically)
+ * 2. Applies filter options (areas, task IDs) from config
+ * 3. Maps tasks to inline format
+ * 4. Builds the full PipelineRequest
+ * 5. Validates against PipelineRequestSchema
+ *
+ * Throws on validation errors (from RepoTaskSource or PipelineRequestSchema).
+ */
+export async function buildRemoteRequest(options) {
+    const { tasksDir, config } = options;
+    // 1. Load and validate local tasks
+    const taskSource = new RepoTaskSource(tasksDir);
+    const filterOptions = buildFilterOptions(config);
+    const tasks = await taskSource.loadTasks(filterOptions);
+    if (tasks.length === 0) {
+        throw new Error("No tasks found after applying filters.\n" +
+            `  Tasks directory: ${tasksDir}\n` +
+            (config.areas ? `  Area filter: ${config.areas.join(", ")}\n` : "") +
+            (config.tasks ? `  Task filter: ${config.tasks.join(", ")}\n` : "") +
+            "  Check that your .ailf/tasks/ YAML files define tasks matching these filters.");
+    }
+    // 2. Convert tasks to inline format
+    const inlineTasks = tasks.map(taskToInlineFormat);
+    // 3. Build the PipelineRequest
+    const raw = {
+        taskMode: "inline",
+        inlineTasks,
+    };
+    // Mode
+    if (config.mode && config.mode !== "full") {
+        raw.mode = config.mode;
+    }
+    // Debug
+    if (config.debug?.enabled) {
+        raw.debug = config.debug;
+    }
+    // Scoping
+    if (config.areas?.length)
+        raw.areas = config.areas;
+    if (config.tasks?.length)
+        raw.tasks = config.tasks;
+    if (config.changedDocs?.length)
+        raw.changedDocs = config.changedDocs;
+    // Source
+    if (config.source)
+        raw.source = config.source;
+    // Comparison
+    if (config.compareEnabled)
+        raw.compare = true;
+    if (config.compareThreshold !== undefined) {
+        raw.compareThreshold = config.compareThreshold;
+    }
+    // Publishing
+    if (config.publishEnabled !== undefined)
+        raw.publish = config.publishEnabled;
+    if (config.publishTag)
+        raw.publishTag = config.publishTag;
+    // Concurrency
+    if (config.concurrency)
+        raw.concurrency = config.concurrency;
+    // Source overrides
+    if (config.datasetOverride)
+        raw.dataset = config.datasetOverride;
+    if (config.projectIdOverride)
+        raw.projectId = config.projectIdOverride;
+    if (config.perspectiveOverride)
+        raw.perspective = config.perspectiveOverride;
+    // Advanced
+    if (config.graderReplications) {
+        raw.graderReplications = config.graderReplications;
+    }
+    if (config.gapAnalysisEnabled)
+        raw.gapAnalysis = true;
+    if (config.readinessEnabled)
+        raw.readiness = true;
+    if (config.discoveryReportEnabled)
+        raw.discoveryReport = true;
+    // 4. Validate the assembled request
+    const parsed = PipelineRequestSchema.parse(raw);
+    return { request: parsed, taskCount: tasks.length };
+}
+// ---------------------------------------------------------------------------
+// Task directory resolution
+// ---------------------------------------------------------------------------
+/**
+ * Find the tasks directory, trying in order:
+ * 1. Explicit path (from --repo-tasks-path)
+ * 2. .ailf/tasks/ relative to rootDir
+ *
+ * Returns the resolved path or throws if not found.
+ */
+export function resolveTasksDir(rootDir, explicitPath) {
+    if (explicitPath) {
+        if (!existsSync(explicitPath)) {
+            throw new Error(`Tasks directory not found: ${explicitPath}\n` +
+                "  Provide a valid path via --repo-tasks-path");
+        }
+        return explicitPath;
+    }
+    const defaultPath = resolve(rootDir, ".ailf", "tasks");
+    if (existsSync(defaultPath)) {
+        return defaultPath;
+    }
+    throw new Error("No tasks directory found.\n" +
+        `  Looked for: ${defaultPath}\n` +
+        "  Remote mode reads task definitions from .ailf/tasks/ in your repo.\n" +
+        "  Run 'ailf init' to create example tasks, or specify a path:\n" +
+        "  ailf eval --remote --repo-tasks-path ./my-tasks/");
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Convert a TaskDefinition back to the camelCase inline format expected
+ * by the API. This is essentially the inverse of RepoTaskSource's
+ * `mapToTaskDefinition()`.
+ */
+function taskToInlineFormat(task) {
+    const inline = {
+        id: task.id,
+        description: task.description,
+        featureArea: task.featureArea,
+        assert: task.assertions,
+    };
+    if (task.canonicalDocs?.length) {
+        inline.canonicalDocs = task.canonicalDocs;
+    }
+    if (task.taskPrompt) {
+        inline.vars = {
+            task: task.taskPrompt,
+            docs: "",
+            ...(task.extraVars ?? {}),
+        };
+    }
+    if (task.docCoverage) {
+        inline.docCoverage = true;
+    }
+    if (task.referenceSolution) {
+        inline.referenceSolution = task.referenceSolution;
+    }
+    if (task.baseline) {
+        inline.baseline = task.baseline;
+    }
+    return inline;
+}
+function buildFilterOptions(config) {
+    const areas = config.areas?.length ? config.areas : undefined;
+    const taskIds = config.tasks?.length ? config.tasks : undefined;
+    if (!areas && !taskIds)
+        return undefined;
+    return { areas, taskIds };
+}

package/dist/adapters/api-client/errors.d.ts

@@ -0,0 +1,43 @@
+/**
+ * api-client/errors.ts — Typed error classes for API client failures.
+ *
+ * Each error class corresponds to a distinct failure mode so callers can
+ * match on `instanceof` for control flow. Error messages are always
+ * human-readable; machine-readable details are in typed fields.
+ */
+/**
+ * The API returned a well-formed error response (JSON envelope with
+ * `object: "error"`). The HTTP status code and error details are preserved.
+ */
+export declare class ApiError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly param?: string | undefined;
+    readonly name: string;
+    constructor(message: string, code: string, statusCode: number, param?: string | undefined);
+}
+/**
+ * The API key is missing, invalid, or lacks the required scope.
+ */
+export declare class ApiAuthError extends ApiError {
+    readonly name = "ApiAuthError";
+}
+/**
+ * The API could not be reached — DNS failure, connection refused,
+ * timeout, or a non-JSON response (e.g., 502 from a CDN).
+ */
+export declare class ApiConnectionError extends Error {
+    readonly url: string;
+    readonly cause?: unknown | undefined;
+    readonly name = "ApiConnectionError";
+    constructor(message: string, url: string, cause?: unknown | undefined);
+}
+/**
+ * The job did not reach a terminal state within the allotted time.
+ */
+export declare class ApiTimeoutError extends Error {
+    readonly jobId: string;
+    readonly timeoutMs: number;
+    readonly name = "ApiTimeoutError";
+    constructor(jobId: string, timeoutMs: number);
+}

package/dist/adapters/api-client/errors.js

@@ -0,0 +1,68 @@
+/**
+ * api-client/errors.ts — Typed error classes for API client failures.
+ *
+ * Each error class corresponds to a distinct failure mode so callers can
+ * match on `instanceof` for control flow. Error messages are always
+ * human-readable; machine-readable details are in typed fields.
+ */
+// ---------------------------------------------------------------------------
+// ApiError — API returned a non-2xx response with a structured error body
+// ---------------------------------------------------------------------------
+/**
+ * The API returned a well-formed error response (JSON envelope with
+ * `object: "error"`). The HTTP status code and error details are preserved.
+ */
+export class ApiError extends Error {
+    code;
+    statusCode;
+    param;
+    name = "ApiError";
+    constructor(message, code, statusCode, param) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+        this.param = param;
+    }
+}
+// ---------------------------------------------------------------------------
+// ApiAuthError — 401/403 from the API
+// ---------------------------------------------------------------------------
+/**
+ * The API key is missing, invalid, or lacks the required scope.
+ */
+export class ApiAuthError extends ApiError {
+    name = "ApiAuthError";
+}
+// ---------------------------------------------------------------------------
+// ApiConnectionError — network-level failure
+// ---------------------------------------------------------------------------
+/**
+ * The API could not be reached — DNS failure, connection refused,
+ * timeout, or a non-JSON response (e.g., 502 from a CDN).
+ */
+export class ApiConnectionError extends Error {
+    url;
+    cause;
+    name = "ApiConnectionError";
+    constructor(message, url, cause) {
+        super(message);
+        this.url = url;
+        this.cause = cause;
+    }
+}
+// ---------------------------------------------------------------------------
+// ApiTimeoutError — polling deadline exceeded
+// ---------------------------------------------------------------------------
+/**
+ * The job did not reach a terminal state within the allotted time.
+ */
+export class ApiTimeoutError extends Error {
+    jobId;
+    timeoutMs;
+    name = "ApiTimeoutError";
+    constructor(jobId, timeoutMs) {
+        super(`Job ${jobId} did not complete within ${Math.round(timeoutMs / 1000)}s`);
+        this.jobId = jobId;
+        this.timeoutMs = timeoutMs;
+    }
+}

package/dist/adapters/api-client/format-error.d.ts

@@ -0,0 +1,22 @@
+/**
+ * api-client/format-error.ts — Human-readable error formatting for failed jobs.
+ *
+ * Produces structured console output that shows the failed step, error
+ * message, and (when available) a remediation hint. The output is designed
+ * to be useful both in interactive terminals and in CI log output.
+ */
+import type { JobResponse } from "./types.js";
+/**
+ * Format a failed job response into a multi-line error string.
+ *
+ * Does NOT call `process.exit()` — the caller decides what to do.
+ *
+ * @example
+ * ```
+ * ❌ Pipeline failed at step 'fetch-docs'
+ *    Postcondition failed: Canonical context for task "foo" is empty.
+ *
+ * 💡 One or more canonicalDocs slugs in your task definitions don't match ...
+ * ```
+ */
+export declare function formatJobError(job: JobResponse): string;

package/dist/adapters/api-client/format-error.js

@@ -0,0 +1,48 @@
+/**
+ * api-client/format-error.ts — Human-readable error formatting for failed jobs.
+ *
+ * Produces structured console output that shows the failed step, error
+ * message, and (when available) a remediation hint. The output is designed
+ * to be useful both in interactive terminals and in CI log output.
+ */
+import { getRemediationHint } from "./remediation.js";
+/**
+ * Format a failed job response into a multi-line error string.
+ *
+ * Does NOT call `process.exit()` — the caller decides what to do.
+ *
+ * @example
+ * ```
+ * ❌ Pipeline failed at step 'fetch-docs'
+ *    Postcondition failed: Canonical context for task "foo" is empty.
+ *
+ * 💡 One or more canonicalDocs slugs in your task definitions don't match ...
+ * ```
+ */
+export function formatJobError(job) {
+    const lines = [];
+    if (job.error?.step && job.error?.message) {
+        lines.push(`❌ Pipeline failed at step '${job.error.step}'`);
+        lines.push(`   ${job.error.message}`);
+    }
+    else if (job.error?.message) {
+        lines.push(`❌ Evaluation failed`);
+        lines.push(`   ${job.error.message}`);
+    }
+    else if (job.status === "timed-out") {
+        lines.push(`❌ Evaluation timed out`);
+        lines.push("   The job did not complete within the server-side deadline.");
+    }
+    else {
+        lines.push(`❌ Evaluation ${job.status}`);
+    }
+    // Remediation hint
+    if (job.error) {
+        const hint = getRemediationHint(job.error);
+        if (hint) {
+            lines.push("");
+            lines.push(`💡 ${hint}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/adapters/api-client/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * api-client/ — Barrel exports for the AILF API client adapter.
+ *
+ * Usage:
+ *   import { ApiClient, buildRemoteRequest, resolveTasksDir } from "./adapters/api-client/index.js"
+ */
+export { ApiClient } from "./api-client.js";
+export { buildRemoteRequest, resolveTasksDir, type BuildRequestOptions, type RemoteConfigSlice, } from "./build-request.js";
+export { ApiAuthError, ApiConnectionError, ApiError, ApiTimeoutError, } from "./errors.js";
+export { formatJobError } from "./format-error.js";
+export { createProgressDisplay } from "./progress.js";
+export { getRemediationHint } from "./remediation.js";
+export type { ApiClientOptions, ApiEnvelope, ApiErrorDetail, ApiErrorResponse, JobError, JobExecution, JobProgress, JobResponse, JobStatus, SubmitResponse, ValidationIssue, ValidationResponse, WaitOptions, } from "./types.js";

package/dist/adapters/api-client/index.js

@@ -0,0 +1,12 @@
+/**
+ * api-client/ — Barrel exports for the AILF API client adapter.
+ *
+ * Usage:
+ *   import { ApiClient, buildRemoteRequest, resolveTasksDir } from "./adapters/api-client/index.js"
+ */
+export { ApiClient } from "./api-client.js";
+export { buildRemoteRequest, resolveTasksDir, } from "./build-request.js";
+export { ApiAuthError, ApiConnectionError, ApiError, ApiTimeoutError, } from "./errors.js";
+export { formatJobError } from "./format-error.js";
+export { createProgressDisplay } from "./progress.js";
+export { getRemediationHint } from "./remediation.js";

package/dist/adapters/api-client/progress.d.ts

@@ -0,0 +1,26 @@
+/**
+ * api-client/progress.ts — Polling progress display for the terminal.
+ *
+ * Creates a callback function that the ApiClient's `waitForCompletion()`
+ * calls after each poll. Tracks elapsed time and emits single-line status
+ * updates so the user sees real-time feedback during remote evaluation.
+ */
+import type { JobResponse } from "./types.js";
+/**
+ * Create a progress display callback for `waitForCompletion()`.
+ *
+ * Usage:
+ * ```ts
+ * const job = await client.waitForCompletion(jobId, {
+ *   onProgress: createProgressDisplay(),
+ * })
+ * ```
+ *
+ * Output example:
+ * ```
+ * ⏳ [queued] Waiting for runner...
+ * ⏳ [running] Step 2/8: fetch-docs (1m 12s)
+ * ⏳ [running] Step 5/8: run-eval (3m 45s)
+ * ```
+ */
+export declare function createProgressDisplay(): (job: JobResponse) => void;

package/dist/adapters/api-client/progress.js

@@ -0,0 +1,69 @@
+/**
+ * api-client/progress.ts — Polling progress display for the terminal.
+ *
+ * Creates a callback function that the ApiClient's `waitForCompletion()`
+ * calls after each poll. Tracks elapsed time and emits single-line status
+ * updates so the user sees real-time feedback during remote evaluation.
+ */
+/**
+ * Create a progress display callback for `waitForCompletion()`.
+ *
+ * Usage:
+ * ```ts
+ * const job = await client.waitForCompletion(jobId, {
+ *   onProgress: createProgressDisplay(),
+ * })
+ * ```
+ *
+ * Output example:
+ * ```
+ * ⏳ [queued] Waiting for runner...
+ * ⏳ [running] Step 2/8: fetch-docs (1m 12s)
+ * ⏳ [running] Step 5/8: run-eval (3m 45s)
+ * ```
+ */
+export function createProgressDisplay() {
+    const startMs = Date.now();
+    let lastLine = "";
+    return (job) => {
+        const elapsed = formatElapsed(Date.now() - startMs);
+        let line;
+        switch (job.status) {
+            case "received":
+                line = `⏳ [received] Submitted, waiting for API... (${elapsed})`;
+                break;
+            case "queued":
+                line = `⏳ [queued] Waiting for runner... (${elapsed})`;
+                break;
+            case "running": {
+                if (job.progress) {
+                    const { step, current, total } = job.progress;
+                    line = `⏳ [running] Step ${current}/${total}: ${step} (${elapsed})`;
+                }
+                else {
+                    line = `⏳ [running] Evaluating... (${elapsed})`;
+                }
+                break;
+            }
+            default:
+                // Terminal states — don't display; waitForCompletion handles them
+                return;
+        }
+        // Only print if the line changed (avoids duplicates during long-poll)
+        if (line !== lastLine) {
+            console.log(line);
+            lastLine = line;
+        }
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function formatElapsed(ms) {
+    const seconds = Math.floor(ms / 1000);
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    const remaining = seconds % 60;
+    return `${minutes}m ${remaining}s`;
+}

package/dist/adapters/api-client/remediation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * api-client/remediation.ts — Error-to-hint matching for common failures.
+ *
+ * When the pipeline fails remotely, the CLI extracts the structured error
+ * (step + message) and matches it against known patterns to provide
+ * actionable remediation advice. This replaces the inline JavaScript
+ * hints that were previously embedded in the generated workflow YAML.
+ *
+ * Keeping hints in TypeScript means they're:
+ * - Testable (unit tests per pattern)
+ * - Version-locked to the CLI (updated automatically)
+ * - Not duplicated across workflow templates
+ */
+import type { JobError } from "./types.js";
+/**
+ * Match an error against known patterns and return a remediation hint,
+ * or `undefined` if no pattern matches.
+ */
+export declare function getRemediationHint(error: JobError): string | undefined;

package/dist/adapters/api-client/remediation.js

@@ -0,0 +1,76 @@
+/**
+ * api-client/remediation.ts — Error-to-hint matching for common failures.
+ *
+ * When the pipeline fails remotely, the CLI extracts the structured error
+ * (step + message) and matches it against known patterns to provide
+ * actionable remediation advice. This replaces the inline JavaScript
+ * hints that were previously embedded in the generated workflow YAML.
+ *
+ * Keeping hints in TypeScript means they're:
+ * - Testable (unit tests per pattern)
+ * - Version-locked to the CLI (updated automatically)
+ * - Not duplicated across workflow templates
+ */
+const HINTS = [
+    {
+        match: (e) => /canonical context.*empty/i.test(e.message) ||
+            /no article found for slug/i.test(e.message),
+        hint: "One or more `canonicalDocs` slugs in your task definitions don't match " +
+            "any article in the documentation. Check the `slug` values in " +
+            "`.ailf/tasks/*.yaml` and ensure they correspond to real articles.\n" +
+            "  Run `ailf validate` to check your task definitions locally.",
+    },
+    {
+        match: (e) => /no tasks found/i.test(e.message),
+        hint: "No evaluation tasks were found. Add task YAML files to `.ailf/tasks/`.\n" +
+            "  Run `ailf init` to generate example tasks.",
+    },
+    {
+        match: (e) => /rate_limit_exceeded/i.test(e.message),
+        hint: "Your daily evaluation budget has been reached. Try again tomorrow,\n" +
+            "  or use `--debug` to run a smaller subset of tests.",
+    },
+    {
+        match: (e) => /concurrent_limit_exceeded/i.test(e.message),
+        hint: "Too many evaluations are running simultaneously.\n" +
+            "  Wait for the current jobs to finish before submitting a new one.",
+    },
+    {
+        match: (e) => /authentication_failed/i.test(e.message) ||
+            /invalid.*api.?key/i.test(e.message),
+        hint: "Check that `AILF_API_KEY` is set correctly in your environment.\n" +
+            "  The key should start with `ailf_live_sk_` or `ailf_test_sk_`.",
+    },
+    {
+        match: (e) => /validation_error/i.test(e.message) && /inlineTasks/i.test(e.message),
+        hint: "Your task definitions have validation errors.\n" +
+            "  Run `ailf validate` locally to see detailed error messages.",
+    },
+    {
+        match: (e) => e.step === "fetch-docs" && /postcondition/i.test(e.message),
+        hint: "The documentation fetch step completed but one or more tasks had " +
+            "empty context. This usually means a `canonicalDocs` slug doesn't " +
+            "match any article.\n" +
+            "  Check the slug values in `.ailf/tasks/*.yaml`.",
+    },
+    {
+        match: (e) => e.step === "dispatch" && /dispatch failed/i.test(e.message),
+        hint: "The evaluation could not be dispatched to the execution backend.\n" +
+            "  This is usually a transient infrastructure issue — try again in a few minutes.",
+    },
+];
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Match an error against known patterns and return a remediation hint,
+ * or `undefined` if no pattern matches.
+ */
+export function getRemediationHint(error) {
+    for (const entry of HINTS) {
+        if (entry.match(error)) {
+            return entry.hint;
+        }
+    }
+    return undefined;
+}