@afromero/kin3o 0.1.0

package/dist/prompts/examples.js

@@ -0,0 +1,168 @@
+/** Hand-crafted, validated Lottie JSON examples for few-shot prompting */
+export const PULSING_CIRCLE = {
+    v: '5.5.2',
+    fr: 60,
+    ip: 0,
+    op: 120,
+    w: 512,
+    h: 512,
+    ddd: 0,
+    assets: [],
+    layers: [
+        {
+            ty: 4,
+            ind: 0,
+            nm: 'Pulsing Circle',
+            ip: 0,
+            op: 120,
+            st: 0,
+            ddd: 0,
+            ks: {
+                a: { a: 0, k: [0, 0] },
+                p: { a: 0, k: [256, 256] },
+                s: {
+                    a: 1,
+                    k: [
+                        {
+                            t: 0,
+                            s: [80, 80],
+                            o: { x: [0.42], y: [0] },
+                            i: { x: [0.58], y: [1] },
+                        },
+                        {
+                            t: 60,
+                            s: [120, 120],
+                            o: { x: [0.42], y: [0] },
+                            i: { x: [0.58], y: [1] },
+                        },
+                        { t: 120, s: [80, 80] },
+                    ],
+                },
+                r: { a: 0, k: 0 },
+                o: { a: 0, k: 100 },
+            },
+            shapes: [
+                {
+                    ty: 'gr',
+                    nm: 'Circle Group',
+                    it: [
+                        {
+                            ty: 'el',
+                            nm: 'Ellipse',
+                            p: { a: 0, k: [0, 0] },
+                            s: { a: 0, k: [200, 200] },
+                        },
+                        {
+                            ty: 'fl',
+                            nm: 'Fill',
+                            c: { a: 0, k: [0.851, 0.467, 0.024, 1] },
+                            o: { a: 0, k: 100 },
+                            r: 1,
+                        },
+                        {
+                            ty: 'tr',
+                            p: { a: 0, k: [0, 0] },
+                            a: { a: 0, k: [0, 0] },
+                            s: { a: 0, k: [100, 100] },
+                            r: { a: 0, k: 0 },
+                            o: { a: 0, k: 100 },
+                        },
+                    ],
+                },
+            ],
+            bm: 0,
+        },
+    ],
+};
+export const WAVEFORM_BARS = {
+    v: '5.5.2',
+    fr: 60,
+    ip: 0,
+    op: 120,
+    w: 512,
+    h: 512,
+    ddd: 0,
+    assets: [],
+    layers: [
+        ...[0, 1, 2].map((i) => {
+            const x = 206 + i * 50;
+            const delay = i * 15;
+            return {
+                ty: 4,
+                ind: i,
+                nm: `Bar ${i + 1}`,
+                ip: 0,
+                op: 120,
+                st: 0,
+                ddd: 0,
+                ks: {
+                    a: { a: 0, k: [0, 0] },
+                    p: { a: 0, k: [x, 256] },
+                    s: { a: 0, k: [100, 100] },
+                    r: { a: 0, k: 0 },
+                    o: { a: 0, k: 100 },
+                },
+                shapes: [
+                    {
+                        ty: 'gr',
+                        nm: `Bar Group ${i + 1}`,
+                        it: [
+                            {
+                                ty: 'rc',
+                                nm: 'Rectangle',
+                                p: { a: 0, k: [0, 0] },
+                                s: {
+                                    a: 1,
+                                    k: [
+                                        {
+                                            t: delay,
+                                            s: [30, 40],
+                                            o: { x: [0.42], y: [0] },
+                                            i: { x: [0.58], y: [1] },
+                                        },
+                                        {
+                                            t: 30 + delay,
+                                            s: [30, 160],
+                                            o: { x: [0.42], y: [0] },
+                                            i: { x: [0.58], y: [1] },
+                                        },
+                                        {
+                                            t: 60 + delay,
+                                            s: [30, 40],
+                                            o: { x: [0.42], y: [0] },
+                                            i: { x: [0.58], y: [1] },
+                                        },
+                                        {
+                                            t: 90 + delay,
+                                            s: [30, 120],
+                                            o: { x: [0.42], y: [0] },
+                                            i: { x: [0.58], y: [1] },
+                                        },
+                                        { t: 120, s: [30, 40] },
+                                    ],
+                                },
+                                r: { a: 0, k: 4 },
+                            },
+                            {
+                                ty: 'fl',
+                                nm: 'Fill',
+                                c: { a: 0, k: [0.851, 0.467, 0.024, 1] },
+                                o: { a: 0, k: 100 },
+                                r: 1,
+                            },
+                            {
+                                ty: 'tr',
+                                p: { a: 0, k: [0, 0] },
+                                a: { a: 0, k: [0, 0] },
+                                s: { a: 0, k: [100, 100] },
+                                r: { a: 0, k: 0 },
+                                o: { a: 0, k: 100 },
+                            },
+                        ],
+                    },
+                ],
+                bm: 0,
+            };
+        }),
+    ],
+};

