@stackwright-pro/openapi 0.0.0-beta-20260417191149

package/README.md

@@ -0,0 +1,399 @@
+# @stackwright-pro/openapi
+
+**Transform OpenAPI specifications into type-safe, runtime-validated Stackwright applications**
+
+> "Point at an API spec, get production-ready code in minutes, not weeks"
+
+## Overview
+
+`@stackwright-pro/openapi` is the cornerstone of Stackwright Pro's value proposition: automatic code generation from OpenAPI 3.x specifications. It generates Zod validation schemas, TypeScript types, typed API clients, and Stackwright CollectionProviders - all with mathematical correctness guarantees.
+
+**For government and enterprise teams:** This means taking existing API specifications (which you already have) and getting type-safe, runtime-validated UIs without manual coding. Hours to first working application. Days to production deployment.
+
+## What Gets Generated
+
+From a single OpenAPI spec, this package generates:
+
+1. **Zod Validation Schemas** - Runtime validation that can't be bypassed
+2. **TypeScript Types** - Compile-time type safety  
+3. **CollectionProviders** - Integration with Stackwright content system
+4. **Typed API Clients** - Fully typed fetch functions (coming soon)
+
+All code is generated at build time via the prebuild plugin system.
+
+## Installation
+
+```bash
+# Private package - contact Per Aspera LLC for access
+pnpm add @stackwright-pro/openapi
+
+# Peer dependencies (already in Stackwright projects)
+pnpm add @stackwright/types @stackwright/build-scripts zod
+```
+
+## Quick Start
+
+### 1. Configure Integration
+
+Add to your `stackwright.yml`:
+
+```yaml
+theme:
+  id: my-app
+  name: My Application
+
+integrations:
+  - type: openapi
+    name: logistics
+    spec: ./specs/logistics-api.yaml
+    auth:
+      type: bearer
+      token: $API_TOKEN
+    collections:
+      - endpoint: /equipment
+        slug_field: id
+      - endpoint: /supplies  
+        slug_field: id
+```
+
+### 2. Register Plugin
+
+Create `scripts/prebuild.js`:
+
+```javascript
+const { runPrebuild } = require('@stackwright/build-scripts');
+const { createOpenAPIPlugin } = require('@stackwright-pro/openapi');
+
+async function main() {
+  await runPrebuild({
+    plugins: [createOpenAPIPlugin()],
+  });
+}
+
+main().catch(console.error);
+```
+
+Update `package.json`:
+
+```json
+{
+  "scripts": {
+    "prebuild": "node scripts/prebuild.js",
+    "predev": "node scripts/prebuild.js",
+    "dev": "next dev",
+    "build": "next build"
+  }
+}
+```
+
+### 3. Generate Code
+
+```bash
+pnpm prebuild
+```
+
+This generates code to `src/generated/logistics/`:
+- `schemas.ts` - Zod validation schemas
+- `types.ts` - TypeScript type definitions
+- `provider.ts` - CollectionProvider implementations
+- `client.ts` - Typed API client (coming soon)
+
+### 4. Use Generated Code
+
+```typescript
+import { EquipmentSchema } from '@/generated/logistics/schemas';
+import type { Equipment } from '@/generated/logistics/types';
+
+// Runtime validation (mathematically proven safe)
+const validated = EquipmentSchema.parse(untrustedData);
+
+// Compile-time type safety
+const equipment: Equipment = {
+  id: '123',
+  name: 'HMMWV',
+  status: 'operational', // TypeScript error if invalid
+};
+```
+
+### 5. Integrate with Stackwright
+
+The generated CollectionProvider automatically integrates with Stackwright:
+
+```yaml
+# pages/equipment/content.yml
+content:
+  content_items:
+    - type: collection_list
+      label: equipment-list
+      source: logistics-equipment  # Auto-generated from OpenAPI
+      card:
+        heading: "{{name}}"
+        description: "{{description}}"
+        metadata:
+          - label: "Status"
+            value: "{{status}}"
+```
+
+## Architecture
+
+### The Zod Schema Generator (Core Engine)
+
+The `ZodSchemaGenerator` is the mathematical proof engine that ensures runtime validation:
+
+**Supported OpenAPI Features:**
+- ✅ All primitive types (string, number, boolean, integer, null)
+- ✅ Objects (required/optional properties, additionalProperties)
+- ✅ Arrays (with item validation, constraints)
+- ✅ Enums (string and number)
+- ✅ String formats (email, url, uuid, date-time, date, time, ipv4, ipv6)
+- ✅ Number constraints (minimum, maximum, multipleOf, exclusiveMinimum/Maximum)
+- ✅ String constraints (minLength, maxLength, pattern regex)
+- ✅ Array constraints (minItems, maxItems, uniqueItems)
+- ✅ Object constraints (minProperties, maxProperties)
+- ✅ Composition (allOf, oneOf, anyOf)
+- ✅ $ref resolution (local and external references)
+- ✅ Nullable types (`nullable: true` or `type: ["string", "null"]`)
+- ✅ Default values
+- ✅ Read-only and write-only properties
+
+**27 comprehensive tests** ensure correctness.
+
+### The OpenAPI Parser
+
+Parses OpenAPI 3.0.x and 3.1.x specifications:
+- Supports local files and remote URLs
+- Validates spec structure
+- Extracts paths, schemas, operations
+- Resolves $ref pointers (including circular references)
+
+### The Type Generator
+
+Converts OpenAPI schemas to TypeScript interfaces:
+- Proper optional vs required property handling
+- Union types for oneOf/anyOf
+- Intersection types for allOf
+- Type inference from Zod schemas
+
+### The CollectionProvider Generator
+
+Generates typed Stackwright CollectionProviders:
+- Fetches data from API endpoints
+- Applies schema validation automatically
+- Handles authentication (bearer, apiKey)
+- Error handling and retries
+- Integrates with Stackwright content system
+
+### The Prebuild Plugin
+
+Runs automatically during `pnpm dev` and `pnpm build`:
+- Reads integration config from `stackwright.yml`
+- Parses OpenAPI specs
+- Generates all code files
+- Writes to `src/generated/{integrationName}/`
+
+## Authentication
+
+### Bearer Token
+
+```yaml
+integrations:
+  - type: openapi
+    name: api
+    spec: ./spec.yaml
+    auth:
+      type: bearer
+      token: $API_TOKEN  # Environment variable
+```
+
+### API Key
+
+```yaml
+integrations:
+  - type: openapi
+    name: api
+    spec: ./spec.yaml
+    auth:
+      type: apiKey
+      name: X-API-Key
+      in: header  # or 'query'
+      value: $API_KEY
+```
+
+### OAuth2 (Coming Soon)
+
+OAuth2 flows will be supported in a future release.
+
+## Collections
+
+Map OpenAPI endpoints to Stackwright collections:
+
+```yaml
+integrations:
+  - type: openapi
+    name: logistics
+    spec: ./specs/logistics-api.yaml
+    collections:
+      - endpoint: /equipment
+        method: get  # default
+        slug_field: id
+        
+      - endpoint: /supplies
+        slug_field: item_id
+        
+      - endpoint: /personnel
+        slug_field: employee_id
+```
+
+Each collection generates:
+- Zod schema for validation
+- TypeScript type for compile-time safety
+- CollectionProvider for data fetching
+
+## Examples
+
+### Government Logistics API
+
+See `examples/marine-logistics-demo/` for a complete working example integrating with a Marine Corps logistics API.
+
+### E-Commerce Product Catalog
+
+```yaml
+integrations:
+  - type: openapi
+    name: products
+    spec: https://api.example.com/openapi.json
+    auth:
+      type: bearer
+      token: $SHOPIFY_TOKEN
+    collections:
+      - endpoint: /products
+        slug_field: sku
+```
+
+### Multi-API Integration
+
+```yaml
+integrations:
+  - type: openapi
+    name: users
+    spec: ./specs/users-api.yaml
+    collections:
+      - endpoint: /users
+        slug_field: id
+        
+  - type: openapi
+    name: orders
+    spec: ./specs/orders-api.yaml
+    collections:
+      - endpoint: /orders
+        slug_field: order_id
+```
+
+## API Reference
+
+### OpenAPIPlugin
+
+```typescript
+import { createOpenAPIPlugin } from '@stackwright-pro/openapi';
+
+const plugin = createOpenAPIPlugin();
+
+await runPrebuild({
+  plugins: [plugin],
+});
+```
+
+### OpenAPIParser
+
+```typescript
+import { OpenAPIParser } from '@stackwright-pro/openapi';
+
+const parser = new OpenAPIParser();
+const { document } = await parser.parse('./spec.yaml');
+```
+
+### ZodSchemaGenerator
+
+```typescript
+import { ZodSchemaGenerator } from '@stackwright-pro/openapi';
+
+const generator = new ZodSchemaGenerator();
+const zodCode = generator.generate(schema, { schemaName: 'UserSchema' });
+```
+
+### TypeGenerator
+
+```typescript
+import { TypeGenerator } from '@stackwright-pro/openapi';
+
+const generator = new TypeGenerator();
+const typeCode = generator.generate(schema, { typeName: 'User' });
+```
+
+### CollectionProviderGenerator
+
+```typescript
+import { CollectionProviderGenerator } from '@stackwright-pro/openapi';
+
+const generator = new CollectionProviderGenerator(openAPIDocument);
+const providerCode = generator.generate(collectionConfig);
+```
+
+## Testing
+
+The package includes comprehensive test coverage:
+
+```bash
+cd packages/openapi
+pnpm test
+```
+
+**Test suites:**
+- `parser.test.ts` - OpenAPI parsing and $ref resolution
+- `zod-generator.test.ts` - 27 tests covering all schema features
+- `type-generator.test.ts` - TypeScript type generation
+- `collection-provider-generator.test.ts` - Provider generation
+- `prebuild-plugin.test.ts` - Plugin integration
+
+## Troubleshooting
+
+### "Integration not found in stackwright.yml"
+
+Ensure your `integrations` section is at the root level of `stackwright.yml`, not nested under `theme` or other properties.
+
+### "Failed to parse OpenAPI spec"
+
+- Validate your spec at https://editor.swagger.io
+- Ensure the spec version is 3.0.x or 3.1.x (not Swagger 2.0)
+- Check for $ref resolution errors
+
+### "Generated code not found"
+
+- Verify `pnpm prebuild` runs successfully
+- Check `src/generated/{integrationName}/` exists
+- Ensure build scripts are configured in `package.json`
+
+### TypeScript errors in generated code
+
+- Run `pnpm build:openapi` to regenerate
+- Check for breaking changes in your OpenAPI spec
+- Verify zod is installed as a dependency
+
+## License
+
+**Proprietary** - Commercial license. See [LICENSE](../../LICENSE) for terms.
+
+The open-source Stackwright framework is MIT licensed at [github.com/Per-Aspera-LLC/stackwright](https://github.com/Per-Aspera-LLC/stackwright).
+
+## Support
+
+For enterprise support, custom integrations, or government procurement inquiries:
+
+- **Email:** support@peraspera.llc
+- **GitHub Issues:** [stackwright-pro/issues](https://github.com/Per-Aspera-LLC/stackwright-pro/issues)
+- **Documentation:** [stackwright-pro/docs](https://github.com/Per-Aspera-LLC/stackwright-pro/tree/main/docs)
+
+---
+
+**Built by [Per Aspera LLC](https://github.com/Per-Aspera-LLC)**  
+*"Through hardship to the stars"*