@suknna/pixelforge 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suknna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# PixelForge
+
+PixelForge is an opencode plugin that adds background image generation tools. The model calls a tool with a prompt and an output path; PixelForge generates the image in the background, writes it to the workspace, and reports completion through an opencode TUI Toast plus an explicit job-status query tool.
+
+## Install
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@suknna/pixelforge"]
+}
+```
+
+For local development against a built checkout:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["./dist/index.js"]
+}
+```
+
+Restart opencode after changing plugin or config files. opencode loads plugins at startup and does not hot-reload them.
+
+## PixelForge Config
+
+PixelForge reads `~/.config/opencode/pixelforge.json`. The plugin fails fast at startup if the file is missing or invalid.
+
+Top-level fields:
+
+- `defaultProfile` (required): the profile tried first for every job.
+- `fallbackProfiles` (optional): an explicit, ordered list of profiles tried after the default. Only profiles listed here are ever attempted. Fallback happens **only** on transient errors (network failure, request timeout, HTTP `429`, HTTP `5xx`). Authentication, configuration, parameter, and moderation failures fail closed without fallback.
+- `notifications` (optional): `tui`, `sessionMessage`, and `autoContinue` booleans.
+- `profiles` (required): a map of profile name to provider config.
+
+Secrets may be plain strings or environment references:
+
+```json
+{ "apiKey": { "env": "OPENAI_API_KEY" } }
+```
+
+See [`examples/`](./examples) for complete multi-provider configurations. Supported providers: `openai-images`, `fal`, `replicate`, `stability-ai`.
+
+## Tools
+
+PixelForge registers three tools. None of them expose the internal `profile` concept — provider and fallback selection stay entirely inside the config.
+
+- `pixelforge_generate_image` — generate an image from a text prompt; returns a `jobId` immediately.
+- `pixelforge_generate_image_from_image` — generate a new image from an existing base image plus a text prompt; returns a `jobId` immediately.
+- `pixelforge_check_image_job` — report the status of a job by `jobId` (`queued`, `running`, `succeeded`, `failed`).
+
+Generation runs in the background. The generation tools return before the file exists; use `pixelforge_check_image_job` to confirm completion.
+
+## Output Paths
+
+Output paths must resolve inside the current opencode workspace. Relative paths are resolved from the session directory. Files are written atomically (temp file plus rename) so a visible output file always means a completed job.
+
+## Testing
+
+Do not commit `.env`. PixelForge itself never reads `.env`. Unit tests are deterministic and need no credentials. Real provider integration tests read credentials directly from environment variables:
+
+```bash
+PIXELFORGE_INTEGRATION=1 npm run test:integration
+```
+
+Without `PIXELFORGE_INTEGRATION`, integration tests skip cleanly. Integration output is written under `.tmp/`.

package/dist/adapters/fal.d.ts

@@ -0,0 +1,11 @@
+import type { ImageAdapter, ResolvedProfile } from "../types.js";
+/**
+ * fal adapter.
+ *
+ * Text-to-image posts to the configured `endpoint`; image-to-image posts to
+ * `imageToImageEndpoint` with the local base image inlined as a data URI.
+ * fal returns image URLs (or data URIs) which are downloaded/decoded to bytes.
+ */
+export declare function createFalAdapter(profile: Extract<ResolvedProfile, {
+    provider: "fal";
+}>): ImageAdapter;

package/dist/adapters/fal.js

