@butlerw/vellum 0.1.0

package/src/commands/completion/index.ts

@@ -0,0 +1,371 @@
+/**
+ * Shell Completion Generator (T-047)
+ *
+ * Generates shell completion scripts for various shells.
+ * Supports: bash, zsh, fish, powershell
+ *
+ * @module cli/commands/completion
+ */
+
+import type { CommandRegistry } from "../registry.js";
+import type { SlashCommand } from "../types.js";
+
+// =============================================================================
+// Interfaces
+// =============================================================================
+
+/**
+ * Shell completion generator interface
+ *
+ * Implementations generate shell-specific completion scripts.
+ */
+export interface CompletionGenerator {
+  /** Shell name for identification */
+  readonly shell: ShellType;
+
+  /**
+   * Generate completion script
+   *
+   * @param commands - Available commands to complete
+   * @param programName - CLI program name (e.g., 'vellum')
+   * @returns Shell script as string
+   */
+  generate(commands: readonly SlashCommand[], programName: string): string;
+}
+
+/**
+ * Supported shell types
+ */
+export type ShellType = "bash" | "zsh" | "fish" | "powershell";
+
+/**
+ * Completion generation options
+ */
+export interface CompletionOptions {
+  /** CLI program name */
+  programName: string;
+  /** Target shell */
+  shell: ShellType;
+  /** Include command descriptions in completions */
+  includeDescriptions?: boolean;
+}
+
+// =============================================================================
+// Bash Completion Generator
+// =============================================================================
+
+/**
+ * Generates Bash completion script
+ */
+export class BashCompletionGenerator implements CompletionGenerator {
+  readonly shell: ShellType = "bash";
+
+  generate(commands: readonly SlashCommand[], programName: string): string {
+    const commandNames = commands.map((c) => c.name).join(" ");
+    const commandCompletions = commands
+      .map((c) => {
+        const flags = (c.namedArgs ?? []).map((a) => `--${a.name}`).join(" ");
+        return flags
+          ? `      ${c.name}) COMPREPLY=( $(compgen -W "${flags}" -- "\${cur}") );;`
+          : "";
+      })
+      .filter(Boolean)
+      .join("\n");
+
+    return `# Bash completion for ${programName}
+# Add to ~/.bashrc: source <(${programName} completion bash)
+
+_${programName}_completions() {
+  local cur prev commands
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  commands="${commandNames}"
+
+  if [[ \${COMP_CWORD} -eq 1 ]]; then
+    # Complete command names (with / prefix)
+    if [[ \${cur} == /* ]]; then
+      COMPREPLY=( $(compgen -P "/" -W "\${commands}" -- "\${cur#/}") )
+    else
+      COMPREPLY=( $(compgen -W "\${commands}" -- "\${cur}") )
+    fi
+    return 0
+  fi
+
+  # Complete command-specific flags
+  case "\${COMP_WORDS[1]#/}" in
+${commandCompletions}
+    *);;
+  esac
+
+  return 0
+}
+
+complete -F _${programName}_completions ${programName}
+`;
+  }
+}
+
+// =============================================================================
+// Zsh Completion Generator
+// =============================================================================
+
+/**
+ * Generates Zsh completion script
+ */
+export class ZshCompletionGenerator implements CompletionGenerator {
+  readonly shell: ShellType = "zsh";
+
+  generate(commands: readonly SlashCommand[], programName: string): string {
+    const commandCompletions = commands
+      .map((c) => `      '/${c.name}:${this.escapeDescription(c.description)}'`)
+      .join(" \\\n");
+
+    const subcommandCompletions = commands
+      .filter((c) => c.namedArgs && c.namedArgs.length > 0)
+      .map((c) => {
+        const flags = (c.namedArgs ?? [])
+          .map((a) => {
+            const desc = this.escapeDescription(a.description);
+            return `        '--${a.name}[${desc}]'`;
+          })
+          .join(" \\\n");
+        return `    ${c.name})\n      _arguments \\\n${flags}\n      ;;`;
+      })
+      .join("\n");
+
+    return `#compdef ${programName}
+# Zsh completion for ${programName}
+# Add to fpath or source directly
+
+_${programName}() {
+  local -a commands
+  commands=(
+${commandCompletions}
+  )
+
+  _arguments -C \\
+    '1: :->command' \\
+    '*: :->args'
+
+  case $state in
+    command)
+      _describe 'commands' commands
+      ;;
+    args)
+      case \${words[2]#/} in
+${subcommandCompletions}
+      esac
+      ;;
+  esac
+}
+
+_${programName} "$@"
+`;
+  }
+
+  private escapeDescription(desc: string): string {
+    return desc.replace(/'/g, "'\\''").replace(/\[/g, "\\[").replace(/\]/g, "\\]");
+  }
+}
+
+// =============================================================================
+// Fish Completion Generator
+// =============================================================================
+
+/**
+ * Generates Fish shell completion script
+ */
+export class FishCompletionGenerator implements CompletionGenerator {
+  readonly shell: ShellType = "fish";
+
+  generate(commands: readonly SlashCommand[], programName: string): string {
+    const commandCompletions = commands
+      .map(
+        (c) =>
+          `complete -c ${programName} -n "__fish_use_subcommand" -a "/${c.name}" -d '${this.escapeDescription(c.description)}'`
+      )
+      .join("\n");
+
+    const flagCompletions = commands
+      .filter((c) => c.namedArgs && c.namedArgs.length > 0)
+      .flatMap((c) =>
+        (c.namedArgs ?? []).map(
+          (a) =>
+            `complete -c ${programName} -n "__fish_seen_subcommand_from /${c.name}" -l ${a.name} -d '${this.escapeDescription(a.description)}'`
+        )
+      )
+      .join("\n");
+
+    return `# Fish completion for ${programName}
+# Save to ~/.config/fish/completions/${programName}.fish
+
+# Disable file completions for command position
+complete -c ${programName} -f
+
+# Command completions
+${commandCompletions}
+
+# Flag completions
+${flagCompletions}
+`;
+  }
+
+  private escapeDescription(desc: string): string {
+    return desc.replace(/'/g, "\\'");
+  }
+}
+
+// =============================================================================
+// PowerShell Completion Generator
+// =============================================================================
+
+/**
+ * Generates PowerShell completion script
+ */
+export class PowerShellCompletionGenerator implements CompletionGenerator {
+  readonly shell: ShellType = "powershell";
+
+  generate(commands: readonly SlashCommand[], programName: string): string {
+    const commandCompletions = commands
+      .map(
+        (c) =>
+          `        @{ Command = '/${c.name}'; Description = '${this.escapeDescription(c.description)}'; Flags = @(${this.formatFlags(c)}) }`
+      )
+      .join("\n");
+
+    return `# PowerShell completion for ${programName}
+# Add to $PROFILE: . <(${programName} completion powershell)
+
+$${programName}Commands = @(
+${commandCompletions}
+)
+
+Register-ArgumentCompleter -Native -CommandName ${programName} -ScriptBlock {
+    param($wordToComplete, $commandAst, $cursorPosition)
+    
+    $commands = $${programName}Commands
+    
+    # Get current command state
+    $elements = $commandAst.CommandElements
+    $command = $null
+    
+    if ($elements.Count -gt 1) {
+        $command = $elements[1].ToString()
+    }
+    
+    if (-not $command -or $wordToComplete -eq $command) {
+        # Complete command names
+        $commands | Where-Object {
+            $_.Command -like "$wordToComplete*"
+        } | ForEach-Object {
+            [System.Management.Automation.CompletionResult]::new(
+                $_.Command,
+                $_.Command,
+                'ParameterValue',
+                $_.Description
+            )
+        }
+    }
+    else {
+        # Complete flags for command
+        $cmdInfo = $commands | Where-Object { $_.Command -eq $command }
+        if ($cmdInfo) {
+            $cmdInfo.Flags | Where-Object {
+                $_ -like "$wordToComplete*"
+            } | ForEach-Object {
+                [System.Management.Automation.CompletionResult]::new(
+                    $_,
+                    $_,
+                    'ParameterName',
+                    $_
+                )
+            }
+        }
+    }
+}
+`;
+  }
+
+  private escapeDescription(desc: string): string {
+    return desc.replace(/'/g, "''");
+  }
+
+  private formatFlags(command: SlashCommand): string {
+    if (!command.namedArgs || command.namedArgs.length === 0) {
+      return "";
+    }
+    return command.namedArgs.map((a) => `'--${a.name}'`).join(", ");
+  }
+}
+
+// =============================================================================
+// Completion Factory
+// =============================================================================
+
+/**
+ * Registry of shell completion generators
+ */
+const GENERATORS: Record<ShellType, CompletionGenerator> = {
+  bash: new BashCompletionGenerator(),
+  zsh: new ZshCompletionGenerator(),
+  fish: new FishCompletionGenerator(),
+  powershell: new PowerShellCompletionGenerator(),
+};
+
+/**
+ * Get available shell types
+ */
+export function getAvailableShells(): readonly ShellType[] {
+  return Object.keys(GENERATORS) as ShellType[];
+}
+
+/**
+ * Check if a shell type is supported
+ */
+export function isValidShell(shell: string): shell is ShellType {
+  return shell in GENERATORS;
+}
+
+/**
+ * Get a completion generator for a specific shell
+ *
+ * @param shell - Target shell type
+ * @returns Completion generator for the shell
+ * @throws Error if shell is not supported
+ */
+export function getGenerator(shell: ShellType): CompletionGenerator {
+  const generator = GENERATORS[shell];
+  if (!generator) {
+    throw new Error(`Unsupported shell: ${shell}. Supported: ${getAvailableShells().join(", ")}`);
+  }
+  return generator;
+}
+
+/**
+ * Generate completion script for a shell
+ *
+ * @param options - Completion options
+ * @param registry - Command registry to get commands from
+ * @returns Generated shell script
+ */
+export function generateCompletion(options: CompletionOptions, registry: CommandRegistry): string {
+  const generator = getGenerator(options.shell);
+  const commands = registry.list();
+  return generator.generate(commands, options.programName);
+}
+
+/**
+ * Generate completion script from a list of commands
+ *
+ * @param options - Completion options
+ * @param commands - Commands to generate completions for
+ * @returns Generated shell script
+ */
+export function generateCompletionFromCommands(
+  options: CompletionOptions,
+  commands: readonly SlashCommand[]
+): string {
+  const generator = getGenerator(options.shell);
+  return generator.generate(commands, options.programName);
+}

package/src/commands/condense.ts

@@ -0,0 +1,191 @@
+/**
+ * Condense Slash Command (Context Management)
+ *
+ * Provides slash command for manually triggering context window optimization:
+ * - /condense - Compact the conversation context
+ * - /condense status - Show current context state
+ *
+ * @module cli/commands/condense
+ */
+
+import type { AgentLoop, ContextManageResult } from "@vellum/core";
+import type { CommandContext, CommandResult, SlashCommand } from "./types.js";
+import { error, success } from "./types.js";
+
+// =============================================================================
+// Module State
+// =============================================================================
+
+/**
+ * Reference to the active AgentLoop instance.
+ * Set by the App component when an agent session is active.
+ */
+let agentLoopRef: AgentLoop | null = null;
+
+/**
+ * Set the AgentLoop instance for context management commands.
+ * Called by the App component when an agent session starts/ends.
+ *
+ * @param loop - The AgentLoop instance to use, or null when session ends
+ */
+export function setCondenseCommandLoop(loop: AgentLoop | null): void {
+  agentLoopRef = loop;
+}
+
+/**
+ * Get the current AgentLoop instance.
+ * Returns null if no agent session is active.
+ */
+export function getCondenseCommandLoop(): AgentLoop | null {
+  return agentLoopRef;
+}
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Context state descriptions for user display
+ */
+const CONTEXT_STATE_DESCRIPTIONS: Record<string, string> = {
+  healthy: "Context is healthy, no action needed",
+  warning: "Context is approaching limits, may compress soon",
+  critical: "Context is near capacity, compression recommended",
+  overflow: "Context has exceeded limits, compression required",
+};
+
+/**
+ * Get human-readable description for context state
+ */
+function getStateDescription(state: string): string {
+  return CONTEXT_STATE_DESCRIPTIONS[state] ?? `Unknown state: ${state}`;
+}
+
+/**
+ * Format context management result for display
+ */
+function formatResult(result: ContextManageResult): string {
+  const lines: string[] = [];
+
+  if (result.modified) {
+    lines.push("✅ Context compacted successfully");
+    lines.push("");
+    lines.push(`📊 State: ${result.state}`);
+
+    if (result.actions.length > 0) {
+      lines.push(`🔧 Actions taken:`);
+      for (const action of result.actions) {
+        lines.push(`   • ${action}`);
+      }
+    }
+
+    lines.push(`📝 Messages: ${result.messages.length}`);
+  } else {
+    lines.push("ℹ️ No compaction needed");
+    lines.push("");
+    lines.push(`📊 State: ${result.state}`);
+    lines.push(`💡 ${getStateDescription(result.state)}`);
+  }
+
+  return lines.join("\n");
+}
+
+// =============================================================================
+// /condense Command
+// =============================================================================
+
+/**
+ * /condense command - Manually compact the conversation context.
+ *
+ * Usage:
+ *   /condense        - Compact the context immediately
+ *   /condense status - Show current context state
+ */
+export const condenseCommand: SlashCommand = {
+  name: "condense",
+  description: "Compact conversation context to free up token space",
+  kind: "builtin",
+  category: "workflow",
+  aliases: ["compact", "compress"],
+  subcommands: [{ name: "status", description: "Show current context state" }],
+  positionalArgs: [
+    {
+      name: "subcommand",
+      type: "string",
+      description: "Subcommand (status)",
+      required: false,
+    },
+  ],
+  namedArgs: [],
+
+  async execute(ctx: CommandContext): Promise<CommandResult> {
+    const { parsedArgs } = ctx;
+
+    // Check if we have access to the agent loop
+    if (!agentLoopRef) {
+      return error("RESOURCE_NOT_FOUND", "Context management is not available", [
+        "No active agent session found. Start a conversation first.",
+      ]);
+    }
+
+    // Check if context management is enabled
+    if (!agentLoopRef.isContextManagementEnabled()) {
+      return error("OPERATION_NOT_ALLOWED", "Context management is disabled", [
+        "Enable context management in your configuration to use this command.",
+        "",
+        "Add to your vellum.config.ts:",
+        "",
+        "  contextManagement: {",
+        "    enabled: true",
+        "  }",
+      ]);
+    }
+
+    // Handle subcommands
+    const subcommand = parsedArgs.positional[0] as string | undefined;
+
+    if (subcommand === "status") {
+      const state = agentLoopRef.getContextState();
+      const messages = agentLoopRef.getMessages();
+
+      const lines: string[] = [
+        "📊 Context Status",
+        "",
+        `   State: ${state ?? "unknown"}`,
+        `   Messages: ${messages.length}`,
+        "",
+        `💡 ${getStateDescription(state ?? "healthy")}`,
+      ];
+
+      return success(lines.join("\n"));
+    }
+
+    if (subcommand && subcommand !== "status") {
+      return error("INVALID_ARGUMENT", `Unknown subcommand: ${subcommand}`, [
+        "Use /condense or /condense status",
+      ]);
+    }
+
+    // Execute compaction
+    try {
+      const result = await agentLoopRef.compactContext();
+
+      if (!result) {
+        return error("INTERNAL_ERROR", "Compaction failed", [
+          "Context management returned no result. This may indicate an internal error.",
+        ]);
+      }
+
+      return success(formatResult(result));
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return error("INTERNAL_ERROR", `Failed to compact context: ${message}`);
+    }
+  },
+};
+
+// =============================================================================
+// Exports
+// =============================================================================
+
+export default condenseCommand;