devglide 0.1.1

package/src/apps/voice/src/index.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { createVoiceMcpServer } from "./mcp.js";
+import { runStdio } from "@devglide/mcp-utils";
+
+// ── Stdio MCP mode ──────────────────────────────────────────────────────────
+if (process.argv.includes("--stdio")) {
+  const mcpServer = createVoiceMcpServer();
+  await runStdio(mcpServer);
+  console.error("Devglide Voice MCP server running on stdio");
+}

package/src/apps/voice/src/mcp.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import { createDevglideMcpServer } from "../../../packages/mcp-utils/src/index.js";
+import { transcribe } from "./transcribe.js";
+import { stats } from "./services/stats.js";
+import { mimeFromFilename } from "./utils/mime.js";
+import { configStore } from "./services/config-store.js";
+
+export function createVoiceMcpServer() {
+  const server = createDevglideMcpServer("devglide-voice", "0.1.0");
+
+  server.tool(
+    "voice_transcribe",
+    "Transcribe audio using the configured speech-to-text provider. Accepts base64-encoded audio data.",
+    {
+      audioBase64: z.string().describe("Base64-encoded audio data"),
+      filename: z
+        .string()
+        .optional()
+        .describe("Original filename with extension (e.g. 'recording.webm')"),
+      language: z
+        .string()
+        .optional()
+        .describe("BCP 47 language hint (e.g. 'en')"),
+    },
+    async ({ audioBase64, filename, language }) => {
+      const startTime = Date.now();
+      try {
+        const name = filename || "audio.webm";
+        const buffer = Buffer.from(audioBase64, "base64");
+        const file = new File([buffer], name, {
+          type: mimeFromFilename(name),
+        });
+
+        const cfg = configStore.get();
+        const lang = language ?? (cfg.language !== "auto" ? cfg.language : undefined);
+        const result = await transcribe(file, { language: lang });
+        const durationSec = (Date.now() - startTime) / 1000;
+        stats.recordSuccess(result.duration ?? durationSec);
+
+        return {
+          content: [
+            { type: "text" as const, text: JSON.stringify(result, null, 2) },
+          ],
+        };
+      } catch (error) {
+        stats.recordError();
+        throw error;
+      }
+    }
+  );
+
+  server.tool(
+    "voice_status",
+    "Check voice service status and transcription statistics",
+    {},
+    async () => {
+      const voiceStats = stats.getStats();
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(voiceStats, null, 2),
+          },
+        ],
+      };
+    }
+  );
+
+  return server;
+}

package/src/apps/voice/src/providers/index.ts

@@ -0,0 +1,85 @@
+import type { ProviderConfig, TranscriptionProvider } from "./types.js";
+import { OpenAICompatibleProvider } from "./openai-compatible.js";
+import { configStore } from "../services/config-store.js";
+
+export type { TranscriptionProvider, ProviderConfig };
+
+interface ProviderMeta {
+  displayName: string;
+  requiresApiKey: boolean;
+  defaultBaseURL?: string;
+  defaultModel: string;
+}
+
+export const PROVIDER_META: Record<string, ProviderMeta> = {
+  openai: {
+    displayName: "OpenAI Whisper",
+    requiresApiKey: true,
+    defaultModel: "whisper-1",
+  },
+  groq: {
+    displayName: "Groq",
+    requiresApiKey: true,
+    defaultBaseURL: "https://api.groq.com/openai/v1",
+    defaultModel: "whisper-large-v3-turbo",
+  },
+  "whisper-cpp": {
+    displayName: "whisper.cpp",
+    requiresApiKey: false,
+    defaultBaseURL: "http://localhost:8080",
+    defaultModel: "default",
+  },
+  "faster-whisper": {
+    displayName: "Faster Whisper",
+    requiresApiKey: false,
+    defaultBaseURL: "http://localhost:8000/v1",
+    defaultModel: "Systran/faster-whisper-small",
+  },
+  vllm: {
+    displayName: "vLLM",
+    requiresApiKey: false,
+    defaultBaseURL: "http://localhost:8000/v1",
+    defaultModel: "default",
+  },
+  "local-ai": {
+    displayName: "LocalAI",
+    requiresApiKey: false,
+    defaultBaseURL: "http://localhost:8080",
+    defaultModel: "whisper-1",
+  },
+};
+
+let cachedProvider: TranscriptionProvider | null = null;
+
+export function invalidateProvider(): void {
+  cachedProvider = null;
+}
+
+function buildConfig(providerName: string): ProviderConfig {
+  const meta = PROVIDER_META[providerName];
+  if (!meta) {
+    throw new Error(
+      `Unknown provider "${providerName}". Supported: ${Object.keys(PROVIDER_META).join(", ")}`
+    );
+  }
+  const settings = configStore.getProviderSettings(providerName);
+  return {
+    name: providerName,
+    displayName: meta.displayName,
+    apiKey: settings.apiKey,
+    baseURL: settings.baseURL ?? meta.defaultBaseURL,
+    model: settings.model || meta.defaultModel,
+    requiresApiKey: meta.requiresApiKey,
+  };
+}
+
+export function getProvider(): TranscriptionProvider {
+  if (cachedProvider) return cachedProvider;
+  const name = configStore.get().provider;
+  cachedProvider = new OpenAICompatibleProvider(buildConfig(name));
+  return cachedProvider;
+}
+
+export function getProviderConfig(): ProviderConfig {
+  return buildConfig(configStore.get().provider);
+}

