@facetlayer/prism-framework 0.4.0 → 0.4.1

package/src/web/corsMiddleware.ts

@@ -0,0 +1,63 @@
+import express from 'express';
+
+export interface CorsConfig {
+  /** Base URL for web application (e.g., 'example.com' or 'https://example.com') */
+  webBaseUrl?: string;
+  /** Allow any localhost origin (http://localhost:*) for local development */
+  allowLocalhost?: boolean;
+  /**
+   * @deprecated Use `allowLocalhost` instead. This field controls both test endpoints and localhost CORS.
+   * When `allowLocalhost` is set, it takes precedence for CORS behavior.
+   */
+  enableTestEndpoints?: boolean;
+}
+
+function setACAOHeader(res: express.Response, reqOrigin: string, config: CorsConfig) {
+  const webBaseUrl = config.webBaseUrl;
+
+  if (!reqOrigin) {
+    // No origin header - probably a same-origin request.
+    if (webBaseUrl) {
+      res.header('Access-Control-Allow-Origin', webBaseUrl);
+    }
+    return;
+  }
+
+  // Origin header is present - check for whitelisted cases
+  if (webBaseUrl) {
+    const allowedOrigins = [`https://${webBaseUrl}`];
+    if (allowedOrigins.includes(reqOrigin)) {
+      // Matches whitelist
+      res.header('Access-Control-Allow-Origin', reqOrigin);
+      return;
+    }
+  }
+
+  // Allow any localhost port for local development
+  const localhostAllowed = config.allowLocalhost ?? config.enableTestEndpoints;
+  if (localhostAllowed && reqOrigin.startsWith('http://localhost:')) {
+    res.header('Access-Control-Allow-Origin', reqOrigin);
+    return;
+  }
+}
+
+export function corsMiddleware(config: CorsConfig = {}) {
+  return (req: express.Request, res: express.Response, next: express.NextFunction) => {
+    setACAOHeader(res, req.headers.origin, config);
+    res.header('Access-Control-Allow-Credentials', 'true');
+    res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS, PATCH');
+    res.header(
+      'Access-Control-Allow-Headers',
+      'Origin, X-Requested-With, Content-Type, Accept, Authorization, Cookie, Cache-Control'
+    );
+    res.header('Access-Control-Max-Age', '86400');
+
+    // Handle preflight requests
+    if (req.method === 'OPTIONS') {
+      res.sendStatus(200);
+      return;
+    }
+
+    next();
+  };
+}

package/src/web/localhostOnlyMiddleware.ts

@@ -0,0 +1,19 @@
+import type { NextFunction, Request, Response } from 'express';
+
+/*
+localhostOnlyMiddleware
+
+Special middleware that restricts an endpoint so that it can only be used by localhost client.
+*/
+
+export function localhostOnlyMiddleware(req: Request, res: Response, next: NextFunction) {
+  const allowedIPs = ['127.0.0.1', '::1', '::ffff:127.0.0.1']; // localhost variations
+
+  const clientIP = req.ip || req.connection?.remoteAddress;
+
+  if (!allowedIPs.includes(clientIP)) {
+    return res.status(404).json({ error: 'Not found' });
+  }
+
+  next();
+}

package/src/web/openapi/OpenAPI.ts