package/dist/prompts/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Prompt Registry — single entry point for all system prompts.
+ *
+ * Static mode:  buildSystemPrompt()        → single Lottie JSON animation
+ * Interactive:  buildInteractiveSystemPrompt() → multi-animation envelope + state machine
+ *
+ * Both share LOTTIE_FORMAT_REFERENCE for consistent Lottie spec knowledge.
+ * Each mode has its own few-shot examples tuned for that output format.
+ */
+export { LOTTIE_FORMAT_REFERENCE } from './system.js';
+export { buildSystemPrompt } from './system.js';
+export { PULSING_CIRCLE, WAVEFORM_BARS } from './examples.js';
+export { buildInteractiveSystemPrompt } from './system-interactive.js';
+export { INTERACTIVE_BUTTON } from './examples-interactive.js';
+export { MASCOT_STATIC, MASCOT_INTERACTIVE } from './examples-mascot.js';
+export { loadDesignTokens, SOTTO_TOKENS } from './tokens.js';
+export type { DesignTokens } from './tokens.js';

package/dist/prompts/index.js

@@ -0,0 +1,21 @@
+/**
+ * Prompt Registry — single entry point for all system prompts.
+ *
+ * Static mode:  buildSystemPrompt()        → single Lottie JSON animation
+ * Interactive:  buildInteractiveSystemPrompt() → multi-animation envelope + state machine
+ *
+ * Both share LOTTIE_FORMAT_REFERENCE for consistent Lottie spec knowledge.
+ * Each mode has its own few-shot examples tuned for that output format.
+ */
+// ── Shared ──
+export { LOTTIE_FORMAT_REFERENCE } from './system.js';
+// ── Static mode ──
+export { buildSystemPrompt } from './system.js';
+export { PULSING_CIRCLE, WAVEFORM_BARS } from './examples.js';
+// ── Interactive mode ──
+export { buildInteractiveSystemPrompt } from './system-interactive.js';
+export { INTERACTIVE_BUTTON } from './examples-interactive.js';
+// ── Mascot ──
+export { MASCOT_STATIC, MASCOT_INTERACTIVE } from './examples-mascot.js';
+// ── Design tokens ──
+export { loadDesignTokens, SOTTO_TOKENS } from './tokens.js';

package/dist/prompts/system-interactive.d.ts

@@ -0,0 +1,2 @@
+import type { DesignTokens } from './tokens.js';
+export declare function buildInteractiveSystemPrompt(tokens?: DesignTokens): string;

package/dist/prompts/system-interactive.js

