@afromero/kin3o 0.2.3 → 0.2.5

package/README.md

@@ -5,9 +5,12 @@
 **Text to Motion. From your terminal.**
 
 [![npm](https://img.shields.io/npm/v/@afromero/kin3o)](https://www.npmjs.com/package/@afromero/kin3o)
+[![downloads](https://img.shields.io/npm/dm/@afromero/kin3o)](https://www.npmjs.com/package/@afromero/kin3o)
 [![CI](https://github.com/affromero/kin3o/actions/workflows/ci.yml/badge.svg)](https://github.com/affromero/kin3o/actions/workflows/ci.yml)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Socket](https://img.shields.io/badge/Socket-protected-blueviolet?logo=socket.dev)](https://socket.dev)
+[![min-release-age](https://img.shields.io/badge/min--release--age-7%20days-brightgreen)](https://docs.npmjs.com/cli/v10/using-npm/config#min-release-age)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/affromero/kin3o/pulls)
 
 AI-powered Lottie animation generator. Turns natural language prompts into valid, playable Lottie JSON and interactive dotLottie state machines using your existing Claude or Codex subscription.
@@ -237,6 +240,14 @@ npm run ci           # typecheck + test
 npm run build        # Compile to dist/
 ```
 
+## Related Projects
+
+| Project | Description |
+|---------|-------------|
+| [**Fairtrail**](https://github.com/affromero/fairtrail) | Flight price evolution tracker with natural language search |
+| [**PriceToken**](https://github.com/affromero/pricetoken) | Real-time LLM pricing API, npm/PyPI packages, and live dashboard |
+| [**gitpane**](https://github.com/affromero/gitpane) | Multi-repo Git workspace dashboard for the terminal |
+
 ## License
 
 MIT

package/dist/index.js

@@ -2,7 +2,7 @@
 import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { Command } from 'commander';
-import { PROVIDERS, detectAvailableProviders, getDefaultProvider } from './providers/registry.js';
+import { PROVIDERS, detectAvailableProviders, getDefaultProvider, diagnoseProvider } from './providers/registry.js';
 import { buildSystemPrompt, buildInteractiveSystemPrompt, buildRefinementUserPrompt, buildInteractiveRefinementUserPrompt, loadDesignTokens } from './prompts/index.js';
 import { validateLottie, autoFix } from './validator.js';
 import { validateStateMachine } from './state-machine-validator.js';
@@ -28,6 +28,7 @@ program
     .option('--no-preview', 'Skip opening preview in browser')
     .option('-t, --tokens <path>', 'Path to design tokens JSON (or "sotto" for built-in)')
     .option('-i, --interactive', 'Generate interactive state machine (.lottie output)', false)
+    .option('--timeout <ms>', 'CLI subprocess timeout in milliseconds (default: auto per model)', parseInt)
     .action(async (prompt, options) => {
     const mode = options.interactive ? 'interactive' : 'static';
     console.log(`\nkin3o — Generating ${mode} animation...`);
@@ -36,7 +37,7 @@ program
     if (!providerKey) {
         providerKey = await getDefaultProvider() ?? undefined;
         if (!providerKey) {
-            console.error('  ✗ No AI providers available. Install Claude Code, Codex, or set ANTHROPIC_API_KEY.');
+            console.error('  ✗ No AI providers available. Run `kin3o providers` for diagnostics.');
             process.exit(1);
         }
     }
@@ -56,7 +57,7 @@ program
         : buildSystemPrompt(tokens);
     // 4. Generate
     try {
-        const result = await provider.generate(model, systemPrompt, prompt);
+        const result = await provider.generate(model, systemPrompt, prompt, options.timeout);
         console.log(`  ✓ Generated in ${(result.durationMs / 1000).toFixed(1)}s`);
         if (options.interactive) {
             await handleInteractiveOutput(result.content, prompt, options);
@@ -166,6 +167,7 @@ program
     .option('-o, --output <path>', 'Output file path')
     .option('--no-preview', 'Skip opening preview in browser')
     .option('-t, --tokens <path>', 'Path to design tokens JSON (or "sotto" for built-in)')
+    .option('--timeout <ms>', 'CLI subprocess timeout in milliseconds (default: 600000)', parseInt)
     .action(async (file, prompt, rawOptions) => {
     const resolvedPath = resolve(file);
     // 1. Validate input file
@@ -202,7 +204,7 @@ program
     if (!providerKey) {
         providerKey = await getDefaultProvider() ?? undefined;
         if (!providerKey) {
-            console.error('  ✗ No AI providers available. Install Claude Code, Codex, or set ANTHROPIC_API_KEY.');
+            console.error('  ✗ No AI providers available. Run `kin3o providers` for diagnostics.');
             process.exit(1);
         }
     }
@@ -225,7 +227,7 @@ program
         : buildRefinementUserPrompt(currentJson, prompt);
     // 6. Generate refined output
     try {
-        const result = await provider.generate(model, systemPrompt, userPrompt);
+        const result = await provider.generate(model, systemPrompt, userPrompt, rawOptions.timeout);
         console.log(`  ✓ Refined in ${(result.durationMs / 1000).toFixed(1)}s`);
         // 7. Compute output path
         const outputDir = ensureOutputDir();
@@ -369,9 +371,22 @@ program
     const available = await detectAvailableProviders();
     console.log('\nAvailable AI Providers:\n');
     for (const [key, config] of Object.entries(PROVIDERS)) {
-        const status = available.includes(key) ? '✓' : '✗';
+        const isAvail = available.includes(key);
+        const status = isAvail ? '✓' : '✗';
         console.log(`  ${status} ${config.displayName} (${key})`);
         console.log(`    Models: ${config.models.join(', ')}`);
+        if (!isAvail) {
+            const diag = diagnoseProvider(key);
+            if (!diag.binaryFound) {
+                console.log(`    Problem: "${diag.binaryName}" not found on PATH`);
+                console.log(`    Fix: Install ${config.displayName} and ensure "${diag.binaryName}" is on your PATH`);
+            }
+            else if (!diag.authFound) {
+                const cmd = key === 'codex' ? 'codex auth' : 'claude';
+                console.log(`    Problem: CLI found but not authenticated`);
+                console.log(`    Fix: Run \`${cmd}\` to log in`);
+            }
+        }
     }
     console.log('');
 });

package/dist/providers/claude.d.ts

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

package/dist/providers/claude.js

@@ -1,13 +1,15 @@
 import { spawn } from 'node:child_process';
+import { getTimeoutMs } from './registry.js';
 import { filterCliStderr } from '../utils.js';
-export async function generateWithClaude(model, systemPrompt, userPrompt) {
+export async function generateWithClaude(model, systemPrompt, userPrompt, timeoutMs) {
     const start = Date.now();
     const fullPrompt = `${systemPrompt}\n\n${userPrompt}`;
+    const timeout = getTimeoutMs(timeoutMs);
     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,
+            timeout,
             env,
         });
         let stdout = '';
@@ -21,7 +23,8 @@ export async function generateWithClaude(model, systemPrompt, userPrompt) {
         proc.on('close', (code) => {
             if (code !== 0) {
                 const filtered = filterCliStderr(stderr);
-                reject(new Error(`claude CLI exited ${code}: ${filtered}`));
+                const hint = code === 143 ? ` (timed out after ${Math.round(timeout / 1000)}s — try --timeout <ms> or a faster model)` : '';
+                reject(new Error(`claude CLI exited ${code}: ${filtered}${hint}`));
             }
             else {
                 resolve(stdout.trim());

package/dist/providers/codex.d.ts

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

package/dist/providers/codex.js

@@ -2,11 +2,13 @@ import { spawn } from 'node:child_process';
 import { mkdtempSync, readFileSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
+import { getTimeoutMs } from './registry.js';
 import { filterCliStderr } from '../utils.js';
-export async function generateWithCodex(model, systemPrompt, userPrompt) {
+export async function generateWithCodex(model, systemPrompt, userPrompt, timeoutMs) {
     const start = Date.now();
     const fullPrompt = `${systemPrompt}\n\n${userPrompt}`;
     const tmpFile = join(mkdtempSync(join(tmpdir(), 'codex-')), 'output.txt');
+    const timeout = getTimeoutMs(timeoutMs);
     const args = [
         'exec', '-',
         '--skip-git-repo-check',
@@ -16,7 +18,7 @@ export async function generateWithCodex(model, systemPrompt, userPrompt) {
     ];
     const content = await new Promise((resolve, reject) => {
         const proc = spawn('codex', args, {
-            timeout: 240_000,
+            timeout,
             env: { ...process.env },
         });
         let stderr = '';
@@ -27,7 +29,9 @@ export async function generateWithCodex(model, systemPrompt, userPrompt) {
             const filtered = filterCliStderr(stderr);
             const hint = filtered.includes('401') || filtered.includes('Unauthorized')
                 ? ' (ensure codex is authenticated via `codex auth`)'
-                : '';
+                : code === 143
+                    ? ` (timed out after ${Math.round(timeout / 1000)}s — try --timeout <ms> or a faster model)`
+                    : '';
             try {
                 const output = readFileSync(tmpFile, 'utf-8').trim();
                 unlinkSync(tmpFile);

package/dist/providers/registry.d.ts

@@ -9,9 +9,19 @@ export interface ProviderConfig {
     models: string[];
     defaultModel: string;
     isAvailable: () => Promise<boolean>;
-    generate: (model: string, systemPrompt: string, userPrompt: string) => Promise<GenerationResult>;
+    generate: (model: string, systemPrompt: string, userPrompt: string, timeoutMs?: number) => Promise<GenerationResult>;
+}
+/** Get timeout with optional user override */
+export declare function getTimeoutMs(userOverride?: number): number;
+export interface ProviderDiagnosis {
+    binaryFound: boolean;
+    authFound: boolean;
+    binaryName: string;
+    authPaths: string[];
 }
 export declare const PROVIDERS: Record<string, ProviderConfig>;
+/** Diagnose why a provider is or isn't available */
+export declare function diagnoseProvider(key: string): ProviderDiagnosis;
 /** Detect which providers are available (binary + auth) */
 export declare function detectAvailableProviders(): Promise<string[]>;
 /** Get default provider (first available in priority order) */

package/dist/providers/registry.js

@@ -4,6 +4,12 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { generateWithClaude } from './claude.js';
 import { generateWithCodex } from './codex.js';
+/** Default CLI subprocess timeout: 10 minutes */
+const DEFAULT_TIMEOUT_MS = 600_000;
+/** Get timeout with optional user override */
+export function getTimeoutMs(userOverride) {
+    return userOverride ?? DEFAULT_TIMEOUT_MS;
+}
 const home = homedir();
 function hasBinary(name) {
     try {
@@ -23,7 +29,8 @@ export const PROVIDERS = {
             if (!hasBinary('claude'))
                 return false;
             return existsSync(join(home, '.claude.json'))
-                || existsSync(join(home, '.claude', 'credentials.json'));
+                || existsSync(join(home, '.claude', 'credentials.json'))
+                || existsSync(join(home, '.claude', '.credentials.json'));
         },
         generate: generateWithClaude,
     },
@@ -39,6 +46,31 @@ export const PROVIDERS = {
         generate: generateWithCodex,
     },
 };
+const PROVIDER_BINARIES = {
+    'claude-code': 'claude',
+    codex: 'codex',
+};
+const PROVIDER_AUTH_PATHS = {
+    'claude-code': [
+        join(home, '.claude.json'),
+        join(home, '.claude', 'credentials.json'),
+        join(home, '.claude', '.credentials.json'),
+    ],
+    codex: [
+        join(home, '.codex', 'auth.json'),
+    ],
+};
+/** Diagnose why a provider is or isn't available */
+export function diagnoseProvider(key) {
+    const binaryName = PROVIDER_BINARIES[key] ?? key;
+    const authPaths = PROVIDER_AUTH_PATHS[key] ?? [];
+    return {
+        binaryFound: hasBinary(binaryName),
+        authFound: authPaths.some(p => existsSync(p)),
+        binaryName,
+        authPaths,
+    };
+}
 /** Detect which providers are available (binary + auth) */
 export async function detectAvailableProviders() {
     const available = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afromero/kin3o",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "AI-powered Lottie animation generator — text to motion from your terminal",
   "type": "module",
   "license": "MIT",
@@ -41,6 +41,7 @@
     "@anthropic-ai/sdk": "^0.78.0",
     "@dotlottie/dotlottie-js": "^1.6.3",
     "commander": "^13.0.0",
+    "lottie-react": "^2.4.1",
     "open": "^10.1.0",
     "puppeteer-core": "^24.0.0"
   },