package/src/apps/voice/src/providers/openai-compatible.ts

@@ -0,0 +1,94 @@
+import type {
+  TranscriptionProvider,
+  ProviderConfig,
+  TranscribeOptions,
+  TranscriptionResult,
+} from "./types.js";
+
+// Cached OpenAI constructor and client instances keyed by config signature
+let _OpenAI: any = null;
+const _clientCache = new Map<string, any>();
+const CLIENT_CACHE_MAX = 8;
+
+function getClientCacheKey(apiKey: string, baseURL?: string): string {
+  return `${apiKey}::${baseURL || ""}`;
+}
+
+export class OpenAICompatibleProvider implements TranscriptionProvider {
+  readonly name: string;
+  readonly displayName: string;
+  readonly requiresApiKey: boolean;
+  private readonly config: ProviderConfig;
+
+  constructor(config: ProviderConfig) {
+    this.config = config;
+    this.name = config.name;
+    this.displayName = config.displayName;
+    this.requiresApiKey = config.requiresApiKey;
+  }
+
+  async transcribe(
+    audio: File,
+    options: TranscribeOptions = {}
+  ): Promise<TranscriptionResult> {
+    if (!_OpenAI) {
+      try {
+        _OpenAI = (await import("openai")).default;
+      } catch {
+        throw new Error(
+          "@devglide/voice server transcription requires the 'openai' package. Install it with: pnpm add openai"
+        );
+      }
+    }
+
+    const apiKey = this.config.apiKey || "not-needed";
+    const cacheKey = getClientCacheKey(apiKey, this.config.baseURL);
+    let client = _clientCache.get(cacheKey);
+    if (!client) {
+      const clientOptions: Record<string, unknown> = { apiKey };
+      if (this.config.baseURL) {
+        clientOptions.baseURL = this.config.baseURL;
+      }
+      client = new _OpenAI(clientOptions);
+      if (_clientCache.size >= CLIENT_CACHE_MAX) {
+        const oldestKey = _clientCache.keys().next().value!;
+        _clientCache.delete(oldestKey);
+      }
+      _clientCache.set(cacheKey, client);
+    }
+
+    let response;
+    try {
+      response = await client.audio.transcriptions.create({
+        file: audio,
+        model: this.config.model,
+        language: options.language,
+        response_format: options.responseFormat || "verbose_json",
+      });
+    } catch (err: unknown) {
+      if (err != null && typeof err === 'object' && 'status' in err && (err as { status: number }).status === 404) {
+        throw new Error(
+          `Model "${this.config.model}" not found on ${this.displayName} (${this.config.baseURL || "api.openai.com"}). Check available models or update the voice config.`
+        );
+      }
+      throw err;
+    }
+
+    if (typeof response === "string") {
+      return { text: response };
+    }
+
+    return {
+      text: response.text,
+      language: response.language,
+      duration: response.duration,
+    };
+  }
+
+  isConfigured(): boolean {
+    if (this.requiresApiKey) {
+      return !!this.config.apiKey;
+    }
+    return !!this.config.baseURL;
+  }
+}

package/src/apps/voice/src/providers/types.ts