@@ -0,0 +1,248 @@
+/*
+ * OpenAPI
+ *
+ * Generates OpenAPI schema from service definitions.
+ * This module transforms endpoint definitions into a complete OpenAPI 3.1.0 specification.
+ */
+
+import {
+  OpenAPIRegistry,
+  OpenApiGeneratorV31,
+  type RouteConfig,
+  extendZodWithOpenApi,
+} from '@asteasolutions/zod-to-openapi';
+import swaggerUi from 'swagger-ui-express';
+import type { OpenAPIObject } from 'openapi3-ts/oas31';
+import z from 'zod';
+import type { ServiceDefinition } from '../../ServiceDefinition.ts';
+import { PrismApp } from '../../app/PrismApp.ts';
+import express, { type Request, type Response } from 'express';
+import { captureError } from '@facetlayer/streams'
+import { validateServicesForOpenapi } from './validateServicesForOpenapi.ts';
+import { getEffectiveOperationId } from '../../endpoints/createEndpoint.ts';
+
+export { validateServicesForOpenapi as validateEndpointForOpenapi } from './validateServicesForOpenapi.ts';
+
+type RequestConfig = RouteConfig['request'];
+
+export interface OpenAPIConfig {
+  enable: boolean
+  enableSwagger?: boolean
+}
+
+export type ParseExpressPathForOpenAPIResult = {
+  openApiPath: string;
+  pathParams: string[];
+};
+
+export interface OpenAPIDocumentInfo {
+  version: string;
+  title: string;
+  description: string;
+}
+
+// Globally modify Zod to support the .openapi() helper method.
+extendZodWithOpenApi(z);
+
+/**
+ * Transforms path parameters in an Express-style URL path (e.g. :pathParameter) into their OpenAPI equivalents (e.g. {pathParameter})
+ * Returns the transformed OpenAPI-style URL path along with any path parameters found.
+ *
+ * @param {string} expressApiPath - An Express-style URL path
+ * @returns {ParseExpressPathForOpenAPIResult} - the transformed OpenAPI-style URL path with any path parameters found
+ */
+export function parseExpressPathForOpenAPI(expressApiPath: string): ParseExpressPathForOpenAPIResult {
+  const expressApiPathParts: string[] = expressApiPath.split('/');
+  const pathParams: string[] = [];
+  const openApiPathParts: string[] = [];
+
+  for (const part of expressApiPathParts) {
+    if (part.startsWith(':')) {
+      pathParams.push(part.substring(1));
+      openApiPathParts.push(`{${part.substring(1)}}`);
+    } else {
+      openApiPathParts.push(part);
+    }
+  }
+
+  return {
+    openApiPath: openApiPathParts.join('/'),
+    pathParams,
+  };
+}
+
+/**
+ * Generates the Open API Schema for all services.
+ *
+ * @param {ServiceDefinition[]} services - Array of service definitions to generate OpenAPI schema for
+ * @param {OpenAPIDocumentInfo} documentInfo - Metadata for the OpenAPI document
+ * @returns {OpenAPIObject} - the Open API schema for all service definitions.
+ */
+export function generateOpenAPISchema(
+  services: ServiceDefinition[],
+  documentInfo: OpenAPIDocumentInfo
+): OpenAPIObject {
+  const registry: OpenAPIRegistry = new OpenAPIRegistry();
+
+  // Register all endpoints from all services
+  for (const service of services) {
+    const endpoints = service.endpoints || [];
+
+    for (const endpoint of endpoints) {
+      const { openApiPath, pathParams }: ParseExpressPathForOpenAPIResult =
+        parseExpressPathForOpenAPI(endpoint.path);
+      const requestConfig: RequestConfig = {};
+
+      // Specify path parameters: Extract path parameters from the route path and create a Zod schema from it.
+      if (pathParams.length > 0) {
+        // TODO: specify stricter typing for path parameters (e.g. enums/numeric values)
+        const pathParamsSchema: Record<string, z.ZodString> = {};
+        for (const param of pathParams) {
+          pathParamsSchema[param] = z.string();
+        }
+        requestConfig.params = z.object(pathParamsSchema);
+      }
+
+      // Specify body parameters: If the endpoint provides a request schema, use that as the body parameter
+      if (endpoint.requestSchema) {
+        requestConfig.body = {
+          content: {
+            'application/json': {
+              schema: endpoint.requestSchema,
+            },
+          },
+        };
+      }
+
+          registry.registerPath({
+            method: endpoint.method.toLowerCase() as any,
+            path: openApiPath,
+            description: endpoint.description || `${endpoint.method} ${endpoint.path}`,
+            operationId: getEffectiveOperationId(endpoint),
+            request: requestConfig,
+            responses: {
+              200: {
+                description: 'Success',
+                content: {
+                  'application/json': {
+                    schema: endpoint.responseSchema ?? z.any(),
+                  },
+                },
+              },
+              /*
+              400: {
+                description: 'Bad Request - Schema validation failed',
+                content: {
+                  'application/json': {
+                    schema: z.object({
+                      error: z.string(),
+                      details: z.array(z.any()),
+                    }),
+                  },
+                },
+              },
+              401: {
+                description: 'Unauthorized',
+                content: {
+                  'application/json': {
+                    schema: z.object({
+                      message: z.string(),
+                      details: z.any().optional(),
+                    }),
+                  },
+                },
+              },
+              500: {
+                description: 'Internal Server Error',
+                content: {
+                  'application/json': {
+                    schema: z.object({
+                      message: z.string(),
+                    }),
+                  },
+                },
+              },
+              */
+            },
+          });
+    }
+  }
+
+  const generator: OpenApiGeneratorV31 = new OpenApiGeneratorV31(
+    registry.definitions
+    
+    /*
+    .concat([
+      {
+        type: 'component',
+        componentType: 'securitySchemes',
+        name: 'bearer_auth',
+        component: {
+          type: 'http',
+          scheme: 'bearer',
+          bearerFormat: 'JWT',
+        },
+      },
+    ])
+      */
+  );
+
+  return generator.generateDocument({
+    openapi: '3.1.0',
+    info: {
+      version: documentInfo.version,
+      title: documentInfo.title,
+      description: documentInfo.description,
+    },
+    servers: [
+      { url: '/api', description: 'API server' },
+    ],
+    security: [
+      {
+        bearer_auth: [],
+      },
+    ],
+  });
+}
+
+export function setupSwaggerUI(app: express.Application | express.Router, openApiJsonPath: string = '/openapi.json'): void {
+  const router = app as express.Router;
+  // Serve Swagger UI on /swagger
+  router.use(
+    '/swagger',
+    swaggerUi.serve,
+    swaggerUi.setup(null, {
+      swaggerOptions: {
+        url: openApiJsonPath,
+      },
+    })
+  );
+}
+
+export function mountOpenAPIEndpoints(config: OpenAPIConfig, target: express.Application | express.Router, prismApp: PrismApp): void {
+  const router = target as express.Router;
+  router.get('/openapi.json', (req: Request, res: Response) => {
+    const services = prismApp.getAllServices();
+    try {
+      res.json(generateOpenAPISchema(services, {
+        version: '1.0.0',
+        title: prismApp.name,
+        description: prismApp.description,
+      }));
+    } catch (error) {
+
+      const validationResult = validateServicesForOpenapi(services);
+
+      console.error("/openapi.json failed to generate schema", {
+        cause: captureError(error),
+        problemEndpoints: validationResult.problemEndpoints,
+      });
+
+      res.status(500).json({ error: "Internal server error" });
+    }
+  });
+
+  if (config.enableSwagger) {
+    setupSwaggerUI(router, '/api/openapi.json');
+  }
+}

