@boolesai/tspec-cli 1.2.0 → 1.3.0

package/README.md

@@ -17,6 +17,120 @@ Or run directly with npx:
 npx @boolesai/tspec-cli <command>
 ```
 
+## Plugin Installation
+
+TSpec uses a plugin architecture to support different protocols. Plugins can be installed automatically or manually.
+
+### Installing Plugins via CLI
+
+The easiest way to install plugins is using the `plugin:install` command:
+
+```bash
+# Install HTTP/HTTPS protocol plugin
+tspec plugin:install @tspec/http
+
+# Install Web browser UI testing plugin  
+tspec plugin:install @tspec/web
+
+# Install and add to global config
+tspec plugin:install @tspec/http --global
+```
+
+### Manual Installation
+
+You can also install plugins manually as npm packages:
+
+```bash
+# Install HTTP/HTTPS protocol plugin
+npm install -D @tspec/http
+
+# Install Web browser UI testing plugin
+npm install -D @tspec/web
+
+# Install multiple plugins at once
+npm install -D @tspec/http @tspec/web
+```
+
+### Plugin Configuration
+
+TSpec uses JSON configuration files. Create a `tspec.config.json` file in your project root:
+
+```json
+{
+  "plugins": [
+    "@tspec/http",
+    "@tspec/web"
+  ],
+  "pluginOptions": {
+    "@tspec/http": {
+      "timeout": 30000,
+      "followRedirects": true,
+      "maxRedirects": 5
+    },
+    "@tspec/web": {
+      "headless": true,
+      "timeout": 30000,
+      "slowMo": 0
+    }
+  }
+}
+```
+
+#### Configuration Locations
+
+TSpec supports dual configuration with local taking precedence:
+
+| Location | Path | Priority |
+|----------|------|----------|
+| Local | `./tspec.config.json` (searched upward) | Higher |
+| Global | `~/.tspec/tspec.config.json` | Lower |
+
+When both configs exist, they are merged with local values overriding global ones.
+
+#### Auto-Installation
+
+When running `tspec run`, missing plugins in your config are automatically installed to `~/.tspec/plugins/`. Use `--no-auto-install` to disable this behavior.
+
+### Available Official Plugins
+
+| Plugin | Protocol | Description | Package |
+|--------|----------|-------------|----------|
+| HTTP/HTTPS | `http`, `https` | REST API testing with axios | `@tspec/http` |
+| Web UI | `web` | Browser testing with Puppeteer | `@tspec/web` |
+
+### Using Plugins
+
+Once installed and configured, plugins are automatically loaded when running tests:
+
+```bash
+# Run HTTP tests
+tspec run tests/**/*.http.tcase
+
+# Run Web UI tests
+tspec run tests/**/*.web.tcase
+
+# List loaded plugins and supported protocols
+tspec list
+```
+
+### Custom Plugins
+
+You can also install custom third-party plugins or create your own:
+
+```bash
+# Install custom plugin from npm
+tspec plugin:install my-custom-tspec-plugin
+
+# Or use a local plugin path in tspec.config.json:
+{
+  "plugins": [
+    "./plugins/my-custom-protocol"
+  ]
+}
+```
+
+For plugin development details, see the [Plugin Development Guide](../plugins/DEVELOPMENT.md).
+
 ## Commands
 
 ### `tspec validate`
@@ -59,6 +173,8 @@ tspec run <files...> [options]
 - `-v, --verbose` - Verbose output
 - `-q, --quiet` - Only output summary
 - `--fail-fast` - Stop on first failure
+- `--config <path>` - Path to tspec.config.json
+- `--no-auto-install` - Skip automatic plugin installation
 
 **Examples:**
 ```bash
