egaki 0.6.0 → 0.7.1

package/src/{models.ts → cli/models.ts}

@@ -36,6 +36,17 @@ export type { ImageModelEntry, VideoModelEntry, AnyModelEntry }
 /** @deprecated Use ImageModelEntry instead */
 export type ModelEntry = ImageModelEntry
 
+/**
+ * Validation error for user-facing input issues (wrong model, missing key, etc.).
+ * CLI prints just the message; provider/runtime errors get full stack + details.
+ */
+export class ValidationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'ValidationError'
+  }
+}
+
 export const IMAGE_MODELS = CATALOG.map((m) => m.id) as [string, ...string[]]
 export const VIDEO_MODELS = VIDEO_CATALOG.map((m) => m.id) as [string, ...string[]]
 
@@ -52,11 +63,10 @@ function stripProviderPrefix(modelId: string): string {
 export const DEFAULT_MODEL = 'nano-banana-pro-preview'
 export const DEFAULT_VIDEO_MODEL = 'veo-3.1-fast-generate-001'
 
-export function getModelConfig(modelId: string): AnyModelEntry {
+export function getModelConfig(modelId: string): Error | AnyModelEntry {
   const entry = findAnyModel(modelId)
   if (!entry) {
-    console.error(pc.red(`Unknown model: ${modelId}`))
-    process.exit(1)
+    return new ValidationError(`Unknown model: ${modelId}`)
   }
   return entry
 }
@@ -72,9 +82,9 @@ export function getModelConfig(modelId: string): AnyModelEntry {
 // That's it — no switch statements to touch.
 
 type ProviderSdk = {
-  image?: (modelId: string) => Promise<ImageModel>
-  text?: (modelId: string) => Promise<LanguageModel>
-  video?: (modelId: string) => Promise<any>
+  image?: (modelId: string) => Promise<Error | ImageModel>
+  text?: (modelId: string) => Promise<Error | LanguageModel>
+  video?: (modelId: string) => Promise<Error | any>
 }
 
 // Vertex is the only provider that uses a prefix (vertex/model-id) in the catalog
@@ -105,10 +115,12 @@ const PROVIDER_SDKS: Record<string, ProviderSdk> = {
   xai: {
     image: async (id) => {
       const xaiProvider = await getXaiProviderInstance()
+      if (xaiProvider instanceof Error) return xaiProvider
       return xaiProvider.image(id)
     },
     video: async (id) => {
       const xaiProvider = await getXaiProviderInstance()
+      if (xaiProvider instanceof Error) return xaiProvider
       return xaiProvider.video(id)
     },
   },
@@ -122,7 +134,7 @@ const PROVIDER_SDKS: Record<string, ProviderSdk> = {
 // OAuth tokens from the Grok Build subscription. OAuth tokens are injected via
 // a custom fetch that replaces the Authorization header on every request.
 
-async function getXaiProviderInstance() {
+async function getXaiProviderInstance(): Promise<Error | ReturnType<Awaited<typeof import('@ai-sdk/xai')>['createXai']>> {
   const { createXai } = await import('@ai-sdk/xai')
 
   // Direct API key path (env or stored)
@@ -135,14 +147,12 @@ async function getXaiProviderInstance() {
   // OAuth path: inject bearer token via custom fetch
   const storedAuth = getXaiAuth()
   if (!storedAuth) {
-    console.error(pc.red('Missing xAI OAuth tokens. Please run `egaki login` and select xAI Grok Build.'))
-    process.exit(1)
+    return new ValidationError('Missing xAI OAuth tokens. Please run `egaki login` and select xAI Grok Build.')
   }
 
   const auth = await getValidXaiAuth(storedAuth, saveXaiAuth)
   if (auth instanceof Error) {
-    console.error(pc.red(auth.message))
-    process.exit(1)
+    return auth
   }
 
   return createXai({
@@ -179,54 +189,29 @@ function hasDirectProviderKey(providerName: string): boolean {
 }
 
 // Check that the provider's API key or OAuth login is available before making API calls.
-// Prints a user-friendly error with instructions on how to configure it.
-export function ensureProviderKey(providerName: string): void {
-  if (hasDirectProviderKey(providerName)) return
+// Returns an Error with a user-friendly message if no key is found.
+export function ensureProviderKey(providerName: string): Error | undefined {
+  if (hasDirectProviderKey(providerName)) return undefined
 
   // Vertex models require a direct key — the upstream Vercel AI Gateway
   // does not support vertex/ routing, so egaki gateway can't proxy them.
   if (providerName === 'vertex') {
-    console.error('')
-    console.error(pc.red(pc.bold('Vertex models require a direct Google Cloud API key')))
-    console.error('')
-    console.error(`  ${pc.cyan('egaki login --provider vertex --key <key>')}`)
-    console.error('')
-    console.error(pc.dim('Get a key at https://console.cloud.google.com/apis/credentials'))
-    console.error(pc.dim('Egaki subscription does not cover Vertex routing yet.'))
-    console.error('')
-    process.exit(1)
+    return new ValidationError(
+      'Vertex models require a direct Google Cloud API key. ' +
+      'Run: egaki login --provider vertex --key <key>. ' +
+      'Get a key at https://console.cloud.google.com/apis/credentials',
+    )
   }
 
-  if (hasEgakiKey()) return
+  if (hasEgakiKey()) return undefined
 
   const info = PROVIDERS[providerName]
-
-  console.error('')
-  console.error(pc.red(pc.bold(`Missing API key for ${info?.label || providerName}`)))
-  console.error('')
-  console.error(`  ${pc.bold('Recommended:')} Use Egaki subscription (all models, one key)`)
-  console.error('')
-  console.error(
-    `    ${pc.cyan('egaki subscribe')}                        get started in 30 seconds`,
-  )
-  console.error('')
-  console.error(`  ${pc.dim('Or configure a provider key directly:')}`)
-  console.error('')
-  console.error(
-    `    ${pc.cyan('egaki login')}                           interactive setup`,
+  const label = info?.label || providerName
+  return new ValidationError(
+    `Missing API key for ${label}. ` +
+    'Use an Egaki subscription (egaki subscribe) or configure a provider key directly (egaki login).' +
+    (info ? ` ${info.hint}` : ''),
   )
-  if (info) {
-    console.error(
-      `    ${pc.cyan(`${info.envVar}=...`)} egaki image ...   inline env var`,
-    )
-    console.error(
-      `    ${pc.cyan(`egaki login --provider ${providerName} --key <key>`)}`,
-    )
-    console.error('')
-    console.error(`  ${pc.dim(info.hint)}`)
-  }
-  console.error('')
-  process.exit(1)
 }
 
 // ─── gateway model factories ─────────────────────────────────────────────────
@@ -335,9 +320,12 @@ function logAuthSource(source: AuthSource): void {
 // Priority for others: direct provider key > egaki gateway > error.
 // Uses PROVIDER_SDKS map for direct provider creation, eliminating switch blocks.
 
-export async function createImageModel(modelId: string): Promise<ImageModel> {
+export async function createImageModel(modelId: string): Promise<Error | ImageModel> {
   const config = getModelConfig(modelId)
-  ensureProviderKey(config.provider)
+  if (config instanceof Error) return config
+
+  const keyError = ensureProviderKey(config.provider)
+  if (keyError) return keyError
 
   const authSource = resolveAuthSource(config.provider)
   logAuthSource(authSource)
@@ -345,31 +333,30 @@ export async function createImageModel(modelId: string): Promise<ImageModel> {
   if (hasDirectProviderKey(config.provider)) {
     const factory = PROVIDER_SDKS[config.provider]?.image
     if (factory) {
-      return factory(modelId)
+      const result = await factory(modelId)
+      if (result instanceof Error) return result
+      return result
     }
-    console.error(
-      pc.red(
-        `Direct image generation is not supported for provider: ${config.provider}.`,
-      ),
-    )
-    process.exit(1)
+    return new ValidationError(`Direct image generation is not supported for provider: ${config.provider}.`)
   }
 
   if (hasEgakiKey()) {
     return createGatewayImageModel(modelId, config.provider)
   }
 
-  console.error(pc.red(`No API key available for provider: ${config.provider}`))
-  process.exit(1)
+  return new ValidationError(`No API key available for provider: ${config.provider}`)
 }
 
-export async function createTextModel(modelId: string): Promise<LanguageModel> {
+export async function createTextModel(modelId: string): Promise<Error | LanguageModel> {
   const config = getModelConfig(modelId)
+  if (config instanceof Error) return config
+
   if (config.strategy !== 'text') {
-    console.error(pc.red(`Model ${modelId} is not a text model`))
-    process.exit(1)
+    return new ValidationError(`Model ${modelId} is not a text model`)
   }
-  ensureProviderKey(config.provider)
+
+  const keyError = ensureProviderKey(config.provider)
+  if (keyError) return keyError
 
   const authSource = resolveAuthSource(config.provider)
   logAuthSource(authSource)
@@ -379,30 +366,26 @@ export async function createTextModel(modelId: string): Promise<LanguageModel> {
     if (factory) {
       return factory(modelId)
     }
-    console.error(
-      pc.red(
-        `Text+image generation is not supported for provider: ${config.provider}`,
-      ),
-    )
-    process.exit(1)
+    return new ValidationError(`Text+image generation is not supported for provider: ${config.provider}`)
   }
 
   if (hasEgakiKey()) {
     return createGatewayTextModel(modelId, config.provider)
   }
 
-  console.error(pc.red(`No API key available for provider: ${config.provider}`))
-  process.exit(1)
+  return new ValidationError(`No API key available for provider: ${config.provider}`)
 }
 
-export async function createVideoModel(modelId: string): Promise<any> {
+export async function createVideoModel(modelId: string): Promise<Error | any> {
   const config = getModelConfig(modelId)
+  if (config instanceof Error) return config
+
   if (config.strategy !== 'video') {
-    console.error(pc.red(`Model ${modelId} is not a video model`))
-    process.exit(1)
+    return new ValidationError(`Model ${modelId} is not a video model`)
   }
 
-  ensureProviderKey(config.provider)
+  const keyError = ensureProviderKey(config.provider)
+  if (keyError) return keyError
 
   const authSource = resolveAuthSource(config.provider)
   logAuthSource(authSource)
@@ -410,20 +393,16 @@ export async function createVideoModel(modelId: string): Promise<any> {
   if (hasDirectProviderKey(config.provider)) {
     const factory = PROVIDER_SDKS[config.provider]?.video
     if (factory) {
-      return factory(modelId)
+      const result = await factory(modelId)
+      if (result instanceof Error) return result
+      return result
     }
-    console.error(
-      pc.red(
-        `Direct video generation is not supported for provider: ${config.provider}. Use an egaki subscription instead.`,
-      ),
-    )
-    process.exit(1)
+    return new ValidationError(`Direct video generation is not supported for provider: ${config.provider}. Use an egaki subscription instead.`)
   }
 
   if (hasEgakiKey()) {
     return createGatewayVideoModel(modelId, config.provider)
   }
 
-  console.error(pc.red(`No API key available for provider: ${config.provider}`))
-  process.exit(1)
+  return new ValidationError(`No API key available for provider: ${config.provider}`)
 }

package/src/cli/openai-speech-provider.ts

@@ -0,0 +1,34 @@
+// OpenAI speech provider for egaki.
+// Wraps the Vercel AI SDK @ai-sdk/openai since OpenAI TTS has no
+// timestamp support. Returns audio only, timestamps are always undefined.
+import {
+  experimental_generateSpeech as aiGenerateSpeech,
+} from 'ai'
+import type { SpeechProvider, SpeechProviderOptions, SpeechProviderResult } from './speech-generate.js'
+
+export function createOpenAISpeechProvider(): SpeechProvider {
+  return {
+    async generate(options: SpeechProviderOptions): Promise<SpeechProviderResult> {
+      const { openai } = await import('@ai-sdk/openai')
+      const model = openai.speech(options.modelId)
+
+      const result = await aiGenerateSpeech({
+        model,
+        text: options.text,
+        ...(options.voice ? { voice: options.voice } : {}),
+        ...(options.outputFormat ? { outputFormat: options.outputFormat } : {}),
+        ...(options.instructions ? { instructions: options.instructions } : {}),
+        ...(options.speed != null ? { speed: options.speed } : {}),
+        ...(options.language ? { language: options.language } : {}),
+        ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
+      })
+
+      return {
+        audio: result.audio.uint8Array,
+        mediaType: result.audio.mediaType || 'audio/mpeg',
+        // OpenAI TTS does not support word timestamps
+        timestamps: undefined,
+      }
+    },
+  }
+}

package/src/cli/separation-generate.ts

@@ -0,0 +1,187 @@
+// Audio separation using fal.ai's Demucs API.
+// Splits audio into stems (vocals, drums, bass, guitar, piano, other).
+// Returns Error | Result (errore style) instead of throwing.
+//
+// Uses @fal-ai/client directly since Demucs is a fal-specific API
+// with no Vercel AI SDK wrapper. Requires FAL_KEY env var or
+// egaki login --provider fal.
+import { fal } from '@fal-ai/client'
+import { injectCredentialsToEnv } from './credentials.js'
+
+// ─── types ──────────────────────────────────────────────────────────────────
+
+export type StemName = 'vocals' | 'drums' | 'bass' | 'other' | 'guitar' | 'piano'
+
+export type DemucsModel =
+  | 'htdemucs'
+  | 'htdemucs_ft'
+  | 'htdemucs_6s'
+  | 'hdemucs_mmi'
+  | 'mdx'
+  | 'mdx_extra'
+  | 'mdx_q'
+  | 'mdx_extra_q'
+
+export interface SeparateAudioOptions {
+  /** Raw audio bytes to separate. */
+  audio: Uint8Array
+  /** Which stems to extract. Default: ['vocals', 'other'] */
+  stems?: StemName[]
+  /** Demucs model variant. Default: 'htdemucs_6s' */
+  model?: DemucsModel
+  /** Output format: 'mp3' or 'wav'. Default: 'mp3' */
+  outputFormat?: 'mp3' | 'wav'
+  /** Number of random shifts for quality (higher = better but slower). Default: 1 */
+  shifts?: number
+  /** Segment overlap 0.0-1.0 (higher = better quality). Default: 0.25 */
+  overlap?: number
+  /** Original filename for display/logging. */
+  filename?: string
+  /** Progress callback for queue updates. */
+  onProgress?: (message: string) => void
+}
+
+export interface StemResult {
+  name: StemName
+  url: string
+  contentType: string
+}
+
+export interface SeparateAudioResult {
+  stems: StemResult[]
+  model: string
+}
+
+// ─── validation ─────────────────────────────────────────────────────────────
+
+const ALL_STEMS: StemName[] = ['vocals', 'drums', 'bass', 'other', 'guitar', 'piano']
+const FOUR_STEM_MODELS: DemucsModel[] = ['htdemucs', 'htdemucs_ft', 'hdemucs_mmi', 'mdx', 'mdx_extra', 'mdx_q', 'mdx_extra_q']
+const SIX_STEM_ONLY: StemName[] = ['guitar', 'piano']
+
+export function validateStems(stems: StemName[], model: DemucsModel): Error | void {
+  for (const s of stems) {
+    if (!ALL_STEMS.includes(s)) {
+      return new Error(`Unknown stem: "${s}". Valid stems: ${ALL_STEMS.join(', ')}`)
+    }
+  }
+  if (FOUR_STEM_MODELS.includes(model)) {
+    const invalid = stems.filter((s) => SIX_STEM_ONLY.includes(s))
+    if (invalid.length > 0) {
+      return new Error(
+        `Stems ${invalid.join(', ')} are only available with htdemucs_6s model. ` +
+        `Current model: ${model}`,
+      )
+    }
+  }
+}
+
+// ─── main function ──────────────────────────────────────────────────────────
+
+export async function separateAudioUncached(
+  opts: SeparateAudioOptions,
+): Promise<Error | SeparateAudioResult> {
+  injectCredentialsToEnv()
+
+  const falKey = process.env['FAL_KEY']
+  if (!falKey) {
+    return new Error(
+      'FAL_KEY not found. Run: egaki login --provider fal\n' +
+      'Get your key at https://fal.ai/dashboard/keys',
+    )
+  }
+
+  fal.config({ credentials: falKey })
+
+  const model: DemucsModel = opts.model ?? 'htdemucs_6s'
+  const stems: StemName[] = opts.stems ?? ['vocals', 'other']
+  const outputFormat = opts.outputFormat ?? 'mp3'
+
+  const validationError = validateStems(stems, model)
+  if (validationError) return validationError
+
+  if (opts.audio.length === 0) {
+    return new Error('No audio data provided')
+  }
+
+  // Upload the audio file to fal storage so the API can access it
+  const file = new File(
+    [Buffer.from(opts.audio)],
+    opts.filename ?? 'audio.mp3',
+    { type: 'audio/mpeg' },
+  )
+
+  opts.onProgress?.('Uploading audio to fal.ai...')
+  let audioUrl: string
+  try {
+    audioUrl = await fal.storage.upload(file)
+  } catch (err) {
+    return new Error(`Failed to upload audio: ${err instanceof Error ? err.message : String(err)}`)
+  }
+  opts.onProgress?.('Audio uploaded. Starting separation...')
+
+  // Call the Demucs API
+  type DemucsOutput = Record<string, { url: string; content_type: string }>
+  let result: { data: DemucsOutput }
+  try {
+    result = await fal.subscribe('fal-ai/demucs', {
+      input: {
+        audio_url: audioUrl,
+        model,
+        stems,
+        shifts: opts.shifts ?? 1,
+        overlap: opts.overlap ?? 0.25,
+        output_format: outputFormat,
+      },
+      logs: true,
+      onQueueUpdate: (update) => {
+        if (update.status === 'IN_PROGRESS') {
+          const u = update as typeof update & { logs?: Array<{ message: string }> }
+          if (u.logs) {
+            for (const log of u.logs) {
+              opts.onProgress?.(log.message)
+            }
+          }
+        }
+      },
+    }) as any
+  } catch (err) {
+    return new Error(`Separation failed: ${err instanceof Error ? err.message : String(err)}`)
+  }
+
+  // Extract the requested stems from the result
+  const resultStems: StemResult[] = []
+  for (const stemName of stems) {
+    const stemData = result.data[stemName]
+    if (stemData?.url) {
+      resultStems.push({
+        name: stemName,
+        url: stemData.url,
+        contentType: stemData.content_type ?? `audio/${outputFormat}`,
+      })
+    }
+  }
+
+  if (resultStems.length === 0) {
+    return new Error('No stems returned from the API. Check model and stem names.')
+  }
+
+  return {
+    stems: resultStems,
+    model,
+  }
+}
+
+// ─── download helper ────────────────────────────────────────────────────────
+
+/** Download a stem from its URL and return the bytes. */
+export async function downloadStem(url: string): Promise<Error | Uint8Array> {
+  try {
+    const response = await fetch(url)
+    if (!response.ok) {
+      return new Error(`Failed to download stem: HTTP ${response.status}`)
+    }
+    return new Uint8Array(await response.arrayBuffer())
+  } catch (err) {
+    return new Error(`Failed to download stem: ${err instanceof Error ? err.message : String(err)}`)
+  }
+}