@facetlayer/prism-framework 0.4.0

package/dist/generate-api-clients.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Convert OpenAPI path parameter format {param} to Express format :param
+ */
+export declare function convertToExpressPath(openApiPath: string): string;
+export declare function generateApiClients(baseUrl: string, outputFiles: string[]): Promise<void>;
+//# sourceMappingURL=generate-api-clients.d.ts.map

package/dist/generate-api-clients.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-api-clients.d.ts","sourceRoot":"","sources":["../src/generate-api-clients.ts"],"names":[],"mappings":"AAqCA;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEhE;AA2DD,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAqG9F"}

package/dist/getPorts.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 declare function getPort(options?: {
+    dir?: string;
+}): number;
+//# sourceMappingURL=getPorts.d.ts.map

package/dist/getPorts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getPorts.d.ts","sourceRoot":"","sources":["../src/getPorts.ts"],"names":[],"mappings":"AAsBA;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAS1D"}

package/dist/list-endpoints-command.d.ts

@@ -0,0 +1,5 @@
+/**
+ * List all available endpoints by calling /endpoints.json
+ */
+export declare function listEndpoints(baseUrl: string): Promise<void>;
+//# sourceMappingURL=list-endpoints-command.d.ts.map

package/dist/list-endpoints-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-endpoints-command.d.ts","sourceRoot":"","sources":["../src/list-endpoints-command.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BlE"}

package/dist/loadEnv.d.ts

@@ -0,0 +1,12 @@
+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 declare function loadEnv(cwd: string): EnvConfig;
+//# sourceMappingURL=loadEnv.d.ts.map

package/dist/loadEnv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadEnv.d.ts","sourceRoot":"","sources":["../src/loadEnv.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CA2C9C"}

package/docs/endpoint-tools.md

@@ -0,0 +1,116 @@
+---
+name: endpoint-tools
+description: CLI tools for listing and calling API endpoints on a running Prism server
+---
+
+# Endpoint Tools
+
+The `prism` CLI provides commands for interacting with your API endpoints. These tools connect to a running Prism API server.
+
+## Prerequisites
+
+Both commands require:
+- A running Prism API server
+- A `.env` file with `PRISM_API_PORT` set to your server's port
+
+## prism list-endpoints
+
+Lists all available endpoints from a running server.
+
+```bash
+prism list-endpoints
+```
+
+Output:
+```
+Using API server at: http://localhost:4003
+
+Available endpoints:
+
+  GET /users
+    List all users
+  POST /users
+    Create a new user
+  GET /users/:id
+    Get user by ID
+  DELETE /users/:id
+    Delete a user
+```
+
+## prism call
+
+Calls an endpoint on a running server.
+
+### Basic Usage
+
+**Important:** Do not use the `/api` prefix in endpoint paths. Use the path directly as defined in the endpoint.
+
+```bash
+# GET request
+prism call /users
+
+# Explicit method
+prism call GET /users
+
+# POST with data
+prism call POST /users --name "John Doe" --email "john@example.com"
+
+# Other methods
+prism call PUT /users/123 --name "Jane"
+prism call PATCH /users/123 --status active
+prism call DELETE /users/123
+```
+
+### Passing Data
+
+Named arguments become the request body:
+
+```bash
+prism call POST /users --name "John" --age 30 --active true
+```
+
+Sends:
+```json
+{
+  "name": "John",
+  "age": 30,
+  "active": true
+}
+```
+
+### JSON Objects
+
+Arguments that look like JSON are parsed automatically:
+
+```bash
+prism call POST /config --settings '{"timeout": 30, "retries": 3}'
+```
+
+### Output
+
+The command prints the response status and body:
+
+```
+Response status: 200
+Response: {"id":"123","name":"John","email":"john@example.com"}
+```
+
+## Troubleshooting
+
+### "Failed to connect"
+
+1. **Check the server is running** - Start your API server
+2. **Verify PRISM_API_PORT** - Ensure `.env` contains `PRISM_API_PORT` matching your server port
+3. **Check dotenv is loaded** - Your server must load the `.env` file:
+
+```typescript
+import { config } from 'dotenv';
+config({ path: '.env' });
+
+const PORT = parseInt(process.env.PRISM_API_PORT, 10);
+await startServer({ app, port: PORT });
+```
+
+### "Endpoint not found"
+
+Use `prism list-endpoints` to see available endpoints and verify the path.

