varg.ai-sdk 0.1.0 → 0.1.1

package/cli/commands/run.ts

@@ -0,0 +1,237 @@
+/**
+ * varg run command
+ * execute actions by scanning filesystem
+ */
+
+import { existsSync } from "node:fs";
+import { defineCommand } from "citty";
+import { resolve } from "../discover";
+import type { Meta } from "../types";
+import { box, c, runningBox } from "../ui";
+
+interface RunOptions {
+  [key: string]: string | boolean | undefined;
+  info?: boolean;
+  schema?: boolean;
+  json?: boolean;
+  quiet?: boolean;
+}
+
+function parseArgs(args: string[]): { target: string; options: RunOptions } {
+  const options: RunOptions = {};
+  let target = "";
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg) continue;
+
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      if (
+        key === "info" ||
+        key === "schema" ||
+        key === "json" ||
+        key === "quiet"
+      ) {
+        options[key] = true;
+      } else {
+        const value = args[++i];
+        if (value) options[key] = value;
+      }
+    } else if (!target) {
+      target = arg;
+    } else {
+      // positional args - check if it looks like a file
+      if (existsSync(arg) || arg.startsWith("./") || arg.startsWith("/")) {
+        if (!options.image && !options.audio) {
+          options.image = arg;
+        }
+      } else if (!options.prompt && !options.text) {
+        options.prompt = arg;
+      }
+    }
+  }
+
+  return { target, options };
+}
+
+function showHelp(item: Meta) {
+  const content: string[] = [];
+  content.push("");
+  content.push(`  ${item.description}`);
+  content.push("");
+  content.push(c.bold(c.dim("  USAGE")));
+  content.push("");
+
+  const required = item.schema.input.required;
+  const reqArgs = required.map((r) => `--${r} <${r}>`).join(" ");
+  content.push(`    varg run ${item.name} ${reqArgs} [options]`);
+
+  content.push("");
+  content.push(c.bold(c.dim("  OPTIONS")));
+  content.push("");
+
+  for (const [key, prop] of Object.entries(item.schema.input.properties)) {
+    const req = item.schema.input.required.includes(key);
+    const reqTag = req ? c.yellow(" (required)") : "";
+    const defaultVal =
+      prop.default !== undefined ? c.dim(` default: ${prop.default}`) : "";
+    const enumVals = prop.enum ? c.dim(` [${prop.enum.join(", ")}]`) : "";
+
+    content.push(
+      `    --${key.padEnd(12)}${prop.description}${reqTag}${defaultVal}${enumVals}`,
+    );
+  }
+
+  content.push("");
+  content.push(`    --json          output result as json`);
+  content.push(`    --quiet         minimal output`);
+  content.push(`    --info          show this help`);
+  content.push("");
+
+  console.log(box(`action: ${item.name}`, content));
+}
+
+function showSchema(item: Meta) {
+  const schema = {
+    name: item.name,
+    type: item.type,
+    description: item.description,
+    input: item.schema.input,
+    output: item.schema.output,
+  };
+
+  console.log(JSON.stringify(schema, null, 2));
+}
+
+export const runCmd = defineCommand({
+  meta: {
+    name: "run",
+    description: "run a model or action",
+  },
+  args: {
+    target: {
+      type: "positional",
+      description: "action to run",
+      required: false,
+    },
+    info: {
+      type: "boolean",
+      description: "show action info",
+    },
+    schema: {
+      type: "boolean",
+      description: "show action schema as json",
+    },
+    json: {
+      type: "boolean",
+      description: "output result as json",
+    },
+    quiet: {
+      type: "boolean",
+      description: "minimal output",
+    },
+  },
+  async run({ rawArgs }) {
+    // use rawArgs for dynamic action options
+    const { target, options } = parseArgs(rawArgs);
+
+    if (!target) {
+      console.error(`${c.red("error:")} target required`);
+      console.log(`\nusage: ${c.cyan("varg run <action> [options]")}`);
+      console.log(`\nrun ${c.cyan("varg list")} to see available actions`);
+      process.exit(1);
+    }
+
+    const item = await resolve(target);
+
+    if (!item) {
+      console.error(`${c.red("error:")} '${target}' not found`);
+      console.log(`\nrun ${c.cyan("varg list")} to see available actions`);
+      process.exit(1);
+    }
+
+    if (options.info) {
+      showHelp(item);
+      return;
+    }
+
+    if (options.schema) {
+      showSchema(item);
+      return;
+    }
+
+    // validate required args
+    for (const req of item.schema.input.required) {
+      if (!options[req]) {
+        console.error(`${c.red("error:")} --${req} is required`);
+        console.log(`\nrun ${c.cyan(`varg run ${target} --info`)} for usage`);
+        process.exit(1);
+      }
+    }
+
+    // build params for display
+    const params: Record<string, string> = {};
+    for (const key of Object.keys(item.schema.input.properties)) {
+      if (options[key] && typeof options[key] === "string") {
+        params[key] = options[key] as string;
+      }
+    }
+
+    if (!options.quiet && !options.json) {
+      console.log(runningBox(target, params, "running"));
+    }
+
+    const startTime = Date.now();
+
+    try {
+      const result = await item.run(options);
+      const elapsed = Date.now() - startTime;
+
+      if (options.json) {
+        console.log(JSON.stringify({ success: true, result, time: elapsed }));
+      } else if (options.quiet) {
+        console.log(JSON.stringify(result));
+      } else {
+        // extract url from result if present
+        const resultObj = result as Record<string, unknown> | null;
+        const url =
+          resultObj?.imageUrl || resultObj?.videoUrl || resultObj?.url || null;
+
+        console.log("\x1b[2J\x1b[H");
+        console.log(
+          runningBox(target, params, "done", {
+            output: url ? "saved" : "done",
+            time: elapsed,
+          }),
+        );
+
+        // print url outside box so it's clickable
+        if (url) {
+          console.log(`\n  ${c.cyan("url")}  ${url}\n`);
+        }
+      }
+    } catch (err) {
+      const elapsed = Date.now() - startTime;
+      const errorMsg = err instanceof Error ? err.message : String(err);
+
+      if (options.json) {
+        console.log(
+          JSON.stringify({ success: false, error: errorMsg, time: elapsed }),
+        );
+      } else if (options.quiet) {
+        console.error(errorMsg);
+      } else {
+        console.log("\x1b[2J\x1b[H");
+        console.log(
+          runningBox(target, params, "error", {
+            error: errorMsg,
+            time: elapsed,
+          }),
+        );
+      }
+
+      process.exit(1);
+    }
+  },
+});

