@unispechq/unispec-platform 0.1.0 → 0.1.4

package/README.md

@@ -1,225 +1,224 @@
-# UniSpec Platform
-
-**CLI and local orchestrator for the UniSpec ecosystem**
-
-This repository contains the official UniSpec CLI and the foundation for a local orchestrator.
-It builds on top of:
-
-- `unispec-spec` — the UniSpec format definition (schemas, examples, reference docs)
-- `@unispechq/unispec-core` — the Core Engine (loader, validator, normalizer, diff, converters)
-
-UniSpec is a modern, multi-protocol API specification format designed to unify:
-
-- REST
-- GraphQL
-- WebSocket
-- (future) event-driven APIs
-
----
-
-## Repository Status
-
-This repository is in early development.
-Current focus:
-
-- Provide a stable CLI surface for `validate`, `normalize`, `diff`, `convert`
-- Lay groundwork for `dev` (local orchestrator)
-- Prepare integration points for the future `unispec-registry` (publish/read)
-
----
-
-## Repository Structure
-
-```text
-unispec-platform/
-├─ src/
-│  ├─ cli.ts              # CLI entrypoint
-│  ├─ commands/           # Command registration (validate/normalize/diff/convert/dev)
-│  ├─ io/                 # File IO + output helpers
-│  └─ config/             # Config loading (future dev/orchestrator mode)
-├─ windsurfrules.yml      # WindSurf rules (stored without dotfile)
-├─ package.json
-├─ tsconfig.json
-└─ README.md
-```
-
-## CLI Commands
-
-Global flags:
-
-- `-q, --quiet` — suppress non-essential output
-- `--verbose` — enable diagnostic output (stderr)
-- `--json-errors` — output errors as JSON (stderr)
-
-### `unispec validate [file]`
-Validates a UniSpec document against the official JSON Schemas.
-
-Options:
-
-- `--stdin` — read spec from stdin (or pass `-` as file)
-
-### `unispec normalize [file]`
-Normalizes a UniSpec document into deterministic canonical form.
-
-Options:
-
-- `--stdin` — read spec from stdin (or pass `-` as file)
-- `--format <format>` — `json|yaml`
-- `--output <file>` — write output to file (use `-` for stdout)
-
-### `unispec diff <oldFile> <newFile>`
-Computes a structural diff between two UniSpec documents.
-
-Options:
-
-- `--format <format>` — `json|yaml`
-- `--output <file>` — write output to file (use `-` for stdout)
-
-### `unispec convert [file] --to <target>`
-Converts UniSpec into other representations.
-
-Targets:
-
-- `openapi` — outputs OpenAPI 3.1 JSON/YAML
-- `graphql-sdl` — outputs GraphQL SDL
-- `ws-model` — outputs a dashboard-friendly WebSocket model
-
-Options:
-
-- `--stdin` — read spec from stdin (or pass `-` as file)
-- `--format <format>` — `json|yaml` (for JSON-like targets)
-- `--output <file>` — write output to file (use `-` for stdout)
-
-### `unispec dev`
-Local orchestrator mode.
-
-Options:
-
-- `--config <path>` — path to config file (default: `unispec.config.json|yaml|yml`)
-- `--host <host>` — bind host (default: `127.0.0.1`)
-- `--port <port>` — bind port (default: `4141`)
-- `--watch` — watch config/spec files and refresh aggregated snapshot
-
-Planned responsibilities:
-
-- Watch local specs and/or connected services
-- Aggregate multiple UniSpec documents (microservices mode)
-- Serve a local dashboard and endpoints (e.g. `/unispec.json` for aggregated view)
-- Provide a single workflow to validate/normalize/diff before publishing to Registry
-
----
-
-## Dev server (local orchestrator)
-
-`unispec dev` starts a local HTTP API that aggregates multiple UniSpec documents.
-
-Default bind:
-
-- Host: `127.0.0.1`
-- Port: `4141`
-
-Endpoints:
-
-- `GET /health` -> `OK`
-- `GET /unispec.json` -> aggregated JSON
-
-Aggregation format (A):
-
-```json
-{
-  "version": 1,
-  "generatedAt": "2025-12-28T12:00:00.000Z",
-  "services": [
-    {
-      "name": "users",
-      "specPath": "./services/users/unispec.yaml",
-      "valid": true,
-      "spec": {}
-    }
-  ]
-}
-```
-
-If at least one service is invalid, `/unispec.json` responds with status `422` and includes per-service errors.
-
-### Example
-
-Create `unispec.config.json` (see `unispec.config.example.json`):
-
-```bash
-cp unispec.config.example.json unispec.config.json
-```
-
-Start the server:
-
-```bash
-npm run dev -- dev --verbose
-```
-
-Run using the bundled examples:
-
-```bash
-npm run dev -- dev -- --config example/unispec.config.json --verbose
-```
-
-Then open:
-
-- `http://127.0.0.1:4141/health`
-- `http://127.0.0.1:4141/unispec.json`
-
----
-
-## Development
-
-### Requirements
-
-- Node.js >= 18
-
-### Install
-
-```bash
-npm install
-```
-
-### Run CLI in dev mode
-
-```bash
-npm run dev -- --help
-```
-
-### Build
-
-```bash
-npm run build
-```
-
-### Run built CLI
-
-```bash
-npm run start -- --help
-```
-
----
-
-## Related Repositories
-
-| Repository | Purpose |
-|---|---|
-| `unispec-spec` | UniSpec format definition (schemas, examples) |
-| `unispec-core` | Core Engine (loader/validator/normalizer/diff/converters) |
-| `unispec-js-adapters` | Framework integrations (Express/NestJS/etc.) |
-| `unispec-registry` | (Future) publishing/reading specs and version history |
-
----
-
-## Contributing
-
-Contributions are welcome.
-
-Please read `windsurfrules.yml` before making changes.
-
----
-
-## License
-
-MIT
+# UniSpec Platform
+
+**CLI and local orchestrator for the UniSpec ecosystem**
+
+This repository contains the official UniSpec CLI and the foundation for a local orchestrator.
+It builds on top of:
+
+- `unispec-spec` — the UniSpec format definition (schemas, examples, reference docs)
+- `@unispechq/unispec-core` — the Core Engine (loader, validator, normalizer, diff, converters)
+
+UniSpec is a modern, multi-protocol API specification format designed to unify:
+
+- REST
+- GraphQL
+- WebSocket
+- (future) event-driven APIs
+
+---
+
+## Repository Status
+
+This repository is in early development.
+Current focus:
+
+- Provide a stable CLI surface for `validate`, `normalize`, `diff`, `convert`
+- Lay groundwork for `dev` (local orchestrator)
+- Prepare integration points for the future `unispec-registry` (publish/read)
+
+---
+
+## Repository Structure
+
+```text
+unispec-platform/
+├─ src/
+│  ├─ cli.ts              # CLI entrypoint
+│  ├─ commands/           # Command registration (validate/normalize/diff/convert/dev)
+│  ├─ io/                 # File IO + output helpers
+│  └─ config/             # Config loading (future dev/orchestrator mode)
+├─ package.json
+├─ tsconfig.json
+└─ README.md
+```
+
+## CLI Commands
+
+Global flags:
+
+- `-q, --quiet` — suppress non-essential output
+- `--verbose` — enable diagnostic output (stderr)
+- `--json-errors` — output errors as JSON (stderr)
+
+### `unispec validate [file]`
+Validates a UniSpec document against the official JSON Schemas.
+
+Options:
+
+- `--stdin` — read spec from stdin (or pass `-` as file)
+
+### `unispec normalize [file]`
+Normalizes a UniSpec document into deterministic canonical form.
+
+Options:
+
+- `--stdin` — read spec from stdin (or pass `-` as file)
+- `--format <format>` — `json|yaml`
+- `--output <file>` — write output to file (use `-` for stdout)
+
+### `unispec diff <oldFile> <newFile>`
+Computes a structural diff between two UniSpec documents.
+
+Options:
+
+- `--format <format>` — `json|yaml`
+- `--output <file>` — write output to file (use `-` for stdout)
+
+### `unispec convert [file] --to <target>`
+Converts UniSpec into other representations.
+
+Targets:
+
+- `openapi` — outputs OpenAPI 3.1 JSON/YAML
+- `graphql-sdl` — outputs GraphQL SDL
+- `ws-model` — outputs a dashboard-friendly WebSocket model
+
+Options:
+
+- `--stdin` — read spec from stdin (or pass `-` as file)
+- `--format <format>` — `json|yaml` (for JSON-like targets)
+- `--output <file>` — write output to file (use `-` for stdout)
+
+### `unispec dev`
+Local orchestrator mode.
+
+Options:
+
+- `--config <path>` — path to config file (default: `unispec.config.json|yaml|yml`)
+- `--host <host>` — bind host (default: `127.0.0.1`)
+- `--port <port>` — bind port (default: `4141`)
+- `--watch` — watch config/spec files and refresh aggregated snapshot
+
+Planned responsibilities:
+
+- Watch local specs and/or connected services
+- Aggregate multiple UniSpec documents (microservices mode)
+- Serve a local dashboard and endpoints (e.g. `/unispec.json` for aggregated view)
+- Provide a single workflow to validate/normalize/diff before publishing to Registry
+
+---
+
+## Dev server (local orchestrator)
+
+`unispec dev` starts a local HTTP API that aggregates multiple UniSpec documents.
+
+Default bind:
+
+- Host: `127.0.0.1`
+- Port: `4141`
+
+Endpoints:
+
+- `GET /health` -> `OK`
+- `GET /unispec.json` -> aggregated JSON
+
+Aggregation format (A):
+
+```json
+{
+  "version": 1,
+  "generatedAt": "2025-12-28T12:00:00.000Z",
+  "services": [
+    {
+      "name": "users",
+      "specPath": "./services/users/unispec.yaml",
+      "valid": true,
+      "spec": {}
+    }
+  ]
+}
+```
+
+If at least one service is invalid, `/unispec.json` responds with status `422` and includes per-service errors.
+
+### Example
+
+Create `unispec.config.json` (see `unispec.config.example.json`):
+
+```bash
+cp unispec.config.example.json unispec.config.json
+```
+
+Start the server:
+
+```bash
+npm run dev -- dev --verbose
+```
+
+Run using the bundled examples:
+
+```bash
+npm run dev -- dev -- --config example/unispec.config.json --verbose
+```
+
+Then open:
+
+- `http://127.0.0.1:4141/health`
+- `http://127.0.0.1:4141/unispec.json`
+
+---
+
+## Development
+
+### Requirements
+
+- Node.js >= 18
+
+### Install
+
+```bash
+npm install
+```
+
+### Run CLI in dev mode
+
+```bash
+npm run dev -- --help
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Run built CLI
+
+```bash
+npm run start -- --help
+```
+
+---
+
+## Related Repositories
+
+| Repository | Purpose |
+|---|---|
+| `unispec-spec` | UniSpec format definition (schemas, examples) |
+| `unispec-core` | Core Engine (loader/validator/normalizer/diff/converters) |
+| `unispec-js-adapters` | Framework integrations (Express/NestJS/etc.) |
+| `unispec-registry` | (Future) publishing/reading specs and version history |
+
+---
+
+## Contributing
+
+Contributions are welcome.
+
+Please read `windsurfrules.yml` before making changes.
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,39 +1,39 @@
-{
-  "name": "@unispechq/unispec-platform",
-  "version": "0.1.0",
-  "description": "CLI and local orchestrator for UniSpec (validate/normalize/diff/convert/dev).",
-  "license": "MIT",
-  "type": "module",
-  "bin": {
-    "unispec": "dist/cli.js"
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "dev": "tsx src/cli.ts",
-    "start": "node dist/cli.js",
-    "test": "npm run build && node --test tests/*.test.mjs",
-    "release:patch": "node scripts/release.js patch",
-    "release:minor": "node scripts/release.js minor",
-    "release:major": "node scripts/release.js major"
-  },
-  "dependencies": {
-    "@unispechq/unispec-core": "^0.2.2",
-    "commander": "^12.1.0",
-    "yaml": "^2.6.1"
-  },
-  "devDependencies": {
-    "@types/node": "^24.10.1",
-    "tsx": "^4.19.2",
-    "typescript": "^5.0.0"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@unispechq/unispec-platform",
+  "version": "0.1.4",
+  "description": "CLI and local orchestrator for UniSpec (validate/normalize/diff/convert/dev).",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "unispec": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "start": "node dist/cli.js",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "release:patch": "node scripts/release.js patch",
+    "release:minor": "node scripts/release.js minor",
+    "release:major": "node scripts/release.js major"
+  },
+  "dependencies": {
+    "@unispechq/unispec-core": "^0.2.2",
+    "commander": "^12.1.0",
+    "yaml": "^2.6.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}