package/src/web/openapi/validateServicesForOpenapi.ts

@@ -0,0 +1,76 @@
+import type { ServiceDefinition } from "../../ServiceDefinition.ts";
+import type { EndpointDefinition } from "../ExpressEndpointSetup.ts";
+import { generateOpenAPISchema } from "./OpenAPI.ts";
+import { captureError, type ErrorDetails } from "@facetlayer/streams";
+
+export interface EndpointValidationResult {
+    error: ErrorDetails
+}
+
+export interface FailedEndpoint {
+    serviceName: string;
+    path: string;
+    method: string;
+    error: ErrorDetails;
+}
+
+export interface ServicesValidationResult {
+    problemEndpoints: FailedEndpoint[];
+}
+
+
+/**
+ * Validates a single endpoint for OpenAPI schema generation compatibility.
+ *
+ * @param serviceName - Name of the service containing the endpoint
+ * @param endpoint - The endpoint definition to validate
+ * @returns ProblematicEndpoint if validation fails, null if endpoint is valid
+ */
+export function validateEndpointForOpenapi(
+  endpoint: EndpointDefinition
+): EndpointValidationResult {
+  const testService: ServiceDefinition = {
+    name: 'test',
+    endpoints: [endpoint],
+  };
+
+  try {
+    generateOpenAPISchema([testService], {
+      version: '1.0.0',
+      title: 'Test',
+      description: 'Test',
+    });
+    return null;
+  } catch (error) {
+    return { error: captureError(error) };
+  }
+}
+
+/**
+ * Finds endpoints that will fail OpenAPI schema generation.
+ * Tests each endpoint individually to identify which ones have unsupported Zod types.
+ *
+ * @param services - Array of service definitions to check
+ * @returns ValidationResult containing any problematic endpoints
+ */
+export function validateServicesForOpenapi(services: ServiceDefinition[]): ServicesValidationResult {
+    const problemEndpoints: FailedEndpoint[] = [];
+
+    for (const service of services) {
+      const endpoints = service.endpoints || [];
+
+      for (const endpoint of endpoints) {
+        const endpointResult = validateEndpointForOpenapi(endpoint);
+        if (endpointResult?.error) {
+          problemEndpoints.push({
+            serviceName: service.name,
+            path: endpoint.path,
+            method: endpoint.method,
+            error: endpointResult.error,
+          });
+        }
+      }
+    }
+
+    return { problemEndpoints };
+  }