package/cli/commands/which.ts

@@ -0,0 +1,66 @@
+/**
+ * varg which command
+ * inspect an action by scanning filesystem
+ */
+
+import { defineCommand } from "citty";
+import { resolve } from "../discover";
+import { box, c, header, separator } from "../ui";
+
+export const whichCmd = defineCommand({
+  meta: {
+    name: "which",
+    description: "inspect what's behind an action",
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "action name",
+      required: true,
+    },
+  },
+  async run({ args }) {
+    const name = args.name;
+
+    if (!name) {
+      console.error(`${c.red("error:")} action name required`);
+      console.log(`\nusage: ${c.cyan("varg which <name>")}`);
+      process.exit(1);
+    }
+
+    const item = await resolve(name);
+
+    if (!item) {
+      console.error(`${c.red("error:")} '${name}' not found`);
+      console.log(`\nrun ${c.cyan("varg list")} to see available actions`);
+      process.exit(1);
+    }
+
+    const content: string[] = [];
+    content.push("");
+    content.push(`  ${item.description}`);
+    content.push("");
+
+    content.push(header("SCHEMA"));
+    content.push("");
+
+    for (const [key, prop] of Object.entries(item.schema.input.properties)) {
+      const required = item.schema.input.required.includes(key);
+      const reqTag = required ? c.yellow("*") : " ";
+      const defaultVal = prop.default
+        ? c.dim(` (default: ${prop.default})`)
+        : "";
+      content.push(
+        `  ${reqTag}${c.cyan(key.padEnd(12))}${prop.description}${defaultVal}`,
+      );
+    }
+
+    content.push("");
+    content.push(separator());
+    content.push("");
+    content.push(`  run ${c.cyan(`varg run ${name} --info`)} for full options`);
+    content.push("");
+
+    console.log(box(`action: ${name}`, content));
+  },
+});

