@seed-ship/mcp-ui-cli 1.0.13 → 1.1.0

package/CHANGELOG.md

@@ -1,11 +1,82 @@
-# @mcp-ui/cli Changelog
+# @seed-ship/mcp-ui-cli Changelog
 
 All notable changes to this project will be documented in this file.
 
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - 2025-11-25
+
+### Documentation
+- **Comprehensive README Rewrite**: Complete documentation overhaul
+  - Fixed npm scope from `@mcp-ui/cli` to `@seed-ship/mcp-ui-cli`
+  - Removed non-existent `create-component` command (was documented but never implemented)
+  - Documented all 4 commands with full options and examples
+  - Added Programmatic API section with TypeScript examples
+  - Added CI/CD Integration section with GitHub Actions example
+  - Documented exit codes for automation
+
+### Notes
+- This minor version bump marks a documentation milestone
+- No CLI changes - all commands identical to v1.0.14
+
+## [1.0.14] - 2025-11-24
+
+### Changed
+- Version bump (synchronized with mcp-ui-solid v1.0.26, mcp-ui-spec v1.0.15)
+
+## [1.0.13] - 2025-11-23
+
+### Changed
+- Version bump (synchronized with mcp-ui-solid v1.0.25, mcp-ui-spec v1.0.14)
+
+## [1.0.11] - 2025-11-23
+
+### Changed
+- Version bump for npm publication with updated token
+- Synchronized with mcp-ui-solid v1.0.23, mcp-ui-spec v1.0.12
+
+## [1.0.10] - 2025-11-23
+
+### Changed
+- Version bump (synchronized with mcp-ui-solid v1.0.22, mcp-ui-spec v1.0.11)
+
+## [1.0.9] - 2025-11-23
+
+### Changed
+- Version bump (synchronized with mcp-ui-solid v1.0.21, mcp-ui-spec v1.0.10)
+
+## [1.0.8] - 2025-11-22
+
+### Changed
+- Version bump (synchronized with mcp-ui-solid v1.0.18, mcp-ui-spec v1.0.8)
+
+## [1.0.6] - 2025-11-22
+
+### Changed
+- Version bump for npm publication
+
+## [1.0.5] - 2025-11-22
+
+### Changed
+- Version bump
+
+## [1.0.2] - 2025-11-17
+
+### Changed
+- Migrate to `@seed-ship` npm scope
+- Updated package name from `@mcp-ui/cli` to `@seed-ship/mcp-ui-cli`
+
+## [1.0.1] - 2025-11-16
+
+### Fixed
+- Add type definitions generation for all packages
+- Correct schema validation tests
+
 ## [1.0.0] - 2025-01-14
 
 ### Added
-- Initial release of `@mcp-ui/cli` package
+- Initial release of `@seed-ship/mcp-ui-cli` package
 - Command-line interface for component registry operations
 - `validate` command: Validates registries against JSON Schema and Zod
 - `generate-types` command: Generates TypeScript types from component schemas
@@ -14,63 +85,24 @@ All notable changes to this project will be documented in this file.
 
 ### Features
 - **Dual Validation**: Both JSON Schema (Ajv) and Zod validation
-- **Type Generation**: Automatic TypeScript type generation with json-schema-to-typescript
+- **Type Generation**: Automatic TypeScript type generation
 - **Example Testing**: Validates all component examples against schemas
-- **Breaking Change Detection**: Semantic diff with breaking/non-breaking classification
+- **Breaking Change Detection**: Semantic diff with classification
 - **Beautiful Output**: Colorful terminal output with chalk and ora spinners
-- **Exit Codes**: Proper exit codes for CI/CD integration
-- **Verbose Mode**: Detailed output for debugging
+- **CI/CD Ready**: Proper exit codes for automation
 
 ### Commands
 
