vcluster-yaml-mcp-server 1.3.2 → 1.4.0

package/dist/cli-handlers.d.ts

@@ -0,0 +1,22 @@
+/**
+ * CLI handlers that bridge CLI commands to underlying logic
+ * Reuses githubClient and validation logic from server.js
+ * Returns structured data for CLI formatters
+ */
+import type { CliQueryOptions, CliValidateOptions, CliResult } from './types/index.js';
+/**
+ * Handle query command
+ * Searches for configuration fields in vCluster YAML
+ */
+export declare function handleQuery(query: string, options: CliQueryOptions): Promise<CliResult>;
+/**
+ * Handle list-versions command
+ * Lists available vCluster versions from GitHub
+ */
+export declare function handleListVersions(): Promise<CliResult>;
+/**
+ * Handle validate command
+ * Validates vCluster YAML configuration
+ */
+export declare function handleValidate(content: string, options: CliValidateOptions): Promise<CliResult>;
+//# sourceMappingURL=cli-handlers.d.ts.map

package/dist/cli-handlers.js

@@ -0,0 +1,258 @@
+/**
+ * CLI handlers that bridge CLI commands to underlying logic
+ * Reuses githubClient and validation logic from server.js
+ * Returns structured data for CLI formatters
+ */
+import yaml from 'js-yaml';
+import { githubClient } from './github.js';
+import { validateSnippet } from './snippet-validator.js';
+// Helper function to get the type of a value
+function getType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    if (typeof value === 'object')
+        return 'object';
+    if (typeof value === 'number') {
+        return Number.isInteger(value) ? 'integer' : 'number';
+    }
+    return typeof value;
+}
+// Helper function to rank search results
+function rankResult(item, searchTerm) {
+    const pathLower = item.path.toLowerCase();
+    const keyLower = item.key.toLowerCase();
+    let score = 0;
+    // Exact match
+    if (pathLower === searchTerm || keyLower === searchTerm) {
+        score += 100;
+    }
+    // Starts with search term
+    if (pathLower.startsWith(searchTerm) || keyLower.startsWith(searchTerm)) {
+        score += 50;
+    }
+    // Ends with search term
+    if (pathLower.endsWith(searchTerm) || keyLower.endsWith(searchTerm)) {
+        score += 40;
+    }
+    // Contains search term
+    if (pathLower.includes(searchTerm) || keyLower.includes(searchTerm)) {
+        score += 30;
+    }
+    // Prefer leaf nodes (actual values)
+    if (item.isLeaf) {
+        score += 10;
+    }
+    // Prefer shorter paths (more specific)
+    const pathDepth = item.path.split('.').length;
+    score -= pathDepth;
+    return score;
+}
+/**
+ * Handle query command
+ * Searches for configuration fields in vCluster YAML
+ */
+export async function handleQuery(query, options) {
+    const version = options.version || 'main';
+    const fileName = options.file || 'chart/values.yaml';
+    let yamlData;
+    try {
+        yamlData = await githubClient.getYamlContent(fileName, version);
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Could not load ${fileName} from GitHub (version: ${version}). Error: ${error instanceof Error ? error.message : String(error)}`,
+            metadata: {
+                query,
+                file: fileName,
+                version
+            }
+        };
+    }
+    const searchTerm = query.toLowerCase();
+    const results = [];
+    // Helper function to extract all paths and values
+    function extractInfo(obj, path = '') {
+        const info = [];
+        if (obj && typeof obj === 'object' && !Array.isArray(obj)) {
+            for (const [key, value] of Object.entries(obj)) {
+                const currentPath = path ? `${path}.${key}` : key;
+                if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                    info.push({ path: currentPath, key, value, isLeaf: false });
+                    info.push(...extractInfo(value, currentPath));
+                }
+                else {
+                    info.push({ path: currentPath, key, value, isLeaf: true });
+                }
+            }
+        }
+        return info;
+    }
+    const allInfo = extractInfo(yamlData);
+    // Support dot notation queries
+    const isDotNotation = searchTerm.includes('.');
+    if (isDotNotation) {
+        // Exact and partial dot notation matching
+        for (const item of allInfo) {
+            const pathLower = item.path.toLowerCase();
+            if (pathLower === searchTerm ||
+                pathLower.endsWith(searchTerm) ||
+                pathLower.includes(searchTerm)) {
+                results.push(item);
+            }
+        }
+    }
+    else {
+        // Keyword-based search
+        const keywords = searchTerm.split(/\s+/);
+        for (const item of allInfo) {
+            const pathLower = item.path.toLowerCase();
+            const keyLower = item.key.toLowerCase();
+            const valueStr = JSON.stringify(item.value).toLowerCase();
+            const allKeywordsMatch = keywords.every(kw => pathLower.includes(kw) || keyLower.includes(kw) || valueStr.includes(kw));
+            if (allKeywordsMatch) {
+                results.push(item);
+            }
+        }
+    }
+    // Sort results by relevance
+    results.sort((a, b) => {
+        const scoreA = rankResult(a, searchTerm);
+        const scoreB = rankResult(b, searchTerm);
+        return scoreB - scoreA;
+    });
+    // Format results for CLI output
+    const formattedResults = results.slice(0, 50).map(item => ({
+        field: item.path,
+        value: item.value,
+        type: getType(item.value),
+        path: item.path,
+        description: '' // Could be enhanced with comments parsing
+    }));
+    return {
+        success: true,
+        results: formattedResults,
+        metadata: {
+            query,
+            file: fileName,
+            version,
+            resultCount: formattedResults.length,
+            totalMatches: results.length
+        }
+    };
+}
+/**
+ * Handle list-versions command
+ * Lists available vCluster versions from GitHub
+ */
+export async function handleListVersions() {
+    try {
+        const tags = await githubClient.getTags();
+        // Only show versions starting with 'v'
+        const versionTags = tags.filter(tag => tag.startsWith('v'));
+        // Always include main branch
+        const versions = ['main', ...versionTags];
+        return {
+            success: true,
+            versions,
+            metadata: {
+                totalCount: versions.length,
+                source: 'github'
+            }
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to fetch versions: ${error instanceof Error ? error.message : String(error)}`,
+            versions: [],
+            metadata: {
+                totalCount: 0,
+                source: 'github'
+            }
+        };
+    }
+}
+/**
+ * Handle validate command
+ * Validates vCluster YAML configuration
+ */
+export async function handleValidate(content, options) {
+    const version = options.version || 'main';
+    // Validate YAML syntax first
+    try {
+        yaml.load(content);
+    }
+    catch (error) {
+        return {
+            success: false,
+            valid: false,
+            errors: [
+                {
+                    path: 'root',
+                    message: error instanceof Error ? error.message : String(error),
+                    type: 'syntax'
+                }
+            ],
+            metadata: {
+                version,
+                contentLength: content.length
+            }
+        };
+    }
+    // Fetch schema for validation
+    try {
+        const schemaContent = await githubClient.getFileContent('chart/values.schema.json', version);
+        const fullSchema = JSON.parse(schemaContent);
+        // Use snippet validator
+        const result = validateSnippet(content, fullSchema, version);
+        if (result.valid) {
+            return {
+                success: true,
+                valid: true,
+                errors: [],
+                metadata: {
+                    version,
+                    contentLength: content.length
+                }
+            };
+        }
+        else {
+            // Format errors for CLI
+            const errors = (result.errors || []).map(err => ({
+                path: err.path || 'root',
+                message: err.message || 'Validation error',
+                type: err.keyword || 'validation'
+            }));
+            return {
+                success: true,
+                valid: false,
+                errors,
+                metadata: {
+                    version,
+                    contentLength: content.length
+                }
+            };
+        }
+    }
+    catch (error) {
+        return {
+            success: false,
+            valid: false,
+            errors: [
+                {
+                    path: 'root',
+                    message: `Failed to load schema: ${error instanceof Error ? error.message : String(error)}`,
+                    type: 'schema-error'
+                }
+            ],
+            metadata: {
+                version,
+                contentLength: content.length
+            }
+        };
+    }
+}
+//# sourceMappingURL=cli-handlers.js.map