package/docs/env-files.md

@@ -0,0 +1,64 @@
+---
+name: env-files
+description: Recommended strategy for environment variable configuration in Prism Framework projects
+---
+
+# Environment Files Strategy
+
+The typical env variables needed for a Prism app are:
+
+### Backend
+
+Next to the API / backend code there should be a .env file with:
+
+
+| name | example value | description |
+| ---- | ------------- | ----------- |
+| PRISM_API_PORT | `<port number>` | The port for the web server |
+| DATABASE_DIR | data | The relative path to a folder that has SQlite databases |
+| WEB_BASE_URL | `http://localhost:<number>` | The URL for the web server |
+| ALLOW_LOCALHOST | `true` | Whether to allow localhost CORS origins for local development |
+
+### Frontend
+
+#### Next.js
+
+| name | example value | description |
+| ---- | ------------- | ----------- |
+| PORT | `<port number>` | The port for the web server. Should match WEB_BASE_URL from the backend. |
+| NEXT_PUBLIC_API_URL | `http://localhost:<number>` | The URL for the API server. Should match PRISM_API_PORT from the backend. |
+
+Remember that if a variable is used in the frontend code, it needs a prefix of `NEXT_PUBLIC_`.
+
+Next.js doesn't load the .env file by default so it's recommended to have this script in package.json:
+
+  "scripts": {
+    "dev": "dotenv -e .env next dev",
+    ...
+  },
+
+#### Vite
+
+| name | example value | description |
+| ---- | ------------- | ----------- |
+| VITE_API_URL | `http://localhost:<number>` | The URL for the API server. Only needed if not using the Vite proxy approach. |
+
+Vite uses the `VITE_` prefix instead of `NEXT_PUBLIC_` for client-exposed variables. Vite loads `.env` files automatically — no extra setup needed.
+
+Access in code:
+
+```typescript
+const apiUrl = import.meta.env.VITE_API_URL;
+```
+
+See the `vite-setup` doc in `@facetlayer/prism-framework-ui` for more details.
+
+# Port assignment
+
+It's recommended to use the `@facetlayer/port-assignment` tool if you need to assign new unique port numbers.
+
+Example:
+
+    npx @facetlayer/port-assignment claim --name <project name>
+
+Run `npx @facetlayer/port-assigment list-docs` for more documentation.

package/docs/generate-api-clients-config.md

@@ -0,0 +1,84 @@
+---
+name: generate-api-clients-config
+description: Configuration file setup for automatic API client type generation
+---
+
+# Generate API Clients Configuration
+
+The `prism generate-api-clients` command generates TypeScript types from your API's OpenAPI schema. You can configure output targets using a `.prism.qc` config file.
+
+## Config File Location
+
+Create a `.prism.qc` file in your project root (where you run `prism` commands from).
+
+## Basic Syntax
+
+The config uses the QC format. Each target is defined with a `generate-api-client` command:
+
+```
+generate-api-client
+  output-file=<path-to-output-file>
+```
+
+The `output-file` path is relative to the project root.
+
+## Examples
+
+### Single Output File
+
+```
+generate-api-client
+  output-file=./src/api-types.ts
+```
+
+### Multiple Output Files
+
+You can define multiple targets to generate the same types to multiple locations:
+
+```
+generate-api-client
+  output-file=./ui/src/lib/api-types.ts
+
+generate-api-client
+  output-file=./mobile/src/api-types.ts
+```
+
+### Typical Project Layouts
+
+**Monorepo with separate UI package:**
+
+```
+generate-api-client
+  output-file=./ui/src/lib/api-types.ts
+```
+
+**Monorepo with web directory:**
+
+```
+generate-api-client
+  output-file=./web/src/client/api-types.ts
+```
+
+## Usage
+
+Once configured, run:
+
+```bash
+prism generate-api-clients
+```
+
+The command will:
+1. Read the API server URL from your `.env` file (`PRISM_API_PORT`)
+2. Fetch the OpenAPI schema from `http://localhost:<port>/openapi.json`
+3. Generate TypeScript types and write them to all configured output files
+
+You can also override the config by specifying `--out` directly:
+
+```bash
+prism generate-api-clients --out ./custom/path/types.ts
+```
+
+## Requirements
+
+- The API server must be running and serving `/openapi.json`
+- A `.env` file with `PRISM_API_PORT` must exist in the project root

package/docs/getting-started.md