-#### validate
-```bash
-mcp-ui validate <file> [--strict] [--verbose]
-```
-Validates a component registry against both JSON Schema and Zod schemas.
-
-#### generate-types
-```bash
-mcp-ui generate-types <input> [output] [--namespace <name>] [--export-all]
-```
-Generates TypeScript types from component schemas.
-
-#### test-examples
-```bash
-mcp-ui test-examples <file> [--component <id>] [--verbose]
-```
-Tests all examples in a component registry.
-
-#### diff
-```bash
-mcp-ui diff <old> <new> [--json] [--fail-on-breaking]
-```
-Compares two registry versions for breaking changes.
-
-### Dependencies
-- commander: CLI framework
-- ajv: JSON Schema validation
-- zod: Runtime TypeScript validation
-- json-schema-to-typescript: Type generation
-- chalk: Terminal colors
-- ora: Spinners
-
-### Installation
-```bash
-pnpm add -D @mcp-ui/cli
-```
-
-### Usage
 ```bash
 # Validate a registry
-mcp-ui validate ./my-registry.json
+mcp-ui validate <file> [--strict] [--verbose]
 
-# Generate types
-mcp-ui generate-types ./my-registry.json ./types.ts
+# Generate TypeScript types
+mcp-ui generate-types <input> [output] [--namespace <name>]
 
 # Test examples
-mcp-ui test-examples ./my-registry.json
+mcp-ui test-examples <file> [--component <id>] [--verbose]
 
 # Check for breaking changes
-mcp-ui diff ./old-registry.json ./new-registry.json --fail-on-breaking
+mcp-ui diff <old> <new> [--json] [--fail-on-breaking]
 ```

package/README.md

@@ -1,66 +1,234 @@
-# @mcp-ui/cli
+# @seed-ship/mcp-ui-cli
 
