@plures/praxis 1.0.2 → 1.1.0

package/docs/core/building-extensions.md

@@ -4,13 +4,13 @@ Praxis is designed to be extensible. This guide explains how to create plugins,
 
 ## Extension Types
 
-| Type | Description | Use Case |
-|------|-------------|----------|
-| **Plugins** | Extend engine behavior | Add middleware, effects, logging |
-| **Generators** | Custom code generation | Generate for other frameworks |
-| **Adapters** | External integrations | Connect to databases, APIs |
-| **Templates** | Custom project scaffolding | Organization-specific setups |
-| **Canvas Extensions** | Extend visual editor | Custom components, tools |
+| Type                  | Description                | Use Case                         |
+| --------------------- | -------------------------- | -------------------------------- |
+| **Plugins**           | Extend engine behavior     | Add middleware, effects, logging |
+| **Generators**        | Custom code generation     | Generate for other frameworks    |
+| **Adapters**          | External integrations      | Connect to databases, APIs       |
+| **Templates**         | Custom project scaffolding | Organization-specific setups     |
+| **Canvas Extensions** | Extend visual editor       | Custom components, tools         |
 
 ## Plugins
 
@@ -29,28 +29,28 @@ interface LoggerOptions {
 export function createLoggerPlugin(options: LoggerOptions): PraxisPlugin {
   return {
     name: 'logger',
-    
+
     // Called when engine is created
     onInit(engine) {
       console.log(`${options.prefix || ''} Engine initialized`);
     },
-    
+
     // Called before each step
     beforeStep(state, events) {
       if (options.level === 'debug') {
         console.log('Events:', events);
       }
-      return { state, events };  // Can modify
+      return { state, events }; // Can modify
     },
-    
+
     // Called after each step
     afterStep(result) {
       if (options.level === 'debug') {
         console.log('Facts:', result.state.facts);
       }
-      return result;  // Can modify
+      return result; // Can modify
     },
-    
+
     // Called on error
     onError(error, state, events) {
       console.error(`${options.prefix || ''} Error:`, error);
@@ -81,26 +81,22 @@ const engine = createPraxisEngine({
 ```typescript
 interface PraxisPlugin<TContext = any> {
   name: string;
-  
+
   // Lifecycle hooks
   onInit?(engine: PraxisEngine<TContext>): void;
   onDestroy?(): void;
-  
+
   // Step hooks
   beforeStep?(
     state: PraxisState<TContext>,
     events: PraxisEvent[]
   ): { state: PraxisState<TContext>; events: PraxisEvent[] };
-  
+
   afterStep?(result: StepResult<TContext>): StepResult<TContext>;
-  
+
   // Error handling
-  onError?(
-    error: Error,
-    state: PraxisState<TContext>,
-    events: PraxisEvent[]
-  ): void;
-  
+  onError?(error: Error, state: PraxisState<TContext>, events: PraxisEvent[]): void;
+
   // Subscription
   onStateChange?(state: PraxisState<TContext>): void;
 }
@@ -123,10 +119,10 @@ interface ReactGeneratorOptions {
 export const reactGenerator: Generator<ReactGeneratorOptions> = {
   name: 'react',
   description: 'Generate React components from PSF schema',
-  
+
   generate(schema: PSFSchema, options: ReactGeneratorOptions): GeneratorOutput[] {
     const outputs: GeneratorOutput[] = [];
-    
+
     // Generate components
     for (const component of schema.components) {
       const code = generateReactComponent(component, options);
@@ -136,7 +132,7 @@ export const reactGenerator: Generator<ReactGeneratorOptions> = {
         type: 'component',
       });
     }
-    
+
     // Generate types (TypeScript only)
     if (options.typescript) {
       const types = generateTypes(schema);
@@ -146,20 +142,20 @@ export const reactGenerator: Generator<ReactGeneratorOptions> = {
         type: 'types',
       });
     }
-    
+
     return outputs;
   },
 };
 
 function generateReactComponent(component: ComponentDef, options: ReactGeneratorOptions): string {
   const { name, type, model, props } = component;
-  
+
   return `
 import React from 'react';
 ${options.typescript ? `import type { ${model} } from '../types';` : ''}
 
 ${options.typescript ? `interface ${name}Props {` : ''}
-${props?.map(p => `  ${p.name}${p.required ? '' : '?'}: ${p.type};`).join('\n')}
+${props?.map((p) => `  ${p.name}${p.required ? '' : '?'}: ${p.type};`).join('\n')}
 ${options.typescript ? '}' : ''}
 
 export function ${name}(${options.typescript ? `props: ${name}Props` : 'props'}) {
@@ -189,11 +185,11 @@ registerGenerator(reactGenerator);
 
 ```typescript
 interface GeneratorOutput {
-  path: string;           // Output file path
-  content: string;        // Generated code
-  type: OutputType;       // 'component' | 'types' | 'docs' | 'config'
-  overwrite?: boolean;    // Allow overwriting existing files
-  format?: boolean;       // Apply code formatting
+  path: string; // Output file path
+  content: string; // Generated code
+  type: OutputType; // 'component' | 'types' | 'docs' | 'config'
+  overwrite?: boolean; // Allow overwriting existing files
+  format?: boolean; // Apply code formatting
 }
 ```
 
@@ -211,24 +207,24 @@ interface PostgresOptions {
 
 export function createPostgresAdapter(options: PostgresOptions): DatabaseAdapter {
   let pool: Pool;
-  
+
   return {
     name: 'postgres',
-    
+
     async connect() {
       pool = new Pool({ connectionString: options.connectionString });
       await pool.connect();
     },
-    
+
     async disconnect() {
       await pool.end();
     },
-    
+
     async createCollection(name: string, schema: CollectionSchema) {
       const columns = schemaToColumns(schema);
       await pool.query(`CREATE TABLE IF NOT EXISTS ${name} (${columns})`);
     },
-    
+
     async insert(collection: string, document: any) {
       const { columns, values, placeholders } = prepareInsert(document);
       const result = await pool.query(
@@ -237,16 +233,13 @@ export function createPostgresAdapter(options: PostgresOptions): DatabaseAdapter
       );
       return result.rows[0];
     },
-    
+
     async find(collection: string, query: Query) {
       const { where, params } = queryToSQL(query);
-      const result = await pool.query(
-        `SELECT * FROM ${collection} ${where}`,
-        params
-      );
+      const result = await pool.query(`SELECT * FROM ${collection} ${where}`, params);
       return result.rows;
     },
-    
+
     // ... other CRUD operations
   };
 }
@@ -284,6 +277,7 @@ templates/
 ```
 
 **template.json:**
+
 ```json
 {
   "name": "my-template",
@@ -300,14 +294,12 @@ templates/
       "prompt": "Author name"
     }
   ],
-  "postInstall": [
-    "npm install",
-    "npx praxis generate --schema ./src/schema.psf.json"
-  ]
+  "postInstall": ["npm install", "npx praxis generate --schema ./src/schema.psf.json"]
 }
 ```
 
 **package.json.template:**
+
 ```json
 {
   "name": "{{appName}}",
@@ -344,7 +336,7 @@ import type { CanvasExtension, CanvasContext } from '@plures/praxis/canvas';
 
 export const customPaletteExtension: CanvasExtension = {
   name: 'custom-palette',
-  
+
   // Add items to the component palette
   palette: {
     category: 'Custom',
@@ -362,7 +354,7 @@ export const customPaletteExtension: CanvasExtension = {
       },
     ],
   },
-  
+
   // Add toolbar buttons
   toolbar: [
     {
@@ -375,7 +367,7 @@ export const customPaletteExtension: CanvasExtension = {
       },
     },
   ],
-  
+
   // Add context menu items
   contextMenu: [
     {
@@ -393,14 +385,15 @@ export const customPaletteExtension: CanvasExtension = {
 ### Registering Canvas Extensions
 
 **canvas.config.ts:**
+
 ```typescript
 import { customPaletteExtension } from './extensions/custom-palette';
 
 export const config: CanvasConfig = {
   extensions: [
     customPaletteExtension,
-    '@plures/canvas-figma',  // npm package
-    './extensions/my-extension.ts',  // local file
+    '@plures/canvas-figma', // npm package
+    './extensions/my-extension.ts', // local file
   ],
 };
 ```
@@ -421,6 +414,7 @@ my-praxis-extension/
 ```
 
 **package.json:**
+
 ```json
 {
   "name": "@myorg/praxis-extension-foo",
@@ -479,7 +473,7 @@ Handle errors gracefully:
 ```typescript
 export const myPlugin: PraxisPlugin = {
   name: 'my-plugin',
-  
+
   beforeStep(state, events) {
     try {
       // Plugin logic
@@ -500,22 +494,25 @@ Include comprehensive README:
 # My Praxis Extension
 
 ## Installation
+
 \`\`\`bash
 npm install @myorg/praxis-extension-foo
 \`\`\`
 
 ## Usage
+
 \`\`\`typescript
 import { createFooPlugin } from '@myorg/praxis-extension-foo';
 
 const engine = createPraxisEngine({
-  plugins: [createFooPlugin({ option: 'value' })],
+plugins: [createFooPlugin({ option: 'value' })],
 });
 \`\`\`
 
 ## Options
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
+
+| Option | Type   | Default   | Description |
+| ------ | ------ | --------- | ----------- |
 | option | string | 'default' | Description |
 ```
 
@@ -534,15 +531,15 @@ describe('MyPlugin', () => {
     const plugin = createMyPlugin({
       onLog: (msg) => logs.push(msg),
     });
-    
+
     const engine = createPraxisEngine({
       initialContext: {},
       registry: new PraxisRegistry(),
       plugins: [plugin],
     });
-    
+
     engine.dispatch([{ tag: 'TEST', payload: {} }]);
-    
+
     expect(logs).toContain('Step executed');
   });
 });

package/docs/core/cli-usage.md

@@ -46,22 +46,22 @@ praxis create app my-app --directory ./projects
 
 **Options:**
 
-| Option | Description |
-|--------|-------------|
-| `--template` | Template to use: `basic`, `fullstack`, `minimal` |
-| `--directory` | Output directory |
-| `--no-git` | Skip git initialization |
-| `--no-install` | Skip npm install |
+| Option         | Description                                      |
+| -------------- | ------------------------------------------------ |
+| `--template`   | Template to use: `basic`, `fullstack`, `minimal` |
+| `--directory`  | Output directory                                 |
+| `--no-git`     | Skip git initialization                          |
+| `--no-install` | Skip npm install                                 |
 
 **Available Templates:**
 
-| Template | Description |
-|----------|-------------|
-| `basic` | Simple app with logic engine and Svelte |
-| `fullstack` | Complete app with PluresDB, auth, and sync |
-| `minimal` | Bare minimum Praxis setup |
-| `component` | Reusable component library |
-| `orchestrator` | Distributed node orchestration |
+| Template       | Description                                |
+| -------------- | ------------------------------------------ |
+| `basic`        | Simple app with logic engine and Svelte    |
+| `fullstack`    | Complete app with PluresDB, auth, and sync |
+| `minimal`      | Bare minimum Praxis setup                  |
+| `component`    | Reusable component library                 |
+| `orchestrator` | Distributed node orchestration             |
 
 ### `praxis generate`
 
@@ -89,15 +89,15 @@ praxis generate --schema ./schema.psf.json --check
 
 **Options:**
 
-| Option | Description |
-|--------|-------------|
-| `--schema` | Path to PSF schema file |
-| `--output` | Output directory (default: `./generated`) |
-| `--only` | Comma-separated targets: `types`, `components`, `docs`, `rules`, `pluresdb` |
-| `--watch` | Watch for changes and regenerate |
-| `--force` | Overwrite existing files |
-| `--check` | Verify files are up-to-date (exit code 1 if not) |
-| `--format` | Output format: `typescript`, `javascript` |
+| Option     | Description                                                                 |
+| ---------- | --------------------------------------------------------------------------- |
+| `--schema` | Path to PSF schema file                                                     |
+| `--output` | Output directory (default: `./generated`)                                   |
+| `--only`   | Comma-separated targets: `types`, `components`, `docs`, `rules`, `pluresdb` |
+| `--watch`  | Watch for changes and regenerate                                            |
+| `--force`  | Overwrite existing files                                                    |
+| `--check`  | Verify files are up-to-date (exit code 1 if not)                            |
+| `--format` | Output format: `typescript`, `javascript`                                   |
 
 ### `praxis canvas`
 
@@ -122,14 +122,14 @@ praxis canvas ./schema.psf.json --mode view
 
 **Options:**
 
-| Option | Description |
-|--------|-------------|
-| `--port` | Server port (default: 3000) |
-| `--host` | Server host (default: localhost) |
-| `--config` | Path to canvas config file |
-| `--mode` | Mode: `edit`, `view`, `present` |
-| `--new` | Create new schema |
-| `--watch` | Enable file watching |
+| Option     | Description                      |
+| ---------- | -------------------------------- |
+| `--port`   | Server port (default: 3000)      |
+| `--host`   | Server host (default: localhost) |
+| `--config` | Path to canvas config file       |
+| `--mode`   | Mode: `edit`, `view`, `present`  |
+| `--new`    | Create new schema                |
+| `--watch`  | Enable file watching             |
 
 ### `praxis dev`
 
@@ -148,12 +148,12 @@ praxis dev --open
 
 **Options:**
 
-| Option | Description |
-|--------|-------------|
-| `--port` | Server port (default: 5173) |
-| `--host` | Server host (default: localhost) |
-| `--open` | Open browser automatically |
-| `--config` | Path to vite config |
+| Option     | Description                      |
+| ---------- | -------------------------------- |
+| `--port`   | Server port (default: 5173)      |
+| `--host`   | Server host (default: localhost) |
+| `--open`   | Open browser automatically       |
+| `--config` | Path to vite config              |
 
 ### `praxis build`
 
@@ -172,10 +172,10 @@ praxis build --target node
 
 **Options:**
 
-| Option | Description |
-|--------|-------------|
-| `--output` | Output directory |
-| `--target` | Build target: `browser`, `node`, `tauri` |
+| Option     | Description                                  |
+| ---------- | -------------------------------------------- |
+| `--output` | Output directory                             |
+| `--target` | Build target: `browser`, `node`, `tauri`     |
 | `--minify` | Minify output (default: true for production) |
 
 ### `praxis validate`
@@ -195,11 +195,11 @@ praxis validate --schema ./schema.psf.json --strict
 
 **Options:**
 
-| Option | Description |
-|--------|-------------|
-| `--schema` | Path to PSF schema file |
+| Option      | Description                   |
+| ----------- | ----------------------------- |
+| `--schema`  | Path to PSF schema file       |
 | `--verbose` | Show detailed validation info |
-| `--strict` | Treat warnings as errors |
+| `--strict`  | Treat warnings as errors      |
 
 ### `praxis docs`
 
@@ -221,13 +221,13 @@ praxis docs --schema ./schema.psf.json --watch
 
 **Options:**
 
-| Option | Description |
-|--------|-------------|
-| `--schema` | Path to PSF schema file |
+| Option     | Description                          |
+| ---------- | ------------------------------------ |
+| `--schema` | Path to PSF schema file              |
 | `--output` | Output directory (default: `./docs`) |
-| `--format` | Output format: `markdown`, `html` |
-| `--serve` | Serve docs on local server |
-| `--watch` | Watch for changes |
+| `--format` | Output format: `markdown`, `html`    |
+| `--serve`  | Serve docs on local server           |
+| `--watch`  | Watch for changes                    |
 
 ### Cloud Commands
 
@@ -304,7 +304,7 @@ export default {
     path: './src/schema.psf.json',
     validate: true,
   },
-  
+
   // Generation settings
   generate: {
     output: './src/generated',
@@ -312,19 +312,19 @@ export default {
     format: 'typescript',
     formatting: 'prettier',
   },
-  
+
   // Development settings
   dev: {
     port: 5173,
     open: true,
   },
-  
+
   // Canvas settings
   canvas: {
     port: 3000,
     sync: true,
   },
-  
+
   // Cloud settings
   cloud: {
     enabled: true,
@@ -411,18 +411,18 @@ jobs:
       - uses: actions/setup-node@v3
         with:
           node-version: 18
-      
+
       - run: npm install
-      
+
       # Validate schema
       - run: npx praxis validate --schema ./src/schema.psf.json --strict
-      
+
       # Check generated files are current
       - run: npx praxis generate --schema ./src/schema.psf.json --check
-      
+
       # Build
       - run: npx praxis build
-      
+
       # Test
       - run: npm test
 ```