@unispechq/unispec-core 0.1.0 → 0.1.1

package/.github/workflows/npm-publish.yml

@@ -1,74 +1,74 @@
-name: CI & Publish UniSpec Core
-
-on:
-  push:
-    branches:
-      - main
-    tags:
-      - "unispec-core-v*"
-  pull_request:
-    branches:
-      - main
-
-jobs:
-  ci:
-    name: CI (install & pack)
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout repo
-        uses: actions/checkout@v4
-
-      - name: Use Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-
-      - name: Install dependencies
-        run: |
-          if [ -f package-lock.json ]; then
-            npm ci
-          else
-            npm install
-          fi
-
-      - name: Run tests (if defined)
-        run: |
-          if npm run | grep -q " test"; then
-            npm test
-          else
-            echo "No test script defined, skipping tests"
-          fi
-
-      - name: Verify package can be packed
-        run: npm pack --dry-run
-
-  publish:
-    name: Publish to npm
-    needs: ci
-    runs-on: ubuntu-latest
-    if: startsWith(github.ref, 'refs/tags/unispec-core-v')
-
-    steps:
-      - name: Checkout repo
-        uses: actions/checkout@v4
-
-      - name: Use Node.js with npm registry
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          registry-url: https://registry.npmjs.org
-          scope: "@unispechq"
-
-      - name: Install dependencies
-        run: |
-          if [ -f package-lock.json ]; then
-            npm ci
-          else
-            npm install
-          fi
-
-      - name: Publish @unispechq/unispec-core to npm
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: npm publish --access public
+name: CI & Publish UniSpec Core
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "unispec-core-v*"
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  ci:
+    name: CI (install & pack)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: |
+          if [ -f package-lock.json ]; then
+            npm ci
+          else
+            npm install
+          fi
+
+      - name: Run tests (if defined)
+        run: |
+          if npm run | grep -q " test"; then
+            npm test
+          else
+            echo "No test script defined, skipping tests"
+          fi
+
+      - name: Verify package can be packed
+        run: npm pack --dry-run
+
+  publish:
+    name: Publish to npm
+    needs: ci
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/unispec-core-v')
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Use Node.js with npm registry
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+          scope: "@unispechq"
+
+      - name: Install dependencies
+        run: |
+          if [ -f package-lock.json ]; then
+            npm ci
+          else
+            npm install
+          fi
+
+      - name: Publish @unispechq/unispec-core to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --access public

package/.windsurfrules

