gazetta 0.6.0 → 0.8.0

package/dist/ai/adapter-scaffold.d.ts

@@ -0,0 +1,63 @@
+import type { AltGenerateInput, AltTextAdapter } from '../alt/adapter.js';
+/** Approximate characters-per-output-token for max-tokens derivation. */
+export declare const CHARS_PER_TOKEN = 4;
+/** Floor for derived max-tokens; ensures small maxChars still gives the model room. */
+export declare const MIN_MAX_TOKENS = 64;
+/**
+ * Provider-specific request closure passed to the scaffold. The closure
+ * makes the actual SDK call and returns the response text.
+ *
+ * The scaffold supplies:
+ *   - `bytes` / `mime` from prepared input
+ *   - `systemPrompt` already prepended with operator override (if any)
+ *   - `maxTokens` already resolved (operator override OR derived from maxChars)
+ *   - `userPrompt` from the suggester's compose-prompt output (the
+ *     base prompt minus operator's prepend; useful for OpenAI/Ollama
+ *     which split system vs. user)
+ *   - `request` original AltRequest for adapters that want maxChars / locale
+ *   - `signal` AbortSignal forwarded from caller
+ */
+export interface ProviderCallInput {
+    bytes: Uint8Array;
+    mime: string;
+    systemPrompt: string;
+    maxTokens: number;
+    request: AltGenerateInput['request'];
+    signal?: AbortSignal;
+}
+export interface AdapterScaffoldOptions {
+    /** Stable identifier for diagnostics ('anthropic', 'openai', 'ollama'). */
+    name: string;
+    /** MIME types the underlying provider accepts. */
+    supportedMimes: ReadonlySet<string>;
+    /** Operator-supplied system prompt; prepended to the system-composed prompt. */
+    operatorSystemPrompt?: string;
+    /** Operator-supplied max tokens; overrides derivation from maxChars. */
+    operatorMaxTokens?: number;
+    /** Provider-specific refusal markers; layered on top of shared markers. */
+    refusalMarkers: readonly string[];
+    /**
+     * Provider SDK call. Returns response text on success; throws on
+     * transport / API failure. Aborts should propagate as-is so the
+     * suggester's `signal.aborted` check returns null.
+     */
+    callProvider(input: ProviderCallInput): Promise<string>;
+    /**
+     * True for the SDK's user-abort exception type. Different SDKs throw
+     * different abort types; the scaffold lets each provider declare
+     * which one to pass through unchanged.
+     */
+    isAbortError(err: unknown): boolean;
+    /**
+     * Optional human-readable context appended to error messages
+     * (e.g., "Is Ollama running at http://localhost:11434?").
+     */
+    errorContextSuffix?: string;
+}
+/**
+ * Build an `AltTextAdapter` from provider-specific configuration. Owns
+ * the orchestration so per-provider files contribute only the SDK call
+ * and shape parsing.
+ */
+export declare function buildAltAdapterFromScaffold(opts: AdapterScaffoldOptions): AltTextAdapter;
+//# sourceMappingURL=adapter-scaffold.d.ts.map

package/dist/ai/adapter-scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-scaffold.d.ts","sourceRoot":"","sources":["../../src/ai/adapter-scaffold.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,gBAAgB,EAAiB,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAExF,yEAAyE;AACzE,eAAO,MAAM,eAAe,IAAI,CAAA;AAChC,uFAAuF;AACvF,eAAO,MAAM,cAAc,KAAK,CAAA;AAEhC;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,UAAU,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,gBAAgB,CAAC,SAAS,CAAC,CAAA;IACpC,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAA;IACZ,kDAAkD;IAClD,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACnC,gFAAgF;IAChF,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,wEAAwE;IACxE,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,2EAA2E;IAC3E,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC;;;;OAIG;IACH,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACvD;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAA;IACnC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,sBAAsB,GAAG,cAAc,CAyDxF"}

package/dist/ai/adapter-scaffold.js

