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

package/src/cli/ui/components/OptionRow.tsx

@@ -0,0 +1,81 @@
+/**
+ * OptionRow - CLI option display with better spacing
+ * Shows option name, description, type hints, defaults, and enums
+ */
+
+import { Box, Text } from "ink";
+import { theme } from "../theme.ts";
+
+interface OptionRowProps {
+  name: string;
+  description?: string;
+  required?: boolean;
+  defaultValue?: unknown;
+  enumValues?: (string | number)[];
+  type?: string;
+  nameWidth?: number;
+}
+
+export function OptionRow({
+  name,
+  description,
+  required = false,
+  defaultValue,
+  enumValues,
+  type,
+  nameWidth = theme.layout.optionNameWidth,
+}: OptionRowProps) {
+  const paddedName = `--${name}`.padEnd(nameWidth);
+  const hasDefault = defaultValue !== undefined;
+  const hasEnum = enumValues && enumValues.length > 0;
+
+  // Format enum values - if many values, show abbreviated
+  const formatEnums = (values: (string | number)[]) => {
+    const stringValues = values.map(String);
+    const joined = stringValues.join(", ");
+    if (joined.length > 50) {
+      // Show first few and count
+      const shown = stringValues.slice(0, 4).join(", ");
+      return `${shown}, ... (${values.length} options)`;
+    }
+    return joined;
+  };
+
+  return (
+    <Box flexDirection="column" marginBottom={1}>
+      {/* Main line: name + description + required */}
+      <Box>
+        <Text color={theme.colors.accent}>{paddedName}</Text>
+        <Text>{description || ""}</Text>
+        {required && <Text color={theme.colors.warning}> (required)</Text>}
+      </Box>
+
+      {/* Type and default on same line if compact */}
+      {(type || hasDefault) && (
+        <Box paddingLeft={nameWidth}>
+          {type && (
+            <Text dimColor>
+              {"<"}
+              {type}
+              {">"}
+            </Text>
+          )}
+          {hasDefault && (
+            <Text dimColor>
+              {type ? " " : ""}default: {String(defaultValue)}
+            </Text>
+          )}
+        </Box>
+      )}
+
+      {/* Enum values on separate line for readability */}
+      {hasEnum && (
+        <Box paddingLeft={nameWidth}>
+          <Text dimColor>[{formatEnums(enumValues)}]</Text>
+        </Box>
+      )}
+    </Box>
+  );
+}
+
+export default OptionRow;

package/src/cli/ui/components/Separator.tsx

@@ -0,0 +1,23 @@
+/**
+ * Separator - Horizontal divider line
+ * Minimal visual separator between sections
+ */
+
+import { Box, Text } from "ink";
+import { theme } from "../theme.ts";
+
+interface SeparatorProps {
+  width?: number;
+}
+
+export function Separator({
+  width = theme.layout.maxWidth - 4,
+}: SeparatorProps) {
+  return (
+    <Box>
+      <Text dimColor>{"─".repeat(width)}</Text>
+    </Box>
+  );
+}
+
+export default Separator;

package/src/cli/ui/components/StatusBox.tsx

