@butlerw/vellum 0.1.0

package/src/commands/custom-agents/index.ts

@@ -0,0 +1,372 @@
+/**
+ * Custom Agents Command Group (T020-T024)
+ *
+ * CLI commands for managing custom agent definitions.
+ *
+ * Subcommands:
+ * - `vellum custom-agents list` - List agents grouped by scope
+ * - `vellum custom-agents create` - Create new agent from template
+ * - `vellum custom-agents validate` - Validate agent files
+ * - `vellum custom-agents info` - Show full agent details
+ * - `vellum custom-agents export` - Export agent to file
+ * - `vellum custom-agents import` - Import agent from file
+ *
+ * @module cli/commands/custom-agents
+ */
+
+import type { CommandContext, CommandResult, SlashCommand } from "../types.js";
+import { success } from "../types.js";
+import { handleCreate } from "./create.js";
+import { handleExport } from "./export.js";
+import { handleImport } from "./import.js";
+import { handleInfo } from "./info.js";
+import { handleList } from "./list.js";
+import { handleValidate } from "./validate.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Custom agents subcommand names
+ */
+export type CustomAgentsSubcommand =
+  | "list"
+  | "create"
+  | "validate"
+  | "info"
+  | "export"
+  | "import"
+  | "help";
+
+/**
+ * Options for list subcommand (T020)
+ */
+export interface ListOptions {
+  /** Output as JSON */
+  json?: boolean;
+  /** Show only global (user-level) agents */
+  global?: boolean;
+  /** Show only local (project-level) agents */
+  local?: boolean;
+}
+
+/**
+ * Options for create subcommand (T021)
+ */
+export interface CreateOptions {
+  /** Template to use (basic, advanced, orchestrator) */
+  template?: string;
+  /** Create in global location (~/.vellum/agents) */
+  global?: boolean;
+  /** Skip interactive prompts */
+  noInteractive?: boolean;
+}
+
+/**
+ * Options for validate subcommand (T022)
+ */
+export interface ValidateOptions {
+  /** Strict mode - treat warnings as errors */
+  strict?: boolean;
+  /** Agent slug or file path to validate */
+  target?: string;
+}
+
+/**
+ * Options for info subcommand (T023)
+ */
+export interface InfoOptions {
+  /** Output as JSON */
+  json?: boolean;
+  /** Show full system prompt */
+  showPrompt?: boolean;
+}
+
+/**
+ * Options for export subcommand (T020a)
+ */
+export interface ExportOptions {
+  /** Output file path */
+  output?: string;
+  /** Output format (yaml or json) */
+  format?: "yaml" | "json";
+}
+
+/**
+ * Options for import subcommand (T020b)
+ */
+export interface ImportOptions {
+  /** Import file path */
+  file: string;
+  /** Import to global location */
+  global?: boolean;
+}
+
+// =============================================================================
+// Help Text
+// =============================================================================
+
+/**
+ * Generate help text for custom-agents command group
+ */
+function getCustomAgentsHelp(): string {
+  return `🤖 Custom Agents Commands
+
+Manage custom agent definitions.
+
+Subcommands:
+  list      List agents grouped by scope (project/user/system)
+  create    Create a new agent from template
+  validate  Validate agent definition files
+  info      Show full agent details (resolved config)
+  export    Export agent definition to file
+  import    Import agent definition from file
+
+Usage:
+  /custom-agents                     Show this help
+  /custom-agents list                List all agents
+  /custom-agents list --json         Output as JSON
+  /custom-agents list --global       Show only user-level agents
+  /custom-agents list --local        Show only project-level agents
+  /custom-agents create <slug>       Create new agent
+  /custom-agents create <slug> --template=advanced
+  /custom-agents validate            Validate all agents
+  /custom-agents validate <slug>     Validate specific agent
+  /custom-agents validate --strict   Treat warnings as errors
+  /custom-agents info <slug>         Show agent details
+  /custom-agents info <slug> --json  Output as JSON
+  /custom-agents info <slug> --show-prompt
+  /custom-agents export <slug>       Export agent
+  /custom-agents export <slug> --output=./agent.yaml
+  /custom-agents export <slug> --format=json
+  /custom-agents import <file>       Import agent from file
+
+Examples:
+  /custom-agents create test-runner --template=basic
+  /custom-agents validate --strict
+  /custom-agents info my-agent --show-prompt
+  /custom-agents export my-agent --format=yaml
+
+See also:
+  /agents - AGENTS.md configuration management`;
+}
+
+// =============================================================================
+// Subcommand Routing
+// =============================================================================
+
+/**
+ * Parse custom-agents subcommand from positional args
+ */
+function parseSubcommand(positional: readonly unknown[]): CustomAgentsSubcommand {
+  const first = positional[0];
+  if (typeof first === "string") {
+    const sub = first.toLowerCase();
+    if (
+      sub === "list" ||
+      sub === "create" ||
+      sub === "validate" ||
+      sub === "info" ||
+      sub === "export" ||
+      sub === "import"
+    ) {
+      return sub;
+    }
+  }
+  return "help";
+}
+
+/**
+ * Execute custom-agents command group
+ *
+ * @param ctx - Command context
+ * @returns Command result
+ */
+export async function executeCustomAgents(ctx: CommandContext): Promise<CommandResult> {
+  const subcommand = parseSubcommand(ctx.parsedArgs.positional);
+  const named = ctx.parsedArgs.named;
+  const positional = ctx.parsedArgs.positional;
+
+  switch (subcommand) {
+    case "list":
+      return handleList({
+        json: named.json as boolean | undefined,
+        global: named.global as boolean | undefined,
+        local: named.local as boolean | undefined,
+      });
+
+    case "create":
+      return handleCreate(
+        positional[1] as string | undefined, // slug
+        {
+          template: named.template as string | undefined,
+          global: named.global as boolean | undefined,
+          noInteractive: named["no-interactive"] as boolean | undefined,
+        }
+      );
+
+    case "validate":
+      return handleValidate({
+        target: positional[1] as string | undefined,
+        strict: named.strict as boolean | undefined,
+      });
+
+    case "info":
+      return handleInfo(positional[1] as string | undefined, {
+        json: named.json as boolean | undefined,
+        showPrompt: named["show-prompt"] as boolean | undefined,
+      });
+
+    case "export":
+      return handleExport(positional[1] as string | undefined, {
+        output: named.output as string | undefined,
+        format: named.format as "yaml" | "json" | undefined,
+      });
+
+    case "import":
+      return handleImport({
+        file: positional[1] as string,
+        global: named.global as boolean | undefined,
+      });
+
+    default:
+      return success(getCustomAgentsHelp());
+  }
+}
+
+// =============================================================================
+// Slash Command Definition
+// =============================================================================
+
+/**
+ * Custom agents command group for TUI
+ *
+ * Provides access to custom agent management operations.
+ */
+export const customAgentsCommand: SlashCommand = {
+  name: "custom-agents",
+  description: "Manage custom agent definitions",
+  kind: "builtin",
+  category: "config",
+  aliases: ["ca", "custom-agent"],
+  positionalArgs: [
+    {
+      name: "subcommand",
+      type: "string",
+      description: "Subcommand: list, create, validate, info, export, import",
+      required: false,
+    },
+    {
+      name: "target",
+      type: "string",
+      description: "Agent slug, file path, or other target",
+      required: false,
+    },
+  ],
+  namedArgs: [
+    // Common flags
+    {
+      name: "json",
+      shorthand: "j",
+      type: "boolean",
+      description: "Output as JSON",
+      required: false,
+      default: false,
+    },
+    // List flags
+    {
+      name: "global",
+      shorthand: "g",
+      type: "boolean",
+      description: "Global (user-level) scope",
+      required: false,
+      default: false,
+    },
+    {
+      name: "local",
+      shorthand: "l",
+      type: "boolean",
+      description: "Local (project-level) scope",
+      required: false,
+      default: false,
+    },
+    // Create flags
+    {
+      name: "template",
+      shorthand: "t",
+      type: "string",
+      description: "Template for new agent (basic, advanced, orchestrator)",
+      required: false,
+    },
+    {
+      name: "no-interactive",
+      type: "boolean",
+      description: "Skip interactive prompts",
+      required: false,
+      default: false,
+    },
+    // Validate flags
+    {
+      name: "strict",
+      shorthand: "s",
+      type: "boolean",
+      description: "Treat warnings as errors",
+      required: false,
+      default: false,
+    },
+    // Info flags
+    {
+      name: "show-prompt",
+      type: "boolean",
+      description: "Show full system prompt",
+      required: false,
+      default: false,
+    },
+    // Export flags
+    {
+      name: "output",
+      shorthand: "o",
+      type: "path",
+      description: "Output file path",
+      required: false,
+    },
+    {
+      name: "format",
+      shorthand: "f",
+      type: "string",
+      description: "Output format (yaml or json)",
+      required: false,
+    },
+  ],
+  examples: [
+    "/custom-agents                           - Show help",
+    "/custom-agents list                      - List all agents",
+    "/custom-agents list --json               - Output as JSON",
+    "/custom-agents list --global             - Show user-level agents only",
+    "/custom-agents create my-agent           - Create new agent",
+    "/custom-agents create my-agent -t basic  - Use basic template",
+    "/custom-agents validate                  - Validate all agents",
+    "/custom-agents validate --strict         - Strict validation",
+    "/custom-agents info my-agent             - Show agent details",
+    "/custom-agents info my-agent --show-prompt",
+    "/custom-agents export my-agent -o ./out.yaml",
+    "/custom-agents import ./agent.yaml       - Import agent",
+  ],
+  subcommands: [
+    { name: "list", description: "List custom agents", aliases: ["ls"] },
+    { name: "create", description: "Create custom agent" },
+    { name: "validate", description: "Validate agent" },
+    { name: "edit", description: "Edit agent" },
+    { name: "export", description: "Export agent" },
+    { name: "import", description: "Import agent" },
+  ],
+
+  execute: executeCustomAgents,
+};
+
+// =============================================================================
+// Re-exports
+// =============================================================================
+
+export { getCustomAgentsHelp };