@@ -0,0 +1,89 @@
+/**
+ * Shared scaffolding for `AltTextAdapter` implementations.
+ *
+ * Per Phase 4 of the Path X migration: the three v1.5 providers (Anthropic,
+ * OpenAI, Ollama) share substantial orchestration — operator-supplied
+ * prompt prepending, max-tokens derivation, refusal-marker layering, error
+ * translation. This module owns those shared concerns; per-provider files
+ * contribute only the provider-specific call (`callProvider`), abort
+ * detection (`isAbortError`), and refusal markers (`refusalMarkers`).
+ *
+ * # SOLID
+ *
+ *   - SRP: this module owns the alt-text adapter orchestration. Provider
+ *     files own the SDK call + response parsing.
+ *   - OCP: adding a fourth provider supplies a `callProvider` closure;
+ *     no edits to scaffolding.
+ *   - LSP: every adapter built via this scaffold honors the
+ *     `AltTextAdapter` contract identically.
+ *   - DIP: scaffold depends on `AltTextAdapter`, `AltGenerateInput`,
+ *     `AltSuggestion` — abstractions, not provider SDK types.
+ */
+import { AIAdapterFailedError, AIError } from './errors.js';
+import { detectRefusal } from './refusal.js';
+/** Approximate characters-per-output-token for max-tokens derivation. */
+export const CHARS_PER_TOKEN = 4;
+/** Floor for derived max-tokens; ensures small maxChars still gives the model room. */
+export const MIN_MAX_TOKENS = 64;
+/**
+ * Build an `AltTextAdapter` from provider-specific configuration. Owns
+ * the orchestration so per-provider files contribute only the SDK call
+ * and shape parsing.
+ */
+export function buildAltAdapterFromScaffold(opts) {
+    const operatorSystemPrompt = opts.operatorSystemPrompt;
+    const operatorMaxTokens = opts.operatorMaxTokens;
+    return {
+        name: opts.name,
+        supports(mime) {
+            return opts.supportedMimes.has(mime);
+        },
+        async generate(input, signal) {
+            // max_tokens: operator override > derived from maxChars.
+            const maxTokens = operatorMaxTokens ?? Math.max(MIN_MAX_TOKENS, Math.ceil(input.request.maxChars / CHARS_PER_TOKEN));
+            // System prompt: operator-supplied prepends to the system-composed
+            // prompt (per design-ai.md "Prompt composition"). Empty/absent
+            // operator prompt → just the system-composed.
+            const systemPrompt = operatorSystemPrompt ? `${operatorSystemPrompt}\n\n${input.prompt}` : input.prompt;
+            let text;
+            try {
+                text = await opts.callProvider({
+                    bytes: input.bytes,
+                    mime: input.mime,
+                    systemPrompt,
+                    maxTokens,
+                    request: input.request,
+                    signal,
+                });
+            }
+            catch (err) {
+                // Aborts pass through — suggester checks `signal.aborted` and
+                // returns null. Wrapping into AIAdapterFailedError would lose
+                // the abort signal.
+                if (opts.isAbortError(err))
+                    throw err;
+                // AI-domain errors thrown by the provider's response-parsing
+                // (e.g., AIInvalidResponseError when the SDK returns no text
+                // block) pass through unchanged. Only transport / SDK-level
+                // failures get wrapped as AIAdapterFailedError.
+                if (err instanceof AIError)
+                    throw err;
+                const suffix = opts.errorContextSuffix ? `. ${opts.errorContextSuffix}` : '';
+                if (err instanceof Error) {
+                    throw new AIAdapterFailedError(`${opts.name} alt-text generation failed: ${err.message}${suffix}`, {
+                        cause: err,
+                    });
+                }
+                throw new AIAdapterFailedError(`${opts.name} alt-text generation failed: unknown error${suffix}`);
+            }
+            const trimmed = text.trim();
+            const refusal = detectRefusal(trimmed, opts.refusalMarkers);
+            return {
+                text: trimmed,
+                refused: refusal.refused,
+                refusalReason: refusal.reason,
+            };
+        },
+    };
+}
+//# sourceMappingURL=adapter-scaffold.js.map