package/cli/discover.ts

@@ -0,0 +1,66 @@
+/**
+ * filesystem-based discovery for varg cli
+ * scans action/ directory for modules with meta exports
+ */
+
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { ActionMeta, Meta } from "./types";
+
+const ACTION_DIR = join(import.meta.dir, "..", "action");
+
+let cachedActions: ActionMeta[] | null = null;
+
+export async function discoverActions(): Promise<ActionMeta[]> {
+  if (cachedActions) return cachedActions;
+
+  const actions: ActionMeta[] = [];
+  const dirs = await readdir(ACTION_DIR);
+
+  for (const dir of dirs) {
+    try {
+      const mod = await import(`../action/${dir}`);
+      if (mod.meta && mod.meta.type === "action") {
+        actions.push(mod.meta);
+      }
+    } catch {
+      // skip directories without valid modules
+    }
+  }
+
+  cachedActions = actions;
+  return actions;
+}
+
+export async function resolve(name: string): Promise<Meta | null> {
+  const actions = await discoverActions();
+
+  // check explicit namespace
+  if (name.startsWith("action/")) {
+    const actionName = name.slice(7);
+    return actions.find((a) => a.name === actionName) || null;
+  }
+
+  // check actions
+  const action = actions.find((a) => a.name === name);
+  if (action) return action;
+
+  return null;
+}
+
+export async function search(query: string): Promise<Meta[]> {
+  const actions = await discoverActions();
+  const q = query.toLowerCase();
+
+  return actions.filter(
+    (a) =>
+      a.name.toLowerCase().includes(q) ||
+      a.description.toLowerCase().includes(q) ||
+      a.inputType.toLowerCase().includes(q) ||
+      a.outputType.toLowerCase().includes(q),
+  );
+}
+
+export async function list(): Promise<Meta[]> {
+  return discoverActions();
+}

package/cli/index.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env bun
+
+/**
+ * varg cli
+ * ai video infrastructure from your terminal
+ */
+
+import { defineCommand, runMain } from "citty";
+import { findCmd } from "./commands/find";
+import { helpCmd } from "./commands/help";
+import { listCmd } from "./commands/list";
+import { runCmd } from "./commands/run";
+import { whichCmd } from "./commands/which";
+
+const main = defineCommand({
+  meta: {
+    name: "varg",
+    version: "0.1.0",
+    description: "ai video infrastructure from your terminal",
+  },
+  subCommands: {
+    run: runCmd,
+    list: listCmd,
+    ls: listCmd,
+    find: findCmd,
+    search: findCmd,
+    which: whichCmd,
+    inspect: whichCmd,
+    help: helpCmd,
+  },
+});
+
+runMain(main);

package/cli/runner.ts