@@ -0,0 +1,93 @@
+import { LOTTIE_FORMAT_REFERENCE } from './system.js';
+import { INTERACTIVE_BUTTON } from './examples-interactive.js';
+export function buildInteractiveSystemPrompt(tokens) {
+    const sections = [];
+    // 1. Role + output rules
+    sections.push(`You are an interactive Lottie animation generator. You create multiple Lottie animations plus a dotLottie state machine that wires them together with user interactions (hover, click, etc.).
+
+Output ONLY valid JSON matching the envelope format below. No markdown fences, no explanation, no commentary. Your output must be directly parseable by JSON.parse().`);
+    // 2. Shared Lottie format reference
+    sections.push(LOTTIE_FORMAT_REFERENCE);
+    // 3. dotLottie state machine spec
+    sections.push(`
+DOTLOTTIE STATE MACHINE FORMAT:
+
+The state machine controls transitions between animations based on user interactions.
+
+Output envelope format:
+{
+  "animations": {
+    "<id>": { <complete Lottie JSON> },
+    "<id>": { <complete Lottie JSON> }
+  },
+  "stateMachine": {
+    "initial": "<state name>",
+    "states": [ ... ],
+    "interactions": [ ... ],
+    "inputs": [ ... ]
+  }
+}
+
+State types:
+- "PlaybackState": plays an animation. Fields: "name", "type", "animation" (animation ID), "transitions" (array)
+- "GlobalState": listens globally. Fields: "name", "type", "transitions" (array)
+
+Transition format:
+{ "type": "Transition", "toState": "<target state name>", "guards": [ ... ] }
+
+Guard format (conditional transition):
+- Boolean: { "type": "Boolean", "inputName": "<name>", "conditionType": "Equal", "compareTo": true/false }
+- Numeric: { "type": "Numeric", "inputName": "<name>", "conditionType": "Equal"|"GreaterThan"|"LessThan", "compareTo": <number> }
+- String: { "type": "String", "inputName": "<name>", "conditionType": "Equal", "compareTo": "<value>" }
+
+Interaction types (user events that set inputs):
+- "PointerDown": mouse click / tap
+- "PointerUp": mouse release
+- "PointerEnter": mouse hover enter
+- "PointerExit": mouse hover leave
+- "OnComplete": animation playback completes (requires "stateName" field)
+- "OnLoopComplete": animation loop completes (requires "stateName" field)
+
+Interaction format:
+{ "type": "<event type>", "actions": [{ "type": "<action type>", "inputName": "<input name>", "value": <value> }] }
+For OnComplete/OnLoopComplete add "stateName": "<which state this applies to>"
+
+Action types:
+- "SetBoolean": set a boolean input { "type": "SetBoolean", "inputName": "...", "value": true/false }
+- "Toggle": toggle a boolean input { "type": "Toggle", "inputName": "..." }
+- "Increment": increment a numeric input { "type": "Increment", "inputName": "...", "value": 1 }
+- "Decrement": decrement a numeric input { "type": "Decrement", "inputName": "...", "value": 1 }
+- "SetString": set a string input { "type": "SetString", "inputName": "...", "value": "..." }
+- "SetNumeric": set a numeric input { "type": "SetNumeric", "inputName": "...", "value": 0 }
+
+Input types:
+- "Boolean": { "name": "<name>", "type": "Boolean", "value": <default bool> }
+- "Numeric": { "name": "<name>", "type": "Numeric", "value": <default number> }
+- "String": { "name": "<name>", "type": "String", "value": "<default string>" }`);
+    // 4. Design rules
+    sections.push(`
+INTERACTIVE DESIGN RULES:
+- Keep individual animations SHORT: 60-120 frames (1-2 seconds at 60fps)
+- Maximum 4 states per state machine
+- Each animation: 512x512 canvas, 60fps, shape layers only
+- Animations should be distinct but visually cohesive (same style, similar colors)
+- Use ease-in-out easing by default
+- Make loopable animations where appropriate (idle states)
+- Always include "ddd": 0 and "assets": []
+- Colors: 0-1 floats (NOT 0-255)
+- Groups MUST end with "tr" transform`);
+    // 5. Design tokens
+    if (tokens) {
+        const colorLines = Object.entries(tokens.colors)
+            .map(([name, rgba]) => `  ${name}: [${rgba.join(', ')}]`)
+            .join('\n');
+        sections.push(`
+DESIGN TOKENS — use these colors when appropriate:
+${colorLines}`);
+    }
+    // 6. Few-shot example
+    sections.push(`
+EXAMPLE — Interactive button (idle/hover/pressed states):
+${JSON.stringify(INTERACTIVE_BUTTON)}`);
+    return sections.join('\n');
+}