package/dist/ai/adapter-scaffold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-scaffold.js","sourceRoot":"","sources":["../../src/ai/adapter-scaffold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAG5C,yEAAyE;AACzE,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAA;AAChC,uFAAuF;AACvF,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,CAAA;AAuDhC;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,IAA4B;IACtE,MAAM,oBAAoB,GAAG,IAAI,CAAC,oBAAoB,CAAA;IACtD,MAAM,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,CAAA;IAEhD,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,QAAQ,CAAC,IAAY;YACnB,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QACtC,CAAC;QACD,KAAK,CAAC,QAAQ,CAAC,KAAuB,EAAE,MAAoB;YAC1D,yDAAyD;YACzD,MAAM,SAAS,GACb,iBAAiB,IAAI,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,GAAG,eAAe,CAAC,CAAC,CAAA;YAEpG,mEAAmE;YACnE,+DAA+D;YAC/D,8CAA8C;YAC9C,MAAM,YAAY,GAAG,oBAAoB,CAAC,CAAC,CAAC,GAAG,oBAAoB,OAAO,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAA;YAEvG,IAAI,IAAY,CAAA;YAChB,IAAI,CAAC;gBACH,IAAI,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC;oBAC7B,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,IAAI,EAAE,KAAK,CAAC,IAAI;oBAChB,YAAY;oBACZ,SAAS;oBACT,OAAO,EAAE,KAAK,CAAC,OAAO;oBACtB,MAAM;iBACP,CAAC,CAAA;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,8DAA8D;gBAC9D,8DAA8D;gBAC9D,oBAAoB;gBACpB,IAAI,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC;oBAAE,MAAM,GAAG,CAAA;gBACrC,6DAA6D;gBAC7D,6DAA6D;gBAC7D,4DAA4D;gBAC5D,gDAAgD;gBAChD,IAAI,GAAG,YAAY,OAAO;oBAAE,MAAM,GAAG,CAAA;gBACrC,MAAM,MAAM,GAAG,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;gBAC5E,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;oBACzB,MAAM,IAAI,oBAAoB,CAAC,GAAG,IAAI,CAAC,IAAI,gCAAgC,GAAG,CAAC,OAAO,GAAG,MAAM,EAAE,EAAE;wBACjG,KAAK,EAAE,GAAG;qBACX,CAAC,CAAA;gBACJ,CAAC;gBACD,MAAM,IAAI,oBAAoB,CAAC,GAAG,IAAI,CAAC,IAAI,6CAA6C,MAAM,EAAE,CAAC,CAAA;YACnG,CAAC;YAED,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;YAC3B,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,CAAC,CAAA;YAC3D,OAAO;gBACL,IAAI,EAAE,OAAO;gBACb,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,aAAa,EAAE,OAAO,CAAC,MAAM;aAC9B,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/ai/compose-prompt.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Generic prompt composer — assembles a final prompt string from an
+ * ordered list of `PromptPolicy<T>` functions, where `T` is the typed
+ * request shape for the calling task.
+ *
+ * # Why generic over `T`
+ *
+ * Each AI task has its own typed request (alt-text has `AltRequest`
+ * with `locale`, `maxChars`, `style`; future translation will have its
+ * own with source/target language pairs, formality, etc.). The
+ * composer doesn't need to know task-specific fields — it just calls
+ * each policy in order and joins the non-empty results.
+ *
+ * Putting the composer in `ai/` (not in `alt/`) means the second task
+ * doesn't reimplement composition. Each task contributes its own
+ * `PromptPolicy<TaskRequest>` modules that import this composer.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this module owns "ordered policies → final prompt string"
+ *   - OCP: callers pass their own policy array; the default policy set
+ *     is the task's responsibility, not this module's
+ *   - LSP: every policy is `(req: T) => string`; trivially substitutable
+ *   - DIP: tasks depend on this generic composer, not on each other
+ *
+ * # Empty-string convention
+ *
+ * Policies that don't apply (e.g., the locale policy when locale is
+ * the default 'en') return an empty string. The composer filters these
+ * out before joining, so empty paragraphs don't appear in the final
+ * prompt. This keeps each policy decision local — no callers need to
+ * reason about "should I include this policy?"
+ */
+/**
+ * One dimension of prompt content. A function from a typed request to
+ * a string paragraph. Empty string means "this policy doesn't apply
+ * for this request" and is dropped before assembly.
+ */
+export type PromptPolicy<TRequest> = (req: TRequest) => string;
+/**
+ * Assemble policies into a prompt. Joins non-empty results with two
+ * newlines (paragraph break) — model providers parse this as natural
+ * structure. Order matters: callers pass the array in the order they
+ * want paragraphs to appear.
+ *
+ * Tests can pass a custom policy array to validate composition without
+ * coupling to any task's default set.
+ */
+export declare function composePrompt<TRequest>(req: TRequest, policies: readonly PromptPolicy<TRequest>[]): string;
+//# sourceMappingURL=compose-prompt.d.ts.map

