@kosdev-code/kos-ui-cli 2.0.44 → 2.0.45

package/README.md

@@ -1,7 +1,484 @@
-# sdk-kos-ui-cli
+# KOS UI CLI
 
-This library was generated with [Nx](https://nx.dev).
+Command-line interface for KOS workspace management and code generation.
 
-## Building
+## Overview
 
-Run `nx build sdk-kos-ui-cli` to build the library.
+The KOS UI CLI (`kosui`) provides tools for:
+
+- Generating KOS models with proper architecture patterns
+- Creating OpenAPI type definitions and service wrappers from device APIs
+- Comparing API versions for breaking change detection
+- Managing workspace configurations
+- Scaffolding new KOS projects
+
+## Installation
+
+The CLI is installed as part of the KOS SDK workspace:
+
+```bash
+npm install @kosdev-code/kos-ui-cli
+```
+
+Or use directly via npx:
+
+```bash
+npx @kosdev-code/kos-ui-cli <command>
+```
+
+## Quick Reference
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `model` | Generate KOS models | `kosui model UserProfile` |
+| `api:generate` | Generate API types from OpenAPI | `kosui api:generate --project my-app` |
+| `api:compare` | Compare API versions for compatibility | `kosui api:compare --project my-app --app kos --base v1.8.0 --target v1.9.0` |
+| `workspace` | Workspace utilities | `kosui workspace:list-models` |
+
+## Commands
+
+### kosui api:generate
+
+Generate TypeScript types and service wrappers from OpenAPI specifications.
+
+Automatically creates type-safe API clients from your device's OpenAPI spec, including:
+- TypeScript type definitions for all endpoints
+- Service wrapper functions with proper error handling
+- Full IntelliSense support for paths, parameters, and responses
+- Filtered output by app namespace
+
+#### Options
+
+**Required:**
+- `--project <name>` - Target project name (must exist in workspace)
+
+**Optional:**
+- `--host <url>` - API host URL (default: inherited from project.json or http://127.0.0.1:8081)
+- `--apps <apps>` - Comma-separated app filters to include specific namespaces (e.g., 'kos,dispense')
+- `--output <path>` - Output path relative to sourceRoot (default: inherited from project.json or 'utils')
+- `--default-version <version>` - Default version for service exports (default: inherited from project.json)
+- `--all-apps-version <version>` - Override all apps to use specific version
+
+**Advanced:**
+- `--alias <json>` - Custom export aliases as JSON (e.g., '{"kos":"KOS"}')
+- `--app-version <json>` - Custom versions per app as JSON (e.g., '{"kos":"v2"}')
+
+**Note:** Options can be configured in `project.json` under `targets.api.options` and will be inherited if not specified on command line. CLI arguments take precedence over project configuration.
+
+#### Examples
+
+**Basic usage with project configuration:**
+```bash
+kosui api:generate --project my-device-models
+```
+
+**Override host and filter by apps:**
+```bash
+kosui api:generate \
+  --project my-device-models \
+  --host http://device.local:8081 \
+  --apps kos,dispense
+```
+
+**Custom output path and version:**
+```bash
+kosui api:generate \
+  --project my-device-models \
+  --output api/types \
+  --default-version v2
+```
+
+**Force all apps to specific version:**
+```bash
+kosui api:generate \
+  --project my-device-models \
+  --all-apps-version v1
+```
+
+#### What Gets Generated
+
+For each app namespace (e.g., `kos`, `dispense`, `freestyle`):
+
+1. **Type definitions** - `utils/services/{app}/{version}/openapi.d.ts`
+   - TypeScript types for all endpoints
+   - Request/response schemas
+   - Path parameter types
+
+2. **Service wrapper** - `utils/services/{app}/{version}/service.ts`
+   - Typed `kosServiceRequest` decorator
+   - Typed API client
+   - Type aliases for IntelliSense
+
+3. **Index files**
+   - `utils/openapi-index.ts` - Aggregated type exports
+   - `utils/services-index.ts` - Aggregated service exports
+
+**Core SDK services** (`kos`, `vfs`, `dispense`, `freestyle`, `handle`, `kosdev.ddk`) are automatically excluded when generating for third-party projects since they're already available in published SDKs.
+
+#### Integration with Project Configuration
+
+Add default configuration to your project's `project.json`:
+
+```json
+{
+  "targets": {
+    "api": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "kosui api:generate --project my-project",
+        "host": "http://127.0.0.1:8081",
+        "outputPath": "utils",
+        "defaultVersion": "v1",
+        "serviceExportAliases": {
+          "kos": "KOS",
+          "dispense": "DISPENSE"
+        },
+        "appVersions": {
+          "kos": "v2",
+          "dispense": "v1"
+        }
+      }
+    }
+  }
+}
+```
+
+Then run simply:
+```bash
+npx nx run my-project:api
+```
+
+#### Using Generated Types
+
+```typescript
+import { kosServiceRequest, type ApiResponse } from './utils/services/kos/v1/service';
+import { DependencyLifecycle } from '@kosdev-code/kos-ui-sdk';
+
+// Path constant with type safety
+const PATH_DEVICE_STATUS = '/api/kos/device/status';
+
+// Service function with tuple-based error handling
+async function getDeviceStatus(): Promise<ApiResponse<typeof PATH_DEVICE_STATUS, 'get'>> {
+  // ... implementation
+}
+
+// Using in a model with decorator
+@kosServiceRequest({
+  path: PATH_DEVICE_STATUS,
+  method: 'get',
+  lifecycle: DependencyLifecycle.LOAD
+})
+private onDeviceStatusLoaded(ctx: ExecutionContext<typeof PATH_DEVICE_STATUS>): void {
+  const [error, data] = ctx.result;
+  if (error) {
+    console.error('Failed to load device status:', error);
+    return;
+  }
+  this.status = data.status;
+}
+```
+
+### kosui api:compare
+
+Compare OpenAPI versions to detect breaking changes and API compatibility issues.
+
+Analyzes two generated API type definitions to identify:
+- Removed endpoints or HTTP methods
+- New or removed parameters
+- Parameter requirement changes
+- Request body modifications
+
+#### Prerequisites
+
+Generate types for both versions before comparing:
+
+```bash
+# Connect to base version device and generate types
+kosui api:generate --project my-models --apps kos
+
+# Connect to target version device and generate types
+kosui api:generate --project my-models --apps kos
+```
+
+#### Options
+
+**Required:**
+- `--project <name>` - Project containing generated API types
+- `--app <name>` - App namespace to compare (kos, dispense, freestyle)
+- `--base <version>` - Base version to compare from
+- `--target <version>` - Target version to compare to
+
+**Optional:**
+- `--format <format>` - Output format: console (default), json, markdown
+- `--output <file>` - Write output to file instead of stdout
+- `--apps <apps>` - Compare multiple apps (comma-separated)
+
+#### Examples
+
+**Basic comparison:**
+```bash
+kosui api:compare \
+  --project device-models \
+  --app kos \
+  --base v1.8.0 \
+  --target v1.9.0
+```
+
+**Generate markdown release notes:**
+```bash
+kosui api:compare \
+  --project device-models \
+  --app kos \
+  --base v1.8.0 \
+  --target v1.9.0 \
+  --format markdown \
+  --output CHANGELOG-API.md
+```
+
+**JSON output for automation:**
+```bash
+kosui api:compare \
+  --project device-models \
+  --app kos \
+  --base v1.8.0 \
+  --target v1.9.0 \
+  --format json
+```
+
+**Compare multiple apps:**
+```bash
+kosui api:compare \
+  --project device-models \
+  --apps kos,dispense,freestyle \
+  --base v1.8.0 \
+  --target v1.9.0
+```
+
+#### Output Formats
+
+**Console (default):**
+- Colored terminal output with compatibility status
+- Summary statistics (added/removed/modified endpoints)
+- Breaking changes highlighted
+- Recommendations for safe upgrade
+
+**JSON:**
+- Machine-readable format for automation
+- Complete comparison data structure
+- Suitable for CI/CD pipelines
+
+**Markdown:**
+- Ready for release notes and documentation
+- Organized sections for breaking/non-breaking changes
+- Suitable for commit messages or changelogs
+
+#### Exit Codes
+
+The command uses exit codes for automation:
+
+- **Exit 0** - Versions are backward compatible
+- **Exit 1** - Breaking changes detected
+
+Example CI/CD usage:
+```bash
+kosui api:compare --project models --app kos --base v1 --target v2
+if [ $? -eq 0 ]; then
+  echo "Safe to upgrade"
+else
+  echo "Breaking changes detected"
+fi
+```
+
+#### Integration with Build Process
+
+Add comparison target to `project.json`:
+
+```json
+{
+  "targets": {
+    "api:compare": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "kosui api:compare --project device-models --app kos --base ${BASE} --target ${TARGET}"
+      }
+    }
+  }
+}
+```
+
+Run via Nx:
+```bash
+BASE=v1.8.0 TARGET=v1.9.0 npx nx run device-models:api:compare
+```
+
+### kosui model
+
+Generate KOS models with proper architecture patterns.
+
+*For detailed model generation documentation, see the KOS UI SDK documentation.*
+
+### kosui workspace
+
+Workspace utilities for managing KOS projects.
+
+*For workspace command documentation, see the KOS UI SDK documentation.*
+
+## Advanced Usage
+
+### Argument Formats
+
+The CLI supports multiple argument formats:
+
+**Boolean flags:**
+```bash
+--singleton          # true
+--singleton=false    # explicit false
+```
+
+**String values:**
+```bash
+--name MyModel
+--name=my-model
+--name="My Model"
+```
+
+**Array values:**
+```bash
+--apps kos,dispense,network
+--apps=kos,dispense
+```
+
+**JSON values:**
+```bash
+--alias '{"kos":"KOS","dispense":"DISPENSE"}'
+--app-version '{"kos":"v2"}'
+```
+
+### Help System
+
+Get contextual help for any command:
+
+```bash
+kosui --help                    # General help
+kosui api:generate --help       # Command-specific help
+kosui model -h                  # Shorthand
+```
+
+The help system shows:
+- Command description and purpose
+- Available options with types and defaults
+- Examples for common use cases
+
+## Configuration
+
+### Project-Level Configuration
+
+Configure defaults in your project's `project.json` to avoid repeating options:
+
+```json
+{
+  "targets": {
+    "api": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "kosui api:generate --project ${projectName}",
+        "host": "http://127.0.0.1:8081",
+        "outputPath": "utils",
+        "defaultVersion": "v1"
+      }
+    }
+  }
+}
+```
+
+Then run via Nx:
+```bash
+npx nx run my-project:api
+```
+
+CLI arguments always override project configuration.
+
+### Workspace-Level Configuration
+
+For monorepo-wide settings, consider creating a shared configuration file that projects can reference.
+
+## Troubleshooting
+
+### Command Not Found
+
+Ensure the package is installed and available in your PATH:
+```bash
+npm install @kosdev-code/kos-ui-cli
+# or
+npm link  # if developing locally
+```
+
+### OpenAPI Generation Fails
+
+**Check device connectivity:**
+```bash
+curl http://127.0.0.1:8081/api/kos/openapi/api
+```
+
+**Verify project name:**
+```bash
+npx nx list  # List all projects
+```
+
+**Check project.json configuration:**
+- Ensure `sourceRoot` is correctly set
+- Verify target configuration if using `inherit` mode
+
+### Generated Types Have Errors
+
+**Regenerate with latest spec:**
+```bash
+kosui api:generate --project my-project --host http://device.local:8081
+```
+
+**Check for breaking changes in OpenAPI spec:**
+- Compare previous and current OpenAPI specs
+- Update service function signatures as needed
+
+### Version Conflicts
+
+When working with multiple API versions:
+
+1. Use `--all-apps-version` to force specific version
+2. Configure `appVersions` in project.json for per-app versions
+3. Check `defaultVersion` setting for export aliases
+
+## Development
+
+### Building
+
+```bash
+npx nx run @kosdev-code/kos-ui-cli:build
+```
+
+### Testing
+
+The CLI is tested through manual integration testing:
+
+```bash
+# Link for local development
+npm link
+
+# Test commands
+kosui --help
+kosui api:generate --project test-project
+```
+
+### Contributing
+
+See the main [CONTRIBUTING.md](../../../CONTRIBUTING.md) for development guidelines.
+
+## Related Documentation
+
+- [KOS UI SDK Documentation](../kos-ui-sdk/README.md)
+- [CODING_STANDARDS.md](../../../CODING_STANDARDS.md)
+- [Workspace Documentation](../../../README.md)
+
+## Support
+
+For issues, questions, or feature requests, please refer to the main KOS monorepo documentation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kosdev-code/kos-ui-cli",
-  "version": "2.0.44",
+  "version": "2.0.45",
   "bin": {
     "kosui": "./src/lib/cli.mjs"
   },
@@ -9,18 +9,20 @@
   ],
   "type": "module",
   "dependencies": {
+    "chalk": "^5.3.0",
     "prettier": "^2.6.2",
     "rimraf": "^5.0.1",
     "plop": "^3.1.2",
     "inquirer-directory": "^2.2.0",
     "figlet": "^1.6.0",
-    "create-nx-workspace": "18.0.3"
+    "create-nx-workspace": "18.0.3",
+    "openapi-typescript": "^7.6.1"
   },
   "module": "./src/index.js",
   "main": "./src/index.js",
   "kos": {
     "build": {
-      "gitHash": "898d506eb3c4558ff600ee7c2f062fa286b617e6"
+      "gitHash": "7e66917455c898a3f35128681c753862339b5fe3"
     }
   },
   "publishConfig": {