package/src/web/requestContextMiddleware.ts

@@ -0,0 +1,25 @@
+import { AsyncLocalStorage } from 'async_hooks';
+import type { NextFunction, Request, Response } from 'express';
+import { v4 as uuidv4 } from 'uuid';
+import { Authorization } from '../authorization/Authorization.ts';
+import type { RequestContext } from '../RequestContext.ts';
+import { requestContextStorage } from '../RequestContext.ts';
+
+export function requestContextMiddleware(req: Request, res: Response, next: NextFunction): void {
+    const requestId = uuidv4();
+    const startTime = Date.now();
+  
+    const context: RequestContext = {
+      requestId,
+      startTime,
+      req,
+      res,
+      auth: new Authorization(),
+    };
+  
+    res.setHeader('X-Request-ID', requestId);
+  
+    requestContextStorage.run(context, () => {
+      next();
+    });
+}

package/.claude/settings.local.json

@@ -1,20 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(git mv:*)",
-      "Bash(prism-endpoint:*)",
-      "Bash(pnpm build:*)",
-      "Bash(pnpm install:*)",
-      "Bash(pnpm typecheck:*)",
-      "Skill(vibe-code-cleanup)",
-      "Bash(node build.mts:*)",
-      "Bash(pnpm test:*)",
-      "Bash(node dist/cli.js:*)",
-      "Bash(mkdir:*)",
-      "Bash(node /Users/andy/node-libraries/prism-framework-tools/dist/cli.js generate-api-clients:*)",
-      "Bash(pnpm local:install:*)"
-    ],
-    "deny": [],
-    "ask": []
-  }
-}

package/CHANGELOG

@@ -1,28 +0,0 @@
-
-0.4.0
- - Renamed from @facetlayer/prism-framework-tools to @facetlayer/prism-framework
-
-0.3.0
- - Add config file support (.prism.qc) with parent directory search
- - Fix API client type generation issues
- - Add generate-api-clients-config documentation
- - Add endpoint-tools and env-files documentation
- - Safety checks for Zod schemas incompatible with OpenAPI
- - Improve getting-started docs
-
-0.2.5
- - Add list-docs and get-doc (with doc-files-helper)
- 
-0.2.4
- - Handle JSONish params in 'call' command
- - generate-api-clients now uses --out param
- 
-0.2.3
- - Fix for list-endpoints
-
-0.2.1
- - Add list-endpoints command
- - Call endpoint - don't fail on response schema failure
-
-0.1.0
- - initial version

package/CLAUDE.md

@@ -1,44 +0,0 @@
-# prism-framework
-
-Base library and CLI tools for the Prism app framework ecosystem.
-
-## Important Files and Directories
-
-### Source Code (`src/`)
-- `cli.ts` - Main CLI entry point, uses yargs for argument parsing
-- `call-command.ts` - Logic for calling endpoints, handles JSON parsing of arguments
-- `generate-api-clients.ts` - Generates TypeScript types from OpenAPI schema
-- `list-endpoints-command.ts` - Lists available endpoints from the API server
-- `loadEnv.ts` - Environment variable loading and validation
-- `getPorts.ts` - Port number utilities
-
-### Documentation (`docs/`)
-
-Markdown files for documentation.
-
-Run `doc-files list-docs` to understand the format.
-
-- `getting-started.md` - Setup guide for Prism Framework projects
-- `run-endpoint-tool.md` - Detailed CLI usage documentation
-- `env-files.md` - Environment configuration strategy
-
-### Tests (`test/`)
-- `call-command.test.ts` - Unit tests for argument parsing logic
-
-### Build Output
-- `dist/cli.js` - Compiled CLI executable (ES modules)
-
-## Build Commands
-
-```bash
-pnpm build      # Build the project
-pnpm test       # Run tests with Vitest
-pnpm typecheck  # TypeScript type checking
-```
-
-## Key Dependencies
-
-- `yargs` - CLI argument parsing
-- `dotenv` - Environment variable loading
-- `@facetlayer/doc-files-helper` - Documentation file management
-- `@facetlayer/prism-framework-api` - Prism API framework types

package/build.mts

@@ -1,8 +0,0 @@
-#! /usr/bin/env node
-
-import { runBuildTool } from '@facetlayer/build-config-nodejs';
-import { cpSync } from 'fs';
-
-await runBuildTool({
-  entryPoints: ['src/cli.ts'],
-});

package/test/call-command.test.ts

