@facetlayer/prism-framework 0.4.0

package/src/cli.ts

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { loadEnv } from './loadEnv.ts';
+import { callEndpoint } from './call-command.ts';
+import { listEndpoints } from './list-endpoints-command.ts';
+import { generateApiClients } from './generate-api-clients.ts';
+import { loadConfig } from './config/index.ts';
+import { DocFilesHelper } from '@facetlayer/doc-files-helper';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const __packageRoot = join(__dirname, '..');
+const packageJson = JSON.parse(
+  readFileSync(join(__packageRoot, 'package.json'), 'utf-8')
+);
+const docFiles = new DocFilesHelper({
+    dirs: [join( __packageRoot, 'docs')],
+    files: [join(__packageRoot, 'README.md')],
+});
+
+async function main() {
+
+  const args = yargs(hideBin(process.argv))
+    .command(
+      'list-endpoints',
+      'List all available endpoints',
+      {},
+      async () => {
+        try {
+          const cwd = process.cwd();
+          const config = loadEnv(cwd);
+          console.log(`Using API server at: ${config.baseUrl}\n`);
+          await listEndpoints(config.baseUrl);
+        } catch (error) {
+          if (error instanceof Error && error.stack) {
+            console.error(error.stack);
+          } else {
+            console.error('Error:', error instanceof Error ? error.message : String(error));
+          }
+          process.exit(1);
+        }
+      }
+    )
+    .command(
+      'call <positionals...>',
+      'Call an endpoint. Named args starting with { } or [ ] are parsed as JSON.',
+      (yargs) => {
+        return yargs
+      },
+      async (argv) => {
+        try {
+          const cwd = process.cwd();
+          const config = loadEnv(cwd);
+
+          // Collect all other arguments as request body data
+          const requestData: Record<string, any> = {};
+          for (const [key, value] of Object.entries(argv)) {
+
+            // Skip known options
+            if (['positionals', '_', '$0'].includes(key)) {
+              continue;
+            }
+            requestData[key] = value;
+          }
+
+          try {
+            const result = await callEndpoint({
+              baseUrl: config.baseUrl,
+              positionalArgs: argv.positionals as string[],
+              namedArgs: requestData,
+            });
+          } catch (error) {
+            console.error('Error calling endpoint:');
+            if (error instanceof Error) {
+              console.error(error.message);
+              if (error.stack) {
+                console.error('\nStack trace:');
+                console.error(error.stack);
+              }
+            } else {
+              console.error(String(error));
+            }
+            process.exit(1);
+          }
+        } catch (error) {
+          if (error instanceof Error && error.stack) {
+            console.error(error.stack);
+          } else {
+            console.error('Error:', error instanceof Error ? error.message : String(error));
+          }
+          process.exit(1);
+        }
+      }
+    )
+    .command(
+      'generate-api-clients',
+      'Generate TypeScript API client types from OpenAPI schema',
+      (yargs) => {
+        return yargs.option('out', {
+          type: 'string',
+          array: true,
+          describe: 'Output file path(s) to write generated types to',
+        });
+      },
+      async (argv) => {
+        try {
+          const cwd = process.cwd();
+          const envConfig = loadEnv(cwd);
+          console.log(`Using API server at: ${envConfig.baseUrl}\n`);
+
+          let outputFiles: string[] = [];
+
+          if (argv.out && argv.out.length > 0) {
+            outputFiles = argv.out;
+          } else {
+            const result = loadConfig(cwd);
+            if (!result || result.config.generateApiClientTargets.length === 0) {
+              console.error('Error: No output files specified.');
+              console.error('Either use --out to specify output files, or configure targets in .prism.qc:');
+              console.error('  generate-api-client-target out=./src/api-types.ts');
+              process.exit(1);
+            }
+            outputFiles = result.config.generateApiClientTargets.map(t => t.outputFile);
+          }
+
+          await generateApiClients(envConfig.baseUrl, outputFiles);
+        } catch (error) {
+          if (error instanceof Error && error.stack) {
+            console.error(error.stack);
+          } else {
+            console.error('Error:', error instanceof Error ? error.message : String(error));
+          }
+          process.exit(1);
+        }
+      }
+    );
+
+    docFiles.yargsSetup(args);
+
+    args
+    .strictCommands()
+    .demandCommand(1, 'You must specify a command')
+    .help()
+    .alias('help', 'h')
+    .version(packageJson.version)
+    .alias('version', 'v')
+    .example([
+      ['$0 list-endpoints', 'List all available endpoints'],
+      ['$0 call /api/users', 'Call GET /api/users'],
+      ['$0 call POST /api/users --name "John" --email "john@example.com"', 'call POST with data'],
+      ['$0 call POST /api/users --config \'{"timeout":30}\'', 'pass JSON objects as args'],
+      ['$0 generate-api-clients --out ./api-types.ts', 'Generate API client types to a file'],
+      ['$0 generate-api-clients --out ./types.ts --out ./backup/types.ts', 'Write to multiple files'],
+    ])
+    .parse();
+}
+
+main();