@@ -0,0 +1,86 @@
+---
+name: getting-started
+description: Guide for setting up a new Prism Framework project with type-safe API and frontend client generation
+---
+
+# Prism Framework Getting Started Guide
+
+## Intro
+
+"Prism framework" is a set of Node.js libraries for a full-stack app that can target multiple platforms.
+
+This includes the following NPM libraries:
+
+### `@facetlayer/prism-framework`
+ - Base library with tooling for various development and testing tasks
+ - Should be installed at the top level in the devDependencies section
+ - First place to look for documentation (`prism list-docs`)
+
+### `@facetlayer/prism-framework-api`
+ - Backend API framework
+ - Can be hosted on HTTP with Express.js
+ - Also supports other launch methods such as IPC for Electron
+
+### `@facetlayer/prism-framework-ui`
+ - Helpers for React-based frontend web apps
+
+### `@facetlayer/prism-framework-desktop`
+ - Helper framework for Electron based desktop apps
+
+## Getting started
+
+ - Install `@facetlayer/prism-framework`
+ - Start using the `prism` CLI tool, especially:
+   - `prism list-docs` - List available documentation files.
+   - `prism get-doc <name>` - Read a documentation file.
+
+## Example Project Setup
+
+Some ways to set up the repo for a Prism project:
+
+### Option 1: API in separate directory
+
+ - `./api` - Backend API
+   - `./api/package.json` - Contains prism-framework-api
+   - `./api/src/` - Backend service implementation
+ - `./web` or `./ui` - Frontend web app
+   - `./web/package.json` - Contains Next.js or Vite, and prism-framework-ui
+   - `./web/src` - Frontend implementation
+
+### Option 2: API in top level directory
+
+ - `./package.json` - Contains prism-framework-api
+ - `./src` - Backend API source code
+ - `./web` or `./ui` - Frontend web app
+   - `./web/package.json` - Contains Next.js or Vite, and prism-framework-ui
+   - `./web/src`
+
+### Frontend framework choice
+
+ - **Vite + React** - Recommended for local tools, GUIs, and apps that don't need SSR. Lighter weight and faster dev server. See the `vite-setup` doc in `@facetlayer/prism-framework-ui`.
+ - **Next.js** - Recommended for production web apps that need SSR, routing, or deployment to platforms like Vercel. See the `nextjs-setup` doc in `@facetlayer/prism-framework-ui`.
+
+## Packages
+
+ - For package management use `pnpm`
+   - Make sure to set up a `pnpm-workspace.yaml` file in the top level
+
+### Top level tools
+
+The top level of the project should have these dependencies:
+
+    `pnpm add typescript dotenv @facetlayer/prism-framework`
+
+## Local service management
+
+Prism projects usually use the `candle` tool (from @facetlayer/candle) to run local services.
+
+Examples:
+
+ Browse documentation:
+   `candle list-docs`
+
+ Set up services in the .candle.json file:
+   `candle add-service api "node --watch src/_main/api.ts" --root ./api
+   `candle add-service web "pnpm dev" --root ./web
+

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@facetlayer/prism-framework",
+  "version": "0.4.0",
+  "description": "Base library and CLI tools for the Prism app framework",
+  "type": "module",
+  "main": "dist/cli.js",
+  "types": "dist/cli.d.ts",
+  "bin": {
+    "prism": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "node build.mts build",
+    "prepublishOnly": "node build.mts validate && node build.mts build",
+    "typecheck": "tsc -p .",
+    "test": "vitest run --testTimeout=30000",
+    "local:install": "pnpm build && npm i -g ."
+  },
+  "keywords": [
+    "framework",
+    "testing",
+    "tools",
+    "typescript"
+  ],
+  "author": "",
+  "license": "MIT",
+  "packageManager": "pnpm@10.15.1",
+  "dependencies": {
+    "@facetlayer/doc-files-helper": "0.1.2",
+    "@facetlayer/prism-framework-api": "0.2.0",
+    "@facetlayer/qc": "^0.1.0",
+    "dotenv": "^16.4.7",
+    "uuid": "^11.1.0",
+    "yargs": "18.0.0"
+  },
+  "devDependencies": {
+    "@facetlayer/build-config-nodejs": "^0.3.0",
+    "@types/node": "^22.10.2",
+    "@types/uuid": "^10.0.0",
+    "@types/yargs": "17.0.34",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.0"
+  }
+}