package/dist/prompts/system.d.ts

@@ -0,0 +1,3 @@
+import type { DesignTokens } from './tokens.js';
+export declare const LOTTIE_FORMAT_REFERENCE = "\nLOTTIE FORMAT REFERENCE:\n\nTop-level required fields:\n- \"v\": string (use \"5.5.2\")\n- \"fr\": number (use 60 for 60fps)\n- \"ip\": 0 (in-point, always 0)\n- \"op\": number (out-point, end frame \u2014 e.g. 120 for 2s at 60fps)\n- \"w\": number (width in pixels)\n- \"h\": number (height in pixels)\n- \"ddd\": 0 (no 3D)\n- \"assets\": [] (empty array)\n- \"layers\": array of layer objects\n\nLayer (shape layer, ty=4):\n- \"ty\": 4 (shape layer)\n- \"ind\": number (unique index)\n- \"nm\": string (layer name)\n- \"ip\": 0, \"op\": same as top-level op\n- \"st\": 0 (start time)\n- \"ddd\": 0\n- \"ks\": transform object\n- \"shapes\": array of shape objects\n- \"bm\": 0 (blend mode, normal)\n\nTransform \"ks\" object:\n- \"a\": anchor point (VECTOR property)\n- \"p\": position (VECTOR property)\n- \"s\": scale (VECTOR property, [100,100] = 100%)\n- \"r\": rotation (SCALAR property, degrees)\n- \"o\": opacity (SCALAR property, 0-100)\n\nPROPERTY TYPES \u2014 this distinction is critical:\n- VECTOR property (position, scale, anchor, size): {\"a\":0,\"k\":[x,y]} or animated {\"a\":1,\"k\":[keyframes]}\n- SCALAR property (rotation, opacity, roundness, stroke width): {\"a\":0,\"k\":0} or animated {\"a\":1,\"k\":[keyframes]}\n- COLOR property: {\"a\":0,\"k\":[r,g,b,1]} with 0-1 floats (NOT 0-255)\n\nKeyframe format:\n{\"t\":frame,\"s\":[values],\"o\":{\"x\":[n],\"y\":[n]},\"i\":{\"x\":[n],\"y\":[n]}}\n- \"t\": frame number\n- \"s\": start values (array for vector, array with single value for scalar)\n- \"o\": out-tangent (ease out), \"i\": in-tangent (ease in)\n- Last keyframe needs only \"t\" and \"s\" (no tangents)\n\nEasing (ease-in-out): \"o\":{\"x\":[0.42],\"y\":[0]}, \"i\":{\"x\":[0.58],\"y\":[1]}\n\nShape types:\n- \"el\": ellipse \u2014 \"p\" (center, vector), \"s\" (size, vector)\n- \"rc\": rectangle \u2014 \"p\" (center, vector), \"s\" (size, vector), \"r\" (roundness, scalar)\n- \"sh\": path \u2014 \"ks\" with bezier {\"c\":bool, \"v\":[[x,y],...], \"i\":[[dx,dy],...], \"o\":[[dx,dy],...]}\n- \"fl\": fill \u2014 \"c\" (color), \"o\" (opacity, scalar), \"r\" (fill rule, 1=nonzero)\n- \"st\": stroke \u2014 \"c\" (color), \"o\" (opacity), \"w\" (width, scalar), \"lc\" (line cap, 2=round), \"lj\" (line join, 2=round)\n- \"gr\": group \u2014 \"it\" array of shapes + MUST end with \"tr\" (group transform)\n- \"tr\": group transform \u2014 same fields as layer transform \"ks\"\n- \"tm\": trim path \u2014 \"s\" (start%, scalar), \"e\" (end%, scalar), \"o\" (offset, scalar)\n\nCRITICAL: Groups MUST have \"tr\" (transform) as the LAST item in their \"it\" array.";
+export declare function buildSystemPrompt(tokens?: DesignTokens): string;

package/dist/prompts/system.js