@@ -0,0 +1,65 @@
+/**
+ * shared cli runner for actions
+ * parses args and calls meta.run()
+ */
+
+import type { Meta } from "./types";
+
+export async function runCli(meta: Meta) {
+  const args = process.argv.slice(2);
+
+  if (args[0] === "help" || args[0] === "--help" || args.length === 0) {
+    console.log(`
+${meta.name} - ${meta.description}
+
+usage:
+  bun run action/${meta.name} [options]
+
+options:`);
+
+    for (const [key, prop] of Object.entries(meta.schema.input.properties)) {
+      const req = meta.schema.input.required.includes(key) ? " (required)" : "";
+      const def =
+        prop.default !== undefined ? ` [default: ${prop.default}]` : "";
+      console.log(`  --${key.padEnd(14)} ${prop.description}${req}${def}`);
+    }
+
+    console.log(`
+examples:
+  bun run action/${meta.name} --${meta.schema.input.required[0]} "value"
+`);
+    return;
+  }
+
+  // parse args
+  const options: Record<string, unknown> = {};
+  const firstRequired = meta.schema.input.required[0];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg?.startsWith("--")) {
+      const key = arg.slice(2);
+      const value = args[++i];
+      options[key] = value;
+    } else if (arg && firstRequired && !options[firstRequired]) {
+      // first positional arg goes to first required field
+      options[firstRequired] = arg;
+    }
+  }
+
+  // validate required
+  for (const req of meta.schema.input.required) {
+    if (!options[req]) {
+      console.error(`error: --${req} is required`);
+      process.exit(1);
+    }
+  }
+
+  try {
+    const result = await meta.run(options);
+    console.log(JSON.stringify(result, null, 2));
+  } catch (err) {
+    console.error(`error: ${err instanceof Error ? err.message : err}`);
+    process.exit(1);
+  }
+}

package/cli/types.ts

@@ -0,0 +1,49 @@
+/**
+ * shared types for varg cli
+ * actions and models export meta objects conforming to these types
+ */
+
+export interface SchemaProperty {
+  type: string;
+  description: string;
+  enum?: (string | number)[];
+  default?: unknown;
+  format?: string;
+}
+
+export interface Schema {
+  input: {
+    type: "object";
+    required: string[];
+    properties: Record<string, SchemaProperty>;
+  };
+  output: {
+    type: string;
+    format?: string;
+    description: string;
+  };
+}
+
+export interface ActionMeta {
+  name: string;
+  type: "action";
+  description: string;
+  inputType: string;
+  outputType: string;
+  schema: Schema;
+  run: (options: Record<string, unknown>) => Promise<unknown>;
+}
+
+export interface ModelMeta {
+  name: string;
+  type: "model";
+  description: string;
+  inputType: string;
+  outputType: string;
+  providers: string[];
+  defaultProvider: string;
+  schema: Schema;
+  run: (options: Record<string, unknown>) => Promise<unknown>;
+}
+
+export type Meta = ActionMeta | ModelMeta;

package/cli/ui.ts