@@ -0,0 +1,56 @@
+import { loadLocalImage, toDataUri } from "../image-input.js";
+import { decodeDataUri, fetchBytes, fetchJson } from "./http.js";
+/**
+ * fal adapter.
+ *
+ * Text-to-image posts to the configured `endpoint`; image-to-image posts to
+ * `imageToImageEndpoint` with the local base image inlined as a data URI.
+ * fal returns image URLs (or data URIs) which are downloaded/decoded to bytes.
+ */
+export function createFalAdapter(profile) {
+    return {
+        provider: "fal",
+        async generateImage(request) {
+            const response = await callFal(profile.endpoint, profile, {
+                prompt: request.prompt,
+                image_size: profile.imageSize,
+                output_format: profile.outputFormat,
+            }, request.signal);
+            return imageFromFalResponse(response);
+        },
+        async generateImageFromImage(request) {
+            const image = await loadLocalImage(request.baseImagePath);
+            const imageUrl = toDataUri(image);
+            const response = await callFal(profile.imageToImageEndpoint, profile, {
+                prompt: request.prompt,
+                image_url: imageUrl,
+                strength: request.strength ?? profile.defaultStrength,
+                image_size: profile.imageSize,
+                output_format: profile.outputFormat,
+            }, request.signal);
+            return imageFromFalResponse(response);
+        },
+    };
+}
+async function callFal(endpoint, profile, input, signal) {
+    const body = Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
+    return fetchJson(`https://fal.run/${endpoint}`, {
+        method: "POST",
+        signal,
+        headers: {
+            Authorization: `Key ${profile.credential}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+    }, "fal");
+}
+async function imageFromFalResponse(response) {
+    const image = response.images?.[0] ?? response.image;
+    const url = image?.url;
+    if (!url)
+        throw new Error("fal response did not include an image URL.");
+    if (url.startsWith("data:"))
+        return { ...decodeDataUri(url), provider: "fal" };
+    const downloaded = await fetchBytes(url, "fal");
+    return { ...downloaded, mimeType: image?.content_type ?? downloaded.mimeType, provider: "fal" };
+}

package/dist/adapters/http.d.ts

@@ -0,0 +1,21 @@
+import type { ProviderName } from "../types.js";
+/**
+ * Shared HTTP helpers for provider adapters.
+ *
+ * Every network failure is funneled through the error classifier so the
+ * runner can make a single retry/fail-closed decision regardless of which
+ * provider produced the error.
+ */
+export declare function fetchJson<T>(input: RequestInfo | URL, init: RequestInit, provider: ProviderName): Promise<T>;
+export declare function fetchBytes(url: string, provider: ProviderName): Promise<{
+    bytes: Uint8Array;
+    mimeType: string;
+}>;
+export declare function decodeBase64Image(base64: string, mimeType?: string): {
+    bytes: Uint8Array;
+    mimeType: string;
+};
+export declare function decodeDataUri(dataUri: string): {
+    bytes: Uint8Array;
+    mimeType: string;
+};

package/dist/adapters/http.js

@@ -0,0 +1,52 @@
+import { classifyHttpStatus, moderationError, PixelForgeError, toPixelForgeError } from "../errors.js";
+/**
+ * Shared HTTP helpers for provider adapters.
+ *
+ * Every network failure is funneled through the error classifier so the
+ * runner can make a single retry/fail-closed decision regardless of which
+ * provider produced the error.
+ */
+export async function fetchJson(input, init, provider) {
+    let response;
+    try {
+        response = await fetch(input, init);
+    }
+    catch (error) {
+        throw toPixelForgeError(error, provider);
+    }
+    const text = await response.text();
+    if (!response.ok)
+        throw providerHttpError(response.status, text, provider);
+    return text ? JSON.parse(text) : {};
+}
+export async function fetchBytes(url, provider) {
+    let response;
+    try {
+        response = await fetch(url);
+    }
+    catch (error) {
+        throw toPixelForgeError(error, provider);
+    }
+    if (!response.ok)
+        throw classifyHttpStatus(response.status, provider);
+    const mimeType = response.headers.get("content-type")?.split(";")[0] || "application/octet-stream";
+    return { bytes: new Uint8Array(await response.arrayBuffer()), mimeType };
+}
+export function decodeBase64Image(base64, mimeType = "image/png") {
+    return { bytes: Buffer.from(base64, "base64"), mimeType };
+}
+export function decodeDataUri(dataUri) {
+    const match = /^data:([^;]+);base64,(.+)$/.exec(dataUri);
+    const mimeType = match?.[1];
+    const base64 = match?.[2];
+    if (!mimeType || !base64) {
+        throw new PixelForgeError({ category: "provider", message: "Invalid data URI image output.", retryable: false });
+    }
+    return decodeBase64Image(base64, mimeType);
+}
+function providerHttpError(statusCode, body, provider) {
+    if (/moderation|safety|blocked|content policy/i.test(body)) {
+        return moderationError("Provider blocked the image request for safety reasons.", provider);
+    }
+    return classifyHttpStatus(statusCode, provider);
+}

package/dist/adapters/index.d.ts

@@ -0,0 +1,6 @@
+import type { ImageAdapter, ResolvedProfile } from "../types.js";
+/**
+ * Maps a resolved profile to its provider adapter. The exhaustive switch keeps
+ * provider selection explicit — no provider is inferred or aliased.
+ */
+export declare function createAdapter(profile: ResolvedProfile): ImageAdapter;

package/dist/adapters/index.js

@@ -0,0 +1,20 @@
+import { createFalAdapter } from "./fal.js";
+import { createOpenAIImagesAdapter } from "./openai-images.js";
+import { createReplicateAdapter } from "./replicate.js";
+import { createStabilityAIAdapter } from "./stability-ai.js";
+/**
+ * Maps a resolved profile to its provider adapter. The exhaustive switch keeps
+ * provider selection explicit — no provider is inferred or aliased.
+ */
+export function createAdapter(profile) {
+    switch (profile.provider) {
+        case "openai-images":
+            return createOpenAIImagesAdapter(profile);
+        case "fal":
+            return createFalAdapter(profile);
+        case "replicate":
+            return createReplicateAdapter(profile);
+        case "stability-ai":
+            return createStabilityAIAdapter(profile);
+    }
+}

package/dist/adapters/openai-images.d.ts

@@ -0,0 +1,11 @@
+import type { ImageAdapter, ResolvedProfile } from "../types.js";
+/**
+ * OpenAI Images adapter.
+ *
+ * Text-to-image hits `/images/generations`; image-to-image hits
+ * `/images/edits` with multipart form data. Both paths read base64 image
+ * bytes from `data[0].b64_json`.
+ */
+export declare function createOpenAIImagesAdapter(profile: Extract<ResolvedProfile, {
+    provider: "openai-images";
+}>): ImageAdapter;

package/dist/adapters/openai-images.js

@@ -0,0 +1,62 @@
+import { createReadStream } from "node:fs";
+import { decodeBase64Image, fetchJson } from "./http.js";
+/**
+ * OpenAI Images adapter.
+ *
+ * Text-to-image hits `/images/generations`; image-to-image hits
+ * `/images/edits` with multipart form data. Both paths read base64 image
+ * bytes from `data[0].b64_json`.
+ */
+export function createOpenAIImagesAdapter(profile) {
+    return {
+        provider: "openai-images",
+        async generateImage(request) {
+            const response = await fetchJson(`${profile.baseUrl.replace(/\/$/, "")}/images/generations`, {
+                method: "POST",
+                signal: request.signal,
+                headers: {
+                    Authorization: `Bearer ${profile.credential}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    model: profile.model,
+                    prompt: request.prompt,
+                    size: profile.size,
+                    quality: profile.quality,
+                    output_format: profile.outputFormat,
+                }),
+            }, "openai-images");
+            return imageFromOpenAIResponse(response, profile.outputFormat);
+        },
+        async generateImageFromImage(request) {
+            const form = new FormData();
+            form.set("model", profile.model);
+            form.set("prompt", request.prompt);
+            form.set("image[]", await fileFromPath(request.baseImagePath));
+            if (profile.size)
+                form.set("size", profile.size);
+            if (profile.quality)
+                form.set("quality", profile.quality);
+            if (profile.outputFormat)
+                form.set("output_format", profile.outputFormat);
+            const response = await fetchJson(`${profile.baseUrl.replace(/\/$/, "")}/images/edits`, {
+                method: "POST",
+                signal: request.signal,
+                headers: { Authorization: `Bearer ${profile.credential}` },
+                body: form,
+            }, "openai-images");
+            return imageFromOpenAIResponse(response, profile.outputFormat);
+        },
+    };
+}
+function imageFromOpenAIResponse(response, outputFormat = "png") {
+    const base64 = response.data?.[0]?.b64_json;
+    if (!base64)
+        throw new Error("OpenAI image response did not include data[0].b64_json.");
+    const mimeType = outputFormat === "jpeg" ? "image/jpeg" : outputFormat === "webp" ? "image/webp" : "image/png";
+    return { ...decodeBase64Image(base64, mimeType), provider: "openai-images" };
+}
+async function fileFromPath(filePath) {
+    const bytes = await new Response(createReadStream(filePath)).arrayBuffer();
+    return new File([bytes], filePath.split(/[\\/]/).at(-1) || "image.png");
+}

