@gobing-ai/knowledge-kit 0.0.12 → 0.0.14

package/plugins/generations/image-gen/package.json

@@ -0,0 +1,17 @@
+{
+    "name": "@gobing-ai/image-gen",
+    "type": "module",
+    "private": true,
+    "scripts": {
+        "typecheck": "tsc --noEmit"
+    },
+    "dependencies": {
+        "@gobing-ai/kk-core": "workspace:*",
+        "@gobing-ai/ts-runtime": "catalog:",
+        "@gobing-ai/ts-utils": "catalog:",
+        "zod": "4.4.3"
+    },
+    "devDependencies": {
+        "@types/bun": "1.3.14"
+    }
+}

package/plugins/generations/image-gen/plugin.json

@@ -0,0 +1,7 @@
+{
+    "name": "image-gen",
+    "kind": "generator",
+    "entry": "./dist/index.js",
+    "version": "0.1.0",
+    "description": "Image generation plugin: free / cover / illustration jobs over the generator Doc[] → Content contract (feature K)"
+}

package/plugins/generations/image-gen/presets/formats/cover.yaml

@@ -0,0 +1,57 @@
+name: cover
+description: Article cover image template (21:9 ultrawide cinematic aspect ratio)
+job: cover
+aspectRatio: '21:9'
+width: 1344
+height: 576
+defaultStyle: vibrant
+keywords:
+    - 8K
+    - ultra-high-quality
+    - masterpiece
+    - cinematic composition
+    - rule of thirds
+    - volumetric lighting
+    - dramatic shadows
+    - fine detail textures
+    - professional color grading
+outputFilename: '{{title | cover}}.png'
+variables:
+    title:
+        description: Article title
+        default: Article
+    subtitle:
+        description: Article subtitle or tagline
+        default: ''
+    topics:
+        description: Main topics or themes
+        default: technology
+    mood:
+        description: Cover mood or atmosphere
+        default: modern and aspirational
+    visual_style:
+        description: Visual approach (abstract-geometric, organic-flowing, photographic, illustrative, isometric)
+        default: abstract geometric with clean modern lines
+    color_palette:
+        description: Color direction with specific tones
+        default: deep navy transitioning to electric blue with warm amber accents
+    composition:
+        description: Composition and layout guidance
+        default: strong central focal point, negative space in upper third for text overlay
+    atmosphere:
+        description: Atmosphere and emotional tone
+        default: professional, aspirational, forward-looking
+    content:
+        description: Article content for context (use --content)
+        default: ''
+template: |-
+    Cinematic wide-format cover illustration for "{{title}}"{{subtitle | , subtitled "{{subtitle}}"}}.
+    Theme: {{topics | technology and innovation}}.
+    Visual approach: {{visual_style | abstract geometric with clean modern lines}}.
+    Composition: {{composition | strong central focal point, negative space in upper third for text overlay}}.
+    Color palette: {{color_palette | deep navy transitioning to electric blue with warm amber accents}}.
+    Atmosphere: {{atmosphere | professional, aspirational, forward-looking}}, {{mood | modern and aspirational}} sensibility.
+    {{content | Inspired by the article's core concepts, }}
+    create a visually striking hero image with dramatic volumetric lighting,
+    fine detail textures, and cinematic depth of field.
+    Magazine-quality digital art with strong visual hierarchy.

package/plugins/generations/image-gen/presets/formats/free.yaml

@@ -0,0 +1,46 @@
+name: free
+description: General-purpose image generation template with rich art direction defaults
+job: free
+aspectRatio: '1:1'
+width: 1024
+height: 1024
+defaultStyle: vibrant
+keywords:
+    - 8K
+    - high-quality
+    - masterpiece
+    - professional
+    - rule of thirds
+    - rich textures
+    - crisp details
+outputFilename: generated-image.png
+variables:
+    subject:
+        description: Main subject of the image
+        default: a beautiful landscape
+    mood:
+        description: Mood or atmosphere
+        default: peaceful and contemplative
+    detail_level:
+        description: Level of detail
+        default: highly detailed
+    color_palette:
+        description: Color direction
+        default: harmonious and balanced, context-appropriate
+    composition:
+        description: Composition style
+        default: balanced with clear focal point and visual breathing room
+    lighting:
+        description: Lighting style
+        default: natural and flattering with gentle shadows
+    content:
+        description: Additional context content (use --content)
+        default: ''
+template: |-
+    {{detail_level | Highly detailed}} depiction of {{subject}}.
+    Mood: {{mood | peaceful and contemplative}} — evoking calm contemplation.
+    Composition: {{composition | balanced with clear focal point and visual breathing room}}.
+    Color palette: {{color_palette | harmonious and balanced, context-appropriate}}.
+    Lighting: {{lighting | natural and flattering with gentle shadows}}.
+    {{content | Drawing from provided context, }}
+    render with artistic precision, rich textures, and professional color grading.

package/plugins/generations/image-gen/presets/formats/illustration.yaml

@@ -0,0 +1,48 @@
+name: illustration
+description: Article illustration template for inline images (4:3 aspect ratio)
+job: illustration
+aspectRatio: '4:3'
+width: 1152
+height: 864
+defaultStyle: technical-diagram
+keywords:
+    - technical
+    - precise
+    - educational
+    - clear
+    - vector-like lines
+    - logical flow
+    - generous whitespace
+    - polished
+outputFilename: '{{title | illustration}}.png'
+variables:
+    title:
+        description: Illustration title/context
+        default: diagram
+    concept:
+        description: Main concept to illustrate
+        default: technical concept
+    style_detail:
+        description: Additional style details
+        default: clean
+    complexity:
+        description: Level of complexity (simple, moderate, complex)
+        default: moderate
+    visual_approach:
+        description: Illustration approach (diagrammatic, conceptual, metaphorical, isometric)
+        default: clean diagrammatic with subtle depth
+    color_scheme:
+        description: Color scheme direction
+        default: professional blues and grays with one accent color for emphasis
+    content:
+        description: Article content for context (use --content)
+        default: ''
+template: |-
+    {{complexity | Moderately complex}} technical illustration of {{concept}}.
+    Visual approach: {{visual_approach | clean diagrammatic with subtle depth}}.
+    Style: {{style_detail | clean}} with precise vector-like lines and clear visual hierarchy.
+    Color scheme: {{color_scheme | professional blues and grays with one accent color for emphasis}}.
+    {{content | Grounded in the article's technical content, }}
+    create an educational diagram with logical flow, labeled components where appropriate,
+    and generous whitespace for readability. Context: {{title}}.
+    Render as a polished technical illustration suitable for professional documentation.

package/plugins/generations/image-gen/presets/styles/clean-webapp-ui.yaml

@@ -0,0 +1,28 @@
+name: clean-webapp-ui
+description: Clean light-mode web-app interface — neutral near-white surfaces, card grid, restrained steel-blue and warm-tan accents on an ink text base.
+modifiers: clean web-app interface style, light neutral surfaces, generous whitespace, card grid layout, rounded corners, subtle borders, restrained steel-blue accents, warm tan highlights, crisp sans-serif typography, flat modern UI
+palette:
+    - { role: background, name: near-white, hex: '#F4F5F6' }
+    - { role: text, name: ink, hex: '#272828' }
+    - { role: primary, name: steel blue, hex: '#647E9C' }
+    - { role: secondary, name: warm tan, hex: '#BD9B67' }
+    - { role: secondary, name: light grey, hex: '#C1C1BB' }
+typography: crisp geometric sans-serif, small muted labels, strong weight contrast between headings and body text
+visualElements:
+    - card grid with rounded corners
+    - hairline borders on neutral ground
+    - flat icons
+    - sparse colour accents against a light grey field
+bestFor: productivity-tool interfaces, dashboards, knowledge-base and bookmark apps, clean SaaS pages
+negative: heavy textures, skeuomorphic depth, neon gradients, cluttered composition
+# source.confidence: extraction-side judgement per the style-extraction decision rule;
+# fidelity: image was regenerated 2026-09-10 from the recorded composed prompt (Antigravity; xAI invalid_grant),
+# but the ref/regen pixel pair was lost in the worktree cleanup (both lived in gitignored .spur/run/). The
+# extraction data below is complete, so the take-the-lower rule resolves the four-axis verdict to LOW. Re-run
+# the style-extraction procedure on a fresh reference to upgrade it.
+source:
+    kind: extracted
+    refImages:
+        - (original reference lost in worktree cleanup 2026-09-10; re-extract to refresh)
+    extractedAt: '2026-09-10T00:57:40Z'
+    confidence: high

package/plugins/generations/image-gen/presets/styles/cute.yaml

@@ -0,0 +1,3 @@
+name: cute
+description: Sweet, playful aesthetic with pastel colors and rounded forms. Kawaii-influenced with soft gradients, gentle curves, and approachable design. Highly engaging on social platforms targeting younger demographics.
+modifiers: cute kawaii aesthetic, pastel colors, rounded shapes, soft gradients, playful design, sweet and gentle, no sharp edges, bubbly composition

package/plugins/generations/image-gen/presets/styles/editorial.yaml

@@ -0,0 +1,3 @@
+name: editorial
+description: Sophisticated, magazine-quality design with strong typography presence and deliberate composition. High-contrast with bold design choices. Communicates authority, expertise, and premium quality.
+modifiers: editorial magazine style, high contrast, bold composition, dramatic directional lighting, sophisticated design, strong visual hierarchy, premium quality

package/plugins/generations/image-gen/presets/styles/fresh.yaml

@@ -0,0 +1,3 @@
+name: fresh
+description: Clean, natural aesthetic with bright whites and green-toned accents. Evokes clarity, health, and new beginnings. Light and airy with generous whitespace.
+modifiers: fresh clean aesthetic, bright natural daylight, soft greens and whites, airy composition, generous whitespace, natural elements, refreshing atmosphere

package/plugins/generations/image-gen/presets/styles/minimalist.yaml

@@ -0,0 +1,3 @@
+name: minimalist
+description: Simple, clean aesthetic with plenty of whitespace. Focus on essential elements with subtle colors and elegant composition. Less is more — every element serves a purpose.
+modifiers: minimalist design, clean lines, simple aesthetic, plenty of whitespace, balanced composition, matte surfaces, geometric alignment

package/plugins/generations/image-gen/presets/styles/photorealistic.yaml

@@ -0,0 +1,3 @@
+name: photorealistic
+description: Highly detailed, realistic images with professional photography quality. Natural lighting, realistic textures, and cinematic depth create convincing photographic results.
+modifiers: photorealistic, highly detailed, realistic lighting, professional photography, natural textures, cinematic depth of field, natural color grading

package/plugins/generations/image-gen/presets/styles/sketch.yaml

@@ -0,0 +1,3 @@
+name: sketch
+description: Hand-drawn, artistic feel with organic lines and pencil drawing aesthetic. Warm and approachable with natural imperfections that convey authenticity and human touch.
+modifiers: hand-drawn sketch style, artistic, pencil drawing feel, organic lines, paper texture, warm tones, cross-hatching, warm paper background

package/plugins/generations/image-gen/presets/styles/technical-diagram.yaml

@@ -0,0 +1,3 @@
+name: technical-diagram
+description: Clean, technical illustrations with precise lines and professional diagram style. Minimal color palette focused on clarity and technical accuracy. Communicates complexity with visual simplicity.
+modifiers: clean technical illustration, precise lines, professional diagram style, flat even lighting, grid-aligned composition

package/plugins/generations/image-gen/presets/styles/vibrant.yaml

@@ -0,0 +1,3 @@
+name: vibrant
+description: Bold colors and high contrast for eye-catching visuals. Energetic and dynamic composition designed to grab attention. Maximum visual impact with saturated hues and dramatic lighting.
+modifiers: bold colors, high contrast, vibrant and energetic, eye-catching, dynamic composition, volumetric light rays, neon accent glow

package/plugins/generations/image-gen/presets/styles/warm.yaml

@@ -0,0 +1,3 @@
+name: warm
+description: Cozy, friendly aesthetic with warm color temperature and inviting atmosphere. Evokes comfort, trust, and approachability. Popular on lifestyle and social media platforms.
+modifiers: warm cozy aesthetic, golden hour lighting, soft warm tones, terracotta and amber palette, inviting atmosphere, gentle shadows, matte textures

package/plugins/generations/image-gen/src/bytes.ts

@@ -0,0 +1,19 @@
+import { readFile, writeFile } from 'node:fs/promises';
+
+/**
+ * no-direct-fs-io seam exemption (recorded in .spur/rules/strict/runtime-boundaries.yaml):
+ * the ts-runtime FileSystem seam is text-only, and image generation is a binary
+ * byte-writer by definition — same class as voice-gen's WAV writer and podcast-pub's
+ * upload reader. Every path here is produced by `artifactPath`, so a hostile provider
+ * extension or stem cannot escape `--out`'s directory.
+ */
+
+/** Write generated image bytes beside `--out` (0107 R1). */
+export async function writeBytes(path: string, bytes: Uint8Array): Promise<void> {
+    await writeFile(path, bytes);
+}
+
+/** Read a reference image for image-to-image requests (0105 legacy — local paths become data URIs). */
+export async function readBytes(path: string): Promise<Uint8Array> {
+    return new Uint8Array(await readFile(path));
+}

package/plugins/generations/image-gen/src/index.ts

@@ -0,0 +1,319 @@
+import { dirname } from 'node:path';
+import { parseArgs } from 'node:util';
+import { type Content, ContentSchema, type Doc, DocListSchema } from '@gobing-ai/kk-core';
+import { createNodeFileSystem } from '@gobing-ai/ts-runtime';
+import { echoError } from '@gobing-ai/ts-utils';
+import { writeBytes } from './bytes';
+import {
+    type CaptionEntry,
+    type ImageArtifact,
+    type ImageGenMetadata,
+    type ImageJobSpec,
+    parseJobSpec,
+    readPositions,
+} from './job';
+import { artifactPath, outStemFor } from './paths';
+import { composePrompt, type FormatPreset, loadPresets, type StylePreset } from './presets';
+import { type ImageProvider, type ImageRequest, PROVIDERS, selectProvider } from './providers/types';
+
+export * from './job';
+export * from './paths';
+export * from './presets';
+export * from './providers/types';
+
+const EMPTY_CONTENT: Content = {
+    title: 'Notice',
+    body: '# Notice\nNo documents provided for generation.',
+    format: 'markdown',
+    references: [],
+};
+
+/** Compiled budget cap (R6). Precedence: spec.maxImages → KK_IMAGE_MAX_IMAGES → this. */
+export const DEFAULT_MAX_IMAGES = 4;
+
+/** Resolve the provider instance for a spec; tests inject a stub here — no network. */
+export type ProviderResolver = (spec: ImageJobSpec) => ImageProvider;
+
+function defaultProviderResolver(spec: ImageJobSpec): ImageProvider {
+    const name = selectProvider(spec.provider);
+    const registration = PROVIDERS[name];
+    if (registration === undefined) {
+        // selectProvider only returns registered names; this guards selector/registry drift.
+        throw new Error(`Provider '${name}' was selected but is missing from the registry`);
+    }
+    return registration.create();
+}
+
+/**
+ * Budget cap resolution (R6): the spec value wins over the env, which wins over
+ * the compiled default — the repo's flag > env > config > default rule, with
+ * `maxImages` occupying the flag slot because plugin flags cannot exist (the
+ * spawn argv is frozen at `--in`/`--out`, `apps/cli/src/invoke.ts:118-123`).
+ */
+export function resolveMaxImages(spec: ImageJobSpec): number {
+    if (spec.maxImages !== undefined) {
+        return spec.maxImages;
+    }
+    const raw = process.env.KK_IMAGE_MAX_IMAGES;
+    if (raw === undefined || raw === '') {
+        return DEFAULT_MAX_IMAGES;
+    }
+    const parsed = /^\d+$/.test(raw) ? Number(raw) : Number.NaN;
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        throw new Error(`KK_IMAGE_MAX_IMAGES must be a positive integer, received '${raw}'`);
+    }
+    return parsed;
+}
+
+/**
+ * Resolve the format/style presets for a spec. Per-job defaults are the three
+ * presets 0102 ships, so `{ job: 'cover' }` alone is a complete working job; a
+ * format whose `job` field contradicts the requested job is a misconfiguration
+ * and fails loud before any spend.
+ */
+function resolvePresets(spec: ImageJobSpec): { format: FormatPreset; style: StylePreset } {
+    const { formats, styles } = loadPresets();
+    const formatName = spec.format ?? spec.job;
+    const format = formats.get(formatName);
+    if (format === undefined) {
+        throw new Error(
+            `Unknown image format preset '${formatName}'. Valid formats: ${[...formats.keys()].sort().join(', ')}`,
+        );
+    }
+    if (format.job !== spec.job) {
+        throw new Error(
+            `Format preset '${formatName}' drives the '${format.job}' job, but the spec requests '${spec.job}'`,
+        );
+    }
+    const styleName = spec.style ?? format.defaultStyle;
+    const style = styles.get(styleName);
+    if (style === undefined) {
+        throw new Error(
+            `Unknown image style preset '${styleName}'. Valid styles: ${[...styles.keys()].sort().join(', ')}`,
+        );
+    }
+    return { format, style };
+}
+
+/**
+ * Compose one prompt per image (0102 composePrompt, frozen segment order).
+ * - free: the bare prompt rides the format's `subject` slot unless the caller set it;
+ * - cover: the caller (0106) supplies vars — the plugin never analyses the article;
+ * - illustration: one prompt per caller-chosen anchor, fed as the `concept` var.
+ */
+function composePrompts(
+    spec: ImageJobSpec,
+    format: FormatPreset,
+    style: StylePreset,
+    doc: Doc | undefined,
+    positions: string[] | undefined,
+): string[] {
+    if (spec.job === 'illustration') {
+        if (spec.count !== undefined && positions !== undefined && positions.length !== spec.count) {
+            throw new Error(
+                `Illustration count ${spec.count} does not match the ${positions.length} metadata.positions anchors`,
+            );
+        }
+        const count = positions?.length ?? Math.max(1, spec.count ?? 1);
+        return Array.from({ length: count }, (_, index) => {
+            const concept = positions?.[index];
+            const vars = concept === undefined ? (spec.vars ?? {}) : { concept, ...(spec.vars ?? {}) };
+            return composePrompt(format, style, vars, spec.extra);
+        });
+    }
+    // free/cover produce exactly one image (v1 rule, ImageRequest.n default 1).
+    const vars = spec.job === 'free' ? { subject: doc?.body ?? '', ...(spec.vars ?? {}) } : (spec.vars ?? {});
+    return [composePrompt(format, style, vars, spec.extra)];
+}
+
+/**
+ * Read validated `Doc[]` input and emit the image-gen `Content` (R1/R3/R6).
+ *
+ * Prototype scope (task 0104): the envelope, preset resolution, budget cap,
+ * provider selection, dry run and failure cleanup are implemented; the three
+ * job branches stop at the money-spending boundary — wiring provider bytes to
+ * disk needs the no-direct-fs-io binary-write seam plus the 0103+ adapters, so
+ * each branch throws `not implemented` after everything before the first
+ * provider call has succeeded.
+ */
+export async function processGeneratorIO(
+    inputPath: string,
+    outputPath: string,
+    options: { providerResolver?: ProviderResolver } = {},
+): Promise<void> {
+    const fs = createNodeFileSystem();
+    // voice-gen rule: start clean, and on any failure delete --out plus every
+    // artefact written this run, then rethrow — a failed run leaves nothing.
+    await fs.deleteFile(outputPath);
+    const written: string[] = [];
+    try {
+        const raw = await fs.readFile(inputPath);
+        let docs: Doc[];
+        try {
+            docs = DocListSchema.parse(JSON.parse(raw));
+        } catch (err: unknown) {
+            throw new Error(`Invalid DocList input: ${err instanceof Error ? err.message : String(err)}`);
+        }
+
+        if (docs.length === 0) {
+            await fs.ensureDir(dirname(outputPath));
+            await fs.writeFile(outputPath, JSON.stringify(ContentSchema.parse(EMPTY_CONTENT), null, 2));
+            return;
+        }
+
+        const spec = parseJobSpec(docs);
+        const positions = readPositions(docs);
+        const doc = docs[0];
+
+        // Fail before any provider work: invalid spec, presets, or budget.
+        const { format, style } = resolvePresets(spec);
+        const prompts = composePrompts(spec, format, style, doc, positions);
+        const cap = resolveMaxImages(spec);
+        if (prompts.length > cap) {
+            throw new Error(
+                `Image count ${prompts.length} exceeds the budget cap ${cap} (raise ImageJobSpec.maxImages or KK_IMAGE_MAX_IMAGES)`,
+            );
+        }
+
+        // Selection must succeed (or fail loud naming the provider) even when nothing is spent.
+        const resolveProvider: ProviderResolver = options.providerResolver ?? defaultProviderResolver;
+        const provider = resolveProvider(spec);
+
+        if (process.env.KK_IMAGE_DRY_RUN === '1') {
+            // R6: compose every prompt, select the provider, spend nothing, write no image.
+            const metadata: ImageGenMetadata = {
+                generator: 'kk:image-gen',
+                job: spec.job,
+                images: [],
+                ...(spec.job !== 'free' && doc?.id !== undefined ? { sourceDocId: doc.id } : {}),
+                dryRun: true,
+            };
+            const content = ContentSchema.parse({
+                body: prompts.join('\n\n---\n\n'),
+                // Design: free/cover title = the format preset's name; illustration = the source doc's title.
+                title: spec.job === 'illustration' ? (doc?.title ?? format.name) : format.name,
+                format: 'image',
+                references: [],
+                metadata,
+            });
+            await fs.ensureDir(dirname(outputPath));
+            await fs.writeFile(outputPath, JSON.stringify(content, null, 2));
+            return;
+        }
+
+        // The money-spending branch: one provider call per prompt, bytes written
+        // beside `--out` via artifactPath (R1/R3 worded as 0104 R3), written[]
+        // tracking keeps failure cleanup live (dead-loop advisory closed here).
+        await fs.ensureDir(dirname(outputPath));
+        const stem = outStemFor(outputPath, spec.outputStem);
+        const artifacts: ImageArtifact[] = [];
+        const captions: CaptionEntry[] = [];
+        let body = doc?.body ?? '';
+        for (const [index, prompt] of prompts.entries()) {
+            const request: ImageRequest = {
+                prompt,
+                model: spec.model ?? provider.defaultModel(),
+                aspectRatio: format.aspectRatio,
+                ...(spec.referenceImages && spec.referenceImages.length > 0
+                    ? { referenceImages: spec.referenceImages }
+                    : {}),
+            };
+            provider.validate?.(request);
+            const result = await provider.generate(request);
+            // Illustration: the anchor must occur exactly once before we spend image 1.
+            let anchor: string | undefined;
+            if (spec.job === 'illustration') {
+                anchor = positions?.[index];
+                if (anchor === undefined) {
+                    throw new Error('Illustration anchor missing from metadata.positions');
+                }
+                const parts = body.split(anchor);
+                if (parts.length !== 2) {
+                    throw new Error(
+                        `Illustration anchor must occur exactly once in the source body, found ${parts.length - 1}: '${anchor.slice(0, 50)}'`,
+                    );
+                }
+            }
+            const path = artifactPath(outputPath, stem, format.name, index + 1, result.extension);
+            await writeBytes(path, result.bytes);
+            written.push(path);
+            const artifact: ImageArtifact = {
+                path,
+                format: format.name,
+                style: style.name,
+                provider: result.provider,
+                model: result.model,
+                prompt,
+                bytes: result.bytes.byteLength,
+            };
+            if (spec.seed !== undefined) {
+                artifact.seed = spec.seed;
+            }
+            artifacts.push(artifact);
+            if (anchor !== undefined) {
+                const parts = body.split(anchor);
+                const altText = `Illustration ${index + 1}`;
+                const markdown = `${anchor}\n\n![${altText}](${path})`;
+                captions.push({
+                    index: index + 1,
+                    path,
+                    caption: anchor,
+                    altText,
+                    anchor,
+                });
+                // Reinsert the anchor verbatim, then the image — index stays human-reviewable.
+                body = `${parts[0]}${markdown}${parts[1]}`;
+            }
+        }
+        const metadata: ImageGenMetadata = {
+            generator: 'kk:image-gen',
+            job: spec.job,
+            images: artifacts,
+            ...(spec.job !== 'free' && doc?.id !== undefined ? { sourceDocId: doc.id } : {}),
+            ...(captions.length > 0 ? { captions } : {}),
+        };
+        const content = ContentSchema.parse({
+            // free/cover: the body is the prompt trail (same as dry run); illustration: the
+            // source body with round-trip refs inserted (0104 R4 — the input is never mutated).
+            body: spec.job === 'illustration' ? body : prompts.join('\n\n---\n\n'),
+            title: spec.job === 'illustration' ? (doc?.title ?? format.name) : format.name,
+            format: 'image',
+            references: [],
+            metadata,
+        });
+        await fs.writeFile(outputPath, JSON.stringify(content, null, 2));
+        return;
+    } catch (err: unknown) {
+        await fs.deleteFile(outputPath);
+        for (const path of written) {
+            await fs.deleteFile(path);
+        }
+        throw err;
+    }
+}
+
+export async function main(): Promise<number> {
+    const { values } = parseArgs({
+        options: {
+            in: { type: 'string' },
+            out: { type: 'string' },
+        },
+    });
+
+    if (!values.in || !values.out) {
+        echoError('image-gen failed: Missing required arguments: --in and --out');
+        return 1;
+    }
+
+    try {
+        await processGeneratorIO(values.in, values.out);
+        return 0;
+    } catch (err: unknown) {
+        echoError(`image-gen failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+}
+
+if (import.meta.main) {
+    process.exit(await main());
+}