@@ -131,6 +247,62 @@ tspec list
 tspec list --output json
 ```
 
+### `tspec plugin:install`
+
+Install a TSpec plugin and add it to configuration.
+
+```bash
+tspec plugin:install <plugin> [options]
+```
+
+**Options:**
+- `-o, --output <format>` - Output format: `json`, `text` (default: `text`)
+- `-g, --global` - Add plugin to global config (`~/.tspec/tspec.config.json`)
+- `-c, --config <path>` - Path to specific config file to update
+
+**Examples:**
+```bash
+# Install plugin (adds to local config if exists, otherwise global)
+tspec plugin:install @tspec/http
+
+# Install and add to global config
+tspec plugin:install @tspec/web --global
+
+# Install and add to specific config file
+tspec plugin:install @tspec/http --config ./tspec.config.json
+```
+
+### `tspec plugin:list`
+
+List all installed TSpec plugins and configuration sources.
+
+```bash
+tspec plugin:list [options]
+```
+
+**Alias:** `tspec plugins`
+
+**Options:**
+- `-o, --output <format>` - Output format: `json`, `text` (default: `text`)
+- `-v, --verbose` - Show detailed plugin information
+- `--health` - Run health checks on all plugins
+- `-c, --config <path>` - Path to tspec.config.json
+
+**Examples:**
+```bash
+# List installed plugins
+tspec plugin:list
+
+# Show detailed information
+tspec plugin:list --verbose
+
+# Check plugin health status
+tspec plugin:list --health
+
+# JSON output
+tspec plugin:list --output json
+```
+
 ### `tspec mcp`
 
 Start MCP (Model Context Protocol) server for AI tool integration.
@@ -143,7 +315,15 @@ This starts an MCP server over stdio that exposes TSpec commands as tools for AI
 
 ## MCP Integration
 
-TSpec CLI can run as an MCP server, exposing all commands as tools for AI assistants.
+TSpec CLI can run as an MCP (Model Context Protocol) server, exposing all commands as tools for AI assistants. This enables AI assistants like Claude to execute TSpec commands directly through the MCP protocol.
+
+### Overview
+
+The MCP server runs over stdio, providing a standardized interface for AI tools to:
+- Execute test cases with customizable parameters
+- Validate test case files for schema correctness
+- Parse test specifications without execution
+- Query supported protocols and configurations
 
 ### Available Tools
 
@@ -154,12 +334,17 @@ TSpec CLI can run as an MCP server, exposing all commands as tools for AI assist
 | `tspec_parse` | Parse and display test case information |
 | `tspec_list` | List supported protocols |
 
-### Claude Desktop Configuration
+### Configuration
+
+#### Claude Desktop
 
 Add the following to your Claude Desktop configuration file:
 
 **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
 **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+**Linux:** `~/.config/Claude/claude_desktop_config.json`
+
+**Option 1: Using npx (recommended for always getting the latest version):**
 
 ```json
 {
@@ -172,7 +357,7 @@ Add the following to your Claude Desktop configuration file:
 }
 ```
 
-Or if installed globally:
+**Option 2: Using global installation:**
 
 ```json
 {
@@ -185,15 +370,56 @@ Or if installed globally:
 }
 ```
 
+**Option 3: Using absolute path (for development or specific versions):**
+
+```json
+{
+  "mcpServers": {
+    "tspec": {
+      "command": "/path/to/tspec/cli/bin/tspec.js",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+#### Other MCP Clients
+
+For other MCP-compatible clients, start the server with:
+
+```bash
+tspec mcp
+```
+
+The server will communicate via stdio, waiting for JSON-RPC 2.0 formatted requests.
+
+### Server Behavior
+
+- **Transport:** stdio (reads from stdin, writes to stdout)
+- **Protocol:** JSON-RPC 2.0 over MCP
+- **Lifecycle:** Runs indefinitely until explicitly terminated (Ctrl+C or SIGTERM)
+- **Logging:** Error logs are written to stderr to avoid polluting stdio transport
+
 ### Tool Parameters
 
 #### tspec_run
 
+Execute test cases with optional configuration.
+
+**Parameters:**
+- `files` (required): Array of file paths or glob patterns
+- `concurrency` (optional): Maximum concurrent test execution (default: 5)
+- `env` (optional): Environment variables as key-value object
+- `params` (optional): Test parameters as key-value object
+- `failFast` (optional): Stop on first failure (default: false)
+- `output` (optional): Output format - "json" or "text" (default: "text")
+
+**Example:**
 ```json
 {
   "files": ["tests/*.tcase"],
   "concurrency": 5,
-  "env": { "API_HOST": "localhost" },
+  "env": { "API_HOST": "localhost", "API_PORT": "8080" },
   "params": { "timeout": "5000" },
   "failFast": false,
   "output": "text"
@@ -202,6 +428,13 @@ Or if installed globally:
 
 #### tspec_validate
 
+Validate test case files for schema correctness.
+
+**Parameters:**
+- `files` (required): Array of file paths or glob patterns
+- `output` (optional): Output format - "json" or "text" (default: "text")
+
+**Example:**
 ```json
 {
   "files": ["tests/*.tcase"],
@@ -211,6 +444,16 @@ Or if installed globally:
 
 #### tspec_parse
 
+Parse test case files without execution.
+
+**Parameters:**
+- `files` (required): Array of file paths or glob patterns
+- `env` (optional): Environment variables for variable substitution
+- `params` (optional): Parameters for variable substitution
+- `verbose` (optional): Show detailed information (default: false)
+- `output` (optional): Output format - "json" or "text" (default: "text")
+
+**Example:**
 ```json
 {
   "files": ["tests/*.tcase"],
@@ -223,12 +466,35 @@ Or if installed globally:
 
 #### tspec_list
 
+List supported protocols and configuration.
+
+**Parameters:**
+- `output` (optional): Output format - "json" or "text" (default: "text")
+
+**Example:**
 ```json
 {
   "output": "text"
 }
 ```
 
+### Troubleshooting
+
+**Server doesn't appear in Claude Desktop:**
+- Verify the configuration file path is correct for your OS
+- Check JSON syntax is valid (use a JSON validator)
+- Restart Claude Desktop after configuration changes
+- Check Claude Desktop logs for connection errors
+
+**Server hangs or doesn't respond:**
+- Ensure Node.js >= 18.0.0 is installed
+- Verify `@boolesai/tspec-cli` is accessible (try running `tspec --version`)
+- Check stderr output for error messages
+
+**Permission errors:**
+- Ensure the tspec executable has proper permissions
+- For global installation, verify npm global bin directory is in PATH
+
 ## Exit Codes
 
 | Code | Description |

package/dist/index.js

@@ -1,11 +1,12 @@
 import { Command } from "commander";
-import { existsSync, statSync, readFileSync } from "fs";
+import { existsSync, statSync, readFileSync, mkdirSync, writeFileSync } from "fs";
 import { fileURLToPath } from "url";
 import { isAbsolute, resolve as resolve$1, basename, relative, dirname, join } from "path";
 import ora from "ora";
-import { getTypeFromFilePath, isSuiteFile, getSuiteProtocolType, validateTestCase, clearTemplateCache, executeSuite, parseTestCases, scheduler, registry as registry$1 } from "@boolesai/tspec";
+import { getTypeFromFilePath, isSuiteFile, getSuiteProtocolType, validateTestCase, clearTemplateCache, getPluginManager, version as version$1, registry as registry$1, executeSuite, parseTestCases, scheduler, PluginManager } from "@boolesai/tspec";
 import { glob } from "glob";
 import chalk from "chalk";
+import { findConfigFile, findLocalConfigFile, findGlobalConfigFile, PLUGINS_DIR, isPluginInstalled, installPlugin, GLOBAL_CONFIG_PATH } from "@boolesai/tspec/plugin";
 import process$2 from "node:process";
 async function discoverTSpecFiles(patterns, cwd) {
   const workingDir = process.cwd();
@@ -353,6 +354,14 @@ async function runFileTestCasesInternal(descriptor, env, params, concurrency, fa
 }
 async function executeRun(params) {
   clearTemplateCache();
+  const configPath = params.config || findConfigFile();
+  if (configPath) {
+    const pluginManager = getPluginManager(version$1);
+    await pluginManager.initialize(configPath, {
+      skipAutoInstall: params.noAutoInstall
+    });
+    registry$1.enablePluginManager();
+  }
   const concurrency = params.concurrency ?? 5;
   const env = params.env ?? {};
   const paramValues = params.params ?? {};
@@ -573,7 +582,7 @@ ${parseErrors.length} file(s) failed to parse:`);
     data: { results: allResults, summary, parseErrors }
   };
 }
-const runCommand = new Command("run").description("Execute test cases and report results").argument("<files...>", "Files or glob patterns to run").option("-o, --output <format>", "Output format: json, text", "text").option("-c, --concurrency <number>", "Max concurrent tests", "5").option("-e, --env <key=value>", "Environment variables", parseKeyValue$1, {}).option("-p, --params <key=value>", "Parameters", parseKeyValue$1, {}).option("-v, --verbose", "Verbose output").option("-q, --quiet", "Only output summary").option("--fail-fast", "Stop on first failure").action(async (files, options) => {
+const runCommand = new Command("run").description("Execute test cases and report results").argument("<files...>", "Files or glob patterns to run").option("-o, --output <format>", "Output format: json, text", "text").option("-c, --concurrency <number>", "Max concurrent tests", "5").option("-e, --env <key=value>", "Environment variables", parseKeyValue$1, {}).option("-p, --params <key=value>", "Parameters", parseKeyValue$1, {}).option("-v, --verbose", "Verbose output").option("-q, --quiet", "Only output summary").option("--fail-fast", "Stop on first failure").option("--config <path>", "Path to tspec.config.json for plugin loading").option("--no-auto-install", "Skip automatic plugin installation").action(async (files, options) => {
   setLoggerOptions({ verbose: options.verbose, quiet: options.quiet });
   const spinner = options.quiet ? null : ora("Running tests...").start();
   try {
@@ -584,6 +593,8 @@ const runCommand = new Command("run").description("Execute test cases and report
       verbose: options.verbose,
       quiet: options.quiet,
       failFast: options.failFast,
+      config: options.config,
+      noAutoInstall: options.noAutoInstall,
       env: options.env,
       params: options.params
     });
@@ -604,9 +615,20 @@ const runCommand = new Command("run").description("Execute test cases and report
     }
     process.exit(result.success ? 0 : 1);
   } catch (err) {
-    spinner?.fail("Execution failed");
+    spinner?.stop();
     const message = err instanceof Error ? err.message : String(err);
-    logger.error(message);
+    if (options.output === "json") {
+      const errorOutput = formatJson({
+        results: [],
+        summary: { total: 0, passed: 0, failed: 0, passRate: 0, duration: 0 },
+        parseErrors: [],
+        error: message
+      });
+      logger.log(errorOutput);
+    } else {
+      spinner?.fail("Execution failed");
+      logger.error(message);
+    }
     process.exit(2);
   }
 });
@@ -15138,6 +15160,262 @@ const mcpCommand = new Command("mcp").description("Start MCP server for tool int
   setLoggerOptions({ quiet: true });
   await startMcpServer();
 });
+async function executePluginList(params) {
+  const output = params.output ?? "text";
+  const pluginManager = new PluginManager(version$1);
+  const localConfigPath = findLocalConfigFile();
+  const globalConfigPath = findGlobalConfigFile();
+  const configPath = params.config || localConfigPath || globalConfigPath;
+  let loadSummary;
+  if (configPath) {
+    loadSummary = await pluginManager.initialize(configPath);
+  }
+  const plugins = pluginManager.list();
+  const protocols = pluginManager.listProtocols();
+  let healthReports;
+  if (params.health) {
+    healthReports = await pluginManager.healthCheck();
+  }
+  const data = {
+    plugins: plugins.map((p) => ({
+      name: p.name,
+      version: p.version,
+      description: p.description,
+      protocols: p.protocols,
+      author: p.author,
+      homepage: p.homepage
+    })),
+    protocols,
+    configPath: configPath || void 0,
+    configSources: {
+      local: localConfigPath || void 0,
+      global: globalConfigPath || void 0
+    },
+    pluginsDir: PLUGINS_DIR,
+    health: healthReports
+  };
+  let outputStr;
+  if (output === "json") {
+    outputStr = JSON.stringify(data, null, 2);
+  } else {
+    outputStr = formatPluginListText(data, params.verbose ?? false, loadSummary);
+  }
+  return {
+    success: true,
+    output: outputStr,
+    data
+  };
+}
+function formatPluginListText(data, verbose, loadSummary) {
+  const lines = [];
+  lines.push(chalk.bold("\nTSpec Plugins\n"));
+  lines.push(chalk.bold("Config:"));
+  if (data.configSources?.local) {
+    lines.push(chalk.gray(`  Local:  ${data.configSources.local}`));
+  } else {
+    lines.push(chalk.gray("  Local:  (none)"));
+  }
+  if (data.configSources?.global) {
+    lines.push(chalk.gray(`  Global: ${data.configSources.global}`));
+  } else {
+    lines.push(chalk.gray("  Global: (none)"));
+  }
+  lines.push(chalk.gray(`  Plugins dir: ${data.pluginsDir}`));
+  if (loadSummary) {
+    lines.push("");
+    lines.push(chalk.gray(`Discovered: ${loadSummary.total}, Loaded: ${loadSummary.loaded}`));
+    if (loadSummary.installed && loadSummary.installed > 0) {
+      lines.push(chalk.green(`Installed: ${loadSummary.installed} plugin(s)`));
+    }
+    if (loadSummary.failed > 0) {
+      lines.push(chalk.red(`Failed: ${loadSummary.failed}`));
+      for (const error2 of loadSummary.errors) {
+        lines.push(chalk.red(`  ${error2.plugin}: ${error2.error}`));
+      }
+    }
+    if (loadSummary.installErrors && loadSummary.installErrors.length > 0) {
+      lines.push(chalk.red(`Install failures:`));
+      for (const error2 of loadSummary.installErrors) {
+        lines.push(chalk.red(`  ${error2.plugin}: ${error2.error}`));
+      }
+    }
+  }
+  lines.push("");
+  if (data.plugins.length === 0) {
+    lines.push(chalk.yellow("No plugins loaded."));
+    lines.push(chalk.gray("Add plugins to your tspec.config.json:"));
+    lines.push(chalk.gray("  {"));
+    lines.push(chalk.gray('    "plugins": ["@tspec/http", "@tspec/web"]'));
+    lines.push(chalk.gray("  }"));
+  } else {
+    for (const plugin of data.plugins) {
+      lines.push(`${chalk.cyan(plugin.name)} ${chalk.gray(`v${plugin.version}`)}`);
+      if (verbose && plugin.description) {
+        lines.push(`  ${plugin.description}`);
+      }
+      lines.push(`  Protocols: ${plugin.protocols.join(", ")}`);
+      if (verbose) {
+        if (plugin.author) {
+          lines.push(`  Author: ${plugin.author}`);
+        }
+        if (plugin.homepage) {
+          lines.push(`  Homepage: ${plugin.homepage}`);
+        }
+      }
+      lines.push("");
+    }
+  }
+  if (data.health) {
+    lines.push(chalk.bold("Health Check\n"));
+    for (const report of data.health) {
+      const status = report.healthy ? chalk.green("✓ Healthy") : chalk.red("✗ Unhealthy");
+      lines.push(`${chalk.cyan(report.plugin)}: ${status}`);
+      if (report.message) {
+        lines.push(`  ${report.message}`);
+      }
+    }
+    lines.push("");
+  }
+  if (data.protocols.length > 0) {
+    lines.push(chalk.bold("Supported Protocols: ") + data.protocols.join(", "));
+  }
+  return lines.join("\n");
+}
+const pluginListCommand = new Command("plugin:list").alias("plugins").description("List all installed TSpec plugins").option("-o, --output <format>", "Output format: json, text", "text").option("-v, --verbose", "Show detailed plugin information").option("--health", "Run health checks on all plugins").option("-c, --config <path>", "Path to tspec.config.json").action(async (options) => {
+  try {
+    const result = await executePluginList({
+      output: options.output,
+      verbose: options.verbose,
+      health: options.health,
+      config: options.config
+    });
+    logger.log(result.output);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    logger.error(`Failed to list plugins: ${message}`);
+    process.exit(2);
+  }
+});
+function loadConfigFile(configPath) {
+  if (!existsSync(configPath)) {
+    return { plugins: [], pluginOptions: {} };
+  }
+  try {
+    const content = readFileSync(configPath, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return { plugins: [], pluginOptions: {} };
+  }
+}
+function saveConfigFile(configPath, config2) {
+  const dir = configPath.substring(0, configPath.lastIndexOf("/"));
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(configPath, JSON.stringify(config2, null, 2) + "\n");
+}
+function addPluginToConfig(config2, pluginName) {
+  if (!config2.plugins) {
+    config2.plugins = [];
+  }
+  if (config2.plugins.includes(pluginName)) {
+    return false;
+  }
+  config2.plugins.push(pluginName);
+  return true;
+}
+async function executePluginInstall(params) {
+  const { pluginName, output = "text", global: useGlobal = false, config: customConfig } = params;
+  let configPath;
+  if (customConfig) {
+    configPath = customConfig;
+  } else if (useGlobal) {
+    configPath = GLOBAL_CONFIG_PATH;
+  } else {
+    const localConfig = findLocalConfigFile();
+    configPath = localConfig || GLOBAL_CONFIG_PATH;
+  }
+  const alreadyInstalled = isPluginInstalled(pluginName);
+  let installed = false;
+  let installError;
+  if (!alreadyInstalled) {
+    const result = await installPlugin(pluginName);
+    installed = result.success;
+    if (!result.success) {
+      installError = result.error;
+    }
+  } else {
+    installed = true;
+  }
+  let configUpdated = false;
+  if (installed) {
+    const config2 = loadConfigFile(configPath);
+    configUpdated = addPluginToConfig(config2, pluginName);
+    if (configUpdated) {
+      saveConfigFile(configPath, config2);
+    }
+  }
+  const data = {
+    plugin: pluginName,
+    installed,
+    configUpdated,
+    configPath: installed ? configPath : void 0,
+    error: installError
+  };
+  let outputStr;
+  if (output === "json") {
+    outputStr = JSON.stringify(data, null, 2);
+  } else {
+    if (!installed) {
+      outputStr = chalk.red(`Failed to install ${pluginName}: ${installError || "Unknown error"}`);
+    } else if (alreadyInstalled && !configUpdated) {
+      outputStr = chalk.yellow(`Plugin ${pluginName} is already installed and configured.`);
+    } else if (alreadyInstalled && configUpdated) {
+      outputStr = [
+        chalk.green(`Plugin ${pluginName} is already installed.`),
+        chalk.green(`Added to config: ${configPath}`)
+      ].join("\n");
+    } else if (configUpdated) {
+      outputStr = [
+        chalk.green(`Successfully installed ${pluginName}`),
+        chalk.green(`Added to config: ${configPath}`)
+      ].join("\n");
+    } else {
+      outputStr = [
+        chalk.green(`Successfully installed ${pluginName}`),
+        chalk.yellow(`Plugin already in config: ${configPath}`)
+      ].join("\n");
+    }
+  }
+  return {
+    success: installed,
+    output: outputStr,
+    data
+  };
+}
+const pluginInstallCommand = new Command("plugin:install").alias("install").description("Install a TSpec plugin and add it to config").argument("<plugin>", "Plugin name (npm package name, e.g., @tspec/http)").option("-o, --output <format>", "Output format: json, text", "text").option("-g, --global", "Add plugin to global config (~/.tspec/tspec.config.json)").option("-c, --config <path>", "Path to config file to update").action(async (plugin, options) => {
+  const spinner = ora(`Installing ${plugin}...`).start();
+  try {
+    const result = await executePluginInstall({
+      pluginName: plugin,
+      output: options.output,
+      global: options.global,
+      config: options.config
+    });
+    spinner.stop();
+    logger.log(result.output);
+    process.exit(result.success ? 0 : 1);
+  } catch (err) {
+    spinner.stop();
+    const message = err instanceof Error ? err.message : String(err);
+    if (options.output === "json") {
+      logger.log(JSON.stringify({ success: false, error: message }, null, 2));
+    } else {
+      logger.error(`Failed to install plugin: ${message}`);
+    }
+    process.exit(2);
+  }
+});
 const __filename$1 = fileURLToPath(import.meta.url);
 const __dirname$1 = dirname(__filename$1);
 const packageJson = JSON.parse(readFileSync(join(__dirname$1, "../package.json"), "utf-8"));
@@ -15148,5 +15426,7 @@ program.addCommand(runCommand);
 program.addCommand(parseCommand);
 program.addCommand(listCommand);
 program.addCommand(mcpCommand);
+program.addCommand(pluginListCommand);
+program.addCommand(pluginInstallCommand);
 await program.parseAsync();
 //# sourceMappingURL=index.js.map