@@ -0,0 +1,108 @@
+/**
+ * StatusBox - Execution status display
+ * Shows running/done/error state with params and results
+ */
+
+import { Box, Text } from "ink";
+import { icons, theme } from "../theme.ts";
+import KeyValue from "./KeyValue.tsx";
+import VargBox from "./VargBox.tsx";
+import { VargProgress } from "./VargProgress.tsx";
+import VargSpinner from "./VargSpinner.tsx";
+import { VargText } from "./VargText.tsx";
+
+type Status = "running" | "done" | "error";
+
+interface StatusBoxProps {
+  title: string;
+  status: Status;
+  params?: Record<string, string>;
+  output?: string;
+  error?: string;
+  duration?: number;
+  progress?: number; // 0-100, shows progress bar when provided
+}
+
+const statusConfig: Record<
+  Status,
+  { icon: string; color: string; label: string }
+> = {
+  running: {
+    icon: icons.running,
+    color: theme.colors.accent,
+    label: "running",
+  },
+  done: { icon: icons.success, color: theme.colors.success, label: "done" },
+  error: { icon: icons.error, color: theme.colors.error, label: "error" },
+};
+
+function formatDuration(ms: number): string {
+  if (ms >= 1000) {
+    return `${(ms / 1000).toFixed(1)}s`;
+  }
+  return `${ms}ms`;
+}
+
+export function StatusBox({
+  title,
+  status,
+  params,
+  output,
+  error,
+  duration,
+  progress,
+}: StatusBoxProps) {
+  const config = statusConfig[status];
+
+  return (
+    <VargBox title={title} variant="bordered">
+      {/* Status indicator */}
+      <Box marginY={1}>
+        {status === "running" ? (
+          <VargSpinner label={config.label} />
+        ) : (
+          <Text color={config.color}>
+            {config.icon} {config.label}
+          </Text>
+        )}
+      </Box>
+
+      {/* Progress bar (when provided) */}
+      {progress !== undefined && status === "running" && (
+        <Box marginBottom={1}>
+          <VargProgress value={progress} label="processing" />
+        </Box>
+      )}
+
+      {/* Parameters */}
+      {params && Object.keys(params).length > 0 && (
+        <Box flexDirection="column" marginBottom={1}>
+          {Object.entries(params).map(([key, value]) => (
+            <KeyValue key={key} label={key} value={value} />
+          ))}
+        </Box>
+      )}
+
+      {/* Output */}
+      {output && (
+        <Box marginTop={1}>
+          <KeyValue label="output" value={output} />
+        </Box>
+      )}
+
+      {/* Error */}
+      {error && (
+        <Box marginTop={1}>
+          <VargText variant="error">error: {error}</VargText>
+        </Box>
+      )}
+
+      {/* Duration */}
+      {duration !== undefined && (
+        <KeyValue label="time" value={formatDuration(duration)} />
+      )}
+    </VargBox>
+  );
+}
+
+export default StatusBox;

package/src/cli/ui/components/VargBox.tsx

@@ -0,0 +1,51 @@
+/**
+ * VargBox - Container component
+ * Luxury minimal styled box with optional title and borders
+ */
+
+import { Box, Text } from "ink";
+import type { ReactNode } from "react";
+import { theme } from "../theme.ts";
+
+type BorderStyle = "single" | "double" | "round" | "bold" | "classic";
+
+interface VargBoxProps {
+  title?: string;
+  subtitle?: string;
+  variant?: "default" | "minimal" | "bordered";
+  width?: number;
+  children: ReactNode;
+}
+
+export function VargBox({
+  title,
+  subtitle,
+  variant = "default",
+  width = theme.layout.maxWidth,
+  children,
+}: VargBoxProps) {
+  const showBorder = variant === "bordered" || (variant === "default" && title);
+
+  return (
+    <Box
+      flexDirection="column"
+      width={width}
+      borderStyle={
+        showBorder ? (theme.borders.style as BorderStyle) : undefined
+      }
+      borderColor={theme.colors.border}
+      paddingX={theme.layout.boxPadding}
+      paddingY={variant === "minimal" ? 0 : 1}
+    >
+      {title && (
+        <Box marginBottom={1}>
+          <Text bold>{title}</Text>
+          {subtitle && <Text dimColor> {subtitle}</Text>}
+        </Box>
+      )}
+      {children}
+    </Box>
+  );
+}
+
+export default VargBox;

package/src/cli/ui/components/VargProgress.tsx

@@ -0,0 +1,36 @@
+/**
+ * VargProgress - Progress bar component
+ * Elegant thin progress visualization
+ */
+
+import { Text } from "ink";
+import { theme } from "../theme.ts";
+
+interface VargProgressProps {
+  value: number; // 0-100
+  width?: number;
+  showPercentage?: boolean;
+  label?: string;
+}
+
+export function VargProgress({
+  value,
+  width = 24,
+  showPercentage = true,
+  label,
+}: VargProgressProps) {
+  const clampedValue = Math.max(0, Math.min(100, value));
+  const filled = Math.round((clampedValue / 100) * width);
+  const empty = width - filled;
+
+  return (
+    <Text>
+      <Text color={theme.colors.accent}>{"█".repeat(filled)}</Text>
+      <Text dimColor>{"░".repeat(empty)}</Text>
+      {showPercentage && <Text dimColor> {clampedValue}%</Text>}
+      {label && <Text dimColor> {label}</Text>}
+    </Text>
+  );
+}
+
+export default VargProgress;