@@ -1,96 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { parseNamedArgs } from '../src/call-command';
-
-describe('parseNamedArgs', () => {
-  describe('basic values', () => {
-    it('should pass through simple string values', () => {
-      const result = parseNamedArgs({ name: 'John', email: 'john@example.com' });
-      expect(result).toEqual({ name: 'John', email: 'john@example.com' });
-    });
-
-    it('should pass through non-string values', () => {
-      const result = parseNamedArgs({ count: 42, active: true });
-      expect(result).toEqual({ count: 42, active: true });
-    });
-  });
-
-  describe('JSON parsing', () => {
-    it('should parse JSON object strings', () => {
-      const result = parseNamedArgs({ config: '{"timeout": 30}' });
-      expect(result).toEqual({ config: { timeout: 30 } });
-    });
-
-    it('should parse JSON array strings', () => {
-      const result = parseNamedArgs({ items: '["a", "b", "c"]' });
-      expect(result).toEqual({ items: ['a', 'b', 'c'] });
-    });
-
-    it('should handle whitespace around JSON', () => {
-      const result = parseNamedArgs({ data: '  {"key": "value"}  ' });
-      expect(result).toEqual({ data: { key: 'value' } });
-    });
-
-    it('should keep invalid JSON as string', () => {
-      const result = parseNamedArgs({ bad: '{not valid json}' });
-      expect(result).toEqual({ bad: '{not valid json}' });
-    });
-
-    it('should not parse strings that only start with { or [', () => {
-      const result = parseNamedArgs({ text: '{hello world' });
-      expect(result).toEqual({ text: '{hello world' });
-    });
-  });
-
-  describe('nested objects from yargs', () => {
-    it('should parse JSON strings inside nested objects', () => {
-      // Yargs creates nested objects from dot notation before we see them
-      const result = parseNamedArgs({
-        schema: {
-          name: 'test-schema',
-          statements: '["CREATE TABLE test (id INT)"]'
-        }
-      });
-      expect(result).toEqual({
-        schema: {
-          name: 'test-schema',
-          statements: ['CREATE TABLE test (id INT)']
-        }
-      });
-    });
-
-    it('should handle deeply nested objects with JSON strings', () => {
-      const result = parseNamedArgs({
-        config: {
-          database: {
-            options: '{"timeout": 30, "retries": 3}'
-          }
-        }
-      });
-      expect(result).toEqual({
-        config: {
-          database: {
-            options: { timeout: 30, retries: 3 }
-          }
-        }
-      });
-    });
-  });
-
-  describe('real-world example from test.sh', () => {
-    it('should handle the migration command args', () => {
-      // Yargs parses --schema.name and --schema.statements into nested object
-      const result = parseNamedArgs({
-        schema: {
-          name: 'test-schema-v2',
-          statements: '["CREATE TABLE test_products (id INTEGER PRIMARY KEY, name TEXT, price REAL)"]'
-        }
-      });
-      expect(result).toEqual({
-        schema: {
-          name: 'test-schema-v2',
-          statements: ['CREATE TABLE test_products (id INTEGER PRIMARY KEY, name TEXT, price REAL)']
-        }
-      });
-    });
-  });
-});

package/test/generate-api-clients.test.ts

@@ -1,33 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { convertToExpressPath } from '../src/generate-api-clients';
-
-describe('convertToExpressPath', () => {
-  it('should convert single path parameter', () => {
-    expect(convertToExpressPath('/users/{id}')).toBe('/users/:id');
-  });
-
-  it('should convert multiple path parameters', () => {
-    expect(convertToExpressPath('/users/{userId}/posts/{postId}')).toBe('/users/:userId/posts/:postId');
-  });
-
-  it('should handle paths without parameters', () => {
-    expect(convertToExpressPath('/users')).toBe('/users');
-    expect(convertToExpressPath('/api/health')).toBe('/api/health');
-  });
-
-  it('should handle root path', () => {
-    expect(convertToExpressPath('/')).toBe('/');
-  });
-
-  it('should handle complex parameter names', () => {
-    expect(convertToExpressPath('/designs/{designId}/nodes/{nodeId}')).toBe('/designs/:designId/nodes/:nodeId');
-  });
-
-  it('should handle parameter at the end of path', () => {
-    expect(convertToExpressPath('/api/items/{id}')).toBe('/api/items/:id');
-  });
-
-  it('should handle parameter with underscores', () => {
-    expect(convertToExpressPath('/api/{user_id}/profile')).toBe('/api/:user_id/profile');
-  });
-});