package/src/commands/custom-agents/info.ts

@@ -0,0 +1,318 @@
+/**
+ * Custom Agents Info Command (T023)
+ *
+ * Shows full agent details including resolved configuration.
+ *
+ * @module cli/commands/custom-agents/info
+ * @see REQ-021
+ */
+
+import { AgentDiscovery, type DiscoveredAgent, DiscoverySource } from "@vellum/core";
+import chalk from "chalk";
+
+import type { CommandResult } from "../types.js";
+import { error, success } from "../types.js";
+import type { InfoOptions } from "./index.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * JSON output format for info command
+ */
+export interface InfoJsonOutput {
+  success: boolean;
+  agent: {
+    slug: string;
+    name: string;
+    description?: string;
+    mode?: string;
+    extends?: string;
+    icon?: string;
+    color?: string;
+    hidden?: boolean;
+    model?: string;
+    systemPrompt?: string;
+    version?: string;
+    author?: string;
+    tags?: string[];
+    docs?: string;
+    level?: string;
+    toolGroups?: unknown[];
+    restrictions?: unknown;
+    settings?: unknown;
+    whenToUse?: unknown;
+    hooks?: unknown;
+    coordination?: unknown;
+  };
+  source: {
+    path: string;
+    scope: string;
+    priority: number;
+    modifiedAt: string;
+  };
+  resolved?: {
+    inheritanceChain: string[];
+    effectiveConfig: Record<string, unknown>;
+  };
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/**
+ * Get scope name from discovery source
+ */
+function getSourceName(source: DiscoverySource): string {
+  switch (source) {
+    case DiscoverySource.PROJECT:
+      return "project";
+    case DiscoverySource.USER:
+      return "user";
+    case DiscoverySource.SYSTEM:
+      return "system";
+    case DiscoverySource.ENV:
+      return "environment";
+    case DiscoverySource.CLI:
+      return "cli";
+    default:
+      return "unknown";
+  }
+}
+
+/**
+ * Format value for display
+ */
+function formatValue(value: unknown, indent = 0): string {
+  const prefix = "  ".repeat(indent);
+
+  if (value === undefined || value === null) {
+    return chalk.gray("(not set)");
+  }
+
+  if (typeof value === "boolean") {
+    return value ? chalk.green("true") : chalk.red("false");
+  }
+
+  if (typeof value === "number") {
+    return chalk.yellow(String(value));
+  }
+
+  if (typeof value === "string") {
+    // Truncate long strings
+    if (value.length > 80) {
+      return chalk.white(`"${value.substring(0, 77)}..."`);
+    }
+    return chalk.white(`"${value}"`);
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      return chalk.gray("[]");
+    }
+    const items = value.map((v) => `${prefix}  - ${formatValue(v, 0)}`).join("\n");
+    return `\n${items}`;
+  }
+
+  if (typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>);
+    if (entries.length === 0) {
+      return chalk.gray("{}");
+    }
+    const items = entries
+      .map(([k, v]) => `${prefix}  ${chalk.cyan(k)}: ${formatValue(v, indent + 1)}`)
+      .join("\n");
+    return `\n${items}`;
+  }
+
+  return String(value);
+}
+
+/**
+ * Format section header
+ */
+function formatSection(title: string): string {
+  return chalk.bold.blue(`\n── ${title} ──`);
+}
+
+/**
+ * Format agent for display
+ */
+function formatAgentInfo(discovered: DiscoveredAgent, options: InfoOptions): string {
+  const { definition: agent, sourcePath, source, modifiedAt } = discovered;
+  const lines: string[] = [];
+
+  // Header
+  const icon = agent.icon ?? "📦";
+  lines.push("");
+  lines.push(chalk.bold(`${icon} ${agent.name}`));
+  lines.push(chalk.gray(`Slug: ${agent.slug}`));
+
+  // Basic Info
+  lines.push(formatSection("Basic Information"));
+  lines.push(`  ${chalk.cyan("Description")}: ${formatValue(agent.description)}`);
+  lines.push(`  ${chalk.cyan("Mode")}: ${formatValue(agent.mode)}`);
+  lines.push(`  ${chalk.cyan("Extends")}: ${formatValue(agent.extends)}`);
+  lines.push(`  ${chalk.cyan("Level")}: ${formatValue(agent.level)}`);
+  lines.push(`  ${chalk.cyan("Hidden")}: ${formatValue(agent.hidden)}`);
+
+  // UI Configuration
+  lines.push(formatSection("UI Configuration"));
+  lines.push(`  ${chalk.cyan("Icon")}: ${formatValue(agent.icon)}`);
+  lines.push(`  ${chalk.cyan("Color")}: ${formatValue(agent.color)}`);
+
+  // LLM Configuration
+  lines.push(formatSection("LLM Configuration"));
+  lines.push(`  ${chalk.cyan("Model")}: ${formatValue(agent.model)}`);
+
+  if (options.showPrompt && agent.systemPrompt) {
+    lines.push(`  ${chalk.cyan("System Prompt")}:`);
+    lines.push(chalk.gray("  ─".repeat(30)));
+    const promptLines = agent.systemPrompt.split("\n");
+    for (const line of promptLines) {
+      lines.push(chalk.white(`  ${line}`));
+    }
+    lines.push(chalk.gray("  ─".repeat(30)));
+  } else if (agent.systemPrompt) {
+    const preview = agent.systemPrompt.substring(0, 60).replace(/\n/g, " ");
+    lines.push(`  ${chalk.cyan("System Prompt")}: ${chalk.gray(`"${preview}..."`)}`);
+    lines.push(chalk.gray("    (use --show-prompt to see full prompt)"));
+  } else {
+    lines.push(`  ${chalk.cyan("System Prompt")}: ${chalk.gray("(not set)")}`);
+  }
+
+  // Access & Restrictions
+  lines.push(formatSection("Access & Restrictions"));
+  lines.push(`  ${chalk.cyan("Tool Groups")}: ${formatValue(agent.toolGroups)}`);
+  lines.push(`  ${chalk.cyan("Restrictions")}: ${formatValue(agent.restrictions)}`);
+
+  // Runtime Settings
+  lines.push(formatSection("Runtime Settings"));
+  lines.push(`  ${chalk.cyan("Settings")}: ${formatValue(agent.settings)}`);
+
+  // Activation
+  lines.push(formatSection("Activation"));
+  lines.push(`  ${chalk.cyan("When to Use")}: ${formatValue(agent.whenToUse)}`);
+
+  // Hooks
+  if (agent.hooks) {
+    lines.push(formatSection("Lifecycle Hooks"));
+    lines.push(`  ${chalk.cyan("Hooks")}: ${formatValue(agent.hooks)}`);
+  }
+
+  // Multi-Agent Coordination
+  if (agent.coordination) {
+    lines.push(formatSection("Multi-Agent Coordination"));
+    lines.push(`  ${chalk.cyan("Coordination")}: ${formatValue(agent.coordination)}`);
+  }
+
+  // Metadata
+  lines.push(formatSection("Metadata"));
+  lines.push(`  ${chalk.cyan("Version")}: ${formatValue(agent.version)}`);
+  lines.push(`  ${chalk.cyan("Author")}: ${formatValue(agent.author)}`);
+  lines.push(`  ${chalk.cyan("Tags")}: ${formatValue(agent.tags)}`);
+  lines.push(`  ${chalk.cyan("Docs")}: ${formatValue(agent.docs)}`);
+
+  // Source Information
+  lines.push(formatSection("Source"));
+  lines.push(`  ${chalk.cyan("Path")}: ${chalk.gray(sourcePath)}`);
+  lines.push(`  ${chalk.cyan("Scope")}: ${formatValue(getSourceName(source))}`);
+  lines.push(`  ${chalk.cyan("Priority")}: ${formatValue(source)}`);
+  lines.push(`  ${chalk.cyan("Modified")}: ${formatValue(modifiedAt.toISOString())}`);
+
+  return lines.join("\n");
+}
+
+/**
+ * Convert agent to JSON output
+ */
+function toJsonOutput(discovered: DiscoveredAgent): InfoJsonOutput {
+  const { definition: agent, sourcePath, source, modifiedAt } = discovered;
+
+  return {
+    success: true,
+    agent: {
+      slug: agent.slug,
+      name: agent.name,
+      description: agent.description,
+      mode: agent.mode,
+      extends: agent.extends,
+      icon: agent.icon,
+      color: agent.color,
+      hidden: agent.hidden,
+      model: agent.model,
+      systemPrompt: agent.systemPrompt,
+      version: agent.version,
+      author: agent.author,
+      tags: agent.tags,
+      docs: agent.docs,
+      level: agent.level !== undefined ? String(agent.level) : undefined,
+      toolGroups: agent.toolGroups,
+      restrictions: agent.restrictions,
+      settings: agent.settings,
+      whenToUse: agent.whenToUse,
+      hooks: agent.hooks,
+      coordination: agent.coordination,
+    },
+    source: {
+      path: sourcePath,
+      scope: getSourceName(source),
+      priority: source,
+      modifiedAt: modifiedAt.toISOString(),
+    },
+  };
+}
+
+// =============================================================================
+// Command Handler
+// =============================================================================
+
+/**
+ * Handle info subcommand
+ *
+ * Shows full details for a specific agent, including resolved configuration.
+ *
+ * @param slug - Agent slug to show info for
+ * @param options - Info options
+ * @returns Command result
+ */
+export async function handleInfo(
+  slug: string | undefined,
+  options: InfoOptions = {}
+): Promise<CommandResult> {
+  // Require slug
+  if (!slug) {
+    return error("MISSING_ARGUMENT", "Agent slug is required", [
+      "Usage: /custom-agents info <slug>",
+      "Use /custom-agents list to see available agents",
+    ]);
+  }
+
+  try {
+    // Discover agents
+    const discovery = new AgentDiscovery({ watchEnabled: false });
+    await discovery.discover();
+
+    // Find agent
+    const agent = discovery.get(slug);
+
+    if (!agent) {
+      return error("RESOURCE_NOT_FOUND", `Agent not found: ${slug}`, [
+        "Check the slug is correct",
+        "Use /custom-agents list to see available agents",
+      ]);
+    }
+
+    // Output format
+    if (options.json) {
+      return success(JSON.stringify(toJsonOutput(agent), null, 2));
+    }
+
+    return success(formatAgentInfo(agent, options));
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return error("INTERNAL_ERROR", `Failed to get agent info: ${message}`);
+  }
+}