@plures/praxis 1.1.3 → 1.2.0

package/dist/node/integrations/svelte.js

@@ -1,7 +1,8 @@
 import {
   ReactiveLogicEngine,
   createReactiveEngine
-} from "../chunk-R45WXWKH.js";
+} from "../chunk-LE2ZJYFC.js";
+import "../chunk-VOMLVI6V.js";
 import "../chunk-QGM4M3NI.js";
 
 // src/integrations/svelte.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plures/praxis",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "The Full Plures Application Framework - declarative schemas, logic engine, component generation, and local-first data",
   "type": "module",
   "main": "./dist/node/index.js",

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/adapter.ts

@@ -143,7 +143,7 @@ export interface PluresDBAdapterConfig {
 export class PluresDBPraxisAdapter implements PraxisDB {
   private db: PluresDBInstance;
   private watchers = new Map<string, Set<(val: unknown) => void>>();
-  private pollIntervals = new Map<string, NodeJS.Timeout>();
+  private pollIntervals = new Map<string, ReturnType<typeof setInterval>>();
   private lastValues = new Map<string, unknown>();
   private pollInterval: number;
 

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

@@ -9,6 +9,11 @@ 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[];
@@ -22,7 +27,7 @@ export interface ReactiveEngineOptions<TContext> {
  */
 export class ReactiveLogicEngine<TContext extends object> {
     // Use Svelte's $state rune for automatic reactivity
-    state = $state({
+    state: { context: TContext; facts: any[]; meta: Record<string, unknown> } = $state({
         context: {} as TContext,
         facts: [] as any[],
         meta: {} as Record<string, unknown>

package/src/core/reactive-engine.ts

@@ -151,7 +151,7 @@ export class ReactiveLogicEngine<TContext extends object> {
     /**
      * Get the full state object
      */
-    get state() {
+    get state(): { context: TContext; facts: any[]; meta: Record<string, unknown> } {
         return {
             context: this._contextProxy,
             facts: this._factsProxy,

package/src/index.browser.ts

@@ -214,3 +214,7 @@ export {
   attachTauriToEngine,
   generateTauriConfig,
 } from './integrations/tauri.js';
+
+// Unified Integration Helpers
+export type { UnifiedAppConfig, UnifiedApp } from './integrations/unified.js';
+export { createUnifiedApp, attachAllIntegrations } from './integrations/unified.js';

package/src/index.ts

@@ -268,3 +268,7 @@ export {
   attachTauriToEngine,
   generateTauriConfig,
 } from './integrations/tauri.js';
+
+// Unified Integration Helpers
+export type { UnifiedAppConfig, UnifiedApp } from './integrations/unified.js';
+export { createUnifiedApp, attachAllIntegrations } from './integrations/unified.js';

package/src/integrations/unified.ts

@@ -0,0 +1,350 @@
+/**
+ * Unified Integration Helpers
+ *
+ * Convenience functions for setting up Praxis with all ecosystem integrations
+ * (PluresDB, Unum, State-Docs, CodeCanvas) in a single call.
+ */
+
+import type { LogicEngine } from '../core/engine.js';
+import type { PraxisRegistry, PraxisModule } from '../core/rules.js';
+import type { PraxisSchema } from '../core/schema/types.js';
+import type { PraxisDB, UnsubscribeFn } from '../core/pluresdb/adapter.js';
+import type { UnumIdentity } from './unum.js';
+import {
+  createPluresDBAdapter,
+  generateId,
+  type PluresDBAdapter,
+} from './pluresdb.js';
+import {
+  createUnumAdapter,
+  attachUnumToEngine,
+  type UnumAdapter,
+  type UnumChannel,
+} from './unum.js';
+import {
+  createStateDocsGenerator,
+  type StateDocsGenerator,
+  type GeneratedDoc,
+} from './state-docs.js';
+import {
+  schemaToCanvas,
+  type CanvasDocument,
+} from './code-canvas.js';
+
+/**
+ * Configuration for unified Praxis application
+ */
+export interface UnifiedAppConfig<TContext = unknown> {
+  /** Praxis registry with rules and constraints */
+  registry: PraxisRegistry<TContext>;
+
+  /** Initial context for the engine */
+  initialContext: TContext;
+
+  /** PluresDB instance (if not provided, creates in-memory DB) */
+  db?: PraxisDB;
+
+  /** Enable Unum for distributed communication */
+  enableUnum?: boolean;
+
+  /** Unum identity configuration (without id and createdAt which are auto-generated) */
+  unumIdentity?: Omit<UnumIdentity, 'id' | 'createdAt'>;
+
+  /** Enable State-Docs documentation generation */
+  enableDocs?: boolean;
+
+  /** State-Docs configuration */
+  docsConfig?: {
+    projectTitle: string;
+    target?: string;
+  };
+
+  /** Praxis schema for CodeCanvas integration */
+  schema?: PraxisSchema;
+}
+
+/**
+ * Unified application instance with all integrations
+ */
+export interface UnifiedApp<TContext = unknown> {
+  /** Praxis logic engine */
+  engine: LogicEngine<TContext>;
+
+  /** PluresDB adapter for persistence */
+  pluresdb: PluresDBAdapter<TContext>;
+
+  /** Unum adapter for distributed communication (if enabled) */
+  unum?: UnumAdapter;
+
+  /** Default Unum channel (if Unum enabled) */
+  channel?: UnumChannel;
+
+  /** State-Docs generator (if enabled) */
+  docs?: StateDocsGenerator;
+
+  /** CodeCanvas document (if schema provided) */
+  canvas?: CanvasDocument;
+
+  /** Generate documentation from current state */
+  generateDocs?: () => GeneratedDoc[];
+
+  /** Cleanup function to dispose all integrations */
+  dispose: () => void;
+}
+
+/**
+ * Create a unified Praxis application with all integrations
+ *
+ * This is a convenience function that sets up:
+ * - Praxis logic engine
+ * - PluresDB for persistence (auto-attaches to engine)
+ * - Unum for distributed communication (optional)
+ * - State-Docs for documentation generation (optional)
+ * - CodeCanvas for visual schema editing (optional)
+ *
+ * @example
+ * ```typescript
+ * import { createUnifiedApp } from '@plures/praxis';
+ *
+ * const app = await createUnifiedApp({
+ *   registry: myRegistry,
+ *   initialContext: { count: 0 },
+ *   enableUnum: true,
+ *   unumIdentity: { name: 'node-1' },
+ *   enableDocs: true,
+ *   docsConfig: { projectTitle: 'My App' },
+ *   schema: mySchema,
+ * });
+ *
+ * // Use the engine
+ * app.engine.step([myEvent]);
+ *
+ * // Broadcast to other nodes
+ * if (app.channel) {
+ *   await app.unum?.broadcastEvent(app.channel.id, myEvent);
+ * }
+ *
+ * // Generate documentation
+ * const docs = app.generateDocs?.();
+ *
+ * // Cleanup
+ * app.dispose();
+ * ```
+ */
+export async function createUnifiedApp<TContext = unknown>(
+  config: UnifiedAppConfig<TContext>
+): Promise<UnifiedApp<TContext>> {
+  const { createPraxisEngine } = await import('../core/engine.js');
+  const { createInMemoryDB } = await import('../core/pluresdb/adapter.js');
+
+  // Create database if not provided
+  const db = config.db || createInMemoryDB();
+
+  // Create PluresDB adapter
+  const pluresdb = createPluresDBAdapter({
+    db,
+    registry: config.registry,
+    initialContext: config.initialContext,
+  });
+
+  // Create Praxis engine
+  const engine = createPraxisEngine({
+    initialContext: config.initialContext,
+    registry: config.registry,
+  });
+
+  // Attach PluresDB to engine
+  pluresdb.attachEngine(engine);
+
+  const disposers: UnsubscribeFn[] = [];
+
+  // Setup Unum if enabled
+  let unum: UnumAdapter | undefined;
+  let channel: UnumChannel | undefined;
+  if (config.enableUnum) {
+    // Convert partial identity to full identity if provided
+    const fullIdentity: UnumIdentity | undefined = config.unumIdentity
+      ? {
+          ...config.unumIdentity,
+          id: generateId(),
+          createdAt: Date.now(),
+        }
+      : undefined;
+
+    unum = await createUnumAdapter({
+      db,
+      identity: fullIdentity,
+      realtime: true,
+    });
+
+    // Create default channel
+    channel = await unum.createChannel(
+      config.unumIdentity?.name || 'praxis-app',
+      []
+    );
+
+    // Attach Unum to engine
+    const unumDisposer = attachUnumToEngine(engine, unum, channel.id);
+    disposers.push(unumDisposer);
+  }
+
+  // Setup State-Docs if enabled
+  let docs: StateDocsGenerator | undefined;
+  let generateDocs: (() => GeneratedDoc[]) | undefined;
+  if (config.enableDocs && config.docsConfig) {
+    docs = createStateDocsGenerator({
+      projectTitle: config.docsConfig.projectTitle,
+      target: config.docsConfig.target || './docs',
+    });
+
+    generateDocs = () => {
+      // Get rules and constraints from registry
+      const module: PraxisModule<TContext> = {
+        rules: config.registry.getAllRules(),
+        constraints: config.registry.getAllConstraints(),
+      };
+      return docs!.generateFromModule(module);
+    };
+  }
+
+  // Setup CodeCanvas if schema provided
+  let canvas: CanvasDocument | undefined;
+  if (config.schema) {
+    // Convert PraxisSchema to PSFSchema format expected by schemaToCanvas
+    // Both types are structurally compatible, so we can safely cast
+    canvas = schemaToCanvas(config.schema as unknown as import('../../core/schema-engine/psf.js').PSFSchema, { layout: 'hierarchical' });
+  }
+
+  return {
+    engine,
+    pluresdb,
+    unum,
+    channel,
+    docs,
+    canvas,
+    generateDocs,
+    dispose: () => {
+      pluresdb.dispose();
+      if (unum) {
+        // Disconnect from Unum, log errors during cleanup
+        unum.disconnect().catch((err) => {
+          console.warn('Warning: Error during Unum disconnect:', err);
+        });
+      }
+      for (const disposer of disposers) {
+        disposer();
+      }
+    },
+  };
+}
+
+/**
+ * Attach all available integrations to an existing Praxis engine
+ *
+ * This is useful when you already have an engine and want to add integrations.
+ *
+ * @example
+ * ```typescript
+ * import { createPraxisEngine, attachAllIntegrations } from '@plures/praxis';
+ *
+ * const engine = createPraxisEngine({ initialContext: {}, registry });
+ *
+ * const integrations = await attachAllIntegrations(engine, registry, {
+ *   enableUnum: true,
+ *   enableDocs: true,
+ * });
+ *
+ * // Later cleanup
+ * integrations.dispose();
+ * ```
+ */
+export async function attachAllIntegrations<TContext = unknown>(
+  engine: LogicEngine<TContext>,
+  registry: PraxisRegistry<TContext>,
+  options: {
+    db?: PraxisDB;
+    enableUnum?: boolean;
+    unumIdentity?: Omit<UnumIdentity, 'id' | 'createdAt'>;
+    enableDocs?: boolean;
+    docsConfig?: { projectTitle: string; target?: string };
+  } = {}
+): Promise<{
+  pluresdb: PluresDBAdapter<TContext>;
+  unum?: UnumAdapter;
+  channel?: UnumChannel;
+  docs?: StateDocsGenerator;
+  dispose: () => void;
+}> {
+  const { createInMemoryDB } = await import('../core/pluresdb/adapter.js');
+
+  // Create database if not provided
+  const db = options.db || createInMemoryDB();
+
+  // Create PluresDB adapter
+  const pluresdb = createPluresDBAdapter({
+    db,
+    registry,
+    initialContext: engine.getContext(),
+  });
+
+  // Attach PluresDB to engine
+  pluresdb.attachEngine(engine);
+
+  const disposers: UnsubscribeFn[] = [];
+
+  // Setup Unum if enabled
+  let unum: UnumAdapter | undefined;
+  let channel: UnumChannel | undefined;
+  if (options.enableUnum) {
+    // Convert partial identity to full identity if provided
+    const fullIdentity: UnumIdentity | undefined = options.unumIdentity
+      ? {
+          ...options.unumIdentity,
+          id: generateId(),
+          createdAt: Date.now(),
+        }
+      : undefined;
+
+    unum = await createUnumAdapter({
+      db,
+      identity: fullIdentity,
+      realtime: true,
+    });
+
+    channel = await unum.createChannel(
+      options.unumIdentity?.name || 'praxis-app',
+      []
+    );
+
+    const unumDisposer = attachUnumToEngine(engine, unum, channel.id);
+    disposers.push(unumDisposer);
+  }
+
+  // Setup State-Docs if enabled
+  let docs: StateDocsGenerator | undefined;
+  if (options.enableDocs && options.docsConfig) {
+    docs = createStateDocsGenerator({
+      projectTitle: options.docsConfig.projectTitle,
+      target: options.docsConfig.target || './docs',
+    });
+  }
+
+  return {
+    pluresdb,
+    unum,
+    channel,
+    docs,
+    dispose: () => {
+      pluresdb.dispose();
+      if (unum) {
+        // Disconnect from Unum, log errors during cleanup
+        unum.disconnect().catch((err) => {
+          console.warn('Warning: Error during Unum disconnect:', err);
+        });
+      }
+      for (const disposer of disposers) {
+        disposer();
+      }
+    },
+  };
+}