package/dist/ai/compose-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-prompt.d.ts","sourceRoot":"","sources":["../../src/ai/compose-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;GAIG;AACH,MAAM,MAAM,YAAY,CAAC,QAAQ,IAAI,CAAC,GAAG,EAAE,QAAQ,KAAK,MAAM,CAAA;AAE9D;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,YAAY,CAAC,QAAQ,CAAC,EAAE,GAAG,MAAM,CAK1G"}

package/dist/ai/compose-prompt.js

@@ -0,0 +1,49 @@
+/**
+ * Generic prompt composer — assembles a final prompt string from an
+ * ordered list of `PromptPolicy<T>` functions, where `T` is the typed
+ * request shape for the calling task.
+ *
+ * # Why generic over `T`
+ *
+ * Each AI task has its own typed request (alt-text has `AltRequest`
+ * with `locale`, `maxChars`, `style`; future translation will have its
+ * own with source/target language pairs, formality, etc.). The
+ * composer doesn't need to know task-specific fields — it just calls
+ * each policy in order and joins the non-empty results.
+ *
+ * Putting the composer in `ai/` (not in `alt/`) means the second task
+ * doesn't reimplement composition. Each task contributes its own
+ * `PromptPolicy<TaskRequest>` modules that import this composer.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this module owns "ordered policies → final prompt string"
+ *   - OCP: callers pass their own policy array; the default policy set
+ *     is the task's responsibility, not this module's
+ *   - LSP: every policy is `(req: T) => string`; trivially substitutable
+ *   - DIP: tasks depend on this generic composer, not on each other
+ *
+ * # Empty-string convention
+ *
+ * Policies that don't apply (e.g., the locale policy when locale is
+ * the default 'en') return an empty string. The composer filters these
+ * out before joining, so empty paragraphs don't appear in the final
+ * prompt. This keeps each policy decision local — no callers need to
+ * reason about "should I include this policy?"
+ */
+/**
+ * Assemble policies into a prompt. Joins non-empty results with two
+ * newlines (paragraph break) — model providers parse this as natural
+ * structure. Order matters: callers pass the array in the order they
+ * want paragraphs to appear.
+ *
+ * Tests can pass a custom policy array to validate composition without
+ * coupling to any task's default set.
+ */
+export function composePrompt(req, policies) {
+    return policies
+        .map(policy => policy(req))
+        .filter(paragraph => paragraph.length > 0)
+        .join('\n\n');
+}
+//# sourceMappingURL=compose-prompt.js.map

package/dist/ai/compose-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-prompt.js","sourceRoot":"","sources":["../../src/ai/compose-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AASH;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAW,GAAa,EAAE,QAA2C;IAChG,OAAO,QAAQ;SACZ,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;SAC1B,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;SACzC,IAAI,CAAC,MAAM,CAAC,CAAA;AACjB,CAAC"}