package/src/cli/ui/components/VargSpinner.tsx

@@ -0,0 +1,34 @@
+/**
+ * VargSpinner - Animated loading indicator
+ * Elegant braille spinner with label
+ */
+
+import { Text } from "ink";
+import { useEffect, useState } from "react";
+import { theme } from "../theme.ts";
+
+interface VargSpinnerProps {
+  label?: string;
+}
+
+export function VargSpinner({ label }: VargSpinnerProps) {
+  const [frame, setFrame] = useState(0);
+  const frames = theme.animation.spinnerFrames;
+
+  useEffect(() => {
+    const timer = setInterval(() => {
+      setFrame((f) => (f + 1) % frames.length);
+    }, theme.animation.spinnerInterval);
+
+    return () => clearInterval(timer);
+  }, [frames.length]);
+
+  return (
+    <Text>
+      <Text color={theme.colors.accent}>{frames[frame]}</Text>
+      {label && <Text> {label}</Text>}
+    </Text>
+  );
+}
+
+export default VargSpinner;

package/src/cli/ui/components/VargText.tsx

@@ -0,0 +1,56 @@
+/**
+ * VargText - Typography component
+ * Provides semantic text variants for consistent styling
+ */
+
+import { Text } from "ink";
+import type { ReactNode } from "react";
+import { theme } from "../theme.ts";
+
+export type TextVariant =
+  | "body"
+  | "label"
+  | "code"
+  | "muted"
+  | "accent"
+  | "success"
+  | "error"
+  | "warning";
+
+interface VargTextProps {
+  variant?: TextVariant;
+  bold?: boolean;
+  dimColor?: boolean;
+  children: ReactNode;
+}
+
+const variantStyles: Record<
+  TextVariant,
+  { color?: string; dimColor?: boolean }
+> = {
+  body: {},
+  label: { dimColor: true },
+  code: { color: theme.colors.accent },
+  muted: { dimColor: true },
+  accent: { color: theme.colors.accent },
+  success: { color: theme.colors.success },
+  error: { color: theme.colors.error },
+  warning: { color: theme.colors.warning },
+};
+
+export function VargText({
+  variant = "body",
+  bold,
+  dimColor,
+  children,
+}: VargTextProps) {
+  const style = variantStyles[variant];
+
+  return (
+    <Text color={style.color} dimColor={dimColor ?? style.dimColor} bold={bold}>
+      {children}
+    </Text>
+  );
+}
+
+export default VargText;

package/src/cli/ui/components/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Varg UI Components
+ * Re-exports all UI components for the CLI
+ */
+
+export { Badge } from "./Badge.tsx";
+export { DataTable } from "./DataTable.tsx";
+export { Header } from "./Header.tsx";
+export { HelpBlock } from "./HelpBlock.tsx";
+export { KeyValue } from "./KeyValue.tsx";
+export { OptionRow } from "./OptionRow.tsx";
+export { Separator } from "./Separator.tsx";
+export { StatusBox } from "./StatusBox.tsx";
+export { VargBox } from "./VargBox.tsx";
+export { VargProgress } from "./VargProgress.tsx";
+export { VargSpinner } from "./VargSpinner.tsx";
+// Re-export types
+export type { TextVariant } from "./VargText.tsx";
+export { VargText } from "./VargText.tsx";

package/src/cli/ui/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Varg CLI UI Module
+ * Ink-based React components for the CLI
+ */
+
+// Components
+export * from "./components/index.ts";
+// Render helpers
+export { renderAndWait, renderLive, renderStatic } from "./render.ts";
+export type { ThemeColors } from "./theme.ts";
+// Theme and tokens
+export { icons, theme } from "./theme.ts";

package/src/cli/ui/render.ts

