@noego/stitch 1.0.0

package/docs/validation.md

@@ -0,0 +1,77 @@
+# Request Validation in This OpenAPI Server
+
+This project uses **Fastify** as the underlying web server, plus an **OpenAPI-driven** approach to routes and validation. Here’s how it works:
+
+1. **OpenAPI Document**  
+   You define your endpoints, request/response schemas, etc. in `example/openapi.yaml`. For example:
+
+   ```yaml
+   paths:
+     /user/create:
+       post:
+         x-controller: user.controller
+         x-action: create
+         summary: Create a new User
+         requestBody:
+           required: true
+           content:
+             application/json:
+               schema:
+                 $ref: '#/components/schemas/NewUser'
+         responses:
+           '200':
+             description: Success
+   components:
+     schemas:
+       NewUser:
+         type: object
+         required:
+           - email
+           - password
+         properties:
+           email:
+             type: string
+             format: email
+           password:
+             type: string
+   ```
+
+2. **Route Generation**  
+   - Our framework loads your `openapi.yaml` using the [`OpenAPIParser`](./framework/openapi/parser.ts).  
+   - The [`FastifyServerImplentation.createRoutes()`](./framework/fastify/FastifyServerImplentation.ts) method reads each path’s schema and automatically sets up Fastify routes with a `schema` property that represents your request params, query, and body definitions.  
+   - Fastify’s built-in validation uses [Ajv](https://ajv.js.org/) behind the scenes to validate inbound requests against those schemas.
+
+3. **Validation Pipeline**  
+   - When a client sends a request to `/user/create`, Fastify matches it to the route defined in `openapi.yaml`.  
+   - Fastify checks if any `parameters` (for path/query) or `requestBody` data are provided in the correct shape.  
+   - If the data doesn’t match the schema, **Fastify** automatically returns an error (e.g. `400`).  
+   - If it’s valid, the request proceeds to your controller method (like `UserController.create`).
+
+4. **Schema Inference**  
+   - For `requestBody`, the schema is taken from `requestBody.content['application/json'].schema`.  
+   - For path or query parameters, the schema is taken from `parameters[].schema` in `openapi.yaml`.  
+   - You can also define response schemas if you want response validation.
+
+5. **Example**  
+   Let’s look at the `NewUser` schema. It declares `email` as a string with an email format, and `password` as required. If a request is missing those, you’ll get an error like:
+
+   ```json
+   {
+     "statusCode": 400,
+     "error": "Bad Request",
+     "message": "body must have required property 'password'"
+   }
+   ```
+
+6. **No Extra Controller Code Needed**  
+   - Since Fastify handles validation, your controllers only receive valid data.  
+   - If the request is invalid, the request never reaches your controller logic.
+
+7. **Where to Edit Schemas**  
+   - Any time you need to change request/response shapes, update `example/openapi.yaml`.  
+   - The changes automatically reflect in the generated routes and validation rules.
+
+8. **Advanced Validation**  
+   - If you need custom rules that aren’t possible in JSON Schema, you can add a [Fastify or Ajv plugin](https://www.fastify.io/docs/latest/Reference/Validation-and-Serialization/#adding-new-keywords).  
+   - But generally, the base JSON Schema approach covers most cases.
+

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@noego/stitch",
+  "version": "1.0.0",
+  "description": "",
+  "license": "ISC",
+  "author": "",
+  "type": "module",
+  "main": "./dist-ssr/server.cjs",
+  "module": "./dist-ssr/server.js",
+  "bin": {
+    "stitch": "./bin/stitch.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist-ssr/server.d.ts",
+      "import": "./dist-ssr/server.js",
+      "require": "./dist-ssr/server.cjs",
+      "default": "./dist-ssr/server.js"
+    },
+    "./browser": {
+      "types": "./dist/browser/index.d.ts",
+      "import": "./dist/client.mjs",
+      "require": "./dist/client.cjs",
+      "default": "./dist/client.mjs"
+    },
+    "./server": {
+      "types": "./dist-ssr/server.d.ts",
+      "import": "./dist-ssr/server.js",
+      "require": "./dist-ssr/server.cjs",
+      "default": "./dist-ssr/server.js"
+    }
+  },
+  "scripts": {
+    "build:client": "vite build --config vite.config.js",
+    "build:ssr": "SSR=true vite build --ssr",
+    "build": "npm run build:client && npm run build:ssr",
+    "prepublishOnly": "npm run build",
+    "dev": "tsx cli.ts dev",
+    "start": "tsx cli.ts run",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "types": "./dist-ssr/server.d.ts",
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "chokidar": "^3.5.3",
+    "glob": "^10.3.10",
+    "js-yaml": "^4.1.0",
+    "minimist": "^1.2.8"
+  },
+  "devDependencies": {
+    "@types/glob": "^8.1.0",
+    "@types/jest": "^29.5.12",
+    "@types/js-yaml": "^4.0.9",
+    "@types/minimist": "^1.2.5",
+    "@types/node": "^20.11.25",
+    "jest": "^29.7.0",
+    "source-map-support": "^0.5.21",
+    "ts-jest": "^29.2.5",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3",
+    "vite": "^6.3.5",
+    "vite-plugin-dts": "^4.5.4"
+  }
+}

