vcluster-yaml-mcp-server 1.0.1 → 1.0.3

package/README.md

@@ -76,9 +76,18 @@ npx -p vcluster-yaml-mcp-server vcluster-yaml query sync --format table
 # Or install globally
 npm install -g vcluster-yaml-mcp-server
 vcluster-yaml query sync --format table
+
+# Validate configurations with ease
+vcluster-yaml validate my-config.yaml
+cat my-config.yaml | vcluster-yaml validate -
+vcluster-yaml validate my-config.yaml --schema-version v0.24.0
+
+# Shell completion (bash/zsh)
+vcluster-yaml completion bash 2>/dev/null > ~/.vcluster-yaml-completion.bash
+vcluster-yaml completion zsh 2>/dev/null > ~/.zsh/completion/_vcluster-yaml
 ```
 
-📖 **[Full CLI Documentation →](docs/CLI.md)**
+📖 **[Full CLI Documentation →](docs/CLI.md)** 
 
 ## Available Tools
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vcluster-yaml-mcp-server",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "MCP server for querying vcluster YAML configurations using jq",
   "main": "src/index.js",
   "type": "module",

package/src/cli-utils.js

@@ -0,0 +1,62 @@
+/**
+ * CLI utility functions
+ * Provides helpers for stdin reading and file operations
+ */
+
+import { readFile } from 'fs/promises';
+import { stdin } from 'process';
+
+/**
+ * Read content from stdin
+ * Used for piping content to CLI commands
+ * @returns {Promise<string>} The content read from stdin
+ */
+export async function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+
+    stdin.setEncoding('utf8');
+    stdin.on('data', chunk => data += chunk);
+    stdin.on('end', () => resolve(data));
+    stdin.on('error', reject);
+  });
+}
+
+/**
+ * Read content from a file or stdin based on the file argument
+ * @param {string|undefined} file - File path, '-' for stdin, or undefined for stdin
+ * @returns {Promise<{content: string, source: string}>} The content and its source
+ */
+export async function readContentSource(file) {
+  // Read from stdin if no file provided or file is '-'
+  if (!file || file === '-') {
+    // If no file argument provided (not even '-'), check if we're in interactive mode
+    // In interactive mode (TTY), we should not wait for stdin
+    if (!file) {
+      // stdin.isTTY is true when running in interactive terminal
+      // stdin.isTTY is false/undefined when piping or redirecting
+      const isInteractive = stdin.isTTY === true;
+
+      if (isInteractive) {
+        throw new Error(
+          'No input provided. Please specify a file or pipe content via stdin.\n' +
+          'Examples:\n' +
+          '  vcluster-yaml validate my-config.yaml\n' +
+          '  cat my-config.yaml | vcluster-yaml validate -\n' +
+          '  vcluster-yaml validate --help'
+        );
+      }
+    }
+
+    const content = await readStdin();
+    return { content, source: 'stdin' };
+  }
+
+  // Read from file
+  try {
+    const content = await readFile(file, 'utf-8');
+    return { content, source: file };
+  } catch (error) {
+    throw new Error(`Cannot read file '${file}': ${error.message}`);
+  }
+}

package/src/cli.js

@@ -7,23 +7,41 @@
  */
 
 import { Command } from 'commander';
+import { readFile } from 'fs/promises';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
 import { handleQuery, handleListVersions, handleValidate } from './cli-handlers.js';
 import { formatOutput } from './formatters.js';
+import { readContentSource } from './cli-utils.js';
+import { generateBashCompletion, generateZshCompletion, getInstallInstructions } from './completions.js';
+
+// Get package.json version
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageJson = JSON.parse(
+  await readFile(join(__dirname, '../package.json'), 'utf-8')
+);
 
 const program = new Command();
 
 program
   .name('vcluster-yaml')
   .description('vCluster YAML configuration CLI')
-  .version('0.1.0');
+  .version(packageJson.version);
 
 // Query command
 program
   .command('query <query>')
   .description('Search for vCluster configuration fields')
   .option('--file <file>', 'Configuration file to search', 'chart/values.yaml')
-  .option('--version <version>', 'vCluster version or branch', 'main')
+  .option('-s, --schema-version <version>', 'vCluster version or branch', 'main')
   .option('-f, --format <format>', 'Output format (json, yaml, table)', 'json')
+  .addHelpText('after', `
+Examples:
+  $ vcluster-yaml query sync
+  $ vcluster-yaml query sync --schema-version v0.24.0
+  $ vcluster-yaml query "controlPlane.replicas" --format table
+  `)
   .action(async (query, options) => {
     try {
       // Validate format option
@@ -32,9 +50,15 @@ program
         process.exit(1);
       }
 
+      // Add validation for empty query
+      if (!query || query.trim() === '') {
+        console.error(`Error: Query cannot be empty. Try 'vcluster-yaml query sync' or see examples with --help`);
+        process.exit(1);
+      }
+
       const result = await handleQuery(query, {
         file: options.file,
-        version: options.version
+        version: options.schemaVersion
       });
 
       if (!result.success) {
@@ -91,11 +115,22 @@ program
 
 // Validate command
 program
-  .command('validate <content>')
+  .command('validate [file]')
   .description('Validate vCluster configuration')
-  .option('--version <version>', 'vCluster version for schema', 'main')
+  .option('-s, --schema-version <version>', 'vCluster version for schema', 'main')
   .option('-f, --format <format>', 'Output format (json, yaml, table)', 'json')
-  .action(async (content, options) => {
+  .addHelpText('after', `
+Arguments:
+  file                   YAML file to validate (use '-' for stdin, omit to read from stdin)
+
+Examples:
+  $ vcluster-yaml validate vcluster.yaml
+  $ vcluster-yaml validate vcluster.yaml --schema-version v0.24.0
+  $ cat vcluster.yaml | vcluster-yaml validate -
+  $ vcluster-yaml validate - < vcluster.yaml
+  $ vcluster-yaml validate vcluster.yaml --format table
+  `)
+  .action(async (file, options) => {
     try {
       // Validate format option
       if (!['json', 'yaml', 'table'].includes(options.format)) {
@@ -103,8 +138,24 @@ program
         process.exit(1);
       }
 
+      // Read content from file or stdin
+      let content;
+      try {
+        const result = await readContentSource(file);
+        content = result.content;
+      } catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+      }
+
+      // Check for empty content
+      if (!content || content.trim() === '') {
+        console.error(`Error: No content to validate. Please provide a file path or pipe content via stdin.`);
+        process.exit(1);
+      }
+
       const result = await handleValidate(content, {
-        version: options.version
+        version: options.schemaVersion
       });
 
       // For validation, always output the result (even if not successful)
@@ -124,5 +175,46 @@ program
     }
   });
 
+// Completion command
+program
+  .command('completion <shell>')
+  .description('Generate shell completion script')
+  .addHelpText('after', `
+Supported shells:
+  bash    Bash completion script
+  zsh     Zsh completion script
+
+Examples:
+  $ vcluster-yaml completion bash > ~/.vcluster-yaml-completion.bash
+  $ vcluster-yaml completion zsh > ~/.zsh/completion/_vcluster-yaml
+  $ vcluster-yaml completion bash --help
+  `)
+  .action((shell) => {
+    const validShells = ['bash', 'zsh'];
+
+    if (!validShells.includes(shell)) {
+      console.error(`Error: Unsupported shell "${shell}". Supported shells: ${validShells.join(', ')}`);
+      console.error('');
+      console.error('Examples:');
+      console.error('  vcluster-yaml completion bash > ~/.vcluster-yaml-completion.bash');
+      console.error('  vcluster-yaml completion zsh > ~/.zsh/completion/_vcluster-yaml');
+      process.exit(1);
+    }
+
+    let script;
+    if (shell === 'bash') {
+      script = generateBashCompletion();
+    } else if (shell === 'zsh') {
+      script = generateZshCompletion();
+    }
+
+    // Output the script
+    console.log(script);
+
+    // Add installation instructions to stderr so they don't end up in the script
+    console.error('');
+    console.error(getInstallInstructions(shell));
+  });
+
 // Parse arguments
 program.parse();

package/src/completions.js

@@ -0,0 +1,234 @@
+/**
+ * Shell completion generators
+ * Generates bash and zsh completion scripts for vcluster-yaml CLI
+ */
+
+/**
+ * Generate bash completion script
+ * @returns {string} Bash completion script
+ */
+export function generateBashCompletion() {
+  return `# vcluster-yaml bash completion
+
+_vcluster_yaml_completions() {
+    local cur prev words cword
+    _init_completion || return
+
+    # Available commands
+    local commands="query list-versions validate help"
+
+    # Available format options
+    local formats="json yaml table"
+
+    case "\${cword}" in
+        1)
+            # First argument: complete commands
+            COMPREPLY=($(compgen -W "\${commands}" -- "\${cur}"))
+            return 0
+            ;;
+        *)
+            # Handle options based on previous word
+            case "\${prev}" in
+                -f|--format)
+                    # Complete format options
+                    COMPREPLY=($(compgen -W "\${formats}" -- "\${cur}"))
+                    return 0
+                    ;;
+                -s|--schema-version)
+                    # Complete common versions (user can type others)
+                    COMPREPLY=($(compgen -W "main v0.28.0 v0.29.0 v0.30.0" -- "\${cur}"))
+                    return 0
+                    ;;
+                --file)
+                    # Complete YAML files
+                    COMPREPLY=($(compgen -f -X '!*.yaml' -- "\${cur}"))
+                    COMPREPLY+=($(compgen -f -X '!*.yml' -- "\${cur}"))
+                    return 0
+                    ;;
+                validate)
+                    # After validate command, complete YAML files or options
+                    if [[ "\${cur}" == -* ]]; then
+                        COMPREPLY=($(compgen -W "-s --schema-version -f --format -h --help" -- "\${cur}"))
+                    else
+                        COMPREPLY=($(compgen -f -X '!*.yaml' -- "\${cur}"))
+                        COMPREPLY+=($(compgen -f -X '!*.yml' -- "\${cur}"))
+                        [[ "\${cur}" == "" || "\${cur}" == "-" ]] && COMPREPLY+=("-")
+                    fi
+                    return 0
+                    ;;
+                query)
+                    # After query command, complete options
+                    if [[ "\${cur}" == -* ]]; then
+                        COMPREPLY=($(compgen -W "--file -s --schema-version -f --format -h --help" -- "\${cur}"))
+                    fi
+                    return 0
+                    ;;
+                list-versions)
+                    # After list-versions command, complete options
+                    COMPREPLY=($(compgen -W "-f --format -h --help" -- "\${cur}"))
+                    return 0
+                    ;;
+            esac
+            ;;
+    esac
+
+    # Default: suggest options if starting with -
+    if [[ "\${cur}" == -* ]]; then
+        COMPREPLY=($(compgen -W "-V --version -h --help" -- "\${cur}"))
+        return 0
+    fi
+}
+
+complete -F _vcluster_yaml_completions vcluster-yaml
+`;
+}
+
+/**
+ * Generate zsh completion script
+ * @returns {string} Zsh completion script
+ */
+export function generateZshCompletion() {
+  return `#compdef vcluster-yaml
+
+# vcluster-yaml zsh completion
+
+_vcluster_yaml() {
+    local -a commands
+    commands=(
+        'query:Search for vCluster configuration fields'
+        'list-versions:List available vCluster versions'
+        'validate:Validate vCluster configuration'
+        'help:Display help for command'
+    )
+
+    local -a formats
+    formats=(
+        'json:JSON output format'
+        'yaml:YAML output format'
+        'table:Table output format'
+    )
+
+    local -a versions
+    versions=(
+        'main:Latest development version'
+        'v0.28.0:Version 0.28.0'
+        'v0.29.0:Version 0.29.0'
+        'v0.30.0:Version 0.30.0'
+    )
+
+    _arguments -C \\
+        '(-V --version)'{-V,--version}'[output the version number]' \\
+        '(-h --help)'{-h,--help}'[display help for command]' \\
+        '1: :->command' \\
+        '*:: :->args'
+
+    case $state in
+        command)
+            _describe 'vcluster-yaml commands' commands
+            ;;
+        args)
+            case $words[1] in
+                query)
+                    _arguments \\
+                        '--file[Configuration file to search]:file:_files -g "*.yaml *.yml"' \\
+                        '(-s --schema-version)'{-s,--schema-version}'[vCluster version or branch]:version:->versions' \\
+                        '(-f --format)'{-f,--format}'[Output format]:format:->formats' \\
+                        '(-h --help)'{-h,--help}'[display help]' \\
+                        '1:query string:'
+
+                    case $state in
+                        formats)
+                            _describe 'output formats' formats
+                            ;;
+                        versions)
+                            _describe 'vCluster versions' versions
+                            ;;
+                    esac
+                    ;;
+                list-versions)
+                    _arguments \\
+                        '(-f --format)'{-f,--format}'[Output format]:format:->formats' \\
+                        '(-h --help)'{-h,--help}'[display help]'
+
+                    case $state in
+                        formats)
+                            _describe 'output formats' formats
+                            ;;
+                    esac
+                    ;;
+                validate)
+                    _arguments \\
+                        '(-s --schema-version)'{-s,--schema-version}'[vCluster version for schema]:version:->versions' \\
+                        '(-f --format)'{-f,--format}'[Output format]:format:->formats' \\
+                        '(-h --help)'{-h,--help}'[display help]' \\
+                        '1:file:_files -g "*.yaml *.yml"'
+
+                    case $state in
+                        formats)
+                            _describe 'output formats' formats
+                            ;;
+                        versions)
+                            _describe 'vCluster versions' versions
+                            ;;
+                    esac
+                    ;;
+                help)
+                    _describe 'vcluster-yaml commands' commands
+                    ;;
+            esac
+            ;;
+    esac
+}
+
+_vcluster_yaml "$@"
+`;
+}
+
+/**
+ * Display installation instructions for a shell
+ * @param {string} shell - Shell type (bash or zsh)
+ * @returns {string} Installation instructions
+ */
+export function getInstallInstructions(shell) {
+  if (shell === 'bash') {
+    return `
+Bash Completion Installation:
+
+1. Save the completion script:
+   $ vcluster-yaml completion bash > ~/.vcluster-yaml-completion.bash
+
+2. Source it in your ~/.bashrc:
+   $ echo 'source ~/.vcluster-yaml-completion.bash' >> ~/.bashrc
+
+3. Reload your shell:
+   $ source ~/.bashrc
+
+Or install system-wide (requires sudo):
+   $ sudo vcluster-yaml completion bash > /etc/bash_completion.d/vcluster-yaml
+`;
+  }
+
+  if (shell === 'zsh') {
+    return `
+Zsh Completion Installation:
+
+1. Create completion directory if needed:
+   $ mkdir -p ~/.zsh/completion
+
+2. Save the completion script:
+   $ vcluster-yaml completion zsh > ~/.zsh/completion/_vcluster-yaml
+
+3. Add to fpath in your ~/.zshrc (before compinit):
+   fpath=(~/.zsh/completion $fpath)
+   autoload -Uz compinit && compinit
+
+4. Reload your shell:
+   $ exec zsh
+
+Or install system-wide (requires sudo):
+   $ sudo vcluster-yaml completion zsh > /usr/local/share/zsh/site-functions/_vcluster-yaml
+`;
+  }
+
+  return 'Unsupported shell. Available: bash, zsh';
+}