@ai-agent-tools/picgen 0.1.0-alpha.0

package/dist/cli.js

@@ -0,0 +1,1602 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import "dotenv/config";
+import { Command } from "commander";
+
+// src/commands/create.ts
+import YAML2 from "yaml";
+
+// src/assets/output.ts
+import { mkdir, writeFile } from "fs/promises";
+import { basename, extname, join } from "path";
+async function createGenerationRun(plan, now = /* @__PURE__ */ new Date()) {
+  const id = createRunId(plan, now);
+  const dateFolder = formatDate(now);
+  const outputDirectory = join(plan.outputDirectory, dateFolder, id);
+  const metadataPath = join(outputDirectory, "metadata.json");
+  const promptPath = join(outputDirectory, "prompt.txt");
+  await mkdir(outputDirectory, { recursive: true });
+  await writeFile(promptPath, plan.prompt, "utf8");
+  return {
+    id,
+    outputDirectory,
+    metadataPath,
+    promptPath
+  };
+}
+async function writeGenerationMetadata(run, metadata) {
+  await writeFile(run.metadataPath, JSON.stringify(redactGenerationMetadata(metadata), null, 2), "utf8");
+}
+function redactGenerationMetadata(metadata) {
+  return {
+    ...metadata,
+    provider_response: metadata.provider_response === void 0 ? void 0 : redactProviderImageData(metadata.provider_response)
+  };
+}
+async function writeProviderImage(run, image, index) {
+  const normalized = await normalizeProviderImage(image);
+  const id = `image-${index + 1}`;
+  const extension = extensionForMimeType(normalized.mime_type);
+  const path = join(run.outputDirectory, `${id}.${extension}`);
+  await writeFile(path, normalized.data);
+  const dimensions = readImageDimensions(normalized.data, normalized.mime_type);
+  return {
+    id,
+    path,
+    mime_type: normalized.mime_type,
+    metadata_path: run.metadataPath,
+    width: dimensions?.width,
+    height: dimensions?.height
+  };
+}
+async function writeProviderImages(run, images) {
+  const results = [];
+  for (const [index, image] of images.entries()) {
+    results.push(await writeProviderImage(run, image, index));
+  }
+  return results;
+}
+async function normalizeProviderImage(image) {
+  if (image.kind === "bytes") {
+    return {
+      data: image.data,
+      mime_type: image.mime_type
+    };
+  }
+  if (image.kind === "base64") {
+    const parsed = parseBase64Image(image.data);
+    return {
+      data: parsed.data,
+      mime_type: image.mime_type ?? parsed.mime_type ?? "image/png"
+    };
+  }
+  const response = await fetch(image.url);
+  if (!response.ok) {
+    throw new Error(`Failed to download generated image: ${response.status} ${response.statusText}`);
+  }
+  const contentType = response.headers.get("content-type")?.split(";")[0]?.trim();
+  return {
+    data: new Uint8Array(await response.arrayBuffer()),
+    mime_type: image.mime_type ?? contentType ?? mimeTypeFromUrl(image.url) ?? "image/png"
+  };
+}
+function parseBase64Image(data) {
+  const dataUrlMatch = /^data:([^;]+);base64,(.+)$/s.exec(data);
+  const mimeType = dataUrlMatch?.[1];
+  const encoded = dataUrlMatch?.[2] ?? data;
+  return {
+    data: Buffer.from(encoded, "base64"),
+    mime_type: mimeType
+  };
+}
+function extensionForMimeType(mimeType) {
+  switch (mimeType) {
+    case "image/jpeg":
+    case "image/jpg":
+      return "jpg";
+    case "image/webp":
+      return "webp";
+    case "image/png":
+      return "png";
+    default:
+      return "bin";
+  }
+}
+function mimeTypeFromUrl(url) {
+  const extension = extname(basename(new URL(url).pathname)).toLowerCase();
+  switch (extension) {
+    case ".jpg":
+    case ".jpeg":
+      return "image/jpeg";
+    case ".webp":
+      return "image/webp";
+    case ".png":
+      return "image/png";
+    default:
+      return void 0;
+  }
+}
+function readImageDimensions(data, mimeType) {
+  const buffer = Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+  if (mimeType === "image/png") {
+    return readPngDimensions(buffer);
+  }
+  if (mimeType === "image/jpeg" || mimeType === "image/jpg") {
+    return readJpegDimensions(buffer);
+  }
+  if (mimeType === "image/webp") {
+    return readWebpDimensions(buffer);
+  }
+  return void 0;
+}
+function readPngDimensions(buffer) {
+  if (buffer.length < 24 || buffer[0] !== 137 || buffer.toString("ascii", 1, 4) !== "PNG" || buffer.toString("ascii", 12, 16) !== "IHDR") {
+    return void 0;
+  }
+  return {
+    width: buffer.readUInt32BE(16),
+    height: buffer.readUInt32BE(20)
+  };
+}
+function readJpegDimensions(buffer) {
+  if (buffer.length < 4 || buffer[0] !== 255 || buffer[1] !== 216) {
+    return void 0;
+  }
+  let offset = 2;
+  while (offset + 9 < buffer.length) {
+    if (buffer[offset] !== 255) return void 0;
+    const marker = buffer[offset + 1];
+    const segmentLength = buffer.readUInt16BE(offset + 2);
+    if (segmentLength < 2 || offset + 2 + segmentLength > buffer.length) return void 0;
+    if (isJpegStartOfFrame(marker)) {
+      return {
+        height: buffer.readUInt16BE(offset + 5),
+        width: buffer.readUInt16BE(offset + 7)
+      };
+    }
+    offset += 2 + segmentLength;
+  }
+  return void 0;
+}
+function isJpegStartOfFrame(marker) {
+  return marker >= 192 && marker <= 195 || marker >= 197 && marker <= 199 || marker >= 201 && marker <= 203 || marker >= 205 && marker <= 207;
+}
+function readWebpDimensions(buffer) {
+  if (buffer.length < 30 || buffer.toString("ascii", 0, 4) !== "RIFF" || buffer.toString("ascii", 8, 12) !== "WEBP") {
+    return void 0;
+  }
+  let offset = 12;
+  while (offset + 8 <= buffer.length) {
+    const chunkType = buffer.toString("ascii", offset, offset + 4);
+    const chunkSize = buffer.readUInt32LE(offset + 4);
+    const chunkDataOffset = offset + 8;
+    if (chunkDataOffset + chunkSize > buffer.length) return void 0;
+    if (chunkType === "VP8X" && chunkSize >= 10) {
+      return {
+        width: 1 + buffer.readUIntLE(chunkDataOffset + 4, 3),
+        height: 1 + buffer.readUIntLE(chunkDataOffset + 7, 3)
+      };
+    }
+    if (chunkType === "VP8L" && chunkSize >= 5 && buffer[chunkDataOffset] === 47) {
+      const b1 = buffer[chunkDataOffset + 1];
+      const b2 = buffer[chunkDataOffset + 2];
+      const b3 = buffer[chunkDataOffset + 3];
+      const b4 = buffer[chunkDataOffset + 4];
+      return {
+        width: 1 + ((b2 & 63) << 8 | b1),
+        height: 1 + ((b4 & 15) << 10 | b3 << 2 | (b2 & 192) >> 6)
+      };
+    }
+    if (chunkType === "VP8 " && chunkSize >= 10 && buffer[chunkDataOffset + 3] === 157 && buffer[chunkDataOffset + 4] === 1 && buffer[chunkDataOffset + 5] === 42) {
+      return {
+        width: buffer.readUInt16LE(chunkDataOffset + 6) & 16383,
+        height: buffer.readUInt16LE(chunkDataOffset + 8) & 16383
+      };
+    }
+    offset = chunkDataOffset + chunkSize + chunkSize % 2;
+  }
+  return void 0;
+}
+function createRunId(plan, date) {
+  const time = `${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}-${padMilliseconds(
+    date.getMilliseconds()
+  )}`;
+  const preset = slug(plan.presetName);
+  const provider2 = slug(plan.providerName);
+  return `${time}-${preset}-${provider2}`;
+}
+function formatDate(date) {
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+function pad(value) {
+  return String(value).padStart(2, "0");
+}
+function padMilliseconds(value) {
+  return String(value).padStart(3, "0");
+}
+function slug(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48);
+}
+function redactProviderImageData(value, key) {
+  if (Array.isArray(value)) {
+    return value.map((item) => redactProviderImageData(item));
+  }
+  if (!value || typeof value !== "object") {
+    return shouldRedactImageDataKey(key) && typeof value === "string" ? redactedProviderDataPlaceholder(value) : value;
+  }
+  return Object.fromEntries(
+    Object.entries(value).map(([entryKey, entryValue]) => [
+      entryKey,
+      redactProviderImageData(entryValue, entryKey)
+    ])
+  );
+}
+function shouldRedactImageDataKey(key) {
+  return key === "b64_json" || key === "data" || key === "thoughtSignature" || key === "thought_signature";
+}
+function redactedProviderDataPlaceholder(value) {
+  return `[redacted provider data: ${value.length} chars]`;
+}
+
+// src/assets/reference.ts
+import { stat } from "fs/promises";
+import { extname as extname2, resolve } from "path";
+async function resolveReferenceImages(paths = []) {
+  const images = [];
+  for (const inputPath of paths) {
+    const absolutePath = resolve(inputPath);
+    const file = await stat(absolutePath).catch(() => {
+      throw new Error(`Reference image not found: ${inputPath}`);
+    });
+    if (!file.isFile()) {
+      throw new Error(`Reference image is not a file: ${inputPath}`);
+    }
+    images.push({
+      path: absolutePath,
+      mime_type: mimeTypeFromPath(absolutePath),
+      bytes: file.size
+    });
+  }
+  return images;
+}
+function mimeTypeFromPath(path) {
+  switch (extname2(path).toLowerCase()) {
+    case ".png":
+      return "image/png";
+    case ".jpg":
+    case ".jpeg":
+      return "image/jpeg";
+    case ".webp":
+      return "image/webp";
+    default:
+      throw new Error(`Unsupported reference image format: ${path}`);
+  }
+}
+
+// src/config/store.ts
+import { mkdir as mkdir2, readFile, writeFile as writeFile2 } from "fs/promises";
+import { dirname, join as join2 } from "path";
+import { homedir } from "os";
+import YAML from "yaml";
+
+// src/config/defaults.ts
+var defaultConfig = {
+  default_preset: "default",
+  routing: {
+    default_mode: "balanced",
+    default_provider: "openai_official",
+    fallback_providers: ["gemini_official"]
+  },
+  providers: {
+    openai_official: {
+      enabled: true,
+      protocol: "openai-images",
+      channel: "official",
+      base_url: "https://api.openai.com",
+      api_key_env: "OPENAI_API_KEY",
+      models: ["gpt-image-2"],
+      capabilities: ["text-to-image"]
+    },
+    gemini_official: {
+      enabled: true,
+      protocol: "gemini",
+      channel: "official",
+      base_url: "https://generativelanguage.googleapis.com",
+      api_key_env: "GEMINI_API_KEY",
+      models: ["gemini-3.1-flash-image-preview", "gemini-3-pro-image-preview"],
+      capabilities: ["text-to-image", "reference-image"]
+    }
+  },
+  modes: {
+    fast: {
+      preferred_models: ["gemini-3.1-flash-image-preview", "gpt-image-2"]
+    },
+    balanced: {
+      preferred_models: ["gpt-image-2", "gemini-3.1-flash-image-preview"]
+    },
+    premium: {
+      preferred_models: ["gemini-3-pro-image-preview", "gpt-image-2"]
+    }
+  },
+  presets: {
+    default: {
+      mode: "balanced",
+      aspect_ratio: "1:1",
+      size: "medium",
+      quality: "auto",
+      n: 1,
+      output_format: "png"
+    },
+    poster: {
+      mode: "premium",
+      aspect_ratio: "3:4",
+      size: "large",
+      quality: "high",
+      n: 2,
+      output_format: "png"
+    },
+    "social-cover": {
+      mode: "balanced",
+      aspect_ratio: "16:9",
+      size: "large",
+      quality: "high",
+      n: 2,
+      output_format: "png"
+    },
+    "product-shot": {
+      mode: "premium",
+      aspect_ratio: "1:1",
+      size: "large",
+      quality: "high",
+      n: 2,
+      output_format: "png"
+    },
+    "fast-draft": {
+      mode: "fast",
+      aspect_ratio: "1:1",
+      size: "medium",
+      quality: "low",
+      n: 1,
+      output_format: "jpeg"
+    }
+  }
+};
+
+// src/config/schema.ts
+import { z } from "zod";
+var providerSchema = z.object({
+  enabled: z.boolean().default(true),
+  protocol: z.enum(["openai-images", "gemini"]),
+  channel: z.enum(["official", "third_party"]),
+  base_url: z.string().url(),
+  api_key_env: z.string().min(1),
+  models: z.array(z.string().min(1)).min(1),
+  test_model: z.string().min(1).optional(),
+  capabilities: z.array(z.enum(["text-to-image", "reference-image"])).optional()
+}).transform((provider2) => ({
+  ...provider2,
+  capabilities: provider2.capabilities ?? defaultCapabilitiesForProtocol(provider2.protocol)
+}));
+var presetSchema = z.object({
+  mode: z.string().min(1),
+  aspect_ratio: z.string().min(1),
+  size: z.string().min(1),
+  quality: z.string().min(1),
+  n: z.number().int().positive(),
+  output_format: z.enum(["png", "jpeg", "webp"])
+});
+var routingSchema = z.object({
+  default_mode: z.string().min(1),
+  default_provider: z.string().min(1).optional(),
+  fallback_providers: z.array(z.string().min(1)).optional(),
+  provider_priority: z.array(z.string().min(1)).optional()
+}).transform((routing) => {
+  if (routing.default_provider) {
+    return {
+      default_mode: routing.default_mode,
+      default_provider: routing.default_provider,
+      fallback_providers: routing.fallback_providers ?? []
+    };
+  }
+  const [defaultProvider, ...fallbackProviders] = routing.provider_priority ?? [];
+  if (!defaultProvider) {
+    throw new Error("routing.default_provider is required.");
+  }
+  return {
+    default_mode: routing.default_mode,
+    default_provider: defaultProvider,
+    fallback_providers: routing.fallback_providers ?? fallbackProviders
+  };
+});
+var picgenConfigSchema = z.object({
+  default_preset: z.string().min(1),
+  routing: routingSchema,
+  providers: z.record(providerSchema),
+  modes: z.record(
+    z.object({
+      preferred_models: z.array(z.string().min(1)).min(1)
+    })
+  ),
+  presets: z.record(presetSchema)
+});
+function defaultCapabilitiesForProtocol(protocol) {
+  if (protocol === "gemini") {
+    return ["text-to-image", "reference-image"];
+  }
+  return ["text-to-image"];
+}
+
+// src/config/store.ts
+function getConfigPath() {
+  return process.env.PICGEN_CONFIG ?? join2(homedir(), ".picgen", "config.yaml");
+}
+async function loadConfig() {
+  const path = getConfigPath();
+  try {
+    const raw = await readFile(path, "utf8");
+    const parsed = YAML.parse(raw);
+    return picgenConfigSchema.parse(parsed);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return structuredClone(defaultConfig);
+    }
+    throw error;
+  }
+}
+async function saveConfig(config) {
+  const parsed = picgenConfigSchema.parse(config);
+  const path = getConfigPath();
+  await mkdir2(dirname(path), { recursive: true });
+  await writeFile2(path, YAML.stringify(parsed), "utf8");
+}
+async function ensureConfig() {
+  const config = await loadConfig();
+  await saveConfig(config);
+  return config;
+}
+
+// src/providers/gemini.ts
+import { readFile as readFile2 } from "fs/promises";
+
+// src/providers/urls.ts
+function normalizeProviderBaseUrl(baseUrl) {
+  const url = new URL(baseUrl);
+  url.pathname = stripKnownApiVersionPath(url.pathname);
+  url.search = "";
+  url.hash = "";
+  return url.toString().replace(/\/+$/, "");
+}
+function buildOpenAIProtocolUrl(baseUrl, path) {
+  return `${normalizeProviderBaseUrl(baseUrl)}/v1/${path.replace(/^\/+/, "")}`;
+}
+function buildGeminiProtocolUrl(baseUrl, path) {
+  return `${normalizeProviderBaseUrl(baseUrl)}/v1beta/${path.replace(/^\/+/, "")}`;
+}
+function defaultProviderBaseUrl(protocol) {
+  return protocol === "openai-images" ? "https://api.openai.com" : "https://generativelanguage.googleapis.com";
+}
+function stripKnownApiVersionPath(pathname) {
+  const normalized = pathname.replace(/\/+$/, "");
+  if (normalized === "" || normalized === "/") return "";
+  if (normalized === "/v1" || normalized === "/v1beta") return "";
+  return normalized;
+}
+
+// src/providers/gemini.ts
+var GeminiAdapter = class {
+  protocol = "gemini";
+  async generate(plan, run) {
+    const apiKey = process.env[plan.provider.api_key_env];
+    if (!apiKey) {
+      throw new Error(`Missing API key environment variable: ${plan.provider.api_key_env}`);
+    }
+    const responses = [];
+    const providerImages = [];
+    const requestCount = Math.max(1, plan.preset.n);
+    const referenceParts = await readReferenceImageParts(plan);
+    for (let index = 0; index < requestCount; index += 1) {
+      const response = await fetch(buildGeminiGenerateContentUrl(plan.provider.base_url, plan.model), {
+        method: "POST",
+        headers: {
+          "x-goog-api-key": apiKey,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(buildGeminiGenerateContentRequest(plan, referenceParts))
+      });
+      const raw = await readJsonResponse(response);
+      if (!response.ok) {
+        throw new Error(formatGeminiError(response.status, response.statusText, raw));
+      }
+      responses.push(raw);
+      providerImages.push(...extractGeminiImages(raw));
+    }
+    const images = await writeProviderImages(run, providerImages);
+    return {
+      images,
+      provider_response: responses.length === 1 ? responses[0] : responses
+    };
+  }
+};
+function buildGeminiGenerateContentRequest(plan, referenceParts = []) {
+  return {
+    contents: [
+      {
+        role: "user",
+        parts: [
+          {
+            text: plan.prompt
+          },
+          ...referenceParts
+        ]
+      }
+    ],
+    generationConfig: {
+      responseModalities: ["IMAGE"],
+      imageConfig: removeUndefined({
+        aspectRatio: plan.preset.aspect_ratio,
+        imageSize: mapGeminiImageSize(plan.preset.size)
+      })
+    }
+  };
+}
+async function readReferenceImageParts(plan) {
+  return Promise.all(
+    plan.referenceImages.map(async (image) => ({
+      inlineData: {
+        mimeType: image.mime_type,
+        data: (await readFile2(image.path)).toString("base64")
+      }
+    }))
+  );
+}
+function extractGeminiImages(response) {
+  const parts = response.candidates?.flatMap((candidate) => candidate.content?.parts ?? []) ?? [];
+  const imageParts = parts.filter((part) => part.thought !== true).map((part) => part.inlineData ?? normalizeInlineData(part.inline_data)).filter(Boolean);
+  if (imageParts.length === 0) {
+    throw new Error("Gemini response did not include generated image data.");
+  }
+  return imageParts.map((image, index) => {
+    if (!image?.data) {
+      throw new Error(`Gemini image part ${index + 1} did not include base64 data.`);
+    }
+    return {
+      kind: "base64",
+      data: image.data,
+      mime_type: image.mimeType ?? "image/png"
+    };
+  });
+}
+function buildGeminiGenerateContentUrl(baseUrl, model) {
+  return buildGeminiProtocolUrl(baseUrl, `models/${encodeURIComponent(model)}:generateContent`);
+}
+function normalizeInlineData(inlineData) {
+  if (!inlineData) return void 0;
+  return {
+    data: inlineData.data,
+    mimeType: inlineData.mime_type
+  };
+}
+function mapGeminiImageSize(size) {
+  switch (size) {
+    case "small":
+      return "512";
+    case "medium":
+      return "1K";
+    case "large":
+      return "2K";
+    case "auto":
+      return void 0;
+    default:
+      return /^(512|1K|2K|4K)$/.test(size) ? size : void 0;
+  }
+}
+function removeUndefined(input3) {
+  return Object.fromEntries(Object.entries(input3).filter(([, value]) => value !== void 0));
+}
+async function readJsonResponse(response) {
+  const text = await response.text();
+  if (!text.trim()) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error("Gemini response was not valid JSON.");
+  }
+}
+function formatGeminiError(status, statusText, response) {
+  const message = extractErrorMessage(response);
+  return `Gemini request failed: ${status} ${statusText}${message ? ` - ${message}` : ""}`;
+}
+function extractErrorMessage(response) {
+  const error = response.error;
+  if (typeof error === "object" && error && "message" in error) {
+    const message = error.message;
+    return typeof message === "string" ? message : void 0;
+  }
+  return void 0;
+}
+
+// src/providers/openaiImages.ts
+var OpenAIImagesAdapter = class {
+  protocol = "openai-images";
+  async generate(plan, run) {
+    const apiKey = process.env[plan.provider.api_key_env];
+    if (!apiKey) {
+      throw new Error(`Missing API key environment variable: ${plan.provider.api_key_env}`);
+    }
+    const response = await fetch(buildOpenAIImagesUrl(plan.provider.base_url), {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(buildOpenAIImagesRequest(plan))
+    });
+    const raw = await readJsonResponse2(response);
+    if (!response.ok) {
+      throw new Error(formatOpenAIImagesError(response.status, response.statusText, raw));
+    }
+    const providerImages = extractOpenAIImages(raw);
+    const images = await writeProviderImages(run, providerImages);
+    const revisedPrompts = raw.data?.map((item) => item.revised_prompt);
+    return {
+      images: images.map((image, index) => ({
+        ...image,
+        revised_prompt: revisedPrompts?.[index]
+      })),
+      provider_response: raw
+    };
+  }
+};
+function buildOpenAIImagesRequest(plan) {
+  if (plan.referenceImages.length > 0) {
+    throw new Error(
+      "Reference images are not supported by the openai-images generation adapter yet. Use a Gemini provider for reference-image generation."
+    );
+  }
+  return removeUndefined2({
+    model: plan.model,
+    prompt: plan.prompt,
+    n: plan.preset.n,
+    size: mapOpenAIImageSize(plan.preset.aspect_ratio, plan.preset.size),
+    quality: mapOpenAIImageQuality(plan.preset.quality),
+    output_format: plan.preset.output_format,
+    response_format: "b64_json"
+  });
+}
+function extractOpenAIImages(response) {
+  if (!Array.isArray(response.data) || response.data.length === 0) {
+    throw new Error("OpenAI images response did not include generated image data.");
+  }
+  return response.data.map((item, index) => {
+    if (item.b64_json) {
+      return {
+        kind: "base64",
+        data: item.b64_json,
+        mime_type: void 0
+      };
+    }
+    if (item.url) {
+      return {
+        kind: "url",
+        url: item.url,
+        mime_type: void 0
+      };
+    }
+    throw new Error(`OpenAI images response item ${index + 1} did not include b64_json or url.`);
+  });
+}
+function buildOpenAIImagesUrl(baseUrl) {
+  return buildOpenAIProtocolUrl(baseUrl, "images/generations");
+}
+function mapOpenAIImageSize(aspectRatio, size) {
+  if (/^\d+x\d+$/.test(size) || size === "auto") return size;
+  switch (aspectRatio) {
+    case "3:4":
+    case "2:3":
+      return "1024x1536";
+    case "4:3":
+    case "3:2":
+    case "16:9":
+    case "9:5":
+      return "1536x1024";
+    case "1:1":
+      return "1024x1024";
+    default:
+      return "auto";
+  }
+}
+function mapOpenAIImageQuality(quality) {
+  if (["low", "medium", "high", "auto"].includes(quality)) return quality;
+  return void 0;
+}
+function removeUndefined2(input3) {
+  return Object.fromEntries(Object.entries(input3).filter(([, value]) => value !== void 0));
+}
+async function readJsonResponse2(response) {
+  const text = await response.text();
+  if (!text.trim()) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error("OpenAI images response was not valid JSON.");
+  }
+}
+function formatOpenAIImagesError(status, statusText, response) {
+  const message = extractErrorMessage2(response);
+  return `OpenAI images request failed: ${status} ${statusText}${message ? ` - ${message}` : ""}`;
+}
+function extractErrorMessage2(response) {
+  const error = response.error;
+  if (typeof error === "object" && error && "message" in error) {
+    const message = error.message;
+    return typeof message === "string" ? message : void 0;
+  }
+  return void 0;
+}
+
+// src/providers/adapters.ts
+var NotImplementedAdapter = class {
+  constructor(protocol) {
+    this.protocol = protocol;
+  }
+  protocol;
+  async generate(plan, _run) {
+    throw new Error(
+      `Real generation is not implemented for ${this.protocol} yet. Dry-run plan is ready for ${plan.providerName}/${plan.model}.`
+    );
+  }
+};
+function getAdapter(protocol) {
+  if (protocol === "openai-images") {
+    return new OpenAIImagesAdapter();
+  }
+  if (protocol === "gemini") {
+    return new GeminiAdapter();
+  }
+  return new NotImplementedAdapter(protocol);
+}
+
+// src/routing/resolve.ts
+import { join as join3 } from "path";
+import { cwd } from "process";
+function resolveGenerationPlan(config, options) {
+  const presetName = options.presetName ?? config.default_preset;
+  const preset = config.presets[presetName];
+  if (!preset) {
+    throw new Error(`Unknown preset: ${presetName}`);
+  }
+  const modeName = options.modeName ?? preset.mode ?? config.routing.default_mode;
+  const mode = config.modes[modeName];
+  if (!mode) {
+    throw new Error(`Unknown mode: ${modeName}`);
+  }
+  const providerCandidates = options.providerName ? [options.providerName] : [config.routing.default_provider, ...config.routing.fallback_providers];
+  const requiredCapability = requiredCapabilityForOptions(options);
+  const unsupportedProviders = [];
+  for (const providerName of providerCandidates) {
+    const provider2 = config.providers[providerName];
+    if (!provider2 || !provider2.enabled) continue;
+    if (!provider2.capabilities.includes(requiredCapability)) {
+      unsupportedProviders.push(providerName);
+      continue;
+    }
+    const modelCandidates = options.model ? [options.model] : mode.preferred_models;
+    const model = modelCandidates.find((candidate) => provider2.models.includes(candidate));
+    if (!model) continue;
+    return {
+      prompt: options.prompt,
+      providerName,
+      provider: provider2,
+      model,
+      presetName,
+      preset,
+      modeName,
+      outputDirectory: options.outputDirectory ?? join3(cwd(), "outputs", "picgen"),
+      referenceImages: options.referenceImages ?? []
+    };
+  }
+  if (options.providerName && unsupportedProviders.includes(options.providerName)) {
+    throw new Error(
+      `Provider "${options.providerName}" does not support ${requiredCapability}.`
+    );
+  }
+  throw new Error(
+    `No enabled provider can satisfy preset "${presetName}" with mode "${modeName}" and capability "${requiredCapability}".`
+  );
+}
+function requiredCapabilityForOptions(options) {
+  return options.referenceImages && options.referenceImages.length > 0 ? "reference-image" : "text-to-image";
+}
+
+// src/commands/confirm.ts
+import { confirm } from "@inquirer/prompts";
+async function confirmGeneration(plan, options) {
+  if (options.yes) {
+    return { confirmed: true, skipped: true };
+  }
+  console.log("PicGen generation preview:");
+  console.log(formatGenerationPreview(plan));
+  const confirmed = await confirm({
+    message: "Generate now? This may consume provider quota.",
+    default: false
+  });
+  return { confirmed, skipped: false };
+}
+function formatGenerationPreview(plan) {
+  return [
+    `Provider: ${plan.provider} (${plan.protocol})`,
+    `Model: ${plan.model}`,
+    `Preset: ${plan.preset}`,
+    `Images: ${plan.n}`,
+    `Reference images: ${plan.reference_images.length}`,
+    `Aspect ratio: ${plan.aspect_ratio}`,
+    `Output: ${plan.output_directory}`
+  ].join("\n");
+}
+
+// src/commands/create.ts
+async function runCreate(promptParts, options) {
+  const prompt = promptParts.join(" ").trim();
+  if (!prompt) {
+    throw new Error("Prompt is required.");
+  }
+  const config = await loadConfig();
+  const referenceImages = await resolveReferenceImages(options.reference ?? []);
+  const plan = resolveGenerationPlan(config, {
+    prompt,
+    presetName: options.preset,
+    providerName: options.provider,
+    modeName: options.mode,
+    model: options.model,
+    outputDirectory: options.outDir,
+    referenceImages
+  });
+  const planOutput = toPlanOutput(plan);
+  if (options.dryRun) {
+    if (options.json) {
+      console.log(
+        JSON.stringify(
+          {
+            ok: true,
+            dry_run: true,
+            provider_called: false,
+            requires_confirmation: true,
+            plan: planOutput
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      console.log("PicGen dry-run plan:");
+      console.log(YAML2.stringify(planOutput));
+    }
+    return;
+  }
+  const confirmation = await confirmGeneration(planOutput, { yes: options.yes });
+  if (!confirmation.confirmed) {
+    const cancelledOutput = {
+      ok: false,
+      cancelled: true,
+      provider_called: false,
+      plan: planOutput
+    };
+    if (options.json) {
+      console.log(JSON.stringify(cancelledOutput, null, 2));
+    } else {
+      console.log("Generation cancelled.");
+    }
+    return;
+  }
+  const run = await createGenerationRun(plan);
+  const runtimePlan = {
+    ...plan,
+    outputDirectory: run.outputDirectory
+  };
+  const runtimePlanOutput = toPlanOutput(runtimePlan);
+  await writeGenerationMetadata(run, {
+    plan: runtimePlanOutput,
+    run: {
+      id: run.id,
+      output_directory: run.outputDirectory,
+      metadata_path: run.metadataPath,
+      prompt_path: run.promptPath
+    }
+  });
+  const adapter = getAdapter(plan.provider.protocol);
+  let result;
+  try {
+    result = await adapter.generate(runtimePlan, run);
+  } catch (error) {
+    await writeGenerationMetadata(run, {
+      plan: runtimePlanOutput,
+      run: {
+        id: run.id,
+        output_directory: run.outputDirectory,
+        metadata_path: run.metadataPath,
+        prompt_path: run.promptPath
+      },
+      error: {
+        message: error instanceof Error ? error.message : String(error),
+        name: error instanceof Error ? error.name : void 0
+      }
+    });
+    throw error;
+  }
+  await writeGenerationMetadata(run, {
+    plan: runtimePlanOutput,
+    run: {
+      id: run.id,
+      output_directory: run.outputDirectory,
+      metadata_path: run.metadataPath,
+      prompt_path: run.promptPath
+    },
+    provider_response: result.provider_response,
+    images: result.images
+  });
+  console.log(
+    JSON.stringify(
+      {
+        ok: true,
+        dry_run: false,
+        output_dir: run.outputDirectory,
+        metadata_path: run.metadataPath,
+        images: result.images
+      },
+      null,
+      2
+    )
+  );
+}
+function toPlanOutput(plan) {
+  return {
+    prompt: plan.prompt,
+    provider: plan.providerName,
+    protocol: plan.provider.protocol,
+    channel: plan.provider.channel,
+    model: plan.model,
+    preset: plan.presetName,
+    mode: plan.modeName,
+    aspect_ratio: plan.preset.aspect_ratio,
+    size: plan.preset.size,
+    quality: plan.preset.quality,
+    n: plan.preset.n,
+    output_format: plan.preset.output_format,
+    output_directory: plan.outputDirectory,
+    reference_images: plan.referenceImages.map((image) => ({
+      path: image.path,
+      mime_type: image.mime_type,
+      bytes: image.bytes
+    }))
+  };
+}
+
+// src/config/doctor.ts
+function inspectProviders(config) {
+  return Object.entries(config.providers).map(([name, provider2]) => {
+    const hasApiKey = Boolean(process.env[provider2.api_key_env]);
+    const status = !provider2.enabled ? "disabled" : hasApiKey ? "ok" : "missing_api_key";
+    return {
+      name,
+      enabled: provider2.enabled,
+      protocol: provider2.protocol,
+      channel: provider2.channel,
+      base_url: provider2.base_url,
+      api_key_env: provider2.api_key_env,
+      has_api_key: hasApiKey,
+      models: provider2.models,
+      capabilities: provider2.capabilities,
+      status
+    };
+  });
+}
+
+// src/commands/doctor.ts
+async function runDoctor(options) {
+  const config = await loadConfig();
+  const providers = inspectProviders(config);
+  const configured = providers.some((provider2) => provider2.status === "ok");
+  if (options.json) {
+    console.log(
+      JSON.stringify(
+        {
+          configured,
+          config_path: getConfigPath(),
+          default_preset: config.default_preset,
+          default_mode: config.routing.default_mode,
+          default_provider: config.routing.default_provider,
+          fallback_providers: config.routing.fallback_providers,
+          providers
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+  console.log(`Config: ${getConfigPath()}`);
+  console.log(`Default preset: ${config.default_preset}`);
+  console.log(`Default mode: ${config.routing.default_mode}`);
+  console.log(`Default provider: ${config.routing.default_provider}`);
+  console.log(`Fallback providers: ${config.routing.fallback_providers.join(", ") || "(none)"}`);
+  console.log("");
+  console.log("Providers:");
+  for (const provider2 of providers) {
+    console.log(
+      `- ${provider2.name} [${provider2.protocol}] ${provider2.status} key=${provider2.api_key_env} capabilities=${provider2.capabilities.join(", ")} models=${provider2.models.join(", ")}`
+    );
+  }
+  if (!configured) {
+    console.log("");
+    console.log("No usable provider found. Run `picgen setup` or set the API key env vars above.");
+  }
+}
+
+// src/commands/provider.ts
+import { input, select } from "@inquirer/prompts";
+
+// src/config/preferences.ts
+function setPreferredProvider(config, name) {
+  if (!config.providers[name]) throw new Error(`Unknown provider: ${name}`);
+  const previousDefault = config.routing.default_provider;
+  config.routing.default_provider = name;
+  config.routing.fallback_providers = [
+    .../* @__PURE__ */ new Set([
+      previousDefault,
+      ...config.routing.fallback_providers.filter((providerName) => providerName !== name)
+    ])
+  ].filter((providerName) => providerName && providerName !== name);
+  return config;
+}
+function setPreferredMode(config, name) {
+  if (!config.modes[name]) throw new Error(`Unknown mode: ${name}`);
+  config.routing.default_mode = name;
+  return config;
+}
+function setPreferredPreset(config, name) {
+  if (!config.presets[name]) throw new Error(`Unknown preset: ${name}`);
+  config.default_preset = name;
+  return config;
+}
+
+// src/providers/health.ts
+async function testProvider(name, provider2) {
+  const base = baseResult(name, provider2);
+  if (!provider2.enabled) {
+    return {
+      ...base,
+      ok: false,
+      status: "disabled",
+      message: "Provider is disabled."
+    };
+  }
+  const apiKey = process.env[provider2.api_key_env];
+  if (!apiKey) {
+    return {
+      ...base,
+      ok: false,
+      status: "missing_api_key",
+      message: `Missing API key environment variable: ${provider2.api_key_env}`
+    };
+  }
+  const model = provider2.test_model ?? provider2.models[0];
+  try {
+    const response = provider2.protocol === "openai-images" ? await testOpenAICompatibleProvider(provider2, apiKey, model) : await testGeminiProvider(provider2, apiKey, model);
+    if (!response.ok) {
+      const message = await readProviderError(response);
+      return {
+        ...base,
+        ok: false,
+        model,
+        status: "provider_error",
+        message: message ?? `Provider check failed: ${response.status} ${response.statusText}`.trim(),
+        http_status: response.status
+      };
+    }
+    return {
+      ...base,
+      ok: true,
+      model,
+      status: "ok",
+      message: "Provider check passed.",
+      http_status: response.status
+    };
+  } catch (error) {
+    return {
+      ...base,
+      ok: false,
+      model,
+      status: "network_error",
+      message: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+function baseResult(name, provider2) {
+  return {
+    ok: false,
+    name,
+    protocol: provider2.protocol,
+    enabled: provider2.enabled,
+    base_url: provider2.base_url,
+    api_key_env: provider2.api_key_env,
+    has_api_key: Boolean(process.env[provider2.api_key_env])
+  };
+}
+async function testOpenAICompatibleProvider(provider2, apiKey, model) {
+  return fetch(buildOpenAIProtocolUrl(provider2.base_url, `models/${encodeURIComponent(model)}`), {
+    method: "GET",
+    headers: {
+      Authorization: `Bearer ${apiKey}`
+    }
+  });
+}
+async function testGeminiProvider(provider2, apiKey, model) {
+  return fetch(buildGeminiProtocolUrl(provider2.base_url, `models/${encodeURIComponent(model)}:generateContent`), {
+    method: "POST",
+    headers: {
+      "x-goog-api-key": apiKey,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({
+      contents: [
+        {
+          role: "user",
+          parts: [{ text: "Say OK only." }]
+        }
+      ]
+    })
+  });
+}
+async function readProviderError(response) {
+  const text = await response.text();
+  if (!text.trim()) return void 0;
+  try {
+    const parsed = JSON.parse(text);
+    const message = parsed.error?.message;
+    if (typeof message === "string") return message;
+  } catch {
+    return text.slice(0, 300);
+  }
+  return text.slice(0, 300);
+}
+
+// src/commands/provider.ts
+async function listProviders() {
+  const config = await loadConfig();
+  for (const [name, provider2] of Object.entries(config.providers)) {
+    const preference = name === config.routing.default_provider ? "default" : config.routing.fallback_providers.includes(name) ? "fallback" : "manual";
+    console.log(
+      `${name}	${provider2.enabled ? "enabled" : "disabled"}	${preference}	${provider2.protocol}	${provider2.channel}	${provider2.capabilities.join(",")}	${provider2.models.join(",")}`
+    );
+  }
+}
+async function addProvider() {
+  const config = await loadConfig();
+  const provider2 = await promptProvider(config);
+  addProviderToConfig(config, provider2.name, provider2.config);
+  await saveConfig(config);
+  console.log(`Added provider: ${provider2.name}`);
+}
+function addProviderToConfig(config, name, provider2) {
+  config.providers[name] = provider2;
+  const knownProviders = [config.routing.default_provider, ...config.routing.fallback_providers];
+  if (!knownProviders.includes(name)) {
+    config.routing.fallback_providers.push(name);
+  }
+}
+async function editProvider(name) {
+  const config = await loadConfig();
+  if (!config.providers[name]) throw new Error(`Unknown provider: ${name}`);
+  const provider2 = await promptProvider(config, name, config.providers[name]);
+  delete config.providers[name];
+  config.providers[provider2.name] = provider2.config;
+  if (config.routing.default_provider === name) {
+    config.routing.default_provider = provider2.name;
+  }
+  config.routing.fallback_providers = config.routing.fallback_providers.map(
+    (item) => item === name ? provider2.name : item
+  );
+  await saveConfig(config);
+  console.log(`Updated provider: ${provider2.name}`);
+}
+async function setProviderEnabled(name, enabled) {
+  const config = await loadConfig();
+  const provider2 = config.providers[name];
+  if (!provider2) throw new Error(`Unknown provider: ${name}`);
+  provider2.enabled = enabled;
+  await saveConfig(config);
+  console.log(`${enabled ? "Enabled" : "Disabled"} provider: ${name}`);
+}
+async function removeProvider(name) {
+  const config = await loadConfig();
+  if (!config.providers[name]) throw new Error(`Unknown provider: ${name}`);
+  delete config.providers[name];
+  config.routing.fallback_providers = config.routing.fallback_providers.filter(
+    (item) => item !== name
+  );
+  if (config.routing.default_provider === name) {
+    const [nextDefault, ...remainingFallbacks] = config.routing.fallback_providers;
+    if (!nextDefault) {
+      throw new Error("Cannot remove the default provider because no fallback provider remains.");
+    }
+    config.routing.default_provider = nextDefault;
+    config.routing.fallback_providers = remainingFallbacks;
+  }
+  await saveConfig(config);
+  console.log(`Removed provider: ${name}`);
+}
+async function preferProvider(name) {
+  const config = await loadConfig();
+  setPreferredProvider(config, name);
+  await saveConfig(config);
+  console.log(`Preferred provider: ${name}`);
+}
+async function runProviderTest(name, options) {
+  const config = await loadConfig();
+  const provider2 = config.providers[name];
+  if (!provider2) throw new Error(`Unknown provider: ${name}`);
+  const result = await testProvider(name, provider2);
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`${result.ok ? "OK" : "FAILED"} ${result.name} [${result.protocol}]`);
+  console.log(result.message);
+  if (result.model) console.log(`Model: ${result.model}`);
+  if (result.http_status) console.log(`HTTP status: ${result.http_status}`);
+}
+async function promptProvider(config, existingName, existing) {
+  const protocol = await select({
+    message: "Select protocol",
+    default: existing?.protocol ?? "openai-images",
+    choices: [
+      { name: "OpenAI-compatible Images API", value: "openai-images" },
+      { name: "Gemini image API", value: "gemini" }
+    ]
+  });
+  const channel = await select({
+    message: "Select channel",
+    default: existing?.channel ?? "official",
+    choices: [
+      { name: "Official", value: "official" },
+      { name: "Third-party proxy / aggregator", value: "third_party" }
+    ]
+  });
+  const defaultName = existingName ?? (protocol === "openai-images" ? channel === "official" ? "openai_official" : "openai_proxy" : channel === "official" ? "gemini_official" : "gemini_proxy");
+  const name = await input({
+    message: "Provider name",
+    default: nextAvailableProviderName(config, defaultName, existingName)
+  });
+  const baseUrl = await input({
+    message: "Provider host URL (do not include /v1 or /v1beta)",
+    default: existing?.base_url ?? defaultProviderBaseUrl(protocol)
+  });
+  const apiKeyEnv = await input({
+    message: "API key environment variable",
+    default: existing?.api_key_env ?? (protocol === "openai-images" ? channel === "official" ? "OPENAI_API_KEY" : "PICGEN_OPENAI_PROXY_KEY" : channel === "official" ? "GEMINI_API_KEY" : "PICGEN_GEMINI_PROXY_KEY")
+  });
+  const defaultModels = protocol === "openai-images" ? "gpt-image-2" : "gemini-3.1-flash-image-preview,gemini-3-pro-image-preview";
+  const modelsRaw = await input({
+    message: "Models (comma separated)",
+    default: existing?.models.join(",") ?? defaultModels
+  });
+  return {
+    name,
+    config: {
+      enabled: existing?.enabled ?? true,
+      protocol,
+      channel,
+      base_url: normalizeProviderBaseUrl(baseUrl),
+      api_key_env: apiKeyEnv,
+      models: modelsRaw.split(",").map((model) => model.trim()).filter(Boolean),
+      capabilities: defaultCapabilitiesForProtocol2(protocol)
+    }
+  };
+}
+function nextAvailableProviderName(config, baseName, existingName) {
+  if (existingName) return existingName;
+  if (!config.providers[baseName]) return baseName;
+  let index = 2;
+  while (config.providers[`${baseName}_${index}`]) index += 1;
+  return `${baseName}_${index}`;
+}
+function defaultCapabilitiesForProtocol2(protocol) {
+  return protocol === "gemini" ? ["text-to-image", "reference-image"] : ["text-to-image"];
+}
+
+// src/commands/preferences.ts
+async function preferMode(name) {
+  const config = await loadConfig();
+  setPreferredMode(config, name);
+  await saveConfig(config);
+  console.log(`Preferred mode: ${name}`);
+}
+async function preferPreset(name) {
+  const config = await loadConfig();
+  setPreferredPreset(config, name);
+  await saveConfig(config);
+  console.log(`Preferred preset: ${name}`);
+}
+
+// src/commands/quickstart.ts
+function runQuickstart() {
+  console.log(formatQuickstart());
+}
+function formatQuickstart() {
+  return [
+    "PicGen quickstart",
+    "",
+    "Install:",
+    "  npm install -g @ai-agent-tools/picgen",
+    "",
+    "Configure:",
+    "  picgen setup",
+    "  picgen doctor --json",
+    "",
+    "Preview before spending quota:",
+    '  picgen create --dry-run "\u4E00\u5F20\u6781\u7B80\u79D1\u6280\u611F\u4EA7\u54C1\u6D77\u62A5"',
+    "",
+    "Generate after confirmation:",
+    '  picgen create --yes "\u4E00\u5F20\u6781\u7B80\u79D1\u6280\u611F\u4EA7\u54C1\u6D77\u62A5"',
+    "",
+    "Use a reference image:",
+    '  picgen create --dry-run --reference ./reference.png "\u57FA\u4E8E\u53C2\u8003\u56FE\u751F\u6210\u4E00\u5F20\u54C1\u724C\u6D77\u62A5"',
+    "",
+    "Agent prompt:",
+    "  \u8BF7\u5B89\u88C5\u5E76\u4F53\u9A8C @ai-agent-tools/picgen\uFF1A\u5168\u5C40\u5B89\u88C5 npm install -g @ai-agent-tools/picgen\uFF0C\u8FD0\u884C picgen setup \u914D\u7F6E\uFF0C\u7136\u540E\u5148 dry-run \u9884\u89C8\uFF0C\u518D\u786E\u8BA4\u751F\u6210\u4E00\u5F20\u6D4B\u8BD5\u56FE\u3002\u5982\u679C\u6211\u8981\u7528\u53C2\u8003\u56FE\uFF0C\u8BF7\u4F7F\u7528 --reference <\u56FE\u7247\u8DEF\u5F84>\u3002",
+    "",
+    "Notes:",
+    "  - Provider host URLs should not include /v1 or /v1beta.",
+    "  - Agent workflows should dry-run before real generation.",
+    "  - Generated images are saved locally; do not paste base64 into chat.",
+    "  - First-user rollout checklist: docs/release-alpha.md"
+  ].join("\n");
+}
+
+// src/commands/setup.ts
+import { confirm as confirm2, input as input2, select as select2 } from "@inquirer/prompts";
+async function runSetup() {
+  await ensureConfig();
+  console.log(`PicGen config: ${getConfigPath()}`);
+  let done = false;
+  while (!done) {
+    console.log("");
+    await printSetupSummary();
+    console.log("");
+    const action = await select2({
+      message: "What do you want to configure?",
+      choices: [
+        { name: "Quick add a common provider/channel", value: "quick-add" },
+        { name: "Choose default provider/channel", value: "provider" },
+        { name: "Choose generation preference", value: "mode" },
+        { name: "Test a provider", value: "test" },
+        { name: "Advanced: add a custom provider/channel", value: "add" },
+        { name: "Finish setup", value: "done" }
+      ]
+    });
+    if (action === "quick-add") {
+      await quickAddProvider();
+    } else if (action === "provider") {
+      await chooseDefaultProvider();
+    } else if (action === "mode") {
+      await chooseDefaultMode();
+    } else if (action === "test") {
+      await chooseProviderToTest();
+    } else if (action === "add") {
+      await addProvider();
+    } else {
+      done = true;
+      console.log("Setup complete.");
+    }
+  }
+}
+async function printSetupSummary() {
+  const config = await loadConfig();
+  console.log(`Default provider: ${config.routing.default_provider}`);
+  console.log(`Generation preference: ${modeLabel(config.routing.default_mode)}`);
+  console.log("Providers:");
+  for (const [providerName, provider2] of Object.entries(config.providers)) {
+    const preference = providerName === config.routing.default_provider ? "default" : config.routing.fallback_providers.includes(providerName) ? "fallback" : "manual";
+    console.log(
+      `- ${providerName}: ${provider2.enabled ? "enabled" : "disabled"}, ${preference}, ${providerLabel(provider2)}, capabilities=${provider2.capabilities.join(",")}`
+    );
+  }
+}
+async function chooseDefaultProvider() {
+  const config = await loadConfig();
+  const name = await select2({
+    message: "Choose the provider PicGen should use by default",
+    default: config.routing.default_provider,
+    choices: Object.entries(config.providers).map(([providerName, provider2]) => ({
+      name: `${providerName} (${provider2.protocol}, ${provider2.enabled ? "enabled" : "disabled"})`,
+      value: providerName
+    }))
+  });
+  setPreferredProvider(config, name);
+  await saveConfig(config);
+  console.log(`Preferred provider: ${name}`);
+}
+async function chooseDefaultMode() {
+  const config = await loadConfig();
+  const name = await select2({
+    message: "Choose the default generation preference",
+    default: config.routing.default_mode,
+    choices: Object.keys(config.modes).map((modeName) => ({
+      name: modeLabel(modeName),
+      value: modeName
+    }))
+  });
+  setPreferredMode(config, name);
+  await saveConfig(config);
+  console.log(`Preferred mode: ${name}`);
+}
+async function chooseProviderToTest() {
+  const config = await loadConfig();
+  const name = await select2({
+    message: "Choose a provider to test",
+    default: config.routing.default_provider,
+    choices: Object.keys(config.providers).map((providerName) => ({
+      name: providerName,
+      value: providerName
+    }))
+  });
+  const result = await testProvider(name, config.providers[name]);
+  console.log(`${result.ok ? "OK" : "FAILED"} ${result.name} [${result.protocol}]`);
+  console.log(result.message);
+  if (result.model) console.log(`Model: ${result.model}`);
+  if (result.http_status) console.log(`HTTP status: ${result.http_status}`);
+}
+async function quickAddProvider() {
+  const config = await loadConfig();
+  const template = await select2({
+    message: "Choose the provider/channel you want to add",
+    choices: [
+      {
+        name: "Third-party OpenAI-compatible channel",
+        value: "openai_proxy"
+      },
+      {
+        name: "Third-party Gemini channel",
+        value: "gemini_proxy"
+      },
+      {
+        name: "OpenAI official",
+        value: "openai_official"
+      },
+      {
+        name: "Gemini official",
+        value: "gemini_official"
+      }
+    ]
+  });
+  const defaults = quickProviderDefaults(template);
+  const name = await input2({
+    message: "Provider name",
+    default: nextAvailableProviderName(config, defaults.name)
+  });
+  const baseUrl = await input2({
+    message: "Provider host URL (do not include /v1 or /v1beta)",
+    default: defaults.base_url
+  });
+  const apiKeyEnv = await input2({
+    message: "API key environment variable",
+    default: defaults.api_key_env
+  });
+  const modelsRaw = await input2({
+    message: "Models (comma separated, press Enter for recommended defaults)",
+    default: defaults.models.join(",")
+  });
+  const provider2 = {
+    enabled: true,
+    protocol: defaults.protocol,
+    channel: defaults.channel,
+    base_url: normalizeProviderBaseUrl(baseUrl),
+    api_key_env: apiKeyEnv,
+    models: parseModels(modelsRaw),
+    capabilities: defaultCapabilitiesForProtocol2(defaults.protocol)
+  };
+  addProviderToConfig(config, name, provider2);
+  const useAsDefault = await confirm2({
+    message: "Use this provider as the default?",
+    default: true
+  });
+  if (useAsDefault) {
+    setPreferredProvider(config, name);
+  }
+  await saveConfig(config);
+  console.log(`Added provider: ${name}`);
+  console.log(`Set ${apiKeyEnv} in your shell or .env before testing this provider.`);
+}
+function quickProviderDefaults(template) {
+  switch (template) {
+    case "openai_proxy":
+      return {
+        name: "openai_proxy",
+        protocol: "openai-images",
+        channel: "third_party",
+        base_url: "https://www.pandai.vip",
+        api_key_env: "OPENAI_API_KEY",
+        models: ["gpt-image-2"]
+      };
+    case "gemini_proxy":
+      return {
+        name: "gemini_proxy",
+        protocol: "gemini",
+        channel: "third_party",
+        base_url: "https://www.pandai.vip",
+        api_key_env: "GEMINI_API_KEY",
+        models: ["gemini-3.1-flash-image-preview", "gemini-3-pro-image-preview"]
+      };
+    case "openai_official":
+      return {
+        name: "openai_official",
+        protocol: "openai-images",
+        channel: "official",
+        base_url: defaultProviderBaseUrl("openai-images"),
+        api_key_env: "OPENAI_API_KEY",
+        models: ["gpt-image-2"]
+      };
+    case "gemini_official":
+      return {
+        name: "gemini_official",
+        protocol: "gemini",
+        channel: "official",
+        base_url: defaultProviderBaseUrl("gemini"),
+        api_key_env: "GEMINI_API_KEY",
+        models: ["gemini-3.1-flash-image-preview", "gemini-3-pro-image-preview"]
+      };
+  }
+}
+function parseModels(raw) {
+  return raw.split(",").map((model) => model.trim()).filter(Boolean);
+}
+function providerLabel(provider2) {
+  if (provider2.channel === "official") {
+    return provider2.protocol === "gemini" ? "Gemini official" : "OpenAI-compatible official";
+  }
+  return provider2.protocol === "gemini" ? "Gemini third-party" : "OpenAI-compatible third-party";
+}
+function modeLabel(modeName) {
+  switch (modeName) {
+    case "fast":
+      return "fast - quick drafts";
+    case "balanced":
+      return "balanced - recommended";
+    case "premium":
+      return "premium - higher quality";
+    default:
+      return modeName;
+  }
+}
+
+// src/cli.ts
+var program = new Command();
+program.name("picgen").description("Lightweight image generation connector for AI agents.").version("0.1.0-alpha.0");
+program.command("setup").description("Run the interactive PicGen setup wizard.").action(runSetup);
+program.command("quickstart").description("Print install and first-run guidance.").action(runQuickstart);
+program.command("doctor").description("Inspect PicGen configuration and provider readiness.").option("--json", "Print machine-readable JSON.").action(runDoctor);
+program.command("create").description("Create an image generation plan or generate images.").argument("<prompt...>", "Prompt text.").option("--dry-run", "Plan generation without calling a provider.").option("--preset <name>", "Preset name.").option("--provider <name>", "Provider name.").option("--mode <name>", "Mode name.").option("--model <name>", "Model name.").option("--out-dir <path>", "Output directory.").option(
+  "--reference <path>",
+  "Reference image path for Gemini generation. Can be repeated.",
+  collectOption,
+  []
+).option("--json", "Print machine-readable JSON.").option("-y, --yes", "Skip confirmation for real generation.").action(runCreate);
+var provider = program.command("provider").description("Manage providers/channels.");
+provider.command("list").description("List providers.").action(listProviders);
+provider.command("add").description("Add a provider.").action(addProvider);
+provider.command("edit").argument("<name>").description("Edit a provider.").action(editProvider);
+provider.command("test").argument("<name>").description("Test provider connectivity without generating an image.").option("--json", "Print machine-readable JSON.").action(runProviderTest);
+provider.command("prefer").argument("<name>").description("Set the default provider preference.").action(preferProvider);
+provider.command("enable").argument("<name>").description("Enable a provider.").action((name) => setProviderEnabled(name, true));
+provider.command("disable").argument("<name>").description("Disable a provider.").action((name) => setProviderEnabled(name, false));
+provider.command("remove").argument("<name>").description("Remove a provider.").action(removeProvider);
+program.command("mode").description("Manage generation mode preferences.").command("prefer").argument("<name>").description("Set the default mode preference.").action(preferMode);
+program.command("preset").description("Manage generation preset preferences.").command("prefer").argument("<name>").description("Set the default preset preference.").action(preferPreset);
+program.parseAsync().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});
+function collectOption(value, previous) {
+  return [...previous, value];
+}