package/dist/ai/errors.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Typed errors for the AI domain — one class per failure mode, each
+ * carrying an HTTP status so route handlers don't pattern-match on
+ * messages.
+ *
+ * Pattern mirrors `assets/errors.ts`: subclass `AIError`, declare the
+ * `code` and `httpStatus` on the class, override `toResponseBody()` if
+ * extra structured fields are needed.
+ *
+ * Adding a new AI error is one new subclass + one new code in the
+ * union. Routes pick up the new HTTP status via the `httpStatus`
+ * property — no route-handler edits required (OCP).
+ */
+export type AIErrorCode = 'AI_ADAPTER_UNAVAILABLE' | 'AI_ADAPTER_FAILED' | 'AI_INVALID_RESPONSE';
+export type AIErrorHttpStatus = 502 | 503;
+export interface AIErrorResponseBody {
+    readonly code: AIErrorCode;
+    readonly message: string;
+}
+/**
+ * Base class. Subclasses set `code` and `httpStatus` as readonly
+ * properties; the base provides the `toResponseBody()` machinery.
+ */
+export declare abstract class AIError extends Error {
+    abstract readonly code: AIErrorCode;
+    abstract readonly httpStatus: AIErrorHttpStatus;
+    toResponseBody(): AIErrorResponseBody;
+}
+/**
+ * No adapter is configured for the target, OR the adapter is configured
+ * but its credentials are missing, OR the adapter doesn't support the
+ * requested MIME. UI hides AI affordances; route returns 503.
+ *
+ * Distinct from `AIAdapterFailedError` because this is a configuration
+ * state, not a runtime failure — retrying won't help.
+ */
+export declare class AIAdapterUnavailableError extends AIError {
+    readonly code = "AI_ADAPTER_UNAVAILABLE";
+    readonly httpStatus = 503;
+}
+/**
+ * Adapter was reached but the call failed — network error, auth
+ * rejection, rate limit not handled by the SDK's own retry, malformed
+ * response. Route returns 502 (we're acting as a gateway to the
+ * upstream provider).
+ *
+ * The provider-specific cause is attached as `cause` (per the standard
+ * Error.cause property) so logs can drill into the underlying failure
+ * without leaking provider details into the API response.
+ */
+export declare class AIAdapterFailedError extends AIError {
+    readonly code = "AI_ADAPTER_FAILED";
+    readonly httpStatus = 502;
+}
+/**
+ * Adapter received a response from the provider, but it didn't parse
+ * into the expected shape (missing content field, unexpected null,
+ * etc.). 502 — same gateway semantics as `AIAdapterFailedError`, but
+ * the cause is parsing rather than transport.
+ */
+export declare class AIInvalidResponseError extends AIError {
+    readonly code = "AI_INVALID_RESPONSE";
+    readonly httpStatus = 502;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/ai/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/ai/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,WAAW,GAAG,wBAAwB,GAAG,mBAAmB,GAAG,qBAAqB,CAAA;AAEhG,MAAM,MAAM,iBAAiB,GAAG,GAAG,GAAG,GAAG,CAAA;AAEzC,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED;;;GAGG;AACH,8BAAsB,OAAQ,SAAQ,KAAK;IACzC,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IACnC,QAAQ,CAAC,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAA;IAE/C,cAAc,IAAI,mBAAmB;CAGtC;AAED;;;;;;;GAOG;AACH,qBAAa,yBAA0B,SAAQ,OAAO;IACpD,QAAQ,CAAC,IAAI,4BAA2B;IACxC,QAAQ,CAAC,UAAU,OAAM;CAC1B;AAED;;;;;;;;;GASG;AACH,qBAAa,oBAAqB,SAAQ,OAAO;IAC/C,QAAQ,CAAC,IAAI,uBAAsB;IACnC,QAAQ,CAAC,UAAU,OAAM;CAC1B;AAED;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,OAAO;IACjD,QAAQ,CAAC,IAAI,yBAAwB;IACrC,QAAQ,CAAC,UAAU,OAAM;CAC1B"}

package/dist/ai/errors.js

@@ -0,0 +1,59 @@
+/**
+ * Typed errors for the AI domain — one class per failure mode, each
+ * carrying an HTTP status so route handlers don't pattern-match on
+ * messages.
+ *
+ * Pattern mirrors `assets/errors.ts`: subclass `AIError`, declare the
+ * `code` and `httpStatus` on the class, override `toResponseBody()` if
+ * extra structured fields are needed.
+ *
+ * Adding a new AI error is one new subclass + one new code in the
+ * union. Routes pick up the new HTTP status via the `httpStatus`
+ * property — no route-handler edits required (OCP).
+ */
+/**
+ * Base class. Subclasses set `code` and `httpStatus` as readonly
+ * properties; the base provides the `toResponseBody()` machinery.
+ */
+export class AIError extends Error {
+    toResponseBody() {
+        return { code: this.code, message: this.message };
+    }
+}
+/**
+ * No adapter is configured for the target, OR the adapter is configured
+ * but its credentials are missing, OR the adapter doesn't support the
+ * requested MIME. UI hides AI affordances; route returns 503.
+ *
+ * Distinct from `AIAdapterFailedError` because this is a configuration
+ * state, not a runtime failure — retrying won't help.
+ */
+export class AIAdapterUnavailableError extends AIError {
+    code = 'AI_ADAPTER_UNAVAILABLE';
+    httpStatus = 503;
+}
+/**
+ * Adapter was reached but the call failed — network error, auth
+ * rejection, rate limit not handled by the SDK's own retry, malformed
+ * response. Route returns 502 (we're acting as a gateway to the
+ * upstream provider).
+ *
+ * The provider-specific cause is attached as `cause` (per the standard
+ * Error.cause property) so logs can drill into the underlying failure
+ * without leaking provider details into the API response.
+ */
+export class AIAdapterFailedError extends AIError {
+    code = 'AI_ADAPTER_FAILED';
+    httpStatus = 502;
+}
+/**
+ * Adapter received a response from the provider, but it didn't parse
+ * into the expected shape (missing content field, unexpected null,
+ * etc.). 502 — same gateway semantics as `AIAdapterFailedError`, but
+ * the cause is parsing rather than transport.
+ */
+export class AIInvalidResponseError extends AIError {
+    code = 'AI_INVALID_RESPONSE';
+    httpStatus = 502;
+}
+//# sourceMappingURL=errors.js.map

package/dist/ai/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/ai/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAWH;;;GAGG;AACH,MAAM,OAAgB,OAAQ,SAAQ,KAAK;IAIzC,cAAc;QACZ,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAA;IACnD,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,yBAA0B,SAAQ,OAAO;IAC3C,IAAI,GAAG,wBAAwB,CAAA;IAC/B,UAAU,GAAG,GAAG,CAAA;CAC1B;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,oBAAqB,SAAQ,OAAO;IACtC,IAAI,GAAG,mBAAmB,CAAA;IAC1B,UAAU,GAAG,GAAG,CAAA;CAC1B;AAED;;;;;GAKG;AACH,MAAM,OAAO,sBAAuB,SAAQ,OAAO;IACxC,IAAI,GAAG,qBAAqB,CAAA;IAC5B,UAAU,GAAG,GAAG,CAAA;CAC1B"}

package/dist/ai/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Public surface of `ai/` — cross-task AI infrastructure shared by
+ * per-task implementations (alt-text in v1.5; translation, tag
+ * suggestion, summarization in future).
+ *
+ * `ai/` is a code library, not an inheritance hierarchy. Tasks compose
+ * these utilities — they don't extend a base class. Per
+ * [team-preferences.md] convention 1: composition over inheritance.
+ */
+export type { AIProvider, AltTextTaskConfig } from './provider.js';
+export { PROVIDER_DEFAULT_MODELS } from './provider.js';
+export { AIError, AIAdapterUnavailableError, AIAdapterFailedError, AIInvalidResponseError, type AIErrorCode, type AIErrorHttpStatus, type AIErrorResponseBody, } from './errors.js';
+export { detectRefusal, type RefusalDetection } from './refusal.js';
+export { composePrompt, type PromptPolicy } from './compose-prompt.js';
+export { prepareForVision, MAX_EDGE, type PrepareInput, type PreparedImage } from './vision-prep.js';
+export { buildAltAdapterFromScaffold, type AdapterScaffoldOptions, type ProviderCallInput, } from './adapter-scaffold.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/ai/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ai/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAClE,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAA;AACvD,OAAO,EACL,OAAO,EACP,yBAAyB,EACzB,oBAAoB,EACpB,sBAAsB,EACtB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACnE,OAAO,EAAE,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACtE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAA;AACpG,OAAO,EACL,2BAA2B,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,GACvB,MAAM,uBAAuB,CAAA"}

package/dist/ai/index.js

@@ -0,0 +1,16 @@
+/**
+ * Public surface of `ai/` — cross-task AI infrastructure shared by
+ * per-task implementations (alt-text in v1.5; translation, tag
+ * suggestion, summarization in future).
+ *
+ * `ai/` is a code library, not an inheritance hierarchy. Tasks compose
+ * these utilities — they don't extend a base class. Per
+ * [team-preferences.md] convention 1: composition over inheritance.
+ */
+export { PROVIDER_DEFAULT_MODELS } from './provider.js';
+export { AIError, AIAdapterUnavailableError, AIAdapterFailedError, AIInvalidResponseError, } from './errors.js';
+export { detectRefusal } from './refusal.js';
+export { composePrompt } from './compose-prompt.js';
+export { prepareForVision, MAX_EDGE } from './vision-prep.js';
+export { buildAltAdapterFromScaffold, } from './adapter-scaffold.js';
+//# sourceMappingURL=index.js.map

package/dist/ai/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ai/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAA;AACvD,OAAO,EACL,OAAO,EACP,yBAAyB,EACzB,oBAAoB,EACpB,sBAAsB,GAIvB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,aAAa,EAAyB,MAAM,cAAc,CAAA;AACnE,OAAO,EAAE,aAAa,EAAqB,MAAM,qBAAqB,CAAA;AACtE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAyC,MAAM,kBAAkB,CAAA;AACpG,OAAO,EACL,2BAA2B,GAG5B,MAAM,uBAAuB,CAAA"}

package/dist/ai/provider.d.ts

@@ -0,0 +1,76 @@
+/**
+ * `AIProvider` — transport-only interface for an AI account / endpoint.
+ *
+ * Per [`design-ai.md`](../../../.claude/rules/design-ai.md) "Two-axis split":
+ * the provider holds transport (apiKey, baseUrl, organizationId, timeout)
+ * and exposes per-task builder methods that return per-task adapters.
+ * Operational config (model, systemPrompt, maxTokens) lives in
+ * data-literal blocks the resolver feeds to `provider.altText({...})`
+ * at boot — not on the provider constructor.
+ *
+ * Why split: one Anthropic account legitimately serves multiple tasks
+ * (alt-text, future translation, future summarization, future
+ * image-gen) with different model + prompt + token-budget per task.
+ * Putting model/prompt on the constructor would force operators to
+ * build a separate provider per task; transport-only keeps providers
+ * reusable across tasks.
+ *
+ * Future tasks add their own builder method here:
+ *   - `translation(taskConfig: TranslationTaskConfig): TranslationAdapter`
+ *   - `summarization(taskConfig: SummarizationTaskConfig): SummarizationAdapter`
+ *
+ * Plugin-supplied providers may extend this with their own builder
+ * methods; consumers depend on the abstraction (`AIProvider`), not
+ * the concrete provider classes.
+ */
+import type { AltTextAdapter } from '../alt/adapter.js';
+/**
+ * Per-task configuration for the alt-text task. Data-literal type fed to
+ * `provider.altText(taskConfig)` by the resolver. Field details:
+ *
+ *   - `model` — non-optional at adapter construction; the resolver always
+ *     supplies one (chain falls through to `PROVIDER_DEFAULT_MODELS`).
+ *     Operator-facing config blocks make it optional and inherit per the
+ *     three-rung chain (target → site → gazetta → provider default).
+ *
+ *   - `systemPrompt` — operator-supplied voice/style override. When set,
+ *     the suggester prepends it to the system-composed neutral prompt
+ *     (see `design-ai.md` "Prompt composition"). Null/undefined = use
+ *     system default only. Custom prompt policies (full replacement of
+ *     the WCAG-grounded base) remain v1.6+ deferred.
+ *
+ *   - `maxTokens` — generation budget cap. Provider-specific default
+ *     applies when null/undefined (Anthropic derives from `maxChars`;
+ *     OpenAI/Ollama use SDK defaults).
+ */
+export interface AltTextTaskConfig {
+    /** Model ID. Non-optional at adapter construction (resolver always supplies). */
+    model: string;
+    /** Operator-supplied system prompt; prepended to the system-composed prompt. */
+    systemPrompt?: string;
+    /** Generation token cap; provider-default applies when absent. */
+    maxTokens?: number;
+}
+/**
+ * Transport-only AI provider. Constructor takes credentials/endpoint
+ * config; builder methods construct per-task adapters from data-literal
+ * task config.
+ */
+export interface AIProvider {
+    /** Stable identifier for diagnostics + per-provider default-model lookup. */
+    readonly name: string;
+    /**
+     * Construct an alt-text adapter from per-task config. Resolver supplies
+     * the merged `AltTextTaskConfig` from the three-rung inheritance chain.
+     */
+    altText(taskConfig: AltTextTaskConfig): AltTextAdapter;
+}
+/**
+ * Per-provider sensible default model. Used when the model field is
+ * unset across the entire chain (gazetta → site → target). Plugin
+ * providers contribute their own name; default-model fallback for
+ * unknown plugin names returns undefined (operator must specify
+ * `model` somewhere in the chain).
+ */
+export declare const PROVIDER_DEFAULT_MODELS: Record<string, string>;
+//# sourceMappingURL=provider.d.ts.map

package/dist/ai/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/ai/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAEvD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAA;IACb,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;OAGG;IACH,OAAO,CAAC,UAAU,EAAE,iBAAiB,GAAG,cAAc,CAAA;CAKvD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAI1D,CAAA"}

package/dist/ai/provider.js

@@ -0,0 +1,13 @@
+/**
+ * Per-provider sensible default model. Used when the model field is
+ * unset across the entire chain (gazetta → site → target). Plugin
+ * providers contribute their own name; default-model fallback for
+ * unknown plugin names returns undefined (operator must specify
+ * `model` somewhere in the chain).
+ */
+export const PROVIDER_DEFAULT_MODELS = {
+    anthropic: 'claude-haiku-4-5',
+    openai: 'gpt-4o-mini',
+    ollama: 'llama3.2-vision:11b',
+};
+//# sourceMappingURL=provider.js.map

package/dist/ai/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/ai/provider.ts"],"names":[],"mappings":"AA2EA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAA2B;IAC7D,SAAS,EAAE,kBAAkB;IAC7B,MAAM,EAAE,aAAa;IACrB,MAAM,EAAE,qBAAqB;CAC9B,CAAA"}

package/dist/ai/refusal.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Refusal detection for AI provider responses.
+ *
+ * # Why this lives in `ai/` and not `alt/`
+ *
+ * Provider safety refusals look the same regardless of task. Whether
+ * the model is asked to describe an image (alt-text) or translate a
+ * paragraph (future), a refusal arrives as a 200 OK with text like
+ * "I can't help with that" in the response body — structurally
+ * indistinguishable from a successful response without inspection.
+ *
+ * v1.5's only consumer is `alt/`, but refusal detection is conceptually
+ * cross-task. Right structure now beats right structure later, per
+ * [team-preferences rule 18]: "extract shared code when you first see
+ * the split concern". Translation as the documented next consumer
+ * (per [design-ai-implementation.md]) makes this a known split.
+ *
+ * # Marker maintenance
+ *
+ * The marker list below MUST stay current as providers tune their
+ * safety messaging. Plan: review at every major model version bump
+ * (e.g., when an adapter's `defaultModel` jumps a major). Provider-
+ * specific phrases live in the adapter (passed via `adapterMarkers`)
+ * so generic markers and provider-specific ones can evolve
+ * independently.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this module owns "raw text → structured refusal info"
+ *   - OCP: per-adapter markers extend without touching the shared list
+ *   - DIP: callers depend on `detectRefusal`, not on substring inspection
+ *     scattered across the codebase
+ */
+export interface RefusalDetection {
+    refused: boolean;
+    /** Truncated reason text when refused; null when not. */
+    reason: string | null;
+}
+/**
+ * Detect whether `text` is a refusal. Caller passes adapter-specific
+ * markers (e.g., Anthropic's particular phrasing) on top of the shared
+ * list.
+ *
+ * Returns `{ refused: false, reason: null }` for descriptive responses;
+ * `{ refused: true, reason: <truncated text> }` otherwise. Reason is
+ * truncated to 200 chars so logs and UI toasts don't render arbitrarily
+ * long refusal blocks.
+ */
+export declare function detectRefusal(text: string, adapterMarkers?: readonly string[]): RefusalDetection;
+//# sourceMappingURL=refusal.d.ts.map

package/dist/ai/refusal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusal.d.ts","sourceRoot":"","sources":["../../src/ai/refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AA2CH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAA;IAChB,yDAAyD;IACzD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,GAAE,SAAS,MAAM,EAAO,GAAG,gBAAgB,CAgBpG"}