@@ -0,0 +1,94 @@
+import { PULSING_CIRCLE, WAVEFORM_BARS } from './examples.js';
+export const LOTTIE_FORMAT_REFERENCE = `
+LOTTIE FORMAT REFERENCE:
+
+Top-level required fields:
+- "v": string (use "5.5.2")
+- "fr": number (use 60 for 60fps)
+- "ip": 0 (in-point, always 0)
+- "op": number (out-point, end frame — e.g. 120 for 2s at 60fps)
+- "w": number (width in pixels)
+- "h": number (height in pixels)
+- "ddd": 0 (no 3D)
+- "assets": [] (empty array)
+- "layers": array of layer objects
+
+Layer (shape layer, ty=4):
+- "ty": 4 (shape layer)
+- "ind": number (unique index)
+- "nm": string (layer name)
+- "ip": 0, "op": same as top-level op
+- "st": 0 (start time)
+- "ddd": 0
+- "ks": transform object
+- "shapes": array of shape objects
+- "bm": 0 (blend mode, normal)
+
+Transform "ks" object:
+- "a": anchor point (VECTOR property)
+- "p": position (VECTOR property)
+- "s": scale (VECTOR property, [100,100] = 100%)
+- "r": rotation (SCALAR property, degrees)
+- "o": opacity (SCALAR property, 0-100)
+
+PROPERTY TYPES — this distinction is critical:
+- VECTOR property (position, scale, anchor, size): {"a":0,"k":[x,y]} or animated {"a":1,"k":[keyframes]}
+- SCALAR property (rotation, opacity, roundness, stroke width): {"a":0,"k":0} or animated {"a":1,"k":[keyframes]}
+- COLOR property: {"a":0,"k":[r,g,b,1]} with 0-1 floats (NOT 0-255)
+
+Keyframe format:
+{"t":frame,"s":[values],"o":{"x":[n],"y":[n]},"i":{"x":[n],"y":[n]}}
+- "t": frame number
+- "s": start values (array for vector, array with single value for scalar)
+- "o": out-tangent (ease out), "i": in-tangent (ease in)
+- Last keyframe needs only "t" and "s" (no tangents)
+
+Easing (ease-in-out): "o":{"x":[0.42],"y":[0]}, "i":{"x":[0.58],"y":[1]}
+
+Shape types:
+- "el": ellipse — "p" (center, vector), "s" (size, vector)
+- "rc": rectangle — "p" (center, vector), "s" (size, vector), "r" (roundness, scalar)
+- "sh": path — "ks" with bezier {"c":bool, "v":[[x,y],...], "i":[[dx,dy],...], "o":[[dx,dy],...]}
+- "fl": fill — "c" (color), "o" (opacity, scalar), "r" (fill rule, 1=nonzero)
+- "st": stroke — "c" (color), "o" (opacity), "w" (width, scalar), "lc" (line cap, 2=round), "lj" (line join, 2=round)
+- "gr": group — "it" array of shapes + MUST end with "tr" (group transform)
+- "tr": group transform — same fields as layer transform "ks"
+- "tm": trim path — "s" (start%, scalar), "e" (end%, scalar), "o" (offset, scalar)
+
+CRITICAL: Groups MUST have "tr" (transform) as the LAST item in their "it" array.`;
+export function buildSystemPrompt(tokens) {
+    const sections = [];
+    // 1. Role + output rules
+    sections.push(`You are a Lottie animation generator. Output ONLY valid JSON. No markdown fences, no explanation, no commentary. Your output must be directly parseable by JSON.parse().`);
+    // 2. Lottie format spec
+    sections.push(LOTTIE_FORMAT_REFERENCE);
+    // 3. Design rules
+    sections.push(`
+DESIGN RULES:
+- Frame rate: 60fps
+- Duration: 120-180 frames (2-3 seconds)
+- Canvas: 512x512 pixels, center at [256, 256]
+- Loopable: last keyframe values must match first keyframe values
+- Use ease-in-out easing by default
+- Shape layers only (ty=4)
+- Always include "ddd": 0 and "assets": []
+- Keep animations smooth and proportional
+- Use distinct colors for different elements`);
+    // 4. Design tokens (conditional)
+    if (tokens) {
+        const colorLines = Object.entries(tokens.colors)
+            .map(([name, rgba]) => `  ${name}: [${rgba.join(', ')}]`)
+            .join('\n');
+        sections.push(`
+DESIGN TOKENS — use these colors when appropriate:
+${colorLines}`);
+    }
+    // 5. Few-shot examples
+    sections.push(`
+EXAMPLE 1 — Pulsing circle (scale animation):
+${JSON.stringify(PULSING_CIRCLE)}
+
+EXAMPLE 2 — 3-bar waveform (staggered position animation):
+${JSON.stringify(WAVEFORM_BARS)}`);
+    return sections.join('\n');
+}