package/dist/cli-utils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * CLI utility functions
+ * Provides helpers for stdin reading and file operations
+ */
+export interface ContentSource {
+    content: string;
+    source: string;
+}
+/**
+ * Read content from stdin
+ * Used for piping content to CLI commands
+ */
+export declare function readStdin(): Promise<string>;
+/**
+ * Read content from a file or stdin based on the file argument
+ */
+export declare function readContentSource(file?: string): Promise<ContentSource>;
+//# sourceMappingURL=cli-utils.d.ts.map

package/dist/cli-utils.js

@@ -0,0 +1,52 @@
+/**
+ * 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
+ */
+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
+ */
+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 instanceof Error ? error.message : String(error)}`);
+    }
+}
+//# sourceMappingURL=cli-utils.js.map

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * vCluster CLI - Standalone command-line interface
+ * Provides query, validate, and list-versions commands
+ * Wraps MCP server functionality with user-friendly CLI
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+/**
+ * vCluster CLI - Standalone command-line interface
+ * Provides query, validate, and list-versions commands
+ * Wraps MCP server functionality with user-friendly CLI
+ */
+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(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('-s, --schema-version <version>', 'vCluster version or branch', 'main')
+    .option('-f, --format <format>', 'Output format: json, yaml, table (default: table)', 'table')
+    .addHelpText('after', `
+Examples:
+  $ vcluster-yaml query sync
+  $ vcluster-yaml query sync --schema-version v0.24.0
+  $ vcluster-yaml query "controlPlane.replicas"
+  `)
+    .action(async (query, options) => {
+    try {
+        const format = options.format;
+        // Validate format option
+        if (!['json', 'yaml', 'table'].includes(format)) {
+            console.error(`Error: Invalid format "${format}". Must be one of: json, yaml, table`);
+            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 || 'chart/values.yaml',
+            version: options.schemaVersion || 'main'
+        });
+        if (!result.success) {
+            // Error case - output error message and exit with code 1
+            if (format === 'json') {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                console.error(result.error);
+            }
+            process.exit(1);
+        }
+        const output = formatOutput(result, format, 'query');
+        console.log(output);
+        process.exit(0);
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    }
+});
+// List versions command
+program
+    .command('list-versions')
+    .description('List available vCluster versions')
+    .option('-f, --format <format>', 'Output format: json, yaml, table (default: table)', 'table')
+    .action(async (options) => {
+    try {
+        const format = options.format;
+        // Validate format option
+        if (!['json', 'yaml', 'table'].includes(format)) {
+            console.error(`Error: Invalid format "${format}". Must be one of: json, yaml, table`);
+            process.exit(1);
+        }
+        const result = await handleListVersions();
+        if (!result.success) {
+            if (format === 'json') {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                console.error(result.error);
+            }
+            process.exit(1);
+        }
+        const output = formatOutput(result, format, 'list-versions');
+        console.log(output);
+        process.exit(0);
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    }
+});
+// Validate command
+program
+    .command('validate [file]')
+    .description('Validate vCluster configuration')
+    .option('-s, --schema-version <version>', 'vCluster version for schema', 'main')
+    .option('-f, --format <format>', 'Output format: json, yaml, table (default: table)', 'table')
+    .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
+  `)
+    .action(async (file, options) => {
+    try {
+        const format = options.format;
+        // Validate format option
+        if (!['json', 'yaml', 'table'].includes(format)) {
+            console.error(`Error: Invalid format "${format}". Must be one of: json, yaml, table`);
+            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 instanceof Error ? error.message : String(error)}`);
+            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.schemaVersion || 'main'
+        });
+        // For validation, always output the result (even if not successful)
+        // The formatOutput will handle error cases appropriately
+        const output = formatOutput(result, format, 'validate');
+        console.log(output);
+        // Exit with code 1 if validation failed OR if we couldn't load schema
+        if (!result.success || !result.valid) {
+            process.exit(1);
+        }
+        process.exit(0);
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    }
+});
+// 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 {
+        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();
+//# sourceMappingURL=cli.js.map

package/dist/completions.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shell completion generators
+ * Generates bash and zsh completion scripts for vcluster-yaml CLI
+ */
+/**
+ * Generate bash completion script
+ */
+export declare function generateBashCompletion(): string;
+/**
+ * Generate zsh completion script
+ */
+export declare function generateZshCompletion(): string;
+/**
+ * Display installation instructions for a shell
+ */
+export declare function getInstallInstructions(shell: string): string;
+//# sourceMappingURL=completions.d.ts.map

package/{src → dist}/completions.js

@@ -2,13 +2,11 @@
  * 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
+    return `# vcluster-yaml bash completion
 
 _vcluster_yaml_completions() {
     local cur prev words cword
@@ -82,13 +80,11 @@ _vcluster_yaml_completions() {
 complete -F _vcluster_yaml_completions vcluster-yaml
 `;
 }
-
 /**
  * Generate zsh completion script
- * @returns {string} Zsh completion script
  */
 export function generateZshCompletion() {
-  return `#compdef vcluster-yaml
+    return `#compdef vcluster-yaml
 
 # vcluster-yaml zsh completion
 
@@ -183,15 +179,12 @@ _vcluster_yaml() {
 _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 `
+    if (shell === 'bash') {
+        return `
 Bash Completion Installation:
 
 1. Save the completion script:
@@ -206,10 +199,9 @@ Bash Completion Installation:
 Or install system-wide (requires sudo):
    $ sudo vcluster-yaml completion bash > /etc/bash_completion.d/vcluster-yaml
 `;
-  }
-
-  if (shell === 'zsh') {
-    return `
+    }
+    if (shell === 'zsh') {
+        return `
 Zsh Completion Installation:
 
 1. Create completion directory if needed:
@@ -228,7 +220,7 @@ Zsh Completion Installation:
 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';
+    }
+    return 'Unsupported shell. Available: bash, zsh';
 }
+//# sourceMappingURL=completions.js.map