package/src/call-command.ts

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+
+const EVERY_METHOD = new Set(['GET','POST','PUT','PATCH',"DELETE"]);
+
+export interface CallEndpointLooseOptions {
+  baseUrl: string
+  positionalArgs: string[]
+  namedArgs: Record<string,any>
+  quiet?: boolean
+}
+
+interface CallEndpointOptions {
+  baseUrl: string
+  method: string
+  path: string
+  requestBody: null | Record<string, any>
+}
+
+function parseValue(value: any): any {
+  if (typeof value === 'string') {
+    // Special case: If the string value looks like {..} or [..], then
+    // parse it as JSON. This way we can use object-based endpoints
+    // using CLI parameters.
+    const trimmed = value.trim();
+    if ((trimmed.startsWith('{') && trimmed.endsWith('}')) ||
+        (trimmed.startsWith('[') && trimmed.endsWith(']'))) {
+      try {
+        return JSON.parse(trimmed);
+      } catch {
+        // If JSON parsing fails, keep the original string
+        return value;
+      }
+    }
+  } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    // Recursively parse nested objects (yargs creates these from dot notation)
+    const result: Record<string, any> = {};
+    for (const [k, v] of Object.entries(value)) {
+      result[k] = parseValue(v);
+    }
+    return result;
+  }
+  return value;
+}
+
+export function parseNamedArgs(namedArgs: Record<string, any>): Record<string, any> {
+  const result: Record<string, any> = {};
+  for (const [key, value] of Object.entries(namedArgs)) {
+    result[key] = parseValue(value);
+  }
+  return result;
+}
+
+function parseOptions(looseOptions: CallEndpointLooseOptions): CallEndpointOptions {
+  const result: CallEndpointOptions = {
+    baseUrl: looseOptions.baseUrl,
+    method: 'GET',
+    path: '/',
+    requestBody: parseNamedArgs(looseOptions.namedArgs),
+  };
+
+  // Look at the positional args and figure out what they mean.
+  for (const positional of looseOptions.positionalArgs) {
+    if (positional.startsWith('/')) {
+      result.path = positional;
+      continue;
+    }
+
+    if (EVERY_METHOD.has(positional.toUpperCase())) {
+      result.method = positional.toUpperCase();
+      continue;
+    }
+
+    if (positional.startsWith("http:") || positional.startsWith("https:")) {
+      result.baseUrl = positional;
+      continue;
+    }
+
+    throw new Error("unrecognized positional arg:" + positional);
+  }
+
+  return result;
+
+}
+
+/**
+ * Make an HTTP request to the local Prism API server
+ */
+export async function callEndpoint(looseOptions: CallEndpointLooseOptions) {
+  const options = parseOptions(looseOptions);
+  const url = `${options.baseUrl}${options.path}`;
+
+  const requestOptions: RequestInit = {
+    method: options.method,
+    headers: {
+      'Content-Type': 'application/json',
+    },
+  };
+
+  // Add body for methods that support it
+  if (['POST', 'PUT', 'PATCH', 'DELETE'].includes(options.method)
+      && options.requestBody
+      && Object.keys(options.requestBody).length > 0) {
+    requestOptions.body = JSON.stringify(options.requestBody);
+  }
+
+  try {
+    const response = await fetch(url, requestOptions);
+
+    if (!looseOptions.quiet)
+      console.log('Response status: ' + response.status);
+
+    // Get the response text first
+    const responseText = await response.text();
+
+    if (!looseOptions.quiet)
+      console.log('Response: ', responseText);
+
+    // Try to parse as JSON
+    let responseData;
+    try {
+      responseData = responseText ? JSON.parse(responseText) : null;
+    } catch {
+      // If not JSON, return as text
+      responseData = responseText;
+    }
+
+    if (!response.ok) {
+      throw new Error(
+        `HTTP ${response.status} ${response.statusText}\n` +
+        `Response: ${JSON.stringify(responseData, null, 2)}`
+      );
+    }
+
+    return responseData;
+  } catch (error) {
+    if (error instanceof Error) {
+      if (error.message.includes('fetch failed') || error.message.includes('ECONNREFUSED')) {
+        throw new Error(
+          `Failed to connect to ${url}\n\n` +
+          'Make sure your Prism API server is running.\n' +
+          `The server should be listening on the port specified in .env (PRISM_API_PORT)`
+        );
+      }
+    }
+    throw error;
+  }
+}