@@ -0,0 +1,27 @@
+export interface TranscriptionResult {
+  text: string;
+  language?: string;
+  duration?: number;
+}
+
+export interface TranscribeOptions {
+  language?: string;
+  responseFormat?: "json" | "text" | "verbose_json";
+}
+
+export interface TranscriptionProvider {
+  readonly name: string;
+  readonly displayName: string;
+  readonly requiresApiKey: boolean;
+  transcribe(audio: File, options?: TranscribeOptions): Promise<TranscriptionResult>;
+  isConfigured(): boolean;
+}
+
+export interface ProviderConfig {
+  name: string;
+  displayName: string;
+  apiKey?: string;
+  baseURL?: string;
+  model: string;
+  requiresApiKey: boolean;
+}

package/src/apps/voice/src/routes/config.ts

@@ -0,0 +1,118 @@
+import { Router, type Router as RouterType } from "express";
+import {
+  getProvider,
+  getProviderConfig,
+  invalidateProvider,
+  PROVIDER_META,
+} from "../providers/index.js";
+import { configStore } from "../services/config-store.js";
+import { stats } from "../services/stats.js";
+import { handleTranscribe } from "./transcribe.js";
+
+export const configRouter: RouterType = Router();
+
+configRouter.get("/", (_req, res) => {
+  const cfg = configStore.get();
+  const pc = getProviderConfig();
+  const settings = configStore.getProviderSettings(cfg.provider);
+  res.json({
+    provider: pc.name,
+    displayName: pc.displayName,
+    model: pc.model,
+    baseURL: pc.baseURL ?? null,
+    language: cfg.language,
+    configured: pc.requiresApiKey ? !!pc.apiKey : !!pc.baseURL,
+    requiresApiKey: pc.requiresApiKey,
+    apiKeyMasked: settings.apiKey ? `...${settings.apiKey.slice(-4)}` : null,
+  });
+});
+
+configRouter.get("/providers", (_req, res) => {
+  const cfg = configStore.get();
+  const providers = Object.entries(PROVIDER_META).map(([id, meta]) => {
+    const settings = configStore.getProviderSettings(id);
+    return {
+      id,
+      displayName: meta.displayName,
+      requiresApiKey: meta.requiresApiKey,
+      defaultBaseURL: meta.defaultBaseURL ?? null,
+      defaultModel: meta.defaultModel,
+      currentApiKeyMasked: settings.apiKey ? `...${settings.apiKey.slice(-4)}` : null,
+      currentBaseURL: settings.baseURL ?? null,
+      currentModel: settings.model ?? null,
+    };
+  });
+  res.json({ current: cfg.provider, language: cfg.language, providers });
+});
+
+configRouter.put("/", (req, res) => {
+  const { provider, language, apiKey, baseURL, model } = req.body as Record<
+    string,
+    string | undefined
+  >;
+
+  if (provider && !PROVIDER_META[provider]) {
+    res.status(400).json({ error: `Unknown provider "${provider}"` });
+    return;
+  }
+
+  // Validate language (BCP 47 pattern or "auto")
+  if (language !== undefined) {
+    if (language !== "auto" && !/^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$/.test(language)) {
+      res.status(400).json({ error: `Invalid language value "${language}". Use BCP 47 code (e.g. "en", "en-US") or "auto".` });
+      return;
+    }
+  }
+
+  // Validate model is non-empty if provided
+  if (model !== undefined && typeof model === "string" && model.trim() === "") {
+    res.status(400).json({ error: "Model must be a non-empty string if provided." });
+    return;
+  }
+
+  const targetProvider = provider ?? configStore.get().provider;
+  const patch: Parameters<typeof configStore.update>[0] = {};
+
+  if (provider) patch.provider = provider;
+  if (language) patch.language = language;
+
+  if (apiKey !== undefined || baseURL !== undefined || model !== undefined) {
+    const settings: Record<string, string | undefined> = {};
+    if (apiKey !== undefined) settings.apiKey = apiKey || undefined;
+    if (baseURL !== undefined) settings.baseURL = baseURL || undefined;
+    if (model !== undefined) settings.model = model || undefined;
+    patch.providerName = targetProvider;
+    patch.providerSettings = settings;
+  }
+
+  configStore.update(patch);
+  invalidateProvider();
+
+  const updated = getProviderConfig();
+  res.json({ ok: true, provider: updated.name, model: updated.model, baseURL: updated.baseURL ?? null });
+});
+
+configRouter.post("/test", (_req, res) => {
+  try {
+    const provider = getProvider();
+    if (!provider.isConfigured()) {
+      res.json({ ok: false, reason: "Provider is not configured (missing API key or base URL)" });
+      return;
+    }
+    res.json({ ok: true, provider: provider.name, displayName: provider.displayName });
+  } catch (err) {
+    res.json({ ok: false, reason: err instanceof Error ? err.message : String(err) });
+  }
+});
+
+configRouter.delete("/stats", (_req, res) => {
+  stats.reset();
+  res.json({ ok: true });
+});
+
+// Alias for backwards compatibility — delegates to the canonical /api/transcribe handler
+configRouter.post("/test-transcription", handleTranscribe);
+
+configRouter.get("/stats", (_req, res) => {
+  res.json(stats.getStats());
+});

