@butlerw/vellum 0.1.0

package/src/commands/agents/index.ts

@@ -0,0 +1,272 @@
+/**
+ * Agents Command Group
+ *
+ * Command group for AGENTS.md management operations.
+ *
+ * Subcommands:
+ * - `vellum agents show` - Display merged configuration
+ * - `vellum agents validate` - Validate syntax and structure
+ * - `vellum agents generate` - Generate optimized AGENTS.md
+ *
+ * @module cli/commands/agents
+ */
+
+import type { CommandContext, CommandResult, SlashCommand } from "../types.js";
+import { success } from "../types.js";
+import { handleAgentsGenerate } from "./generate.js";
+// Import subcommand handlers
+import { handleAgentsShow } from "./show.js";
+import { handleAgentsValidate } from "./validate.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Agents subcommand names
+ */
+export type AgentsSubcommand = "show" | "validate" | "generate" | "help";
+
+/**
+ * Options for agents subcommands
+ */
+export interface AgentsShowOptions {
+  /** Output as JSON */
+  json?: boolean;
+  /** Show all details including sources */
+  verbose?: boolean;
+  /** Show config for specific file/directory */
+  scope?: string;
+}
+
+export interface AgentsValidateOptions {
+  /** Path to AGENTS.md file */
+  file?: string;
+  /** Show verbose output */
+  verbose?: boolean;
+  /** Output as JSON */
+  json?: boolean;
+}
+
+export interface AgentsGenerateOptions {
+  /** Output file path */
+  output?: string;
+  /** Merge with existing file */
+  merge?: boolean;
+  /** Dry run - show what would be generated */
+  dryRun?: boolean;
+}
+
+// =============================================================================
+// Help Text
+// =============================================================================
+
+/**
+ * Generate help text for agents command group
+ */
+function getAgentsHelp(): string {
+  return `📋 Agents Commands
+
+Manage AGENTS.md configuration files.
+
+Subcommands:
+  show      Display merged AGENTS.md configuration
+  validate  Validate syntax and structure
+  generate  Generate optimized AGENTS.md from codebase
+
+Usage:
+  /agents                  Show this help
+  /agents show             Display current config
+  /agents show --json      Output as JSON
+  /agents show --verbose   Show all details
+  /agents validate         Validate current config
+  /agents validate <file>  Validate specific file
+  /agents generate         Generate new config
+
+Examples:
+  /agents show --scope ./src    Show config for src directory
+  /agents validate --verbose    Validate with detailed output
+  /agents generate --dry-run    Preview generated config
+
+See also:
+  /init    Create new AGENTS.md file`;
+}
+
+// =============================================================================
+// Subcommand Handlers
+// =============================================================================
+
+/**
+ * Handle agents show subcommand
+ */
+async function handleShow(options: AgentsShowOptions): Promise<CommandResult> {
+  return handleAgentsShow(options);
+}
+
+/**
+ * Handle agents validate subcommand
+ */
+async function handleValidate(options: AgentsValidateOptions): Promise<CommandResult> {
+  return handleAgentsValidate(options);
+}
+
+/**
+ * Handle agents generate subcommand
+ */
+async function handleGenerate(options: AgentsGenerateOptions): Promise<CommandResult> {
+  return handleAgentsGenerate(options);
+}
+
+// =============================================================================
+// Command Execution
+// =============================================================================
+
+/**
+ * Parse agents subcommand from positional args
+ */
+function parseSubcommand(positional: readonly unknown[]): AgentsSubcommand {
+  const first = positional[0];
+  if (typeof first === "string") {
+    const sub = first.toLowerCase();
+    if (sub === "show" || sub === "validate" || sub === "generate") {
+      return sub;
+    }
+  }
+  return "help";
+}
+
+/**
+ * Execute agents command group
+ *
+ * @param ctx - Command context
+ * @returns Command result
+ */
+export async function executeAgents(ctx: CommandContext): Promise<CommandResult> {
+  const subcommand = parseSubcommand(ctx.parsedArgs.positional);
+  const named = ctx.parsedArgs.named;
+
+  switch (subcommand) {
+    case "show":
+      return handleShow({
+        json: named.json as boolean | undefined,
+        verbose: named.verbose as boolean | undefined,
+        scope: named.scope as string | undefined,
+      });
+
+    case "validate":
+      return handleValidate({
+        file: ctx.parsedArgs.positional[1] as string | undefined,
+        verbose: named.verbose as boolean | undefined,
+      });
+
+    case "generate":
+      return handleGenerate({
+        output: named.output as string | undefined,
+        merge: named.merge as boolean | undefined,
+        dryRun: named["dry-run"] as boolean | undefined,
+      });
+
+    default:
+      return success(getAgentsHelp());
+  }
+}
+
+// =============================================================================
+// Slash Command Definition
+// =============================================================================
+
+/**
+ * Agents command group for TUI
+ *
+ * Provides access to AGENTS.md management operations.
+ */
+export const agentsCommand: SlashCommand = {
+  name: "agents",
+  description: "Manage AGENTS.md configuration",
+  kind: "builtin",
+  category: "config",
+  aliases: ["agent"],
+  positionalArgs: [
+    {
+      name: "subcommand",
+      type: "string",
+      description: "Subcommand: show, validate, generate",
+      required: false,
+    },
+    {
+      name: "file",
+      type: "path",
+      description: "Target file (for validate subcommand)",
+      required: false,
+    },
+  ],
+  namedArgs: [
+    {
+      name: "json",
+      shorthand: "j",
+      type: "boolean",
+      description: "Output as JSON (for show)",
+      required: false,
+      default: false,
+    },
+    {
+      name: "verbose",
+      shorthand: "v",
+      type: "boolean",
+      description: "Show verbose output",
+      required: false,
+      default: false,
+    },
+    {
+      name: "scope",
+      shorthand: "s",
+      type: "path",
+      description: "Scope to specific file/directory (for show)",
+      required: false,
+    },
+    {
+      name: "output",
+      shorthand: "o",
+      type: "path",
+      description: "Output file path (for generate)",
+      required: false,
+    },
+    {
+      name: "merge",
+      shorthand: "m",
+      type: "boolean",
+      description: "Merge with existing file (for generate)",
+      required: false,
+      default: false,
+    },
+    {
+      name: "dry-run",
+      type: "boolean",
+      description: "Preview without writing (for generate)",
+      required: false,
+      default: false,
+    },
+  ],
+  examples: [
+    "/agents                     - Show help",
+    "/agents show                - Display current config",
+    "/agents show --json         - Output as JSON",
+    "/agents show --verbose      - Show all details",
+    "/agents validate            - Validate current config",
+    "/agents validate ./AGENTS.md - Validate specific file",
+    "/agents generate --dry-run  - Preview generated config",
+  ],
+  subcommands: [
+    { name: "show", description: "Show agent details" },
+    { name: "validate", description: "Validate agents" },
+    { name: "generate", description: "Generate agent" },
+  ],
+
+  execute: executeAgents,
+};
+
+// =============================================================================
+// Re-exports
+// =============================================================================
+
+export { getAgentsHelp };