package/readme.md

@@ -0,0 +1,159 @@
+# Stitch — Modular YAML Merging and Validation
+
+Stitch merges multiple YAML files into a single, validated artifact. It’s ideal for modular OpenAPI specs and other structured YAML, with CLI, Node, and browser support — plus VSCode schema integration for real‑time validation.
+
+## Why Stitch
+
+- Modularize YAML: Keep specs split across files and folders without losing clarity.
+- Validate output: Use JSON Schema (AJV) or basic structure checks.
+- Watch and rebuild: Fast dev feedback when files change.
+- Run anywhere: Same engine for CLI, Node, and browser (Vite).
+- IDE assistance: Auto‑configure VSCode to validate YAML as you type.
+
+## Key Capabilities
+
+- Merge: Ordered deep‑merge of YAML files and globs; later files override earlier keys.
+- Validate: AJV JSON Schema or basic OpenAPI structure checks.
+- Output: YAML or JSON to stdout or file (with generated‑file headers when writing files).
+- Watch: Rebuild on changes with chokidar.
+- VSCode: Install yaml.schemas mapping into `.vscode/settings.json`.
+- Browser: Merge content via `import.meta.glob` or raw strings (Vite).
+
+## Quick Start
+
+### CLI
+
+```bash
+stitch [command] [input-file] [options]
+
+# Build and print to stdout (defaults to stitch.yaml)
+stitch build
+
+# Build specific config
+stitch build my-config.yaml
+
+# Output to a file (adds generated-file header)
+stitch build --output dist/openapi.yaml
+
+# Output JSON instead of YAML
+stitch build --format json
+
+# Validate (basic) or with a schema
+stitch build --validate
+stitch build --validate schemas/schema.json
+
+# Watch for changes and rebuild
+stitch watch --validate schemas/schema.json
+```
+
+Options
+- `--output <file>`: write to a file instead of stdout
+- `--format <json|yaml>`: output format (default: yaml)
+- `--validate [schema]`: basic validation or path to JSON Schema
+- `--quiet`: build/validate but don’t print content
+
+### Programmatic (Node)
+
+```ts
+import { stitch, StitchEngine } from 'stitch';
+
+// Convenience API
+await stitch.build({
+  input: 'stitch.yaml',
+  output: 'dist/openapi.yaml',
+  format: 'yaml',
+  validate: 'schemas/schema.json',
+});
+
+// Direct engine usage
+const engine = new StitchEngine();
+const result = engine.buildSync('stitch.yaml', { format: 'json' });
+await engine.watch('stitch.yaml', { validate: true });
+
+// VSCode schema installation
+engine.install({
+  schemaPath: 'schemas/schema.json',
+  targets: ['*.yaml', 'openapi/*.yaml'],
+  vscodeSettingsPath: '.vscode/settings.json',
+});
+```
+
+### Browser / Vite
+
+```ts
+import { stitchFromViteImports, stitchFromContent } from 'stitch/browser';
+
+// Vite import.meta.glob integration
+const imports = import.meta.glob('./openapi/*.yaml', { as: 'raw' });
+const merged = await stitchFromViteImports(imports);
+
+// Direct content merging
+const result = stitchFromContent([
+  { content: baseYaml, name: 'base.yaml' },
+  { content: pathsYaml, name: 'paths.yaml' },
+]);
+```
+
+## Merge Rules
+
+- Objects: deep‑merge — later files override keys.
+- Arrays: later arrays replace earlier arrays (no concatenation).
+- Primitives: later values replace earlier values.
+
+## Validation
+
+- Basic: `--validate` enables lightweight OpenAPI shape checks (`openapi`, `info`).
+- JSON Schema: `--validate schemas/schema.json` enables full AJV validation against your schema.
+
+## VSCode Integration
+
+Install a JSON Schema mapping so VSCode validates YAML in real‑time:
+
+```bash
+stitch install schemas/schema.json --target "**/*.yaml"
+```
+
+Manual configuration example (`.vscode/settings.json`):
+
+```json
+{
+  "yaml.schemas": {
+    "./schemas/schema.json": ["**/*.yaml"]
+  },
+  "yaml.validate": true
+}
+```
+
+Alternative paths
+- "@noego/forge/schema.json" – Package export (if supported by VSCode)
+- "node_modules/@noego/forge/schema.json" – Direct node_modules path (most reliable)
+
+## Example Project Structure
+
+```
+project/
+├── stitch.yaml
+├── openapi/
+│   ├── base.yaml
+│   ├── paths/
+│   │   ├── users.yaml
+│   │   └── posts.yaml
+│   └── components/
+│       └── schemas/
+└── schemas/
+    └── schema.json
+```
+
+## Framework Integrations (Optional)
+
+If you use framework‑specific schemas, you can install them too:
+
+```bash
+stitch install @noego/forge/schema.json  --target "openapi/*.yaml"
+stitch install @noego/dinner/schema.json --target "**/*.yaml"
+```
+
+## License
+
+MIT
+