package/src/apps/voice/src/routes/transcribe.ts

@@ -0,0 +1,90 @@
+import { Router, type Request, type Response } from "express";
+import { getProvider } from "../providers/index.js";
+import { configStore } from "../services/config-store.js";
+import { stats } from "../services/stats.js";
+import { mimeFromFilename } from "../utils/mime.js";
+
+export const transcribeRouter: Router = Router();
+
+export async function handleTranscribe(req: Request, res: Response) {
+  const { audioBase64, filename, language } = req.body as {
+    audioBase64?: string;
+    filename?: string;
+    language?: string;
+  };
+
+  if (!audioBase64 || !filename) {
+    res.status(400).json({ error: "audioBase64 and filename are required" });
+    return;
+  }
+
+  // Reject payloads larger than 25MB of base64 (~18.75MB decoded)
+  if (audioBase64.length > 25 * 1024 * 1024) {
+    res.status(413).json({ error: "audioBase64 exceeds maximum size (25MB)" });
+    return;
+  }
+
+  // Validate base64: check length is valid and content uses only base64 chars.
+  // Use a chunked regex to avoid catastrophic backtracking on large strings.
+  const b64Len = audioBase64.length;
+  if (b64Len % 4 !== 0) {
+    res.status(400).json({ error: "audioBase64 is not valid base64" });
+    return;
+  }
+  const b64ChunkRe = /^[A-Za-z0-9+/]*$/;
+  const CHUNK = 64 * 1024; // validate in 64KB chunks
+  let b64Valid = true;
+  for (let off = 0; off < b64Len; off += CHUNK) {
+    const slice = audioBase64.slice(off, Math.min(off + CHUNK, b64Len));
+    // Allow trailing '=' only in the final chunk
+    if (off + CHUNK >= b64Len) {
+      if (!/^[A-Za-z0-9+/]*={0,2}$/.test(slice)) { b64Valid = false; break; }
+    } else {
+      if (!b64ChunkRe.test(slice)) { b64Valid = false; break; }
+    }
+  }
+  if (!b64Valid) {
+    res.status(400).json({ error: "audioBase64 is not valid base64" });
+    return;
+  }
+
+  // Sanitize filename: strip path components, null bytes, and control characters
+  const sanitizedFilename = filename
+    .replace(/.*[/\\]/, "")           // strip path components
+    .replace(/[\x00-\x1f\x7f]/g, ""); // strip null bytes & control chars
+
+  if (!sanitizedFilename) {
+    res.status(400).json({ error: "filename is invalid after sanitization" });
+    return;
+  }
+
+  const startTime = Date.now();
+
+  try {
+    let buffer: Buffer;
+    try {
+      buffer = Buffer.from(audioBase64, "base64");
+    } catch {
+      res.status(400).json({ error: "audioBase64 could not be decoded" });
+      return;
+    }
+    const file = new File([buffer], sanitizedFilename, {
+      type: mimeFromFilename(sanitizedFilename),
+    });
+    const cfg = configStore.get();
+    const lang =
+      language ?? (cfg.language !== "auto" ? cfg.language : undefined);
+    const provider = getProvider();
+    const result = await provider.transcribe(file, { language: lang });
+    const durationSec = (Date.now() - startTime) / 1000;
+    stats.recordSuccess(result.duration ?? durationSec);
+    res.json({ ok: true, ...result });
+  } catch (err) {
+    stats.recordError();
+    res
+      .status(500)
+      .json({ ok: false, error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+transcribeRouter.post("/", handleTranscribe);

package/src/apps/voice/src/services/config-store.ts

@@ -0,0 +1,129 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import { VOICE_DIR } from "../../../../packages/paths.js";
+
+const DATA_DIR = VOICE_DIR;
+const CONFIG_FILE = join(DATA_DIR, "config.json");
+
+export interface PerProviderConfig {
+  apiKey?: string;
+  baseURL?: string;
+  model?: string;
+}
+
+export interface PersistentConfig {
+  provider: string;
+  language: string;
+  providers: Record<string, PerProviderConfig>;
+}
+
+function loadFile(): Partial<PersistentConfig> {
+  try {
+    if (existsSync(CONFIG_FILE)) {
+      const raw = readFileSync(CONFIG_FILE, "utf-8");
+      try {
+        return JSON.parse(raw) as Partial<PersistentConfig>;
+      } catch (parseErr) {
+        console.error(`[voice] corrupt config file at ${CONFIG_FILE} — ignoring and using defaults. Parse error:`, parseErr);
+        return {};
+      }
+    }
+  } catch (e) {
+    console.error(`[voice] failed to read config file at ${CONFIG_FILE}:`, e);
+  }
+  return {};
+}
+
+function saveFile(config: PersistentConfig): void {
+  mkdirSync(DATA_DIR, { recursive: true, mode: 0o700 });
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 0o600 });
+}
+
+function fromEnv(): PersistentConfig {
+  return {
+    provider: process.env.VOICE_PROVIDER || "openai",
+    language: process.env.WHISPER_LANGUAGE || "auto",
+    providers: {
+      openai: {
+        apiKey: process.env.OPENAI_API_KEY,
+        model: process.env.WHISPER_MODEL || "whisper-1",
+      },
+      groq: {
+        apiKey: process.env.GROQ_API_KEY,
+        baseURL: "https://api.groq.com/openai/v1",
+        model: process.env.GROQ_WHISPER_MODEL || "whisper-large-v3-turbo",
+      },
+      "whisper-cpp": {
+        baseURL: process.env.WHISPER_CPP_URL || "http://localhost:8080",
+        model: process.env.WHISPER_CPP_MODEL || "default",
+      },
+      "faster-whisper": {
+        baseURL: process.env.FASTER_WHISPER_URL || "http://localhost:8000/v1",
+        model: process.env.FASTER_WHISPER_MODEL || "default",
+      },
+      vllm: {
+        baseURL: process.env.VLLM_URL || "http://localhost:8000/v1",
+        model: process.env.VLLM_WHISPER_MODEL || "default",
+      },
+      "local-ai": {
+        baseURL: process.env.LOCAL_AI_URL || "http://localhost:8080",
+        model: process.env.LOCAL_AI_WHISPER_MODEL || "whisper-1",
+      },
+    },
+  };
+}
+
+class ConfigStore {
+  private static _instance: ConfigStore;
+  private config: PersistentConfig;
+
+  private constructor() {
+    const env = fromEnv();
+    const file = loadFile();
+    this.config = {
+      provider: file.provider ?? env.provider,
+      language: file.language ?? env.language,
+      providers: {},
+    };
+    for (const key of Object.keys(env.providers)) {
+      this.config.providers[key] = {
+        ...env.providers[key],
+        ...(file.providers?.[key] ?? {}),
+      };
+    }
+  }
+
+  static getInstance(): ConfigStore {
+    if (!ConfigStore._instance) {
+      ConfigStore._instance = new ConfigStore();
+    }
+    return ConfigStore._instance;
+  }
+
+  get(): PersistentConfig {
+    return structuredClone(this.config);
+  }
+
+  update(patch: {
+    provider?: string;
+    language?: string;
+    providerName?: string;
+    providerSettings?: PerProviderConfig;
+  }): void {
+    if (patch.provider != null) this.config.provider = patch.provider;
+    if (patch.language != null) this.config.language = patch.language;
+    if (patch.providerName && patch.providerSettings) {
+      this.config.providers[patch.providerName] = {
+        ...this.config.providers[patch.providerName],
+        ...patch.providerSettings,
+      };
+    }
+    saveFile(this.config);
+  }
+
+  getProviderSettings(name: string): PerProviderConfig {
+    return this.config.providers[name] ?? {};
+  }
+}
+
+export const configStore = ConfigStore.getInstance();