@@ -0,0 +1,35 @@
+/**
+ * Citty ↔ Ink Bridge
+ * Helpers to render Ink components from citty commands
+ */
+
+import { render } from "ink";
+import type { ReactElement } from "react";
+
+/**
+ * Render a static component that auto-exits after mounting
+ * Use for: list, help, which, find commands
+ */
+export function renderStatic(element: ReactElement): void {
+  const { unmount } = render(element);
+  // Give React time to render, then unmount
+  setTimeout(() => unmount(), 50);
+}
+
+/**
+ * Render a component with live updates
+ * Use for: run command with spinner/progress
+ * Returns control handle for manual rerender and unmount
+ */
+export function renderLive(element: ReactElement) {
+  return render(element);
+}
+
+/**
+ * Render and wait for component to signal exit
+ * Use for: interactive components (future)
+ */
+export async function renderAndWait(element: ReactElement): Promise<void> {
+  const { waitUntilExit } = render(element);
+  await waitUntilExit();
+}

package/src/cli/ui/theme.ts

@@ -0,0 +1,63 @@
+/**
+ * Design System for Varg CLI
+ * Luxury Minimal aesthetic - Vercel/Linear inspired
+ */
+
+export const theme = {
+  colors: {
+    // Primary accent - single color for emphasis
+    accent: "cyan",
+
+    // Semantic colors
+    success: "green",
+    error: "red",
+    warning: "yellow",
+
+    // Neutrals (Ink uses color names, not hex)
+    text: {
+      primary: "white",
+      secondary: "gray",
+      muted: "gray",
+    },
+
+    // Borders
+    border: "gray",
+  },
+
+  spacing: {
+    xs: 1,
+    sm: 2,
+    md: 3,
+    lg: 4,
+  },
+
+  borders: {
+    style: "round" as const, // Rounded corners: ╭╮╰╯
+  },
+
+  animation: {
+    // Elegant braille spinner
+    spinnerFrames: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+    spinnerInterval: 80,
+  },
+
+  layout: {
+    maxWidth: 100,
+    boxPadding: 2,
+    optionNameWidth: 22,
+  },
+} as const;
+
+// Status icons - refined geometric shapes
+export const icons = {
+  running: "●",
+  success: "✓",
+  error: "✗",
+  warning: "!",
+  info: "○",
+  arrow: "→",
+  bullet: "·",
+  required: "*",
+} as const;
+
+export type ThemeColors = keyof typeof theme.colors;

package/src/cli/utils.ts

@@ -0,0 +1,78 @@
+/**
+ * CLI utilities
+ */
+
+import { z } from "zod";
+import type { Definition } from "../core/schema/types";
+import type { JsonSchema, NotFoundOptions } from "./types";
+
+/**
+ * Handle "not found" errors consistently
+ */
+export function handleNotFound(
+  name: string,
+  options: NotFoundOptions = {},
+): never | undefined {
+  const {
+    suggestions = [],
+    maxSuggestions = 3,
+    hint = "run `varg list` to see available items",
+    errorColorFn = (s) => s,
+    hintColorFn = (s) => s,
+    exit = true,
+  } = options;
+
+  console.error(`\n  ${errorColorFn("not found:")} '${name}'\n`);
+
+  if (suggestions.length > 0) {
+    const shown = suggestions.slice(0, maxSuggestions).join(", ");
+    console.log(`  did you mean: ${shown}?\n`);
+  }
+
+  if (hint) {
+    console.log(`  ${hintColorFn(hint)}\n`);
+  }
+
+  if (exit) {
+    process.exit(1);
+  }
+}
+
+/**
+ * Convert a definition to a table row object
+ */
+export const definitionToRow = (d: Definition) => ({
+  name: d.name,
+  description: d.description,
+  type: d.type,
+});
+
+/**
+ * Convert an array of definitions to table rows
+ */
+export const definitionsToRows = (defs: Definition[]) =>
+  defs.map(definitionToRow);
+
+/**
+ * Get JSON Schema for display - converts Zod schema to JSON Schema
+ */
+export function getDisplaySchema(item: Definition): {
+  input: JsonSchema;
+  output: JsonSchema;
+} {
+  if (!item.schema) {
+    return {
+      input: { type: "object", properties: {}, required: [] },
+      output: { type: "object" },
+    };
+  }
+
+  const input = z.toJSONSchema(item.schema.input, {
+    io: "input",
+  }) as JsonSchema;
+  const output = item.schema.output
+    ? (z.toJSONSchema(item.schema.output, { io: "output" }) as JsonSchema)
+    : { type: "object" };
+
+  return { input, output };
+}