package/dist/prompts/tokens.d.ts

@@ -0,0 +1,6 @@
+export interface DesignTokens {
+    colors: Record<string, [number, number, number, number]>;
+}
+export declare const SOTTO_TOKENS: DesignTokens;
+/** Load design tokens from a JSON file, converting hex colors to Lottie RGBA */
+export declare function loadDesignTokens(path?: string): DesignTokens | undefined;

package/dist/prompts/tokens.js

@@ -0,0 +1,28 @@
+import { readFileSync } from 'node:fs';
+import { hexToLottieColor } from '../utils.js';
+export const SOTTO_TOKENS = {
+    colors: {
+        primary: hexToLottieColor('#D97706'),
+        accent: hexToLottieColor('#1E3A5F'),
+        background: hexToLottieColor('#FEFCF8'),
+        surface: hexToLottieColor('#FFFFFF'),
+        text: hexToLottieColor('#1A1A1A'),
+        muted: hexToLottieColor('#6B7280'),
+    },
+};
+/** Load design tokens from a JSON file, converting hex colors to Lottie RGBA */
+export function loadDesignTokens(path) {
+    if (!path)
+        return undefined;
+    if (path === 'sotto')
+        return SOTTO_TOKENS;
+    const raw = readFileSync(path, 'utf-8');
+    const data = JSON.parse(raw);
+    if (!data.colors)
+        return undefined;
+    const colors = {};
+    for (const [name, hex] of Object.entries(data.colors)) {
+        colors[name] = hexToLottieColor(hex);
+    }
+    return { colors };
+}

package/dist/providers/anthropic.d.ts

@@ -0,0 +1,2 @@
+import type { GenerationResult } from './registry.js';
+export declare function generateWithAnthropic(model: string, systemPrompt: string, userPrompt: string): Promise<GenerationResult>;

package/dist/providers/anthropic.js

@@ -0,0 +1,25 @@
+import Anthropic from '@anthropic-ai/sdk';
+export async function generateWithAnthropic(model, systemPrompt, userPrompt) {
+    const apiKey = process.env['ANTHROPIC_API_KEY'];
+    if (!apiKey) {
+        throw new Error('ANTHROPIC_API_KEY environment variable is required');
+    }
+    const start = Date.now();
+    const client = new Anthropic({ apiKey });
+    const response = await client.messages.create({
+        model,
+        max_tokens: 16384,
+        system: systemPrompt,
+        messages: [{ role: 'user', content: userPrompt }],
+    });
+    const text = response.content
+        .filter((block) => block.type === 'text')
+        .map((block) => block.text)
+        .join('');
+    return {
+        content: text,
+        provider: 'anthropic',
+        model,
+        durationMs: Date.now() - start,
+    };
+}

package/dist/providers/claude.d.ts

@@ -0,0 +1,2 @@
+import type { GenerationResult } from './registry.js';
+export declare function generateWithClaude(model: string, systemPrompt: string, userPrompt: string): Promise<GenerationResult>;

package/dist/providers/claude.js

