@afromero/kin3o 0.1.0

package/dist/providers/registry.js

@@ -0,0 +1,62 @@
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { generateWithClaude } from './claude.js';
+import { generateWithCodex } from './codex.js';
+const home = homedir();
+function hasBinary(name) {
+    try {
+        execSync(`which ${name}`, { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export const PROVIDERS = {
+    'claude-code': {
+        displayName: 'Claude Code (Max/Pro)',
+        models: ['sonnet', 'opus', 'haiku'],
+        defaultModel: 'sonnet',
+        isAvailable: async () => {
+            if (!hasBinary('claude'))
+                return false;
+            return existsSync(join(home, '.claude.json'))
+                || existsSync(join(home, '.claude', 'credentials.json'));
+        },
+        generate: generateWithClaude,
+    },
+    codex: {
+        displayName: 'OpenAI Codex (CLI)',
+        models: ['gpt-5.4', 'gpt-5.3-codex', 'gpt-5.3-codex-spark', 'codex-mini-latest'],
+        defaultModel: 'codex-mini-latest',
+        isAvailable: async () => {
+            if (!hasBinary('codex'))
+                return false;
+            return existsSync(join(home, '.codex', 'auth.json'));
+        },
+        generate: generateWithCodex,
+    },
+};
+/** Detect which providers are available (binary + auth) */
+export async function detectAvailableProviders() {
+    const available = [];
+    for (const [key, config] of Object.entries(PROVIDERS)) {
+        if (await config.isAvailable()) {
+            available.push(key);
+        }
+    }
+    return available;
+}
+/** Get default provider (first available in priority order) */
+export async function getDefaultProvider() {
+    const priority = ['claude-code', 'codex'];
+    for (const key of priority) {
+        const config = PROVIDERS[key];
+        if (config && await config.isAvailable()) {
+            return key;
+        }
+    }
+    return null;
+}

package/dist/state-machine-validator.d.ts

@@ -0,0 +1,6 @@
+export interface StateMachineValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+export declare function validateStateMachine(sm: unknown, animationIds: string[]): StateMachineValidationResult;

package/dist/state-machine-validator.js

@@ -0,0 +1,182 @@
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+export function validateStateMachine(sm, animationIds) {
+    const errors = [];
+    const warnings = [];
+    if (!isObject(sm)) {
+        return { valid: false, errors: ['State machine is not an object'], warnings };
+    }
+    // Validate initial
+    if (typeof sm['initial'] !== 'string') {
+        errors.push('Missing or invalid "initial" (must be string)');
+    }
+    // Validate states
+    if (!Array.isArray(sm['states'])) {
+        errors.push('Missing or invalid "states" (must be array)');
+        return { valid: errors.length === 0, errors, warnings };
+    }
+    const states = sm['states'];
+    const stateNames = new Set();
+    for (let i = 0; i < states.length; i++) {
+        const state = states[i];
+        if (!isObject(state)) {
+            errors.push(`states[${i}] is not an object`);
+            continue;
+        }
+        if (typeof state['name'] !== 'string') {
+            errors.push(`states[${i}] missing "name" (must be string)`);
+            continue;
+        }
+        const name = state['name'];
+        stateNames.add(name);
+        const type = state['type'];
+        if (type !== 'PlaybackState' && type !== 'GlobalState') {
+            errors.push(`states[${i}] ("${name}") has invalid "type": "${String(type)}" (must be "PlaybackState" or "GlobalState")`);
+        }
+        // PlaybackState must reference a valid animation
+        if (type === 'PlaybackState' && typeof state['animation'] === 'string') {
+            if (!animationIds.includes(state['animation'])) {
+                errors.push(`states[${i}] ("${name}") references unknown animation "${state['animation']}"`);
+            }
+        }
+    }
+    // Validate initial references existing state
+    if (typeof sm['initial'] === 'string' && !stateNames.has(sm['initial'])) {
+        errors.push(`"initial" references non-existent state "${sm['initial']}"`);
+    }
+    // Collect declared inputs
+    const declaredInputs = new Set();
+    if (Array.isArray(sm['inputs'])) {
+        for (const input of sm['inputs']) {
+            if (isObject(input) && typeof input['name'] === 'string') {
+                declaredInputs.add(input['name']);
+            }
+        }
+    }
+    // Validate transitions on states + collect referenced inputs
+    const referencedInputs = new Set();
+    const transitionTargets = new Set();
+    const statesWithTransitions = new Set();
+    for (let i = 0; i < states.length; i++) {
+        const state = states[i];
+        if (!isObject(state))
+            continue;
+        const name = state['name'] ?? `states[${i}]`;
+        const transitions = state['transitions'];
+        if (Array.isArray(transitions)) {
+            if (transitions.length > 0)
+                statesWithTransitions.add(name);
+            for (let j = 0; j < transitions.length; j++) {
+                const t = transitions[j];
+                if (!isObject(t))
+                    continue;
+                if (typeof t['toState'] === 'string') {
+                    const target = t['toState'];
+                    transitionTargets.add(target);
+                    if (!stateNames.has(target)) {
+                        errors.push(`states[${i}] ("${name}") transition[${j}] references non-existent toState "${target}"`);
+                    }
+                }
+                // Check guards
+                const guards = t['guards'];
+                if (Array.isArray(guards)) {
+                    for (const guard of guards) {
+                        if (isObject(guard) && typeof guard['inputName'] === 'string') {
+                            const inputName = guard['inputName'];
+                            referencedInputs.add(inputName);
+                            if (!declaredInputs.has(inputName)) {
+                                errors.push(`states[${i}] ("${name}") guard references undeclared input "${inputName}"`);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // Validate interactions
+    if (Array.isArray(sm['interactions'])) {
+        for (let i = 0; i < sm['interactions'].length; i++) {
+            const interaction = sm['interactions'][i];
+            if (!isObject(interaction))
+                continue;
+            // Check action inputName references
+            const actions = interaction['actions'];
+            if (Array.isArray(actions)) {
+                for (const action of actions) {
+                    if (isObject(action) && typeof action['inputName'] === 'string') {
+                        const inputName = action['inputName'];
+                        referencedInputs.add(inputName);
+                        if (!declaredInputs.has(inputName)) {
+                            errors.push(`interactions[${i}] action references undeclared input "${inputName}"`);
+                        }
+                    }
+                }
+            }
+            // OnComplete/OnLoopComplete stateName references
+            const type = interaction['type'];
+            if ((type === 'OnComplete' || type === 'OnLoopComplete') && typeof interaction['stateName'] === 'string') {
+                const stateName = interaction['stateName'];
+                if (!stateNames.has(stateName)) {
+                    errors.push(`interactions[${i}] ("${String(type)}") references non-existent stateName "${stateName}"`);
+                }
+            }
+        }
+    }
+    // Warnings: unreachable states (BFS from initial)
+    if (typeof sm['initial'] === 'string' && stateNames.has(sm['initial'])) {
+        const reachable = new Set();
+        const queue = [sm['initial']];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            if (reachable.has(current))
+                continue;
+            reachable.add(current);
+            // Find transitions from this state
+            const stateObj = states.find(s => isObject(s) && s['name'] === current);
+            if (stateObj && Array.isArray(stateObj['transitions'])) {
+                for (const t of stateObj['transitions']) {
+                    if (isObject(t) && typeof t['toState'] === 'string') {
+                        queue.push(t['toState']);
+                    }
+                }
+            }
+        }
+        for (const name of stateNames) {
+            if (!reachable.has(name)) {
+                warnings.push(`State "${name}" is unreachable from initial state`);
+            }
+        }
+    }
+    // Warnings: dead-end states (non-final states with zero transitions)
+    for (const state of states) {
+        if (!isObject(state))
+            continue;
+        const name = state['name'];
+        if (!name)
+            continue;
+        const transitions = state['transitions'];
+        const hasTransitions = Array.isArray(transitions) && transitions.length > 0;
+        // A state is a dead end if it has no transitions and other states transition TO it
+        // (i.e., it's not the only state)
+        if (!hasTransitions && stateNames.size > 1 && transitionTargets.has(name)) {
+            // This is a valid terminal state, not necessarily a warning
+            // Only warn if it's NOT the only state reached as a target and it's not a natural end
+        }
+        // Simpler: warn about non-final states with no outgoing transitions
+        // (states that are not leaves in the graph)
+        if (!hasTransitions && stateNames.size > 1) {
+            // Check if this is the initial state with no transitions — that's a real dead end
+            if (sm['initial'] === name) {
+                warnings.push(`Initial state "${name}" has no transitions (dead end)`);
+            }
+        }
+    }
+    // Warnings: declared inputs never referenced
+    for (const inputName of declaredInputs) {
+        if (!referencedInputs.has(inputName)) {
+            warnings.push(`Input "${inputName}" is declared but never referenced in guards or interactions`);
+        }
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}

package/dist/utils.d.ts

@@ -0,0 +1,20 @@
+/** Strip benign CLI warnings (e.g. PATH update failures) from stderr */
+export declare function filterCliStderr(stderr: string): string;
+/** Extract a JSON object from LLM output (strips markdown fences, surrounding text) */
+export declare function extractJson(raw: string): string;
+export interface InteractiveEnvelope {
+    animations: Record<string, object>;
+    stateMachine: {
+        initial: string;
+        states: unknown[];
+        [key: string]: unknown;
+    };
+}
+/** Extract an interactive envelope JSON (animations + stateMachine) from LLM output */
+export declare function extractInteractiveJson(raw: string): InteractiveEnvelope;
+/** Convert hex color string to Lottie [r, g, b, 1] array (0-1 floats) */
+export declare function hexToLottieColor(hex: string): [number, number, number, number];
+/** Convert a prompt string to a filename-safe slug */
+export declare function slugify(text: string, maxLength?: number): string;
+/** Ensure the output directory exists */
+export declare function ensureOutputDir(dir?: string): string;

package/dist/utils.js

@@ -0,0 +1,89 @@
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+/** Strip benign CLI warnings (e.g. PATH update failures) from stderr */
+export function filterCliStderr(stderr) {
+    return stderr
+        .split('\n')
+        .filter(line => !line.includes('could not update PATH'))
+        .join('\n')
+        .trim();
+}
+/** Extract a JSON object from LLM output (strips markdown fences, surrounding text) */
+export function extractJson(raw) {
+    // Strip markdown code fences
+    let cleaned = raw.replace(/```(?:json)?\s*\n?/g, '').replace(/```\s*$/g, '');
+    // Try to extract a JSON object
+    const match = cleaned.match(/\{[\s\S]*\}/);
+    if (!match) {
+        throw new Error('No JSON object found in output');
+    }
+    const jsonStr = match[0];
+    // Validate it parses
+    JSON.parse(jsonStr);
+    return jsonStr;
+}
+/** Extract an interactive envelope JSON (animations + stateMachine) from LLM output */
+export function extractInteractiveJson(raw) {
+    const jsonStr = extractJson(raw);
+    const parsed = JSON.parse(jsonStr);
+    if (typeof parsed['animations'] !== 'object' || parsed['animations'] === null || Array.isArray(parsed['animations'])) {
+        throw new Error('Interactive envelope missing "animations" object');
+    }
+    const animations = parsed['animations'];
+    const animKeys = Object.keys(animations);
+    if (animKeys.length === 0) {
+        throw new Error('Interactive envelope "animations" is empty');
+    }
+    for (const key of animKeys) {
+        if (typeof animations[key] !== 'object' || animations[key] === null) {
+            throw new Error(`Animation "${key}" is not a valid object`);
+        }
+    }
+    if (typeof parsed['stateMachine'] !== 'object' || parsed['stateMachine'] === null || Array.isArray(parsed['stateMachine'])) {
+        throw new Error('Interactive envelope missing "stateMachine" object');
+    }
+    const sm = parsed['stateMachine'];
+    if (typeof sm['initial'] !== 'string') {
+        throw new Error('State machine missing "initial" string');
+    }
+    if (!Array.isArray(sm['states'])) {
+        throw new Error('State machine missing "states" array');
+    }
+    return {
+        animations: animations,
+        stateMachine: sm,
+    };
+}
+/** Convert hex color string to Lottie [r, g, b, 1] array (0-1 floats) */
+export function hexToLottieColor(hex) {
+    let h = hex.replace(/^#/, '');
+    // Expand 3-char hex
+    if (h.length === 3) {
+        h = h[0] + h[0] + h[1] + h[1] + h[2] + h[2];
+    }
+    const r = parseInt(h.slice(0, 2), 16) / 255;
+    const g = parseInt(h.slice(2, 4), 16) / 255;
+    const b = parseInt(h.slice(4, 6), 16) / 255;
+    return [
+        Math.round(r * 1000) / 1000,
+        Math.round(g * 1000) / 1000,
+        Math.round(b * 1000) / 1000,
+        1,
+    ];
+}
+/** Convert a prompt string to a filename-safe slug */
+export function slugify(text, maxLength = 40) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, '')
+        .replace(/\s+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, maxLength);
+}
+/** Ensure the output directory exists */
+export function ensureOutputDir(dir = 'output') {
+    const outputPath = join(process.cwd(), dir);
+    mkdirSync(outputPath, { recursive: true });
+    return outputPath;
+}

package/dist/validator.d.ts

@@ -0,0 +1,8 @@
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+export declare function validateLottie(json: unknown): ValidationResult;
+/** Auto-fix common AI generation mistakes (returns a deep clone) */
+export declare function autoFix(json: object): object;

package/dist/validator.js

@@ -0,0 +1,195 @@
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function checkAnimatedProperty(prop, path, errors) {
+    if (!isObject(prop))
+        return;
+    const a = prop['a'];
+    const k = prop['k'];
+    if (a === 1 && Array.isArray(k)) {
+        for (let i = 0; i < k.length; i++) {
+            const kf = k[i];
+            if (!isObject(kf)) {
+                errors.push(`${path}.k[${i}] is not an object`);
+                continue;
+            }
+            if (typeof kf['t'] !== 'number') {
+                errors.push(`${path}.k[${i}] missing "t" (frame number)`);
+            }
+            if (!Array.isArray(kf['s'])) {
+                errors.push(`${path}.k[${i}] missing "s" (start values array)`);
+            }
+        }
+    }
+}
+function checkGroup(shape, path, errors) {
+    const it = shape['it'];
+    if (!Array.isArray(it) || it.length === 0) {
+        errors.push(`${path} group has no "it" array`);
+        return;
+    }
+    const last = it[it.length - 1];
+    if (!isObject(last) || last['ty'] !== 'tr') {
+        errors.push(`${path} group "it" array must end with a "tr" (transform) item`);
+    }
+}
+function checkColors(obj, path, warnings) {
+    if (!isObject(obj))
+        return;
+    // Check if this looks like a color property
+    if (obj['ty'] === 'fl' || obj['ty'] === 'st') {
+        const c = obj['c'];
+        if (isObject(c)) {
+            const k = c['k'];
+            if (Array.isArray(k) && k.length >= 3) {
+                const hasHighValues = k.slice(0, 3).some((v) => typeof v === 'number' && v > 1);
+                if (hasHighValues) {
+                    warnings.push(`${path}.c has values > 1 (likely 0-255 instead of 0-1)`);
+                }
+            }
+        }
+    }
+    for (const [key, val] of Object.entries(obj)) {
+        if (Array.isArray(val)) {
+            val.forEach((item, i) => checkColors(item, `${path}.${key}[${i}]`, warnings));
+        }
+        else if (isObject(val)) {
+            checkColors(val, `${path}.${key}`, warnings);
+        }
+    }
+}
+export function validateLottie(json) {
+    const errors = [];
+    const warnings = [];
+    if (!isObject(json)) {
+        return { valid: false, errors: ['Input is not an object'], warnings };
+    }
+    const lottie = json;
+    // Required top-level fields
+    for (const field of ['w', 'h', 'fr', 'ip', 'op']) {
+        if (typeof lottie[field] !== 'number') {
+            errors.push(`Missing or invalid required field "${field}" (must be number)`);
+        }
+    }
+    if (!Array.isArray(lottie['layers'])) {
+        errors.push('Missing or invalid "layers" (must be array)');
+        return { valid: errors.length === 0, errors, warnings };
+    }
+    // Warnings for optional fields
+    if (typeof lottie['v'] !== 'string') {
+        warnings.push('Missing "v" version string');
+    }
+    if (!Array.isArray(lottie['assets'])) {
+        warnings.push('Missing "assets" array at top level');
+    }
+    if (lottie['ip'] === lottie['op']) {
+        warnings.push('"op" equals "ip" — animation has zero duration');
+    }
+    // Check each layer
+    const layers = lottie['layers'];
+    layers.forEach((layer, i) => {
+        if (!isObject(layer)) {
+            errors.push(`layers[${i}] is not an object`);
+            return;
+        }
+        const l = layer;
+        if (typeof l['ty'] !== 'number') {
+            errors.push(`layers[${i}] missing "ty" (type, must be number)`);
+        }
+        if (!isObject(l['ks'])) {
+            errors.push(`layers[${i}] missing "ks" (transform object)`);
+        }
+        else {
+            const ks = l['ks'];
+            for (const prop of ['a', 'p', 's', 'r', 'o']) {
+                if (ks[prop]) {
+                    checkAnimatedProperty(ks[prop], `layers[${i}].ks.${prop}`, errors);
+                }
+            }
+        }
+        if (typeof l['ip'] !== 'number') {
+            errors.push(`layers[${i}] missing "ip" (in-point)`);
+        }
+        if (typeof l['op'] !== 'number') {
+            errors.push(`layers[${i}] missing "op" (out-point)`);
+        }
+        if (l['ddd'] === undefined) {
+            warnings.push(`layers[${i}] missing "ddd" field`);
+        }
+        // Shape layer checks
+        if (l['ty'] === 4) {
+            if (!Array.isArray(l['shapes']) || l['shapes'].length === 0) {
+                errors.push(`layers[${i}] (shape layer) has no "shapes" array`);
+            }
+            else {
+                const shapes = l['shapes'];
+                shapes.forEach((shape, j) => {
+                    if (isObject(shape) && shape['ty'] === 'gr') {
+                        checkGroup(shape, `layers[${i}].shapes[${j}]`, errors);
+                    }
+                });
+            }
+        }
+        // Check colors recursively
+        checkColors(l, `layers[${i}]`, warnings);
+    });
+    return { valid: errors.length === 0, errors, warnings };
+}
+/** Auto-fix common AI generation mistakes (returns a deep clone) */
+export function autoFix(json) {
+    const fixed = JSON.parse(JSON.stringify(json));
+    // Add version if missing
+    if (typeof fixed['v'] !== 'string') {
+        fixed['v'] = '5.5.2';
+    }
+    // Add assets if missing
+    if (!Array.isArray(fixed['assets'])) {
+        fixed['assets'] = [];
+    }
+    // Fix layers
+    if (Array.isArray(fixed['layers'])) {
+        for (const layer of fixed['layers']) {
+            if (!isObject(layer))
+                continue;
+            // Add ddd if missing
+            if (layer['ddd'] === undefined) {
+                layer['ddd'] = 0;
+            }
+            // Add st if missing
+            if (layer['st'] === undefined) {
+                layer['st'] = 0;
+            }
+            // Normalize 0-255 colors to 0-1
+            normalizeColors(layer);
+        }
+    }
+    return fixed;
+}
+function normalizeColors(obj) {
+    if (!isObject(obj))
+        return;
+    if (obj['ty'] === 'fl' || obj['ty'] === 'st') {
+        const c = obj['c'];
+        if (isObject(c)) {
+            const k = c['k'];
+            if (Array.isArray(k) && k.length >= 3) {
+                const hasHighValues = k.slice(0, 3).some((v) => typeof v === 'number' && v > 1);
+                if (hasHighValues) {
+                    for (let i = 0; i < 3 && i < k.length; i++) {
+                        if (typeof k[i] === 'number') {
+                            k[i] = Math.round((k[i] / 255) * 1000) / 1000;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    for (const val of Object.values(obj)) {
+        if (Array.isArray(val)) {
+            val.forEach(item => normalizeColors(item));
+        }
+        else if (isObject(val)) {
+            normalizeColors(val);
+        }
+    }
+}