package/schemas/schema.json

@@ -0,0 +1,360 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Dinner Framework OpenAPI Schema",
+  "description": "JSON Schema for OpenAPI 3.0.3 specification with Dinner framework extensions",
+  "type": "object",
+  "required": [],
+  "properties": {
+    "openapi": {
+      "type": "string",
+      "pattern": "^3\\.0\\.[0-9]+(\\.[0-9]+)*$",
+      "description": "The OpenAPI specification version"
+    },
+    "info": {
+      "type": "object",
+      "required": ["title", "version"],
+      "properties": {
+        "title": {
+          "type": "string",
+          "description": "The title of the API"
+        },
+        "version": {
+          "type": "string",
+          "description": "The version of the API"
+        },
+        "description": {
+          "type": "string",
+          "description": "A description of the API"
+        },
+        "contact": {
+          "type": "object",
+          "properties": {
+            "name": { "type": "string" },
+            "url": { "type": "string" },
+            "email": { "type": "string" }
+          }
+        },
+        "license": {
+          "type": "object",
+          "required": ["name"],
+          "properties": {
+            "name": { "type": "string" },
+            "url": { "type": "string" }
+          }
+        }
+      }
+    },
+    "servers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["url"],
+        "properties": {
+          "url": {
+            "type": "string",
+            "description": "A URL to the target host"
+          },
+          "description": {
+            "type": "string",
+            "description": "An optional string describing the host"
+          }
+        }
+      }
+    },
+    "paths": {
+      "type": "object",
+      "patternProperties": {
+        "^/": {
+          "type": "object",
+          "properties": {
+            "get": { "$ref": "#/definitions/operation" },
+            "post": { "$ref": "#/definitions/operation" },
+            "put": { "$ref": "#/definitions/operation" },
+            "delete": { "$ref": "#/definitions/operation" },
+            "patch": { "$ref": "#/definitions/operation" },
+            "head": { "$ref": "#/definitions/operation" },
+            "options": { "$ref": "#/definitions/operation" },
+            "trace": { "$ref": "#/definitions/operation" },
+            "parameters": {
+              "type": "array",
+              "items": { "$ref": "#/definitions/parameter" }
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "module": {
+      "type": "object",
+      "description": "Dinner framework: Module definitions with base paths and sub-paths",
+      "patternProperties": {
+        "^[a-zA-Z0-9_-]+$": {
+          "type": "object",
+          "required": ["basePath", "paths"],
+          "properties": {
+            "basePath": {
+              "type": "string",
+              "pattern": "^/",
+              "description": "Base path for all routes in this module"
+            },
+            "paths": {
+              "type": "object",
+              "patternProperties": {
+                "^/": {
+                  "type": "object",
+                  "properties": {
+                    "get": { "$ref": "#/definitions/operation" },
+                    "post": { "$ref": "#/definitions/operation" },
+                    "put": { "$ref": "#/definitions/operation" },
+                    "delete": { "$ref": "#/definitions/operation" },
+                    "patch": { "$ref": "#/definitions/operation" },
+                    "head": { "$ref": "#/definitions/operation" },
+                    "options": { "$ref": "#/definitions/operation" },
+                    "trace": { "$ref": "#/definitions/operation" },
+                    "parameters": {
+                      "type": "array",
+                      "items": { "$ref": "#/definitions/parameter" }
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "components": {
+      "type": "object",
+      "properties": {
+        "schemas": {
+          "type": "object",
+          "patternProperties": {
+            "^[a-zA-Z0-9\\.\\-_]+$": {
+              "$ref": "#/definitions/schema"
+            }
+          }
+        },
+        "responses": {
+          "type": "object",
+          "patternProperties": {
+            "^[a-zA-Z0-9\\.\\-_]+$": {
+              "$ref": "#/definitions/response"
+            }
+          }
+        },
+        "parameters": {
+          "type": "object",
+          "patternProperties": {
+            "^[a-zA-Z0-9\\.\\-_]+$": {
+              "$ref": "#/definitions/parameter"
+            }
+          }
+        },
+        "securitySchemes": {
+          "type": "object",
+          "patternProperties": {
+            "^[a-zA-Z0-9\\.\\-_]+$": {
+              "$ref": "#/definitions/securityScheme"
+            }
+          }
+        }
+      }
+    },
+    "security": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name"],
+        "properties": {
+          "name": { "type": "string" },
+          "description": { "type": "string" }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "operation": {
+      "type": "object",
+      "required": ["x-controller", "x-action"],
+      "properties": {
+        "summary": {
+          "type": "string",
+          "description": "A brief summary of what the operation does"
+        },
+        "description": {
+          "type": "string",
+          "description": "A verbose explanation of the operation behavior"
+        },
+        "operationId": {
+          "type": "string",
+          "description": "Unique string used to identify the operation"
+        },
+        "parameters": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/parameter" }
+        },
+        "requestBody": {
+          "$ref": "#/definitions/requestBody"
+        },
+        "responses": {
+          "type": "object",
+          "patternProperties": {
+            "^[1-5][0-9][0-9]$|^default$": {
+              "$ref": "#/definitions/response"
+            }
+          }
+        },
+        "tags": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "security": {
+          "type": "array",
+          "items": { "type": "object" }
+        },
+        "x-controller": {
+          "type": "string",
+          "description": "Dinner framework: Controller class path (e.g., 'controllers/user.controller')"
+        },
+        "x-action": {
+          "type": "string",
+          "description": "Dinner framework: Controller method name (e.g., 'create', 'getAll')"
+        },
+        "x-middleware": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Dinner framework: Middleware chain to apply before controller action"
+        }
+      },
+      "additionalProperties": false
+    },
+    "response": {
+      "type": "object",
+      "required": ["description"],
+      "properties": {
+        "description": {
+          "type": "string",
+          "description": "A description of the response"
+        },
+        "content": {
+          "type": "object",
+          "patternProperties": {
+            "^[a-zA-Z0-9][a-zA-Z0-9!#$&\\-\\^_]*\\/[a-zA-Z0-9][a-zA-Z0-9!#$&\\-\\^_]*$": {
+              "type": "object",
+              "properties": {
+                "schema": { "$ref": "#/definitions/schema" }
+              }
+            }
+          }
+        },
+        "headers": {
+          "type": "object",
+          "patternProperties": {
+            "^[a-zA-Z0-9\\.\\-_]+$": {
+              "type": "object",
+              "properties": {
+                "description": { "type": "string" },
+                "schema": { "$ref": "#/definitions/schema" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "parameter": {
+      "type": "object",
+      "required": ["name", "in"],
+      "properties": {
+        "name": { "type": "string" },
+        "in": {
+          "type": "string",
+          "enum": ["query", "header", "path", "cookie"]
+        },
+        "description": { "type": "string" },
+        "required": { "type": "boolean" },
+        "schema": { "$ref": "#/definitions/schema" }
+      }
+    },
+    "requestBody": {
+      "type": "object",
+      "properties": {
+        "description": { "type": "string" },
+        "content": {
+          "type": "object",
+          "patternProperties": {
+            "^[a-zA-Z0-9][a-zA-Z0-9!#$&\\-\\^_]*\\/[a-zA-Z0-9][a-zA-Z0-9!#$&\\-\\^_]*$": {
+              "type": "object",
+              "properties": {
+                "schema": { "$ref": "#/definitions/schema" }
+              }
+            }
+          }
+        },
+        "required": { "type": "boolean" }
+      }
+    },
+    "schema": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["null", "boolean", "object", "array", "number", "string", "integer"]
+        },
+        "properties": {
+          "type": "object",
+          "patternProperties": {
+            "^.*$": { "$ref": "#/definitions/schema" }
+          }
+        },
+        "items": { "$ref": "#/definitions/schema" },
+        "required": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "format": { "type": "string" },
+        "enum": {
+          "type": "array"
+        },
+        "minimum": { "type": "number" },
+        "maximum": { "type": "number" },
+        "minLength": { "type": "integer", "minimum": 0 },
+        "maxLength": { "type": "integer", "minimum": 0 },
+        "pattern": { "type": "string" },
+        "description": { "type": "string" },
+        "example": {},
+        "default": {},
+        "$ref": { "type": "string" }
+      }
+    },
+    "securityScheme": {
+      "type": "object",
+      "required": ["type"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["apiKey", "http", "oauth2", "openIdConnect"]
+        },
+        "description": { "type": "string" },
+        "name": { "type": "string" },
+        "in": {
+          "type": "string",
+          "enum": ["query", "header", "cookie"]
+        },
+        "scheme": { "type": "string" },
+        "bearerFormat": { "type": "string" }
+      }
+    }
+  }
+}
+