varg.ai-sdk 0.1.1 → 0.4.0-alpha.1

package/src/core/registry/loader.ts

@@ -0,0 +1,149 @@
+/**
+ * Definition Loader
+ * Auto-loads definitions from the definitions/ directory
+ */
+
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { Definition } from "../schema/types";
+import { registry } from "./registry";
+
+const DEFINITIONS_DIR = join(import.meta.dir, "..", "..", "definitions");
+
+export interface LoaderOptions {
+  /** Additional paths to scan for definitions */
+  additionalPaths?: string[];
+  /** If true, log loading progress */
+  verbose?: boolean;
+}
+
+/**
+ * Load all definitions from the definitions directory
+ */
+export async function loadDefinitions(options?: LoaderOptions): Promise<void> {
+  const { verbose = false } = options ?? {};
+
+  // Load built-in definitions
+  await loadFromDirectory(join(DEFINITIONS_DIR, "models"), verbose);
+  await loadFromDirectory(join(DEFINITIONS_DIR, "actions"), verbose);
+  await loadFromDirectory(join(DEFINITIONS_DIR, "skills"), verbose);
+
+  // Load from additional paths
+  if (options?.additionalPaths) {
+    for (const path of options.additionalPaths) {
+      await loadFromDirectory(path, verbose);
+    }
+  }
+
+  if (verbose) {
+    console.log(`[loader] loaded: ${JSON.stringify(registry.stats)}`);
+  }
+}
+
+/**
+ * Load definitions from a directory
+ */
+async function loadFromDirectory(
+  dirPath: string,
+  verbose: boolean,
+): Promise<void> {
+  try {
+    const entries = await readdir(dirPath, { withFileTypes: true });
+
+    for (const entry of entries) {
+      // Skip non-TypeScript files
+      if (!entry.isFile() || !entry.name.endsWith(".ts")) {
+        continue;
+      }
+
+      // Skip index files
+      if (entry.name === "index.ts") {
+        continue;
+      }
+
+      try {
+        const modulePath = join(dirPath, entry.name);
+        const mod = await import(modulePath);
+
+        // Check for definition export (named 'definition' or default)
+        const definition: Definition | undefined =
+          mod.definition ?? mod.default;
+
+        if (definition && isValidDefinition(definition)) {
+          registry.register(definition);
+          if (verbose) {
+            console.log(
+              `[loader] loaded: ${definition.name} (${definition.type})`,
+            );
+          }
+        }
+
+        // Also check for meta export (backward compatibility with action format)
+        if (mod.meta && isValidDefinition(mod.meta)) {
+          registry.register(mod.meta);
+          if (verbose) {
+            console.log(`[loader] loaded: ${mod.meta.name} (${mod.meta.type})`);
+          }
+        }
+      } catch (error) {
+        if (verbose) {
+          console.warn(
+            `[loader] failed to load ${entry.name}:`,
+            error instanceof Error ? error.message : error,
+          );
+        }
+      }
+    }
+  } catch (error) {
+    // Directory doesn't exist - that's okay
+    if (verbose && (error as NodeJS.ErrnoException).code !== "ENOENT") {
+      console.warn(`[loader] error reading ${dirPath}:`, error);
+    }
+  }
+}
+
+/**
+ * Check if an object is a valid definition
+ */
+function isValidDefinition(obj: unknown): obj is Definition {
+  if (!obj || typeof obj !== "object") return false;
+
+  const def = obj as Record<string, unknown>;
+
+  return (
+    typeof def.type === "string" &&
+    ["model", "action", "skill"].includes(def.type) &&
+    typeof def.name === "string" &&
+    typeof def.description === "string" &&
+    typeof def.schema === "object"
+  );
+}
+
+/**
+ * Load user skills from ~/.varg/skills/
+ */
+export async function loadUserSkills(verbose = false): Promise<void> {
+  const homeDir = process.env.HOME || process.env.USERPROFILE || "";
+  const userSkillsDir = join(homeDir, ".varg", "skills");
+
+  await loadFromDirectory(userSkillsDir, verbose);
+}
+
+/**
+ * Reload all definitions (useful for hot-reloading)
+ */
+export async function reloadDefinitions(
+  options?: LoaderOptions,
+): Promise<void> {
+  // Clear existing definitions (but keep providers)
+  const stats = registry.stats;
+
+  if (options?.verbose) {
+    console.log(
+      `[loader] clearing ${stats.models + stats.actions + stats.skills} definitions...`,
+    );
+  }
+
+  // Re-load everything
+  await loadDefinitions(options);
+}