@@ -0,0 +1,47 @@
+import { spawn } from 'node:child_process';
+import { filterCliStderr } from '../utils.js';
+export async function generateWithClaude(model, systemPrompt, userPrompt) {
+    const start = Date.now();
+    const fullPrompt = `${systemPrompt}\n\n${userPrompt}`;
+    const content = await new Promise((resolve, reject) => {
+        const env = { ...process.env };
+        delete env.ANTHROPIC_API_KEY;
+        const proc = spawn('claude', ['--print', '--model', model], {
+            timeout: 240_000,
+            env,
+        });
+        let stdout = '';
+        let stderr = '';
+        proc.stdout.on('data', (d) => {
+            stdout += d.toString();
+        });
+        proc.stderr.on('data', (d) => {
+            stderr += d.toString();
+        });
+        proc.on('close', (code) => {
+            if (code !== 0) {
+                const filtered = filterCliStderr(stderr);
+                reject(new Error(`claude CLI exited ${code}: ${filtered}`));
+            }
+            else {
+                resolve(stdout.trim());
+            }
+        });
+        proc.on('error', (err) => {
+            if (err.code === 'ENOENT') {
+                reject(new Error('claude CLI not found. Install Claude Code first.'));
+            }
+            else {
+                reject(err);
+            }
+        });
+        proc.stdin.write(fullPrompt);
+        proc.stdin.end();
+    });
+    return {
+        content,
+        provider: 'claude-code',
+        model,
+        durationMs: Date.now() - start,
+    };
+}

package/dist/providers/codex.d.ts

@@ -0,0 +1,2 @@
+import type { GenerationResult } from './registry.js';
+export declare function generateWithCodex(model: string, systemPrompt: string, userPrompt: string): Promise<GenerationResult>;

package/dist/providers/codex.js

@@ -0,0 +1,60 @@
+import { spawn } from 'node:child_process';
+import { mkdtempSync, readFileSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { filterCliStderr } from '../utils.js';
+export async function generateWithCodex(model, systemPrompt, userPrompt) {
+    const start = Date.now();
+    const fullPrompt = `${systemPrompt}\n\n${userPrompt}`;
+    const tmpFile = join(mkdtempSync(join(tmpdir(), 'codex-')), 'output.txt');
+    const args = [
+        'exec', '-',
+        '--skip-git-repo-check',
+        '--ephemeral',
+        '-o', tmpFile,
+        '--model', model,
+    ];
+    const content = await new Promise((resolve, reject) => {
+        const proc = spawn('codex', args, {
+            timeout: 240_000,
+            env: { ...process.env },
+        });
+        let stderr = '';
+        proc.stderr.on('data', (d) => {
+            stderr += d.toString();
+        });
+        proc.on('close', (code) => {
+            const filtered = filterCliStderr(stderr);
+            const hint = filtered.includes('401') || filtered.includes('Unauthorized')
+                ? ' (ensure codex is authenticated via `codex auth`)'
+                : '';
+            try {
+                const output = readFileSync(tmpFile, 'utf-8').trim();
+                unlinkSync(tmpFile);
+                if (code !== 0)
+                    reject(new Error(`codex CLI exited ${code}: ${filtered}${hint}`));
+                else
+                    resolve(output);
+            }
+            catch {
+                reject(new Error(`codex CLI exited ${code}: ${filtered}${hint}`));
+            }
+        });
+        proc.on('error', (err) => {
+            if (err.code === 'ENOENT') {
+                reject(new Error('codex CLI not found. Install Codex first.'));
+            }
+            else {
+                reject(err);
+            }
+        });
+        proc.stdin.write(fullPrompt);
+        proc.stdin.end();
+    });
+    return {
+        content,
+        provider: 'codex',
+        model,
+        durationMs: Date.now() - start,
+    };
+}

package/dist/providers/registry.d.ts

@@ -0,0 +1,18 @@
+export interface GenerationResult {
+    content: string;
+    provider: string;
+    model: string;
+    durationMs: number;
+}
+export interface ProviderConfig {
+    displayName: string;
+    models: string[];
+    defaultModel: string;
+    isAvailable: () => Promise<boolean>;
+    generate: (model: string, systemPrompt: string, userPrompt: string) => Promise<GenerationResult>;
+}
+export declare const PROVIDERS: Record<string, ProviderConfig>;
+/** Detect which providers are available (binary + auth) */
+export declare function detectAvailableProviders(): Promise<string[]>;
+/** Get default provider (first available in priority order) */
+export declare function getDefaultProvider(): Promise<string | null>;