@plures/praxis 1.1.2 → 1.2.0

package/src/cli/commands/docs.ts

@@ -0,0 +1,147 @@
+/**
+ * Docs Command
+ *
+ * Generate documentation from Praxis schemas using State-Docs integration.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { createStateDocsGenerator } from '../../integrations/state-docs.js';
+import { loadSchemaFromFile } from '../../core/schema/loader.js';
+import type { PraxisRegistry } from '../../core/rules.js';
+
+/**
+ * Docs command options
+ */
+export interface DocsOptions {
+  /** Output directory for generated docs */
+  output?: string;
+  /** Documentation title */
+  title?: string;
+  /** Include table of contents */
+  toc?: boolean;
+  /** Include timestamp */
+  timestamp?: boolean;
+  /** Visualization format */
+  format?: 'mermaid' | 'dot';
+  /** Custom header content */
+  header?: string;
+  /** Custom footer content */
+  footer?: string;
+  /** Generate from registry instead of schema */
+  fromRegistry?: boolean;
+}
+
+/**
+ * Generate documentation from schema or registry
+ */
+export async function docs(
+  schemaOrRegistryPath: string | undefined,
+  options: DocsOptions
+): Promise<void> {
+  console.log('\n╔═══════════════════════════════════════════════════╗');
+  console.log('║   Praxis Documentation Generator                 ║');
+  console.log('╚═══════════════════════════════════════════════════╝\n');
+
+  if (!schemaOrRegistryPath || !fs.existsSync(schemaOrRegistryPath)) {
+    console.error('Error: Schema or registry file required');
+    console.log('Usage: praxis docs <schema-file> [options]');
+    console.log('\nOptions:');
+    console.log('  --output <dir>       Output directory (default: ./docs)');
+    console.log('  --title <title>      Documentation title');
+    console.log('  --format <format>    Diagram format: mermaid (default) or dot');
+    console.log('  --no-toc            Disable table of contents');
+    console.log('  --no-timestamp      Disable timestamp');
+    console.log('  --from-registry      Generate from registry instead of schema');
+    process.exit(1);
+  }
+
+  const outputDir = options.output || './docs';
+  const title = options.title || 'Praxis Application';
+
+  // Create generator
+  const generator = createStateDocsGenerator({
+    projectTitle: title,
+    target: outputDir,
+    visualization: {
+      format: options.format || 'mermaid',
+      exportPng: false,
+    },
+    template: {
+      toc: options.toc !== false,
+      timestamp: options.timestamp !== false,
+      header: options.header,
+      footer: options.footer,
+    },
+  });
+
+  console.log(`Source: ${schemaOrRegistryPath}`);
+  console.log(`Output: ${outputDir}\n`);
+
+  try {
+    let generatedDocs;
+
+    if (options.fromRegistry) {
+      // Load registry module
+      console.log('Loading registry module...');
+      const module = await import(path.resolve(schemaOrRegistryPath));
+      const registry: PraxisRegistry<unknown> =
+        module.registry || module.default || module;
+
+      if (!registry || typeof registry.getAllRules !== 'function') {
+        console.error('Error: Invalid registry module');
+        console.log('Expected: export const registry = new PraxisRegistry()');
+        process.exit(1);
+      }
+
+      console.log('Generating documentation from registry...');
+      // Create module object from registry
+      const praxisModule = {
+        rules: registry.getAllRules(),
+        constraints: registry.getAllConstraints(),
+      };
+      generatedDocs = generator.generateFromModule(praxisModule);
+    } else {
+      // Load schema
+      console.log('Loading schema...');
+      const result = await loadSchemaFromFile(schemaOrRegistryPath);
+
+      if (result.errors.length > 0 || !result.schema) {
+        console.error(`Error loading schema: ${result.errors.join(', ')}`);
+        process.exit(1);
+      }
+
+      console.log('Generating documentation from schema...');
+      generatedDocs = generator.generateFromSchema(result.schema);
+    }
+
+    // Ensure output directory exists
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, { recursive: true });
+    }
+
+    // Write all generated docs
+    console.log('\nWriting documentation files:\n');
+    for (const doc of generatedDocs) {
+      const fullPath = path.resolve(doc.path);
+      const dir = path.dirname(fullPath);
+
+      // Ensure directory exists
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+
+      fs.writeFileSync(fullPath, doc.content);
+      console.log(`  ✓ ${doc.path} (${doc.type})`);
+    }
+
+    console.log(`\n✓ Generated ${generatedDocs.length} documentation file(s)`);
+    console.log(`\nView your documentation: ${path.resolve(outputDir, 'README.md')}`);
+  } catch (error) {
+    console.error(`Error generating documentation: ${error}`);
+    if (error instanceof Error) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}