@@ -1,138 +1,138 @@
-# WindSurf Rules for `unispec-core`
-# ---------------------------------
-# This ruleset defines how AI assistants, contributors, and reviewers must
-# interact with the UniSpec Core Engine repository.
-# The Core Engine provides validation, parsing, normalization, diffing,
-# and conversion logic for UniSpec specifications.
-
-repository:
-  name: "unispec-core"
-  description: "Runtime implementation of the UniSpec Core Engine (loader, validator, normalizer, diff engine, converters, shared types). This repository contains only the Core Engine used by other UniSpec platform components (CLI, Registry, Portal, adapters, SDKs)."
-  visibility: public
-  criticality: core
-
-goals:
-  - Implement the runtime mechanics of the UniSpec format defined in `unispec-spec`.
-  - Provide parsing, validation, normalization, and diffing for UniSpec documents.
-  - Provide reusable shared types and utilities for CLI, adapters, registry, and portal.
-  - Ensure strict alignment with the specification and JSON Schemas.
-  - Consume organization-wide context through MCP GitHub server without violating boundaries.
-  - Remain lightweight, stable, deterministic, and fully spec-compliant.
-
-assistant_instructions:
-  allowed_actions:
-    - Read and reference content from other UniSpec repositories via MCP GitHub.
-    - Generate and update logic within this repository related to:
-        - parsing UniSpec documents,
-        - JSON Schema validation,
-        - normalization,
-        - diffing,
-        - conversions (OpenAPI, GraphQL SDL, WebSocket models),
-        - shared types and interfaces.
-    - Suggest architectural improvements to core modules.
-    - Assist in writing documentation, API descriptions, comments, and design notes.
-    - Validate behavior using actual spec files from `unispec-spec`.
-
-  forbidden_actions:
-    - Modify any files in external repositories.
-    - Introduce changes to the UniSpec language itself (belongs to `unispec-spec`).
-    - Implement features that are not grounded in the official spec.
-    - Add framework-specific or platform-specific logic (belongs to adapters).
-    - Add server code, API endpoints, frontend components, or CLI commands.
-    - Introduce non-deterministic behavior or global mutable state.
-    - Modify specification version numbers (belongs to `unispec-spec`).
-
-  escalation_policy:
-    - Any behavior that deviates from the official UniSpec spec must require maintainer confirmation.
-    - If MCP data reveals discrepancies between spec and code, assistant must warn and suggest alignment.
-    - For potentially breaking API changes, assistant must halt and request maintainer approval.
-
-context_model:
-  mcp_github_usage:
-    allowed:
-      - Access organization repositories for context (read-only).
-      - Inspect:
-          - UniSpec format (`unispec-spec`)
-          - CLI behavior (`unispec-platform`)
-          - Adapters (`unispec-js-adapters`, `unispec-python-adapters`)
-          - Registry and Portal APIs
-      - Use cross-repo information to ensure Core Engine behavior matches platform expectations.
-    forbidden:
-      - Editing or mutating files in other repositories.
-      - Making assumptions not supported by spec.
-      - Introducing coupling that makes core depend on implementation details.
-    behaviors:
-      - Treat external repos purely as reference sources.
-      - Maintain strict alignment with the spec repo.
-      - Do not derive new behaviors not defined by the spec.
-
-file_structure:
-  required_directories:
-    src: "Source code for the Core Engine logic"
-    src/loader: "Spec loader and YAML/JSON reading utilities"
-    src/validator: "Schema validation logic using official UniSpec JSON Schemas"
-    src/normalizer: "Canonical normalization of UniSpec documents"
-    src/diff: "Diff engine and breaking change detection"
-    src/converters: "Converters for OpenAPI, GraphQL, WebSocket, etc."
-    src/types: "Shared public-facing TypeScript types/interfaces"
-    docs: "Developer documentation and design notes"
-
-  required_files:
-    - "README.md"
-    - "package.json"
-    - "src/index.ts"
-    - "src/types/index.ts"
-
-content_guidelines:
-  code_requirements:
-    - Must be deterministic, pure, and side-effect-free where possible.
-    - Must strictly follow the UniSpec JSON Schema definitions.
-    - Must use official schemas from `unispec-spec` (via MCP reference or local import).
-    - Should be modular, composable, and testable.
-    - Must not depend on frameworks (Express, Nest, FastAPI, etc).
-    - Must not include platform logic (Registry/Portal).
-
-  documentation:
-    - All modules must have clear API descriptions and rationale.
-    - Example inputs and outputs should reference real UniSpec examples.
-    - Must reflect the latest UniSpec specification.
-
-  testing:
-    - Core behavior must be validated using examples from `unispec-spec/examples`.
-    - All changes must include tests for validation, normalization, diffing, and conversions.
-    - Tests must cover edge cases and backward compatibility.
-
-versioning_policy:
-  rules:
-    - Core versioning follows the platform, not the spec.
-    - Breaking API changes require:
-        - Maintainer approval
-    - Minor versions may add new converters or metadata fields if spec permits.
-    - Patch versions fix issues, improve accuracy, or correct types.
-
-pull_request_rules:
-  - PRs must describe:
-      - intent,
-      - expected behavior,
-      - impact on users,
-      - compatibility implications.
-  - PRs affecting validation, types, or normalization must include:
-      - tests,
-      - updated docs,
-      - verification against real examples.
-  - Schema-dependent logic must be checked against `unispec-spec` via MCP.
-
-tone_and_style:
-  - Code and docs must be clean, consistent, and professional.
-  - Naming conventions must follow spec terminology.
-  - No noisy logs, no temporary/debug code.
-
-license:
-  - Must remain open-source.
-  - Core engine logic must be available for public use.
-
-notes:
-  - This repository implements the *mechanics* of UniSpec, not the language definition.
-  - The UniSpec format itself lives in `unispec-spec`.
-  - Adapters, CLI, Registry, and Portal depend on core — keep APIs stable and predictable.
-  - MCP GitHub context may be used for reasoning but not for cross-repo modifications.
+# WindSurf Rules for `unispec-core`
+# ---------------------------------
+# This ruleset defines how AI assistants, contributors, and reviewers must
+# interact with the UniSpec Core Engine repository.
+# The Core Engine provides validation, parsing, normalization, diffing,
+# and conversion logic for UniSpec specifications.
+
+repository:
+  name: "unispec-core"
+  description: "Runtime implementation of the UniSpec Core Engine (loader, validator, normalizer, diff engine, converters, shared types). This repository contains only the Core Engine used by other UniSpec platform components (CLI, Registry, Portal, adapters, SDKs)."
+  visibility: public
+  criticality: core
+
+goals:
+  - Implement the runtime mechanics of the UniSpec format defined in `unispec-spec`.
+  - Provide parsing, validation, normalization, and diffing for UniSpec documents.
+  - Provide reusable shared types and utilities for CLI, adapters, registry, and portal.
+  - Ensure strict alignment with the specification and JSON Schemas.
+  - Consume organization-wide context through MCP GitHub server without violating boundaries.
+  - Remain lightweight, stable, deterministic, and fully spec-compliant.
+
+assistant_instructions:
+  allowed_actions:
+    - Read and reference content from other UniSpec repositories via MCP GitHub.
+    - Generate and update logic within this repository related to:
+        - parsing UniSpec documents,
+        - JSON Schema validation,
+        - normalization,
+        - diffing,
+        - conversions (OpenAPI, GraphQL SDL, WebSocket models),
+        - shared types and interfaces.
+    - Suggest architectural improvements to core modules.
+    - Assist in writing documentation, API descriptions, comments, and design notes.
+    - Validate behavior using actual spec files from `unispec-spec`.
+
+  forbidden_actions:
+    - Modify any files in external repositories.
+    - Introduce changes to the UniSpec language itself (belongs to `unispec-spec`).
+    - Implement features that are not grounded in the official spec.
+    - Add framework-specific or platform-specific logic (belongs to adapters).
+    - Add server code, API endpoints, frontend components, or CLI commands.
+    - Introduce non-deterministic behavior or global mutable state.
+    - Modify specification version numbers (belongs to `unispec-spec`).
+
+  escalation_policy:
+    - Any behavior that deviates from the official UniSpec spec must require maintainer confirmation.
+    - If MCP data reveals discrepancies between spec and code, assistant must warn and suggest alignment.
+    - For potentially breaking API changes, assistant must halt and request maintainer approval.
+
+context_model:
+  mcp_github_usage:
+    allowed:
+      - Access organization repositories for context (read-only).
+      - Inspect:
+          - UniSpec format (`unispec-spec`)
+          - CLI behavior (`unispec-platform`)
+          - Adapters (`unispec-js-adapters`, `unispec-python-adapters`)
+          - Registry and Portal APIs
+      - Use cross-repo information to ensure Core Engine behavior matches platform expectations.
+    forbidden:
+      - Editing or mutating files in other repositories.
+      - Making assumptions not supported by spec.
+      - Introducing coupling that makes core depend on implementation details.
+    behaviors:
+      - Treat external repos purely as reference sources.
+      - Maintain strict alignment with the spec repo.
+      - Do not derive new behaviors not defined by the spec.
+
+file_structure:
+  required_directories:
+    src: "Source code for the Core Engine logic"
+    src/loader: "Spec loader and YAML/JSON reading utilities"
+    src/validator: "Schema validation logic using official UniSpec JSON Schemas"
+    src/normalizer: "Canonical normalization of UniSpec documents"
+    src/diff: "Diff engine and breaking change detection"
+    src/converters: "Converters for OpenAPI, GraphQL, WebSocket, etc."
+    src/types: "Shared public-facing TypeScript types/interfaces"
+    docs: "Developer documentation and design notes"
+
+  required_files:
+    - "README.md"
+    - "package.json"
+    - "src/index.ts"
+    - "src/types/index.ts"
+
+content_guidelines:
+  code_requirements:
+    - Must be deterministic, pure, and side-effect-free where possible.
+    - Must strictly follow the UniSpec JSON Schema definitions.
+    - Must use official schemas from `unispec-spec` (via MCP reference or local import).
+    - Should be modular, composable, and testable.
+    - Must not depend on frameworks (Express, Nest, FastAPI, etc).
+    - Must not include platform logic (Registry/Portal).
+
+  documentation:
+    - All modules must have clear API descriptions and rationale.
+    - Example inputs and outputs should reference real UniSpec examples.
+    - Must reflect the latest UniSpec specification.
+
+  testing:
+    - Core behavior must be validated using examples from `unispec-spec/examples`.
+    - All changes must include tests for validation, normalization, diffing, and conversions.
+    - Tests must cover edge cases and backward compatibility.
+
+versioning_policy:
+  rules:
+    - Core versioning follows the platform, not the spec.
+    - Breaking API changes require:
+        - Maintainer approval
+    - Minor versions may add new converters or metadata fields if spec permits.
+    - Patch versions fix issues, improve accuracy, or correct types.
+
+pull_request_rules:
+  - PRs must describe:
+      - intent,
+      - expected behavior,
+      - impact on users,
+      - compatibility implications.
+  - PRs affecting validation, types, or normalization must include:
+      - tests,
+      - updated docs,
+      - verification against real examples.
+  - Schema-dependent logic must be checked against `unispec-spec` via MCP.
+
+tone_and_style:
+  - Code and docs must be clean, consistent, and professional.
+  - Naming conventions must follow spec terminology.
+  - No noisy logs, no temporary/debug code.
+
+license:
+  - Must remain open-source.
+  - Core engine logic must be available for public use.
+
+notes:
+  - This repository implements the *mechanics* of UniSpec, not the language definition.
+  - The UniSpec format itself lives in `unispec-spec`.
+  - Adapters, CLI, Registry, and Portal depend on core — keep APIs stable and predictable.
+  - MCP GitHub context may be used for reasoning but not for cross-repo modifications.