package/src/config/ConfigFile.ts

@@ -0,0 +1,7 @@
+export interface GenerateApiClientTarget {
+  outputFile: string;
+}
+
+export interface ConfigFile {
+  generateApiClientTargets: GenerateApiClientTarget[];
+}

package/src/config/index.ts

@@ -0,0 +1,3 @@
+export type { ConfigFile, GenerateApiClientTarget } from './ConfigFile.ts';
+export type { LoadConfigResult } from './loadConfig.ts';
+export { loadConfig } from './loadConfig.ts';

package/src/config/loadConfig.ts

@@ -0,0 +1,58 @@
+import { existsSync, readFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { parseFile } from '@facetlayer/qc';
+import type { ConfigFile, GenerateApiClientTarget } from './ConfigFile.ts';
+
+const CONFIG_FILENAME = '.prism.qc';
+
+export interface LoadConfigResult {
+  config: ConfigFile;
+  configDir: string;
+}
+
+/**
+ * Find and load the .prism.qc config file.
+ * Searches in the provided directory and parent directories until found or root is reached.
+ */
+export function loadConfig(cwd: string): LoadConfigResult | null {
+  let currentDir = resolve(cwd);
+
+  while (true) {
+    const configPath = join(currentDir, CONFIG_FILENAME);
+
+    if (existsSync(configPath)) {
+      const config = parseConfigFile(configPath);
+      return { config, configDir: currentDir };
+    }
+
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      // Reached root directory
+      return null;
+    }
+    currentDir = parentDir;
+  }
+}
+
+function parseConfigFile(configPath: string): ConfigFile {
+  const content = readFileSync(configPath, 'utf-8');
+  const queries = parseFile(content);
+
+  const generateApiClientTargets: GenerateApiClientTarget[] = [];
+
+  for (const query of queries) {
+    switch (query.command) {
+      case 'generate-api-client': {
+        const outputFile = query.getStringValue('output-file');
+        generateApiClientTargets.push({ outputFile });
+        break;
+      }
+      default:
+        throw new Error(`Unknown command "${query.command}" in ${CONFIG_FILENAME}`);
+    }
+  }
+
+  return {
+    generateApiClientTargets,
+  };
+}

package/src/generate-api-clients.ts