package/dist/adapters/replicate.d.ts

@@ -0,0 +1,6 @@
+import type { ImageAdapter, ResolvedProfile } from "../types.js";
+type ReplicateProfile = Extract<ResolvedProfile, {
+    provider: "replicate";
+}>;
+export declare function createReplicateAdapter(profile: ReplicateProfile): ImageAdapter;
+export {};

package/dist/adapters/replicate.js

@@ -0,0 +1,67 @@
+import { loadLocalImage, toDataUri } from "../image-input.js";
+import { decodeDataUri, fetchBytes, fetchJson } from "./http.js";
+export function createReplicateAdapter(profile) {
+    return {
+        provider: "replicate",
+        async generateImage(request) {
+            const prediction = await createPrediction(profile, { [profile.promptInputKey]: request.prompt }, request.signal);
+            return pollPrediction(profile, prediction, request.signal);
+        },
+        async generateImageFromImage(request) {
+            const image = await loadLocalImage(request.baseImagePath);
+            const input = {
+                [profile.promptInputKey]: request.prompt,
+                [profile.imageInputKey]: toDataUri(image),
+            };
+            if (profile.strengthInputKey) {
+                const strength = request.strength ?? profile.defaultStrength;
+                if (strength !== undefined)
+                    input[profile.strengthInputKey] = strength;
+            }
+            const prediction = await createPrediction(profile, input, request.signal);
+            return pollPrediction(profile, prediction, request.signal);
+        },
+    };
+}
+async function createPrediction(profile, input, signal) {
+    return fetchJson("https://api.replicate.com/v1/predictions", {
+        method: "POST",
+        signal,
+        headers: {
+            Authorization: `Bearer ${profile.credential}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ version: profile.version, input }),
+    }, "replicate");
+}
+async function pollPrediction(profile, prediction, signal) {
+    let current = prediction;
+    while (current.status === "starting" || current.status === "processing") {
+        await sleep(profile.pollIntervalMs, signal);
+        const pollUrl = current.urls?.get;
+        if (!pollUrl)
+            throw new Error("Replicate prediction did not include urls.get.");
+        current = await fetchJson(pollUrl, { method: "GET", signal, headers: { Authorization: `Bearer ${profile.credential}` } }, "replicate");
+    }
+    if (current.status !== "succeeded") {
+        throw new Error(current.error || `Replicate prediction ended with status ${current.status}.`);
+    }
+    return outputToImageResult(current.output);
+}
+async function outputToImageResult(output) {
+    const value = Array.isArray(output) ? output[0] : typeof output === "object" ? output?.url : output;
+    if (!value)
+        throw new Error("Replicate prediction succeeded without image output.");
+    if (value.startsWith("data:"))
+        return { ...decodeDataUri(value), provider: "replicate" };
+    return { ...(await fetchBytes(value, "replicate")), provider: "replicate" };
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(resolve, ms);
+        signal.addEventListener("abort", () => {
+            clearTimeout(timer);
+            reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+        }, { once: true });
+    });
+}

package/dist/adapters/stability-ai.d.ts

@@ -0,0 +1,11 @@
+import type { ImageAdapter, ResolvedProfile } from "../types.js";
+type StabilityProfile = Extract<ResolvedProfile, {
+    provider: "stability-ai";
+}>;
+/**
+ * Stability returns base64 image payloads. Text-to-image uses a JSON body;
+ * image-to-image uploads the base image as multipart form data with an
+ * explicit strength parameter.
+ */
+export declare function createStabilityAIAdapter(profile: StabilityProfile): ImageAdapter;
+export {};

package/dist/adapters/stability-ai.js

@@ -0,0 +1,57 @@
+import { blobFromImage, loadLocalImage } from "../image-input.js";
+import { decodeBase64Image, fetchJson } from "./http.js";
+/**
+ * Stability returns base64 image payloads. Text-to-image uses a JSON body;
+ * image-to-image uploads the base image as multipart form data with an
+ * explicit strength parameter.
+ */
+export function createStabilityAIAdapter(profile) {
+    return {
+        provider: "stability-ai",
+        async generateImage(request) {
+            const response = await fetchJson(`${profile.baseUrl.replace(/\/$/, "")}${profile.textToImagePath}`, {
+                method: "POST",
+                signal: request.signal,
+                headers: {
+                    Authorization: `Bearer ${profile.credential}`,
+                    "Content-Type": "application/json",
+                    Accept: "application/json",
+                },
+                body: JSON.stringify({
+                    prompt: request.prompt,
+                    output_format: profile.outputFormat,
+                    width: profile.width,
+                    height: profile.height,
+                }),
+            }, "stability-ai");
+            return imageFromStabilityResponse(response, profile.outputFormat);
+        },
+        async generateImageFromImage(request) {
+            const image = await loadLocalImage(request.baseImagePath);
+            const form = new FormData();
+            form.set("prompt", request.prompt);
+            form.set("output_format", profile.outputFormat ?? "png");
+            const strength = request.strength ?? profile.defaultStrength;
+            if (strength !== undefined)
+                form.set("strength", String(strength));
+            form.set("image", blobFromImage(image), image.fileName);
+            const response = await fetchJson(`${profile.baseUrl.replace(/\/$/, "")}${profile.imageToImagePath}`, {
+                method: "POST",
+                signal: request.signal,
+                headers: {
+                    Authorization: `Bearer ${profile.credential}`,
+                    Accept: "application/json",
+                },
+                body: form,
+            }, "stability-ai");
+            return imageFromStabilityResponse(response, profile.outputFormat);
+        },
+    };
+}
+function imageFromStabilityResponse(response, outputFormat = "png") {
+    const base64 = response.image ?? response.images?.[0] ?? response.artifacts?.[0]?.base64;
+    if (!base64)
+        throw new Error("Stability AI response did not include an image.");
+    const mimeType = outputFormat === "jpeg" ? "image/jpeg" : outputFormat === "webp" ? "image/webp" : "image/png";
+    return { ...decodeBase64Image(base64, mimeType), provider: "stability-ai" };
+}

package/dist/config.d.ts

@@ -0,0 +1,5 @@
+import type { PixelForgeConfig, RawPixelForgeConfig } from "./types.js";
+export declare const DEFAULT_CONFIG_PATH: string;
+export declare function loadPixelForgeConfig(configPath?: string): Promise<PixelForgeConfig>;
+export declare function parseConfig(text: string, source?: string): RawPixelForgeConfig;
+export declare function resolveConfig(raw: RawPixelForgeConfig, env?: NodeJS.ProcessEnv): PixelForgeConfig;

package/dist/config.js

@@ -0,0 +1,103 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { configurationError } from "./errors.js";
+export const DEFAULT_CONFIG_PATH = path.join(homedir(), ".config", "opencode", "pixelforge.json");
+const DEFAULT_NOTIFICATIONS = { tui: true, sessionMessage: true, autoContinue: false };
+export async function loadPixelForgeConfig(configPath = DEFAULT_CONFIG_PATH) {
+    const text = await readFile(configPath, "utf8").catch((error) => {
+        throw configurationError(`Cannot read PixelForge config at ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    const raw = parseConfig(text, configPath);
+    return resolveConfig(raw);
+}
+export function parseConfig(text, source = "pixelforge.json") {
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw configurationError(`Invalid JSON in ${source}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export function resolveConfig(raw, env = process.env) {
+    if (!raw || typeof raw !== "object")
+        throw configurationError("PixelForge config must be a JSON object.");
+    if (!raw.defaultProfile)
+        throw configurationError("PixelForge config requires defaultProfile.");
+    if (!raw.profiles || typeof raw.profiles !== "object")
+        throw configurationError("PixelForge config requires profiles.");
+    if (!raw.profiles[raw.defaultProfile]) {
+        throw configurationError(`defaultProfile '${raw.defaultProfile}' is not defined in profiles.`);
+    }
+    const fallbackProfiles = raw.fallbackProfiles ?? [];
+    if (!Array.isArray(fallbackProfiles))
+        throw configurationError("fallbackProfiles must be an array.");
+    for (const name of fallbackProfiles) {
+        if (!raw.profiles[name])
+            throw configurationError(`fallbackProfiles contains unknown profile '${name}'.`);
+    }
+    const profiles = {};
+    for (const [profileName, profile] of Object.entries(raw.profiles)) {
+        profiles[profileName] = resolveProfile(profileName, profile, env);
+    }
+    return {
+        defaultProfile: raw.defaultProfile,
+        fallbackProfiles,
+        notifications: raw.notifications ?? { ...DEFAULT_NOTIFICATIONS },
+        profiles,
+    };
+}
+function resolveProfile(profileName, profile, env) {
+    validateTimeout(profileName, profile.timeoutMs);
+    validateStrength(profileName, profile.defaultStrength);
+    switch (profile.provider) {
+        case "openai-images":
+            requireString(profileName, "model", profile.model);
+            requireString(profileName, "baseUrl", profile.baseUrl);
+            requireString(profileName, "size", profile.size);
+            return { ...profile, profileName, credential: resolveSecret(profile.apiKey, env, `${profileName}.apiKey`) };
+        case "fal":
+            requireString(profileName, "endpoint", profile.endpoint);
+            requireString(profileName, "imageToImageEndpoint", profile.imageToImageEndpoint);
+            return { ...profile, profileName, credential: resolveSecret(profile.apiKey, env, `${profileName}.apiKey`) };
+        case "replicate":
+            requireString(profileName, "version", profile.version);
+            requireString(profileName, "promptInputKey", profile.promptInputKey);
+            requireString(profileName, "imageInputKey", profile.imageInputKey);
+            validateTimeout(profileName, profile.pollIntervalMs, "pollIntervalMs");
+            return { ...profile, profileName, credential: resolveSecret(profile.apiToken, env, `${profileName}.apiToken`) };
+        case "stability-ai":
+            requireString(profileName, "baseUrl", profile.baseUrl);
+            requireString(profileName, "textToImagePath", profile.textToImagePath);
+            requireString(profileName, "imageToImagePath", profile.imageToImagePath);
+            return { ...profile, profileName, credential: resolveSecret(profile.apiKey, env, `${profileName}.apiKey`) };
+    }
+}
+function resolveSecret(value, env, field) {
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    if (typeof value === "object" && value && "env" in value && value.env) {
+        const resolved = env[value.env];
+        if (!resolved)
+            throw configurationError(`${field} references missing environment variable ${value.env}.`);
+        return resolved;
+    }
+    throw configurationError(`${field} must be a non-empty string or { "env": "VAR" }.`);
+}
+function validateTimeout(profileName, timeoutMs, field = "timeoutMs") {
+    if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+        throw configurationError(`${profileName}.${field} must be a positive integer.`);
+    }
+}
+function validateStrength(profileName, strength) {
+    if (strength === undefined)
+        return;
+    if (typeof strength !== "number" || strength < 0 || strength > 1) {
+        throw configurationError(`${profileName}.defaultStrength must be between 0 and 1.`);
+    }
+}
+function requireString(profileName, field, value) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw configurationError(`${profileName}.${field} must be a non-empty string.`);
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,15 @@
+import type { ErrorCategory, ProviderError, ProviderName } from "./types.js";
+export declare class PixelForgeError extends Error implements ProviderError {
+    readonly category: ErrorCategory;
+    readonly retryable: boolean;
+    readonly statusCode?: number;
+    readonly provider?: ProviderName;
+    constructor(input: ProviderError);
+}
+export declare function classifyHttpStatus(statusCode: number, provider?: ProviderName): PixelForgeError;
+export declare function networkError(message: string, provider?: ProviderName): PixelForgeError;
+export declare function timeoutError(provider?: ProviderName): PixelForgeError;
+export declare function moderationError(message: string, provider?: ProviderName): PixelForgeError;
+export declare function configurationError(message: string): PixelForgeError;
+export declare function filesystemError(message: string): PixelForgeError;
+export declare function toPixelForgeError(error: unknown, provider?: ProviderName): PixelForgeError;