package/src/core/registry/registry.ts

@@ -0,0 +1,221 @@
+/**
+ * Central Registry
+ * The brain that knows about all models, actions, skills, and providers
+ */
+
+import { getCliSchemaInfo, toJsonSchema } from "../schema/helpers";
+import type {
+  ActionDefinition,
+  Definition,
+  ModelDefinition,
+  Provider,
+  SearchOptions,
+  SkillDefinition,
+} from "../schema/types";
+
+export class Registry {
+  private models = new Map<string, ModelDefinition>();
+  private actions = new Map<string, ActionDefinition>();
+  private skills = new Map<string, SkillDefinition>();
+  private providers = new Map<string, Provider>();
+
+  // ============================================================================
+  // Registration
+  // ============================================================================
+
+  /**
+   * Register a definition (model, action, or skill)
+   */
+  register(definition: Definition): void {
+    switch (definition.type) {
+      case "model":
+        this.models.set(definition.name, definition);
+        break;
+      case "action":
+        this.actions.set(definition.name, definition);
+        break;
+      case "skill":
+        this.skills.set(definition.name, definition);
+        break;
+    }
+  }
+
+  /**
+   * Register a provider
+   */
+  registerProvider(provider: Provider): void {
+    this.providers.set(provider.name, provider);
+  }
+
+  /**
+   * Unregister a definition by name
+   */
+  unregister(name: string): boolean {
+    return (
+      this.models.delete(name) ||
+      this.actions.delete(name) ||
+      this.skills.delete(name)
+    );
+  }
+
+  // ============================================================================
+  // Resolution
+  // ============================================================================
+
+  /**
+   * Resolve a name to its definition
+   * Resolution order: models -> actions -> skills
+   */
+
+  resolve(name: string): Definition | null {
+    // Handle explicit namespace prefixes
+    if (name.startsWith("model/")) {
+      return this.models.get(name.slice(6)) ?? null;
+    }
+    if (name.startsWith("action/")) {
+      return this.actions.get(name.slice(7)) ?? null;
+    }
+    if (name.startsWith("skill/")) {
+      return this.skills.get(name.slice(6)) ?? null;
+    }
+
+    // Try each type in order
+    return (
+      this.models.get(name) ??
+      this.actions.get(name) ??
+      this.skills.get(name) ??
+      null
+    );
+  }
+
+  /**
+   * Get a provider by name
+   */
+  getProvider(name: string): Provider | undefined {
+    return this.providers.get(name);
+  }
+
+  /**
+   * Check if a name exists
+   */
+  has(name: string): boolean {
+    return this.resolve(name) !== null;
+  }
+
+  // ============================================================================
+  // Search
+  // ============================================================================
+
+  /**
+   * Search definitions by query string
+   */
+  search(query: string, options?: SearchOptions): Definition[] {
+    const q = query.toLowerCase();
+    const results: Definition[] = [];
+
+    // Get all definitions based on type filter
+    const definitions = this.list(options?.type);
+
+    for (const def of definitions) {
+      // Match by name or description
+      if (
+        def.name.toLowerCase().includes(q) ||
+        def.description.toLowerCase().includes(q)
+      ) {
+        results.push(def);
+        continue;
+      }
+
+      // Match by input/output type (from schema)
+      const inputSchema = getCliSchemaInfo(def.schema.input);
+      const outputSchema = toJsonSchema(def.schema.output);
+      const inputType = inputSchema.properties?.type?.type ?? "";
+      const outputType = outputSchema.type ?? "";
+
+      if (
+        options?.inputType &&
+        inputType.toLowerCase().includes(options.inputType.toLowerCase())
+      ) {
+        results.push(def);
+        continue;
+      }
+
+      if (
+        options?.outputType &&
+        outputType.toLowerCase().includes(options.outputType.toLowerCase())
+      ) {
+        results.push(def);
+        continue;
+      }
+
+      // Match by provider (for models)
+      if (
+        options?.provider &&
+        def.type === "model" &&
+        (def as ModelDefinition).providers.includes(options.provider)
+      ) {
+        results.push(def);
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * List all definitions, optionally filtered by type
+   */
+  list(type?: "model" | "action" | "skill"): Definition[] {
+    const results: Definition[] = [];
+
+    if (!type || type === "model") {
+      results.push(...this.models.values());
+    }
+    if (!type || type === "action") {
+      results.push(...this.actions.values());
+    }
+    if (!type || type === "skill") {
+      results.push(...this.skills.values());
+    }
+
+    return results;
+  }
+
+  /**
+   * List all providers
+   */
+  listProviders(): Provider[] {
+    return Array.from(this.providers.values());
+  }
+
+  // ============================================================================
+  // Getters
+  // ============================================================================
+
+  getModel(name: string): ModelDefinition | undefined {
+    return this.models.get(name);
+  }
+
+  getAction(name: string): ActionDefinition | undefined {
+    return this.actions.get(name);
+  }
+
+  getSkill(name: string): SkillDefinition | undefined {
+    return this.skills.get(name);
+  }
+
+  // ============================================================================
+  // Stats
+  // ============================================================================
+
+  get stats() {
+    return {
+      models: this.models.size,
+      actions: this.actions.size,
+      skills: this.skills.size,
+      providers: this.providers.size,
+    };
+  }
+}
+
+// Global registry instance
+export const registry = new Registry();

package/src/core/registry/resolver.ts

@@ -0,0 +1,206 @@
+/**
+ * Name Resolution Logic
+ * Handles smart resolution of names to definitions with fuzzy matching
+ */
+
+import type { Definition, SearchOptions } from "../schema/types";
+import { registry } from "./registry";
+
+export interface ResolveOptions {
+  /** If true, throw an error if not found */
+  required?: boolean;
+  /** Preferred type to resolve to */
+  preferType?: "model" | "action" | "skill";
+  /** If true, allow fuzzy matching */
+  fuzzy?: boolean;
+}
+
+export interface ResolveResult {
+  definition: Definition | null;
+  matchType: "exact" | "namespace" | "fuzzy" | "alias" | null;
+  suggestions?: string[];
+}
+
+// Common aliases for actions/models
+const ALIASES: Record<string, string> = {
+  // Video generation
+  i2v: "image-to-video",
+  t2v: "text-to-video",
+  img2vid: "image-to-video",
+  txt2vid: "text-to-video",
+
+  // Image generation
+  i2i: "image-to-image",
+  t2i: "text-to-image",
+  img2img: "image-to-image",
+  txt2img: "text-to-image",
+
+  // Voice/Audio
+  tts: "text-to-speech",
+  stt: "speech-to-text",
+  voice: "text-to-speech",
+
+  // Video editing
+  concat: "merge",
+  join: "merge",
+  combine: "merge",
+  crop: "trim",
+  clip: "trim",
+};
+
+/**
+ * Resolve a name to a definition with smart matching
+ */
+export function resolve(name: string, options?: ResolveOptions): ResolveResult {
+  // 1. Check direct/exact match
+  const exact = registry.resolve(name);
+  if (exact) {
+    return { definition: exact, matchType: "exact" };
+  }
+
+  // 2. Check aliases
+  const aliasTarget = ALIASES[name.toLowerCase()];
+  if (aliasTarget) {
+    const aliased = registry.resolve(aliasTarget);
+    if (aliased) {
+      return { definition: aliased, matchType: "alias" };
+    }
+  }
+
+  // 3. Try with namespace prefix if preferType is set
+  if (options?.preferType) {
+    const namespaced = registry.resolve(`${options.preferType}/${name}`);
+    if (namespaced) {
+      return { definition: namespaced, matchType: "namespace" };
+    }
+  }
+
+  // 4. Fuzzy matching if enabled
+  if (options?.fuzzy) {
+    const suggestions = findSimilar(name);
+    const firstSuggestion = suggestions[0];
+    if (firstSuggestion) {
+      const topMatch = registry.resolve(firstSuggestion);
+      if (topMatch) {
+        return {
+          definition: topMatch,
+          matchType: "fuzzy",
+          suggestions,
+        };
+      }
+    }
+  }
+
+  // 5. Not found
+  if (options?.required) {
+    const suggestions = findSimilar(name);
+    const suggestionText =
+      suggestions.length > 0
+        ? ` Did you mean: ${suggestions.slice(0, 3).join(", ")}?`
+        : "";
+    throw new Error(`Definition not found: "${name}".${suggestionText}`);
+  }
+
+  return {
+    definition: null,
+    matchType: null,
+    suggestions: findSimilar(name),
+  };
+}
+
+/**
+ * Find similar names using Levenshtein distance
+ */
+export function findSimilar(query: string, limit = 5): string[] {
+  const q = query.toLowerCase();
+  const all = registry.list();
+
+  const scored = all.map((def) => ({
+    name: def.name,
+    score: similarity(q, def.name.toLowerCase()),
+  }));
+
+  // Sort by similarity score (higher is better)
+  scored.sort((a, b) => b.score - a.score);
+
+  // Return top matches with reasonable similarity
+  return scored
+    .filter((s) => s.score > 0.3)
+    .slice(0, limit)
+    .map((s) => s.name);
+}
+
+/**
+ * Simple similarity score based on common substrings and Levenshtein
+ */
+function similarity(a: string, b: string): number {
+  // Exact match
+  if (a === b) return 1;
+
+  // Prefix match
+  if (b.startsWith(a) || a.startsWith(b)) return 0.9;
+
+  // Contains match
+  if (b.includes(a) || a.includes(b)) return 0.7;
+
+  // Levenshtein-based similarity
+  const distance = levenshteinDistance(a, b);
+  const maxLen = Math.max(a.length, b.length);
+  return 1 - distance / maxLen;
+}
+
+/**
+ * Calculate Levenshtein edit distance
+ */
+function levenshteinDistance(a: string, b: string): number {
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+
+  // Create matrix with proper initialization
+  const matrix: number[][] = Array.from({ length: b.length + 1 }, (_, i) =>
+    Array.from({ length: a.length + 1 }, (_, j) =>
+      i === 0 ? j : j === 0 ? i : 0,
+    ),
+  );
+
+  // Fill matrix
+  for (let i = 1; i <= b.length; i++) {
+    for (let j = 1; j <= a.length; j++) {
+      const prevRow = matrix[i - 1];
+      const currRow = matrix[i];
+      if (!prevRow || !currRow) continue;
+
+      if (b[i - 1] === a[j - 1]) {
+        currRow[j] = prevRow[j - 1] ?? 0;
+      } else {
+        currRow[j] = Math.min(
+          (prevRow[j - 1] ?? 0) + 1, // substitution
+          (currRow[j - 1] ?? 0) + 1, // insertion
+          (prevRow[j] ?? 0) + 1, // deletion
+        );
+      }
+    }
+  }
+
+  return matrix[b.length]?.[a.length] ?? Math.max(a.length, b.length);
+}
+
+/**
+ * Search with filters
+ */
+export function search(query: string, options?: SearchOptions): Definition[] {
+  return registry.search(query, options);
+}
+
+/**
+ * Get suggestions for partial input (autocomplete)
+ */
+export function suggest(partial: string, limit = 10): string[] {
+  const p = partial.toLowerCase();
+  const all = registry.list();
+
+  return all
+    .filter((def) => def.name.toLowerCase().startsWith(p))
+    .slice(0, limit)
+    .map((def) => def.name);
+}

package/src/core/schema/helpers.ts

@@ -0,0 +1,134 @@
+/**
+ * Schema helpers for CLI introspection
+ * Uses Zod v4's native toJSONSchema() method
+ */
+
+import type { JsonSchema, SchemaProperty } from "./types";
+
+/**
+ * Convert a Zod schema to JSON Schema format
+ * Uses Zod v4's native toJSONSchema() method
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Zod v4 type compatibility
+export function toJsonSchema(schema: any): JsonSchema {
+  // Zod v4 has native toJSONSchema() method
+  if (typeof schema.toJSONSchema === "function") {
+    try {
+      return schema.toJSONSchema() as JsonSchema;
+    } catch {
+      // Some Zod types (transforms, custom) can't be represented in JSON Schema
+      // Return a basic schema with description if available
+      return {
+        type: "object",
+        description: schema._def?.description,
+      } as JsonSchema;
+    }
+  }
+  // Fallback for older Zod versions or non-Zod schemas
+  return schema as JsonSchema;
+}
+
+/**
+ * Get CLI-friendly schema info for displaying help
+ * Returns properties and required fields in JSON Schema format
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Zod v4 type compatibility
+export function getCliSchemaInfo(schema: any): {
+  properties: Record<string, SchemaProperty>;
+  required: string[];
+} {
+  const jsonSchema = toJsonSchema(schema);
+
+  return {
+    properties: (jsonSchema.properties || {}) as Record<string, SchemaProperty>,
+    required: jsonSchema.required || [],
+  };
+}
+
+/**
+ * Generate CLI help text from a Zod schema
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Zod v4 type compatibility
+export function schemaToCliHelp(schema: any): string {
+  const { properties, required } = getCliSchemaInfo(schema);
+  const lines: string[] = [];
+
+  for (const [key, prop] of Object.entries(properties)) {
+    const isRequired = required.includes(key);
+    const parts: string[] = [`--${key.padEnd(15)}`];
+
+    if (prop.description) {
+      parts.push(prop.description);
+    }
+
+    if (isRequired) {
+      parts.push("(required)");
+    }
+
+    if (prop.default !== undefined) {
+      parts.push(`[default: ${JSON.stringify(prop.default)}]`);
+    }
+
+    if (prop.enum && prop.enum.length > 0) {
+      parts.push(`[${prop.enum.join(", ")}]`);
+    }
+
+    lines.push(parts.join(" "));
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Coerce a CLI string value to the proper type based on JSON Schema property
+ */
+export function coerceCliValue(value: string, prop: SchemaProperty): unknown {
+  switch (prop.type) {
+    case "number":
+    case "integer":
+      return Number(value);
+    case "boolean":
+      return value === "true" || value === "1";
+    case "array":
+      // Handle comma-separated values
+      return value.split(",").map((v) => v.trim());
+    default:
+      return value;
+  }
+}
+
+/**
+ * Parse CLI arguments into an object based on schema
+ */
+export function parseCliArgs(
+  args: string[],
+  // biome-ignore lint/suspicious/noExplicitAny: Zod v4 type compatibility
+  schema: any,
+): Record<string, unknown> {
+  const { properties } = getCliSchemaInfo(schema);
+  const result: Record<string, unknown> = {};
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg?.startsWith("--")) continue;
+
+    const key = arg.slice(2);
+    const prop = properties[key];
+
+    if (!prop) continue;
+
+    // Boolean flags don't require a value
+    if (prop.type === "boolean") {
+      result[key] = true;
+      continue;
+    }
+
+    // Get the value
+    const value = args[++i];
+    if (value && !value.startsWith("--")) {
+      result[key] = coerceCliValue(value, prop);
+    }
+  }
+
+  return result;
+}

package/src/core/schema/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Schema module exports
+ */
+
+export * from "./helpers";
+export * from "./shared";
+export * from "./types";
+export * from "./validator";