package/src/commands/agents/show.ts

@@ -0,0 +1,271 @@
+/**
+ * Agents Show Command
+ *
+ * Displays merged AGENTS.md configuration with all contributing sources.
+ * Supports JSON output for programmatic usage and verbose mode for debugging.
+ *
+ * @module cli/commands/agents/show
+ */
+
+import * as path from "node:path";
+import {
+  type AgentsConfig,
+  AgentsLoader,
+  type AgentsLoadResult,
+  type AgentsWarning,
+  type ToolPermission,
+} from "@vellum/core";
+import chalk from "chalk";
+
+import type { CommandContext, CommandResult } from "../types.js";
+import { error, success } from "../types.js";
+import type { AgentsShowOptions } from "./index.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * JSON output format for agents show
+ */
+export interface AgentsShowJsonOutput {
+  /** Whether the configuration was loaded successfully */
+  success: boolean;
+  /** Merged configuration (null if failed) */
+  config: AgentsConfig | null;
+  /** Source files that contributed to configuration */
+  sources: string[];
+  /** Warnings during loading */
+  warnings: Array<{
+    file: string;
+    message: string;
+    severity: string;
+    line?: number;
+  }>;
+  /** Whether result came from cache */
+  fromCache: boolean;
+}
+
+// =============================================================================
+// Formatters
+// =============================================================================
+
+/**
+ * Format tool permissions for display
+ */
+function formatToolPermissions(config: AgentsConfig): string {
+  if (config.allowedTools.length === 0) {
+    return chalk.gray("  No explicit tool permissions set");
+  }
+
+  return config.allowedTools
+    .map((tool: ToolPermission) => {
+      const icon = tool.negated ? chalk.red("❌") : chalk.green("✅");
+      const pattern = tool.negated ? tool.pattern.replace(/^!/, "") : tool.pattern;
+      const args = tool.args?.length ? chalk.gray(` (args: ${tool.args.join(", ")})`) : "";
+      return `  ${icon} ${tool.negated ? chalk.red(pattern) : chalk.cyan(pattern)}${args}`;
+    })
+    .join("\n");
+}
+
+/**
+ * Format sources list for display
+ */
+function formatSources(sources: string[], cwd: string): string {
+  if (sources.length === 0) {
+    return chalk.gray("  No sources found");
+  }
+
+  return sources
+    .map((source, index) => {
+      // Make paths relative to cwd for readability
+      const relativePath = path.relative(cwd, source) || source;
+      return `  ${chalk.gray(`${index + 1}.`)} ${chalk.blue(relativePath)}`;
+    })
+    .join("\n");
+}
+
+/**
+ * Format warnings list for display
+ */
+function formatWarnings(result: AgentsLoadResult): string {
+  if (result.warnings.length === 0) {
+    return "";
+  }
+
+  const warningLines = result.warnings.map((w: AgentsWarning) => {
+    const loc = w.line ? `:${w.line}` : "";
+    const file = chalk.gray(`${path.basename(w.file)}${loc}`);
+    const icon = w.severity === "warn" ? chalk.yellow("⚠") : chalk.blue("ℹ");
+    return `  ${icon} ${file}: ${w.message}`;
+  });
+
+  return `\n${chalk.yellow("⚠️ Warnings:")}\n${warningLines.join("\n")}`;
+}
+
+/**
+ * Format configuration for human-readable display
+ */
+function formatConfigDisplay(result: AgentsLoadResult, cwd: string, verbose: boolean): string {
+  const config = result.config;
+
+  if (!config) {
+    return chalk.yellow(
+      "No AGENTS.md configuration found.\n\n" +
+        "Run " +
+        chalk.cyan("/init") +
+        " to create one, or create AGENTS.md manually."
+    );
+  }
+
+  const lines: string[] = [
+    chalk.bold("📋 AGENTS.md Configuration"),
+    chalk.gray("━".repeat(40)),
+    "",
+  ];
+
+  // Name and description
+  if (config.name) {
+    lines.push(`${chalk.gray("Name:")} ${chalk.white(config.name)}`);
+  }
+  if (config.description) {
+    lines.push(`${chalk.gray("Description:")} ${config.description}`);
+  }
+  lines.push(`${chalk.gray("Priority:")} ${config.priority}`);
+  lines.push("");
+
+  // Instructions
+  if (config.instructions) {
+    lines.push(chalk.bold("📝 Instructions:"));
+    const instructionPreview =
+      config.instructions.length > 200
+        ? config.instructions.slice(0, 200) + chalk.gray("...")
+        : config.instructions;
+    lines.push(chalk.gray(`  ${instructionPreview.split("\n").join("\n  ")}`));
+    lines.push("");
+  }
+
+  // Tools
+  lines.push(chalk.bold("🔧 Allowed Tools:"));
+  lines.push(formatToolPermissions(config));
+  lines.push("");
+
+  // Merge config (verbose only)
+  if (verbose) {
+    lines.push(chalk.bold("🔀 Merge Configuration:"));
+    lines.push(`  Strategy: ${chalk.cyan(config.merge.strategy)}`);
+    lines.push(`  Arrays: ${chalk.cyan(config.merge.arrays)}`);
+    lines.push("");
+
+    // Scope (verbose only)
+    if (config.scope.include.length > 0 || config.scope.exclude.length > 0) {
+      lines.push(chalk.bold("📂 Scope:"));
+      if (config.scope.include.length > 0) {
+        lines.push(`  Include: ${chalk.green(config.scope.include.join(", "))}`);
+      }
+      if (config.scope.exclude.length > 0) {
+        lines.push(`  Exclude: ${chalk.red(config.scope.exclude.join(", "))}`);
+      }
+      lines.push("");
+    }
+  }
+
+  // Sources
+  lines.push(chalk.bold("📁 Sources:"));
+  lines.push(formatSources(config.sources, cwd));
+
+  // Warnings (if any)
+  lines.push(formatWarnings(result));
+
+  // Cache info (verbose only)
+  if (verbose && result.fromCache) {
+    lines.push("");
+    lines.push(chalk.gray("(Loaded from cache)"));
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Convert load result to JSON output format
+ */
+function toJsonOutput(result: AgentsLoadResult): AgentsShowJsonOutput {
+  return {
+    success: result.config !== null,
+    config: result.config,
+    sources: result.config?.sources ?? [],
+    warnings: result.warnings.map((w: AgentsWarning) => ({
+      file: w.file,
+      message: w.message,
+      severity: w.severity,
+      line: w.line,
+    })),
+    fromCache: result.fromCache,
+  };
+}
+
+// =============================================================================
+// Command Handler
+// =============================================================================
+
+/**
+ * Execute agents show command
+ *
+ * @param options - Command options
+ * @returns Command result
+ */
+export async function handleAgentsShow(options: AgentsShowOptions): Promise<CommandResult> {
+  const cwd = options.scope ? path.resolve(options.scope) : process.cwd();
+
+  try {
+    // Create loader with cache disabled for fresh results
+    const loader = new AgentsLoader({
+      enableCache: !options.verbose, // Disable cache in verbose mode
+    });
+
+    // Load configuration
+    const result = await loader.load(cwd);
+
+    // JSON output
+    if (options.json) {
+      const jsonOutput = toJsonOutput(result);
+      return success(JSON.stringify(jsonOutput, null, 2), {
+        format: "json",
+        data: jsonOutput,
+      });
+    }
+
+    // Human-readable output
+    const display = formatConfigDisplay(result, cwd, options.verbose ?? false);
+    return success(display);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+
+    if (options.json) {
+      const jsonError = {
+        success: false,
+        config: null,
+        sources: [],
+        warnings: [],
+        fromCache: false,
+        error: message,
+      };
+      return error("INTERNAL_ERROR", JSON.stringify(jsonError, null, 2));
+    }
+
+    return error("INTERNAL_ERROR", `Failed to load AGENTS.md configuration: ${message}`);
+  }
+}
+
+/**
+ * Execute handler for command context
+ */
+export async function executeShow(ctx: CommandContext): Promise<CommandResult> {
+  const options: AgentsShowOptions = {
+    json: ctx.parsedArgs.named.json as boolean | undefined,
+    verbose: ctx.parsedArgs.named.verbose as boolean | undefined,
+    scope: ctx.parsedArgs.named.scope as string | undefined,
+  };
+
+  return handleAgentsShow(options);
+}