-CLI tools for validating and generating MCP UI component registries.
+CLI tools for validating and managing MCP UI component registries. Part of the MCP UI ecosystem.
+
+[![npm version](https://img.shields.io/npm/v/@seed-ship/mcp-ui-cli.svg)](https://www.npmjs.com/package/@seed-ship/mcp-ui-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## Installation
 
 ```bash
-pnpm add -D @mcp-ui/cli
+# Global installation (recommended for CLI usage)
+pnpm add -g @seed-ship/mcp-ui-cli
+
+# Local installation (for programmatic use)
+pnpm add -D @seed-ship/mcp-ui-cli
 ```
 
 ## Commands
 
-### Validate Registry
+The CLI provides 4 commands for registry management:
+
+### validate
+
+Validates a component registry against both Zod and JSON Schema specifications.
 
 ```bash
-mcp-ui validate registry.json
+mcp-ui validate <file> [options]
 ```
 
-Validates a component registry against the JSON Schema specification.
+**Arguments:**
+- `<file>` - Path to registry JSON file
 
-### Generate TypeScript Types
+**Options:**
+- `--strict` - Enable strict validation mode (all errors reported)
+- `--verbose` - Show detailed validation output with registry summary
 
+**Features:**
+- **Dual validation**: Validates against both Zod schemas and JSON Schema (Ajv)
+- **Verbose mode**: Displays registry version, component count, and component list
+- **Detailed errors**: Shows path-based error locations (e.g., `components[0].schema.required`)
+
+**Example:**
 ```bash
-mcp-ui generate-types registry.json --output types/
+# Basic validation
+mcp-ui validate ./my-registry.json
+
+# Strict mode with verbose output
+mcp-ui validate ./my-registry.json --strict --verbose
 ```
 
+---
+
+### generate-types
+
 Generates TypeScript type definitions from a component registry.
 
-### Test Examples
+```bash
+mcp-ui generate-types <input> [output] [options]
+```
+
+**Arguments:**
+- `<input>` - Path to registry JSON file
+- `[output]` - Output file path (optional, defaults to stdout)
+
+**Options:**
+- `--namespace <name>` - Wrap generated types in a namespace
+- `--export-all` - Export all generated types
+
+**Features:**
+- Converts component IDs to TypeScript type names (kebab-case to PascalCase)
+- Uses `json-schema-to-typescript` for accurate type generation
+- Adds auto-generation header comment
+
+**Example:**
+```bash
+# Generate types to stdout
+mcp-ui generate-types ./registry.json
+
+# Generate to file with namespace
+mcp-ui generate-types ./registry.json ./types/components.d.ts --namespace MCPComponents --export-all
+```
+
+---
+
+### test-examples
+
+Tests all component examples in a registry for validity.
+
+```bash
+mcp-ui test-examples <file> [options]
+```
+
+**Arguments:**
+- `<file>` - Path to registry JSON file
+
+**Options:**
+- `--component <id>` - Test only a specific component (by ID)
+- `--verbose` - Show detailed test output
+
+**Features:**
+- Validates each example against its component schema
+- Color-coded results (✓ pass, ✗ fail)
+- Returns exit code 1 if any examples fail (CI-friendly)
 
+**Example:**
 ```bash
-mcp-ui test-examples registry.json
+# Test all examples
+mcp-ui test-examples ./registry.json
+
+# Test specific component only
+mcp-ui test-examples ./registry.json --component quickchart-bar --verbose
 ```
 
-Validates all component examples in the registry.
+---
+
+### diff
 
-### Create Component
+Compares two registry versions and detects breaking changes.
 
 ```bash
-mcp-ui create-component quickchart-line
+mcp-ui diff <old> <new> [options]
 ```
 
-Creates a new component template.
+**Arguments:**
+- `<old>` - Path to old registry JSON file
+- `<new>` - Path to new registry JSON file
+
+**Options:**
+- `--json` - Output diff as JSON (for programmatic parsing)
+- `--fail-on-breaking` - Exit with error code 1 if breaking changes found
+
+**Breaking Changes Detected:**
+- Component removal
+- Component type changes
+- New required fields added
+- Major version changes
 
-### Check Breaking Changes
+**Non-Breaking Changes Detected:**
+- Component addition
+- Component deprecation
+- Removed required fields
+- Minor/patch version changes
 
+**Example:**
 ```bash
-mcp-ui diff registry-old.json registry-new.json
+# Basic diff
+mcp-ui diff ./registry-v1.json ./registry-v2.json
+
+# CI/CD usage with fail-on-breaking
+mcp-ui diff ./old.json ./new.json --fail-on-breaking --json
+```
+
+---
+
+## Programmatic API
+
+All commands are available as functions for programmatic use:
+
+```typescript
+import {
+  validateCommand,
+  generateTypesCommand,
+  testExamplesCommand,
+  diffCommand
+} from '@seed-ship/mcp-ui-cli'
+
+// Validate a registry
+const isValid = await validateCommand('./registry.json', { strict: true })
+
+// Generate types
+const types = await generateTypesCommand('./registry.json', undefined, { exportAll: true })
+
+// Test examples
+const results = await testExamplesCommand('./registry.json', { component: 'chart' })
+
+// Compare registries
+const diff = await diffCommand('./old.json', './new.json', { json: true })
 ```
 
-Compares two registry files and reports breaking changes.
+## CI/CD Integration
 
-## Usage in CI
+### GitHub Actions
 
 ```yaml
-# .github/workflows/validate.yml
-- name: Validate Component Registry
-  run: pnpm mcp-ui validate registry.json
+name: Validate Registry
+
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install CLI
+        run: npm install -g @seed-ship/mcp-ui-cli
+
+      - name: Validate Registry
+        run: mcp-ui validate ./registry.json --strict
+
+      - name: Test Examples
+        run: mcp-ui test-examples ./registry.json
+
+      - name: Check Breaking Changes
+        run: mcp-ui diff ./registry-main.json ./registry.json --fail-on-breaking
 ```
 
-## Documentation
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Validation failed / Breaking changes detected / Examples failed |
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@seed-ship/mcp-ui-solid`](../mcp-ui-solid) | SolidJS UI components |
+| [`@seed-ship/mcp-ui-spec`](../mcp-ui-spec) | JSON schemas and Zod validators |
+
+## Versioning
+
+This package follows [Semantic Versioning](https://semver.org/). See [CHANGELOG.md](./CHANGELOG.md) for release notes.
 
-See the [full documentation](../../docs/features/generative-ui/) for more details.
+**Current Version:** 1.1.0
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seed-ship/mcp-ui-cli",
-  "version": "1.0.13",
+  "version": "1.1.0",
   "description": "CLI tools for validating and generating MCP UI component registries",
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
     "zod": "^3.22.4",
     "chalk": "^5.3.0",
     "ora": "^7.0.1",
-    "@seed-ship/mcp-ui-spec": "1.0.14"
+    "@seed-ship/mcp-ui-spec": "1.1.0"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",