@@ -0,0 +1,185 @@
+/**
+ * terminal ui helpers for varg cli
+ * beautiful boxes and formatting
+ */
+
+const COLORS = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  magenta: "\x1b[35m",
+  cyan: "\x1b[36m",
+  red: "\x1b[31m",
+  gray: "\x1b[90m",
+};
+
+export const c = {
+  reset: (s: string) => `${COLORS.reset}${s}${COLORS.reset}`,
+  bold: (s: string) => `${COLORS.bold}${s}${COLORS.reset}`,
+  dim: (s: string) => `${COLORS.dim}${s}${COLORS.reset}`,
+  green: (s: string) => `${COLORS.green}${s}${COLORS.reset}`,
+  yellow: (s: string) => `${COLORS.yellow}${s}${COLORS.reset}`,
+  blue: (s: string) => `${COLORS.blue}${s}${COLORS.reset}`,
+  magenta: (s: string) => `${COLORS.magenta}${s}${COLORS.reset}`,
+  cyan: (s: string) => `${COLORS.cyan}${s}${COLORS.reset}`,
+  red: (s: string) => `${COLORS.red}${s}${COLORS.reset}`,
+  gray: (s: string) => `${COLORS.gray}${s}${COLORS.reset}`,
+};
+
+// strip ansi codes for length calculation
+// biome-ignore lint/complexity/useRegexLiterals: literal triggers noControlCharactersInRegex
+const ANSI_REGEX = new RegExp("\x1b\\[[0-9;]*m", "g");
+function stripAnsi(s: string): string {
+  return s.replace(ANSI_REGEX, "");
+}
+
+// box drawing characters
+const BOX = {
+  topLeft: "┌",
+  topRight: "┐",
+  bottomLeft: "└",
+  bottomRight: "┘",
+  horizontal: "─",
+  vertical: "│",
+  line: "─",
+};
+
+export const WIDTH = 71;
+
+export function box(title: string, content: string[]): string {
+  const lines: string[] = [];
+
+  // top border with title
+  const titlePart = title ? `${BOX.line} ${title} ` : "";
+  const remainingWidth = WIDTH - 2 - stripAnsi(titlePart).length;
+  lines.push(
+    `${BOX.topLeft}${titlePart}${BOX.horizontal.repeat(remainingWidth)}${BOX.topRight}`,
+  );
+
+  // content lines
+  for (const line of content) {
+    const stripped = stripAnsi(line);
+    const padding = WIDTH - 2 - stripped.length;
+    if (padding >= 0) {
+      lines.push(`${BOX.vertical}${line}${" ".repeat(padding)}${BOX.vertical}`);
+    } else {
+      // truncate if too long
+      lines.push(
+        `${BOX.vertical}${line.slice(0, WIDTH - 5)}...${BOX.vertical}`,
+      );
+    }
+  }
+
+  // bottom border
+  lines.push(
+    `${BOX.bottomLeft}${BOX.horizontal.repeat(WIDTH - 2)}${BOX.bottomRight}`,
+  );
+
+  return lines.join("\n");
+}
+
+export function separator(): string {
+  return `  ${c.dim(BOX.horizontal.repeat(WIDTH - 4))}`;
+}
+
+export function header(text: string): string {
+  return c.bold(c.dim(`  ${text}`));
+}
+
+export function row(label: string, value: string, indent = 2): string {
+  const spaces = " ".repeat(indent);
+  const labelWidth = 14;
+  const paddedLabel = label.padEnd(labelWidth);
+  return `${spaces}${c.dim(paddedLabel)}${value}`;
+}
+
+export function success(message: string): string {
+  return `  ${c.green("✓")} ${message}`;
+}
+
+export function error(message: string): string {
+  return `  ${c.red("✗")} ${message}`;
+}
+
+export function spinner(message: string): string {
+  return `  ${c.cyan("◐")} ${message}`;
+}
+
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  const s = Math.round(ms / 1000);
+  return `${s}s`;
+}
+
+export function formatCost(dollars: number): string {
+  return `$${dollars.toFixed(3)}`;
+}
+
+// table formatting for list command
+export interface TableRow {
+  name: string;
+  description: string;
+  providers?: string;
+}
+
+export function table(rows: TableRow[], nameWidth = 16): string[] {
+  const lines: string[] = [];
+
+  for (const row of rows) {
+    const name = row.name.padEnd(nameWidth);
+    const desc = row.description;
+    const providers = row.providers ? c.dim(row.providers) : "";
+
+    if (providers) {
+      lines.push(`  ${c.cyan(name)}${desc.padEnd(30)}${providers}`);
+    } else {
+      lines.push(`  ${c.cyan(name)}${desc}`);
+    }
+  }
+
+  return lines;
+}
+
+// progress output for running commands
+export function runningBox(
+  name: string,
+  params: Record<string, string>,
+  status: "running" | "done" | "error",
+  result?: { output?: string; cost?: number; error?: string; time?: number },
+): string {
+  const content: string[] = [""];
+
+  // params
+  for (const [key, value] of Object.entries(params)) {
+    const displayValue =
+      value.length > 40 ? `"${value.slice(0, 37)}..."` : `"${value}"`;
+    content.push(row(key, displayValue));
+  }
+
+  content.push("");
+
+  // status
+  if (status === "running") {
+    content.push(spinner("generating..."));
+  } else if (status === "done" && result) {
+    content.push(success(`done in ${formatDuration(result.time || 0)}`));
+    content.push("");
+    if (result.output) {
+      content.push(row("output", result.output));
+    }
+    if (result.cost) {
+      content.push(row("cost", formatCost(result.cost)));
+    }
+  } else if (status === "error" && result?.error) {
+    content.push(error("failed"));
+    content.push("");
+    content.push(row("error", result.error));
+  }
+
+  content.push("");
+
+  return box(name, content);
+}