@@ -0,0 +1,203 @@
+interface OpenAPISchema {
+  paths: Record<string, Record<string, Operation>>;
+  components?: {
+    schemas?: Record<string, any>;
+  };
+}
+
+interface Operation {
+  operationId?: string;
+  requestBody?: {
+    content?: {
+      'application/json'?: {
+        schema?: any;
+      };
+    };
+  };
+  responses?: {
+    '200'?: {
+      content?: {
+        'application/json'?: {
+          schema?: any;
+        };
+      };
+    };
+  };
+}
+
+interface EndpointMapping {
+  method: string;
+  path: string;
+  operationId: string;
+}
+
+function capitalizeFirst(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+/**
+ * Convert OpenAPI path parameter format {param} to Express format :param
+ */
+export function convertToExpressPath(openApiPath: string): string {
+  return openApiPath.replace(/\{([^}]+)\}/g, ':$1');
+}
+
+function schemaToTypeScript(schema: any, components?: Record<string, any>, indent = 0): string {
+  if (!schema) {
+    return 'unknown';
+  }
+
+  const indentStr = '  '.repeat(indent);
+
+  // Handle $ref
+  if (schema.$ref) {
+    const refName = schema.$ref.split('/').pop();
+    return refName;
+  }
+
+  // Handle array
+  if (schema.type === 'array') {
+    const itemType = schemaToTypeScript(schema.items, components, indent);
+    return `Array<${itemType}>`;
+  }
+
+  // Handle object
+  if (schema.type === 'object' || schema.properties) {
+    const properties = schema.properties || {};
+    const required = schema.required || [];
+
+    if (Object.keys(properties).length === 0) {
+      return 'Record<string, unknown>';
+    }
+
+    const props = Object.entries(properties).map(([key, value]: [string, any]) => {
+      const isRequired = required.includes(key);
+      const propType = schemaToTypeScript(value, components, indent + 1);
+      const optional = isRequired ? '' : '?';
+      return `${indentStr}  ${key}${optional}: ${propType};`;
+    });
+
+    return `{\n${props.join('\n')}\n${indentStr}}`;
+  }
+
+  // Handle primitives
+  switch (schema.type) {
+    case 'string':
+      return 'string';
+    case 'number':
+    case 'integer':
+      return 'number';
+    case 'boolean':
+      return 'boolean';
+    case 'null':
+      return 'null';
+    default:
+      return 'unknown';
+  }
+}
+
+import { mkdirSync, writeFileSync } from 'fs';
+import { dirname, resolve } from 'path';
+
+export async function generateApiClients(baseUrl: string, outputFiles: string[]): Promise<void> {
+  if (outputFiles.length === 0) {
+    throw new Error('At least one --out file must be specified');
+  }
+
+  try {
+    // Fetch the OpenAPI schema from the server
+    const response = await fetch(`${baseUrl}/openapi.json`);
+
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch OpenAPI schema: ${response.status} ${response.statusText}\n` +
+        `Make sure the Prism API server is running at ${baseUrl}`
+      );
+    }
+
+    const schema = await response.json() as OpenAPISchema;
+
+    const lines: string[] = [];
+    const endpointMap: EndpointMapping[] = [];
+
+    // Generate component schemas first
+    if (schema.components?.schemas) {
+      lines.push('// Component Schemas');
+      for (const [name, componentSchema] of Object.entries(schema.components.schemas)) {
+        const typeStr = schemaToTypeScript(componentSchema, schema.components.schemas);
+        lines.push(`export type ${name} = ${typeStr};\n`);
+      }
+      lines.push('');
+    }
+
+    // Process each endpoint
+    lines.push('// Endpoint Types');
+    for (const [pathStr, pathItem] of Object.entries(schema.paths)) {
+      for (const [method, operation] of Object.entries(pathItem)) {
+        if (!operation.operationId) continue;
+
+        const typeName = capitalizeFirst(operation.operationId);
+        const expressPath = convertToExpressPath(pathStr);
+        endpointMap.push({ method: method.toLowerCase(), path: expressPath, operationId: operation.operationId });
+
+        // Generate Request type
+        const requestSchema = operation.requestBody?.content?.['application/json']?.schema;
+        const requestType = requestSchema
+          ? schemaToTypeScript(requestSchema, schema.components?.schemas)
+          : 'void';
+        lines.push(`export type ${typeName}Request = ${requestType};\n`);
+
+        // Generate Response type
+        const responseSchema = operation.responses?.['200']?.content?.['application/json']?.schema;
+        const responseType = responseSchema
+          ? schemaToTypeScript(responseSchema, schema.components?.schemas)
+          : 'void';
+        lines.push(`export type ${typeName}Response = ${responseType};\n`);
+      }
+    }
+
+    // Generate ApiEndpoint union type
+    lines.push('// Union type of all valid endpoints');
+    lines.push('export type ApiEndpoint =');
+    const endpointStrings = endpointMap.map(({ method, path }) => `  | "${method} ${path}"`);
+    lines.push(endpointStrings.join('\n'));
+    lines.push(';\n');
+
+    // Generate generic RequestType and ResponseType
+    lines.push('// Generic Request/Response Types by Endpoint');
+    lines.push('export type RequestType<T extends ApiEndpoint> =');
+    const requestCases = endpointMap.map(({ method, path, operationId }) =>
+      `  T extends "${method} ${path}" ? ${capitalizeFirst(operationId)}Request :`
+    );
+    lines.push(requestCases.join('\n'));
+    lines.push('  never;\n');
+
+    lines.push('export type ResponseType<T extends ApiEndpoint> =');
+    const responseCases = endpointMap.map(({ method, path, operationId }) =>
+      `  T extends "${method} ${path}" ? ${capitalizeFirst(operationId)}Response :`
+    );
+    lines.push(responseCases.join('\n'));
+    lines.push('  never;\n');
+
+    const output = lines.join('\n');
+
+    // Add header comment
+    const header = `// Generated API client types
+// Auto-generated from OpenAPI schema - do not edit manually
+
+`;
+
+    const content = header + output;
+
+    // Write to each output file
+    for (const outputFile of outputFiles) {
+      const resolvedPath = resolve(outputFile);
+      mkdirSync(dirname(resolvedPath), { recursive: true });
+      writeFileSync(resolvedPath, content, 'utf-8');
+      console.log(`Written: ${resolvedPath}`);
+    }
+  } catch (error) {
+    console.error('❌ Error generating client:', error);
+    throw error;
+  }
+}

package/src/getPorts.ts

@@ -0,0 +1,39 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as dotenv from 'dotenv';
+
+/**
+ * Finds and reads the .env file for a directory
+ * Searches in the directory itself, then checks parent directories
+ * @param dir - Directory to search from
+ * @returns Parsed environment variables
+ */
+function loadEnvFile(dir: string): Record<string, string> {
+  // First, check if there's a .env file directly in the provided directory
+  let envPath = path.join(dir, '.env');
+
+  if (fs.existsSync(envPath)) {
+    const envConfig = dotenv.parse(fs.readFileSync(envPath));
+    return envConfig;
+  }
+
+  throw new Error(`Environment file not found. Searched: ${dir}/.env`);
+}
+
+/**
+ * Gets the port from a directory's .env file
+ * @param options - Configuration options
+ * @param options.dir - Directory to search for .env file (defaults to current working directory)
+ * @returns The port number
+ */
+export function getPort(options?: { dir?: string }): number {
+  const dir = options?.dir || process.cwd();
+  const env = loadEnvFile(dir);
+
+  if (env.PORT) {
+    return parseInt(env.PORT, 10);
+  }
+
+  throw new Error('Unable to determine port from .env file');
+}
+

package/src/list-endpoints-command.ts

@@ -0,0 +1,34 @@
+import { callEndpoint } from './call-command.ts';
+
+/**
+ * List all available endpoints by calling /endpoints.json
+ */
+export async function listEndpoints(baseUrl: string): Promise<void> {
+  try {
+    const response = await callEndpoint({
+      baseUrl,
+      positionalArgs: ['GET', '/endpoints.json'],
+      namedArgs: {},
+      quiet: true,
+    });
+
+    const endpoints = response.endpoints;
+
+    console.log('Available endpoints:\n');
+    if (Array.isArray(endpoints)) {
+      for (const endpoint of endpoints) {
+        const fullPath = `${endpoint.method} ${endpoint.path}`;
+        console.log(`  ${fullPath}`);
+        if (endpoint.description) {
+          console.log(`    ${endpoint.description}`);
+        }
+      }
+    } else {
+      console.log(JSON.stringify(endpoints, null, 2));
+    }
+  } catch (error) {
+    console.error('Could not list endpoints. The server may not support the /api/endpoints introspection endpoint.');
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}

package/src/loadEnv.ts

@@ -0,0 +1,59 @@
+import * as path from 'path';
+import * as fs from 'fs';
+import { config } from 'dotenv';
+
+export interface EnvConfig {
+  port: number;
+  baseUrl: string;
+}
+
+/**
+ * Load and parse the .env file from the project directory
+ * @param cwd - Current working directory to search from
+ * @returns Configuration object with port and baseUrl
+ * @throws Error if .env file is missing or PRISM_API_PORT is not defined
+ */
+export function loadEnv(cwd: string): EnvConfig {
+  const envPath = path.resolve(cwd, '.env');
+
+  if (!fs.existsSync(envPath)) {
+    throw new Error(
+      `No .env file found at ${envPath}\n\n` +
+      'Please create a .env file with PRISM_API_PORT defined.\n' +
+      'Example:\n' +
+      '  PRISM_API_PORT=3000'
+    );
+  }
+
+  // Load the .env file
+  const result = config({ path: envPath });
+
+  if (result.error) {
+    throw new Error(`Failed to load .env file: ${result.error.message}`);
+  }
+
+  const port = process.env.PRISM_API_PORT;
+
+  if (!port) {
+    throw new Error(
+      'PRISM_API_PORT is not defined in .env file\n\n' +
+      'Please add PRISM_API_PORT to your .env file.\n' +
+      'Example:\n' +
+      '  PRISM_API_PORT=3000'
+    );
+  }
+
+  const portNumber = parseInt(port, 10);
+
+  if (isNaN(portNumber) || portNumber <= 0 || portNumber > 65535) {
+    throw new Error(
+      `Invalid PRISM_API_PORT value: ${port}\n\n` +
+      'Port must be a number between 1 and 65535'
+    );
+  }
+
+  return {
+    port: portNumber,
+    baseUrl: `http://localhost:${portNumber}`,
+  };
+}

package/test/call-command.test.ts

@@ -0,0 +1,96 @@
+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)']
+        }
+      });
+    });
+  });
+});