package/src/cli/index.ts

@@ -90,6 +90,27 @@ program
     await generate(options);
   });
 
+program
+  .command('docs [schema]')
+  .description('Generate documentation from schemas or registries')
+  .option('-o, --output <dir>', 'Output directory', './docs')
+  .option('--title <title>', 'Documentation title')
+  .option('--format <format>', 'Diagram format (mermaid, dot)', 'mermaid')
+  .option('--no-toc', 'Disable table of contents')
+  .option('--no-timestamp', 'Disable timestamp')
+  .option('--from-registry', 'Generate from registry instead of schema')
+  .option('--header <content>', 'Custom header content')
+  .option('--footer <content>', 'Custom footer content')
+  .action(async (schema, options) => {
+    try {
+      const { docs } = await import('./commands/docs.js');
+      await docs(schema, options);
+    } catch (error) {
+      console.error('Error generating documentation:', error);
+      process.exit(1);
+    }
+  });
+
 program
   .command('canvas [schema]')
   .description('Open CodeCanvas for visual editing')

package/src/core/pluresdb/README.md

@@ -0,0 +1,156 @@
+# PluresDB Integration
+
+This module provides integration between Praxis and PluresDB for local-first, reactive data storage.
+
+## Overview
+
+Praxis supports PluresDB through a simple adapter interface (`PraxisDB`) that can be backed by:
+
+1. **In-memory storage** (for development/testing) - `InMemoryPraxisDB`
+2. **Official PluresDB** (for production) - `PluresDBPraxisAdapter`
+
+## Using the Official PluresDB
+
+The official PluresDB package from NPM provides a complete local-first database with P2P sync, CRDT conflict resolution, and more.
+
+### Installation
+
+PluresDB is included as a dependency in Praxis:
+
+```bash
+npm install @plures/praxis
+# PluresDB is automatically installed as a dependency
+```
+
+### Basic Usage
+
+```typescript
+import { PluresNode } from 'pluresdb';
+import { createPluresDB, createPraxisDBStore } from '@plures/praxis';
+import { PraxisRegistry } from '@plures/praxis';
+
+// Initialize PluresDB
+const pluresdb = new PluresNode({
+  config: {
+    port: 34567,
+    host: 'localhost',
+    dataDir: './data',
+  },
+  autoStart: true,
+});
+
+// Wrap it with the Praxis adapter
+const db = createPluresDB(pluresdb);
+
+// Use with Praxis store
+const registry = new PraxisRegistry();
+const store = createPraxisDBStore(db, registry);
+
+// Now you can use the store with Praxis engine
+```
+
+### Using with In-Memory Storage (Development)
+
+For testing and development, use the in-memory implementation:
+
+```typescript
+import { createInMemoryDB, createPraxisDBStore } from '@plures/praxis';
+import { PraxisRegistry } from '@plures/praxis';
+
+// Create in-memory database
+const db = createInMemoryDB();
+
+// Use with Praxis store
+const registry = new PraxisRegistry();
+const store = createPraxisDBStore(db, registry);
+```
+
+## API Reference
+
+### PraxisDB Interface
+
+All database adapters implement this interface:
+
+```typescript
+interface PraxisDB {
+  // Get a value by key
+  get<T>(key: string): Promise<T | undefined>;
+  
+  // Set a value by key
+  set<T>(key: string, value: T): Promise<void>;
+  
+  // Watch a key for changes
+  watch<T>(key: string, callback: (val: T) => void): UnsubscribeFn;
+}
+```
+
+### createPluresDB(db)
+
+Creates a Praxis adapter for the official PluresDB package.
+
+**Parameters:**
+- `db`: PluresDB instance (PluresNode or SQLiteCompatibleAPI)
+
+**Returns:** `PluresDBPraxisAdapter` instance
+
+### createInMemoryDB()
+
+Creates an in-memory database for testing/development.
+
+**Returns:** `InMemoryPraxisDB` instance
+
+## Features
+
+### Event Sourcing
+
+Store facts and events in PluresDB:
+
+```typescript
+import { createPraxisEngine, createPluresDBAdapter } from '@plures/praxis';
+
+const adapter = createPluresDBAdapter({ db, registry });
+const engine = createPraxisEngine({ initialContext: {}, registry });
+adapter.attachEngine(engine);
+
+// Events are now persisted to PluresDB
+```
+
+### Reactive Queries
+
+Watch for changes in the database:
+
+```typescript
+const unsubscribe = db.watch('user:123', (user) => {
+  console.log('User updated:', user);
+});
+
+// Later: unsubscribe
+unsubscribe();
+```
+
+## PluresDB Features
+
+The official PluresDB package provides:
+
+- **P2P Graph Database**: Distributed, peer-to-peer data storage
+- **SQLite Compatibility**: 95% SQLite API compatibility
+- **CRDT Conflict Resolution**: Automatic conflict resolution
+- **Vector Search**: Built-in vector embeddings and similarity search
+- **Local-First**: Offline-first data storage with sync when online
+- **Cross-Device Sync**: Automatic synchronization across devices
+
+For more information, see the [PluresDB documentation](https://github.com/plures/pluresdb).
+
+## Migration
+
+If you're using the in-memory implementation and want to migrate to PluresDB:
+
+1. Install PluresDB (already included as dependency)
+2. Replace `createInMemoryDB()` with `createPluresDB(pluresdb)`
+3. The API remains the same - no other code changes needed!
+
+## Notes
+
+- The `PluresDBPraxisAdapter` uses polling to watch for changes (since PluresDB doesn't natively support reactive queries in the current API)
+- For production use, consider the polling interval and adjust if needed
+- The adapter automatically handles cleanup of polling intervals when watchers are removed

package/src/core/pluresdb/adapter.ts

@@ -115,3 +115,168 @@ export class InMemoryPraxisDB implements PraxisDB {
 export function createInMemoryDB(): InMemoryPraxisDB {
   return new InMemoryPraxisDB();
 }
+
+/**
+ * PluresDB instance type - represents either PluresNode or SQLiteCompatibleAPI
+ */
+export type PluresDBInstance = {
+  get(key: string): Promise<any>;
+  put(key: string, value: any): Promise<void>;
+};
+
+/**
+ * Configuration options for PluresDBPraxisAdapter
+ */
+export interface PluresDBAdapterConfig {
+  /** PluresDB instance */
+  db: PluresDBInstance;
+  /** Polling interval in milliseconds for watch functionality (default: 1000ms) */
+  pollInterval?: number;
+}
+
+/**
+ * PluresDB-backed implementation of PraxisDB
+ *
+ * Wraps the official PluresDB package from NPM to provide
+ * the PraxisDB interface for production use.
+ */
+export class PluresDBPraxisAdapter implements PraxisDB {
+  private db: PluresDBInstance;
+  private watchers = new Map<string, Set<(val: unknown) => void>>();
+  private pollIntervals = new Map<string, ReturnType<typeof setInterval>>();
+  private lastValues = new Map<string, unknown>();
+  private pollInterval: number;
+
+  constructor(config: PluresDBAdapterConfig | PluresDBInstance) {
+    // Support both old API (direct db instance) and new config API
+    if ('get' in config && 'put' in config) {
+      this.db = config;
+      this.pollInterval = 1000;
+    } else {
+      this.db = config.db;
+      this.pollInterval = config.pollInterval ?? 1000;
+    }
+  }
+
+  async get<T>(key: string): Promise<T | undefined> {
+    try {
+      const value = await this.db.get(key);
+      return value as T | undefined;
+    } catch (error) {
+      // PluresDB returns undefined/null for missing keys
+      return undefined;
+    }
+  }
+
+  async set<T>(key: string, value: T): Promise<void> {
+    await this.db.put(key, value);
+
+    // Update last known value
+    this.lastValues.set(key, value);
+
+    // Notify watchers
+    const keyWatchers = this.watchers.get(key);
+    if (keyWatchers) {
+      for (const callback of keyWatchers) {
+        callback(value);
+      }
+    }
+  }
+
+  watch<T>(key: string, callback: (val: T) => void): UnsubscribeFn {
+    if (!this.watchers.has(key)) {
+      this.watchers.set(key, new Set());
+    }
+
+    const watchers = this.watchers.get(key)!;
+    const wrappedCallback = (val: unknown) => callback(val as T);
+    watchers.add(wrappedCallback);
+
+    // Set up polling for this key if not already set up
+    if (!this.pollIntervals.has(key)) {
+      const interval = setInterval(async () => {
+        try {
+          const value = await this.db.get(key);
+          const lastValue = this.lastValues.get(key);
+          
+          // Only notify if value has actually changed
+          if (JSON.stringify(value) !== JSON.stringify(lastValue)) {
+            this.lastValues.set(key, value);
+            const currentWatchers = this.watchers.get(key);
+            if (currentWatchers) {
+              for (const cb of currentWatchers) {
+                cb(value);
+              }
+            }
+          }
+        } catch (error) {
+          // Ignore errors in polling
+        }
+      }, this.pollInterval);
+
+      this.pollIntervals.set(key, interval);
+    }
+
+    // Return unsubscribe function
+    return () => {
+      watchers.delete(wrappedCallback);
+      if (watchers.size === 0) {
+        this.watchers.delete(key);
+        // Clean up polling interval
+        const interval = this.pollIntervals.get(key);
+        if (interval) {
+          clearInterval(interval);
+          this.pollIntervals.delete(key);
+        }
+        // Clean up last value cache
+        this.lastValues.delete(key);
+      }
+    };
+  }
+
+  /**
+   * Clean up all resources
+   */
+  dispose(): void {
+    // Clear all polling intervals
+    for (const interval of this.pollIntervals.values()) {
+      clearInterval(interval);
+    }
+    this.pollIntervals.clear();
+    this.watchers.clear();
+    this.lastValues.clear();
+  }
+}
+
+/**
+ * Create a PluresDB-backed PraxisDB instance
+ *
+ * Wraps the official PluresDB package from NPM.
+ *
+ * @param config PluresDB instance or configuration object
+ * @returns PluresDBPraxisAdapter instance
+ *
+ * @example
+ * ```typescript
+ * import { PluresNode } from 'pluresdb';
+ * import { createPluresDB } from '@plures/praxis';
+ *
+ * const pluresdb = new PluresNode({ autoStart: true });
+ * const db = createPluresDB(pluresdb);
+ *
+ * await db.set('user:1', { name: 'Alice' });
+ * const user = await db.get('user:1');
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom polling interval
+ * const db = createPluresDB({
+ *   db: pluresdb,
+ *   pollInterval: 500, // Poll every 500ms
+ * });
+ * ```
+ */
+export function createPluresDB(config: PluresDBAdapterConfig | PluresDBInstance): PluresDBPraxisAdapter {
+  return new PluresDBPraxisAdapter(config);
+}

package/src/core/pluresdb/index.ts

@@ -5,9 +5,9 @@
  * It provides the core adapter layer, store, and schema registry.
  */
 
-// Adapter - Core interface and in-memory implementation
-export type { PraxisDB, UnsubscribeFn } from './adapter.js';
-export { InMemoryPraxisDB, createInMemoryDB } from './adapter.js';
+// Adapter - Core interface and implementations (in-memory + PluresDB)
+export type { PraxisDB, UnsubscribeFn, PluresDBInstance, PluresDBAdapterConfig } from './adapter.js';
+export { InMemoryPraxisDB, createInMemoryDB, PluresDBPraxisAdapter, createPluresDB } from './adapter.js';
 
 // Store - Manages facts, events, and reactive updates
 export type { EventStreamEntry, PraxisDBStoreOptions, RuleErrorHandler } from './store.js';

package/src/core/reactive-engine.svelte.ts

@@ -1,39 +1,65 @@
 /**
- * Praxis Reactive Logic Engine
+ * Praxis Reactive Logic Engine - Svelte 5 Implementation
  * 
- * A Svelte 5 native implementation of the Praxis Logic Engine.
- * Uses Runes ($state, $derived, $effect) for fine-grained reactivity.
+ * This version uses Svelte 5 runes ($state) for built-in reactivity.
+ * The state object is automatically reactive when used in Svelte components.
  */
 
+import { PraxisRegistry } from '../core/rules.js';
+import type { PraxisEvent } from '../core/protocol.js';
+import { LogicEngine, createPraxisEngine } from '../core/engine.js';
+
+// Type declaration for Svelte 5 $state rune
+// This is needed for TypeScript compilation; the actual implementation
+// is provided by the Svelte compiler when processing .svelte.ts files
+declare function $state<T>(initial: T): T;
+
 export interface ReactiveEngineOptions<TContext> {
     initialContext: TContext;
     initialFacts?: any[];
     initialMeta?: Record<string, unknown>;
+    registry?: PraxisRegistry<TContext>;
 }
 
+/**
+ * Reactive Logic Engine using Svelte 5 runes.
+ * Combines the standard LogicEngine with reactive state management.
+ */
 export class ReactiveLogicEngine<TContext extends object> {
-    // The single source of truth, reactive by default
-    // We use $state.raw for things that shouldn't be deeply reactive if needed,
-    // but for context we usually want deep reactivity.
-    state: { context: TContext; facts: any[]; meta: Record<string, unknown> } = $state<{
-        context: TContext;
-        facts: any[];
-        meta: Record<string, unknown>;
-    }>({
+    // Use Svelte's $state rune for automatic reactivity
+    state: { context: TContext; facts: any[]; meta: Record<string, unknown> } = $state({
         context: {} as TContext,
-        facts: [],
-        meta: {}
+        facts: [] as any[],
+        meta: {} as Record<string, unknown>
     });
 
+    // Internal engine for logic processing
+    private _engine: LogicEngine<TContext>;
+
     constructor(options: ReactiveEngineOptions<TContext>) {
+        // Initialize reactive state
         this.state.context = options.initialContext;
         this.state.facts = options.initialFacts ?? [];
         this.state.meta = options.initialMeta ?? {};
+
+        // Create internal engine if registry is provided
+        if (options.registry) {
+            this._engine = createPraxisEngine({
+                initialContext: options.initialContext,
+                registry: options.registry,
+            });
+        } else {
+            // Create a basic engine without registry
+            this._engine = createPraxisEngine({
+                initialContext: options.initialContext,
+                registry: new PraxisRegistry<TContext>(),
+            });
+        }
     }
 
     /**
-     * Access the reactive context directly.
-     * Consumers can use this in $derived() or $effect().
+     * Access the reactive context.
+     * In Svelte 5 components, changes to this object will automatically trigger updates.
      */
     get context(): TContext {
         return this.state.context;
@@ -46,9 +72,16 @@ export class ReactiveLogicEngine<TContext extends object> {
         return this.state.facts;
     }
 
+    /**
+     * Access the reactive metadata.
+     */
+    get meta(): Record<string, unknown> {
+        return this.state.meta;
+    }
+
     /**
      * Apply a mutation to the state.
-     * This is the "Action" or "Rule" equivalent.
+     * Changes will automatically trigger Svelte reactivity.
      * 
      * @param mutator A function that receives the state and modifies it.
      */
@@ -57,9 +90,50 @@ export class ReactiveLogicEngine<TContext extends object> {
     }
 
     /**
-     * Access the reactive meta.
+     * Process events through the logic engine and update reactive state.
+     * 
+     * @param events Events to process
      */
-    get meta(): Record<string, unknown> {
-        return this.state.meta;
+    step(events: PraxisEvent[]): void {
+        const result = this._engine.step(events);
+        
+        // Update reactive state with engine results
+        this.state.context = result.state.context as TContext;
+        this.state.facts = result.state.facts;
+        this.state.meta = result.state.meta ?? {};
     }
 }
+
+/**
+ * Create a reactive logic engine with Svelte 5 runes.
+ * 
+ * @param options Configuration options
+ * @returns A reactive logic engine instance
+ * 
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { createReactiveEngine } from '@plures/praxis/svelte';
+ * 
+ *   const engine = createReactiveEngine({
+ *     initialContext: { count: 0 },
+ *     registry
+ *   });
+ * 
+ *   // Use $derived for computed values
+ *   const count = $derived(engine.context.count);
+ *   const doubled = $derived(engine.context.count * 2);
+ * 
+ *   function increment() {
+ *     engine.step([Increment.create({ amount: 1 })]);
+ *   }
+ * </script>
+ * 
+ * <button on:click={increment}>Count: {count}, Doubled: {doubled}</button>
+ * ```
+ */
+export function createReactiveEngine<TContext extends object>(
+    options: ReactiveEngineOptions<TContext>
+): ReactiveLogicEngine<TContext> {
+    return new ReactiveLogicEngine(options);
+}