@plures/praxis 0.2.0 → 1.0.0

package/README.md

@@ -4,6 +4,7 @@
 [![CodeQL](https://github.com/plures/praxis/workflows/CodeQL/badge.svg)](https://github.com/plures/praxis/actions/workflows/codeql.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm version](https://img.shields.io/npm/v/@plures/praxis.svg)](https://www.npmjs.com/package/@plures/praxis)
+[![NuGet](https://img.shields.io/nuget/v/Plures.Praxis.svg)](https://www.nuget.org/packages/Plures.Praxis/)
 [![JSR](https://jsr.io/badges/@plures/praxis)](https://jsr.io/@plures/praxis)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
 [![Deno Compatible](https://img.shields.io/badge/deno-compatible-brightgreen)](https://deno.land/)
@@ -19,29 +20,38 @@
 - 💬 [Discussions](https://github.com/plures/praxis/discussions) | [Issues](https://github.com/plures/praxis/issues)
 - 🚀 [Contributing](./CONTRIBUTING.md) | [Security Policy](./SECURITY.md)
 - 📋 [Changelog](./CHANGELOG.md) | [Roadmap](https://github.com/plures/praxis/issues?q=is%3Aissue+is%3Aopen+label%3Aroadmap)
+- 🔄 [Cross-Language Sync](./CROSS_LANGUAGE_SYNC.md) | [C# Documentation](./csharp/Praxis/README.md)
 
 ### Project Status
 
 | Category | Status |
 |----------|--------|
 | **CI/CD** | ✅ Automated testing & builds |
-| **Version** | 0.1.0 (Alpha) |
-| **Runtime Support** | Node.js 18+, Deno (experimental) |
-| **Package Registries** | npm ✅ / JSR 🚧 (coming soon) |
-| **Test Coverage** | 165 tests passing |
+| **Version** | 0.2.1 (Alpha) |
+| **Runtime Support** | Node.js 18+, Deno (experimental), .NET 8+ |
+| **Package Registries** | npm ✅ / NuGet ✅ / JSR 🚧 (coming soon) |
+| **Test Coverage** | 202 TypeScript + 68 C# tests passing |
 | **Documentation** | 📚 Comprehensive guides available |
 
+### Language Support
+
+| Language | Package | Registry | Status |
+|----------|---------|----------|--------|
+| **TypeScript** | @plures/praxis | npm | ✅ Available |
+| **C#** | Plures.Praxis | NuGet | ✅ Available |
+| **PowerShell** | Praxis.psm1 | GitHub | ✅ Available |
+
 ### Integration Status
 
 | Integration | Status | Notes |
 |------------|--------|-------|
 | **Praxis Cloud** | ✅ Available | Azure-hosted relay for sync & monetization |
-| **PluresDB** | 🚧 In Development | Local-first reactive datastore |
-| **Unum** | 🚧 Planned | Identity & channels |
+| **PluresDB** | ✅ Available | Local-first reactive datastore with 32 tests |
+| **Unum** | ✅ Available | Identity & channels integration |
 | **Svelte 5** | ✅ Full Support | Runes API, stores, history, time-travel |
-| **Tauri** | 🚧 Planned | Cross-platform runtime |
-| **CodeCanvas** | 🚧 Planned | Visual schema editor |
-| **State-Docs** | 🚧 Planned | Documentation generation |
+| **Tauri** | ✅ Available | Cross-platform desktop runtime |
+| **CodeCanvas** | ✅ Available | Visual schema editor & FSM enforcement |
+| **State-Docs** | ✅ Available | Documentation generation from schemas |
 
 ---
 
@@ -49,29 +59,84 @@
 
 Praxis is not just a logic engine—it's a **complete framework** for building modern, local-first, distributed applications. It provides:
 
-- **Declarative Schemas**: Define your data models, logic, and components in a unified schema format
+- **Declarative Schemas**: Define your data models, logic, and components in a unified schema format (PSF)
 - **Logic/State Machines**: Pure, functional application logic with facts, events, rules, and constraints
 - **Component Generation**: Automatically generate Svelte components from schemas
 - **Local-First Data**: Integrated PluresDB for reactive, offline-capable data storage
-- **Documentation Generation**: Automatic State-Docs generation from your schemas
+- **Documentation Generation**: Automatic documentation generation from schemas with Mermaid diagrams
 - **Visual Design**: CodeCanvas integration for visual schema and logic editing
+- **Real-Time Code ↔ Canvas Sync**: Bidirectional synchronization between code and visual editor
 - **Orchestration**: DSC/MCP support for distributed system coordination
 - **Cross-Platform Runtime**: Web, desktop, and mobile via Svelte + Tauri
 
+## 🚀 Praxis 1.0 Architecture
+
+Praxis 1.0 introduces a **schema-driven, modular architecture** where the Praxis Schema Format (PSF) serves as the single source of truth.
+
+### Praxis Schema Format (PSF)
+
+PSF is the canonical JSON/AST format that defines your entire application:
+
+```json
+{
+  "$version": "1.0.0",
+  "id": "my-app",
+  "name": "My Application",
+  "facts": [...],
+  "events": [...],
+  "rules": [...],
+  "constraints": [...],
+  "models": [...],
+  "components": [...],
+  "flows": [...]
+}
+```
+
+From this schema, Praxis generates:
+- **TypeScript types** for facts, events, rules
+- **Svelte components** for UI
+- **Markdown documentation** with Mermaid diagrams
+- **Database schemas** for PluresDB
+- **Canvas visualization** for visual editing
+
+### Modular Folder Structure
+
+```
+/praxis
+├── core/                     # Core framework modules
+│   ├── schema-engine/        # PSF types, compiler, generator, validator
+│   ├── logic-engine/         # Rules, constraints, engine, PSF adapter
+│   ├── db-adapter/           # PluresDB sync engine
+│   └── codegen/              # Documentation and code generators
+├── ui/                       # UI modules
+│   ├── svelte-generator/     # PSF-aware Svelte component generation
+│   └── canvas/               # Visual canvas state and projection
+├── tools/                    # Developer tools
+│   ├── cli/                  # Command-line interface
+│   └── watcher/              # File watching and live sync
+├── extensions/               # Optional integrations
+│   ├── dsc/                  # DSC/MCP orchestration
+│   ├── azure/                # Azure integration
+│   └── devtools/             # Developer tools
+└── examples/                 # Example applications
+    ├── hero-shop/            # Full e-commerce example
+    └── todo/                 # Minimal todo example
+```
+
 ### Framework Philosophy
 
 ### Core Framework Components
 
 Praxis provides these integrated capabilities:
 
-- **Schema System** – Declarative definitions that generate models, components, and documentation
+- **Schema Engine** – PSF parser, compiler, generator, and validator
 - **Logic Engine** – Typed facts, events, rules, and constraints for application logic
 - **Component Factory** – Generate Svelte components from schemas with data bindings
 - **Data Layer** – PluresDB integration for reactive, local-first data storage
 - **State Machines** – Flows and scenarios for orchestrated behaviors
 - **Actors** – Effectful units for side effects and external system integration
-- **Terminal Nodes** – Execute commands and scripts within the Praxis framework (NEW!)
-- **Documentation** – Automatic State-Docs generation from schemas and logic
+- **Terminal Nodes** – Execute commands and scripts within the Praxis framework
+- **Documentation** – Automatic documentation generation from schemas with Mermaid diagrams
 - **Visual IDE** – CodeCanvas integration for schema and logic editing
 - **Orchestration** – DSC/MCP support for distributed coordination
 - **CLI Tools** – Command-line interface for scaffolding and generation
@@ -144,20 +209,26 @@ Praxis provides these integrated capabilities:
 - 🔒 **Type-Safe**: Full TypeScript support with strict typing
 - 🔍 **Introspection**: Generate schemas, graphs, and visualizations of your logic
 - 🌐 **Cross-Language**: PowerShell adapter with protocol versioning (C# coming soon)
-- 📊 **Comprehensive Testing**: 165+ tests covering all features
+- 📊 **Comprehensive Testing**: 197+ TypeScript and 95+ C# tests covering all features
 - 🎭 **Hero Example**: Full e-commerce demo with auth, cart, features, and actors
 
-## What's New in v0.1.0
+## What's New in v0.2.0
 
 ### 🎉 Major Features
 
+#### Full Application Framework
+Praxis 0.2.0 transforms from a logic engine into a **complete application framework**:
+- **Complete Schema System**: Comprehensive type definitions for models, components, logic, and orchestration
+- **Component Generation**: Automatic Svelte component generation from schemas
+- **CLI Tools**: `praxis create`, `praxis generate`, `praxis canvas` commands
+- **Cloud Integration**: GitHub-based authentication and tier-based billing
+- **PluresDB Integration**: Local-first reactive datastore with full implementation
+
 #### Svelte 5 Integration (@plures/praxis/svelte)
-- **Runes Composables**: `usePraxisEngine`, `usePraxisContext`, `usePraxisSubscription`
-- **History State Pattern**: `HistoryStateManager`, `createHistoryEngine`
-- **Time-Travel Debugging**: Navigate through state snapshots
-- **Undo/Redo**: Built-in with configurable history size
+- **Runes Composables**: `usePraxisState`, `usePraxisHistory`, `usePraxisComputed`
+- **History State Pattern**: Time-travel debugging with undo/redo
 - **Store API**: Compatible with Svelte 4 and 5
-- **16 new tests** ensuring rock-solid reliability
+- **Full TypeScript support** with generics
 
 #### Documentation & Guides
 - **[Svelte Integration Guide](docs/guides/svelte-integration.md)**: Complete guide to Svelte 5 integration
@@ -166,15 +237,23 @@ Praxis provides these integrated capabilities:
 - **[Advanced Todo Example](src/examples/advanced-todo/)**: Full-featured demo with history
 
 ### 🧪 Hardened TypeScript Core
-- **165 comprehensive tests** (up from 63) covering:
+- **197 comprehensive tests** (up from 9 in v0.1.0) covering:
   - Svelte integration with runes and stores
+  - PluresDB integration (32 tests)
   - History state management and navigation
   - Edge cases and failure paths
   - Actor lifecycle and state change notifications
   - Constraint violations and rule errors
   - Registry operations and module composition
+  - Cloud integration and billing
+  - Terminal node functionality
 - Full test coverage ensures production-ready reliability
 
+### 🔒 C# Implementation
+- **95 comprehensive C# tests** with full parity to TypeScript features
+- Functional, immutable design with records
+- NuGet package available
+
 ### 📖 Protocol Versioning (v1.0.0)
 - **Explicit protocol version** (`protocolVersion` field in state)
 - **Stability guarantees** for cross-language compatibility
@@ -214,6 +293,20 @@ A comprehensive example demonstrating all Praxis features:
 npm install @plures/praxis
 ```
 
+### NuGet (.NET / C#)
+
+```bash
+dotnet add package Plures.Praxis
+```
+
+Or add to your `.csproj`:
+
+```xml
+<PackageReference Include="Plures.Praxis" Version="0.2.1" />
+```
+
+See [C# Documentation](./csharp/Praxis/README.md) for detailed usage.
+
 ### JSR (Deno)
 
 ```bash
@@ -227,7 +320,7 @@ For now, you can use Praxis with Deno via import maps:
 // import_map.json
 {
   "imports": {
-    "@plures/praxis": "npm:@plures/praxis@^0.1.0"
+    "@plures/praxis": "npm:@plures/praxis@^0.2.1"
   }
 }
 ```
@@ -239,14 +332,15 @@ For now, you can use Praxis with Deno via import maps:
 git clone https://github.com/plures/praxis.git
 cd praxis
 
-# Install dependencies
+# TypeScript
 npm install
-
-# Build
 npm run build
-
-# Run tests
 npm test
+
+# C#
+cd csharp
+dotnet build
+dotnet test
 ```
 
 ## Quick Start
@@ -510,25 +604,41 @@ This protocol is:
 │   │   └── introspection.ts      # Introspection and visualization
 │   ├── component/                 # Component generation
 │   │   └── generator.ts          # Svelte component generator
+│   ├── pluresdb/                  # PluresDB integration core
+│   │   ├── adapter.ts            # Database adapter interface
+│   │   ├── store.ts              # Reactive store implementation
+│   │   ├── schema-registry.ts    # Schema registry for PluresDB
+│   │   └── generator.ts          # PluresDB config generator
 │   └── runtime/                   # Runtime abstractions
+├── cloud/                         # Praxis Cloud integration
+│   ├── auth.ts                   # GitHub OAuth authentication
+│   ├── billing.ts                # Tier-based billing
+│   ├── provisioning.ts           # Tenant provisioning
+│   └── relay/                    # Azure relay service
 ├── integrations/                  # Ecosystem integrations
-│   ├── pluresdb/                 # PluresDB reactive datastore
+│   ├── pluresdb.ts               # PluresDB integration exports
+│   ├── svelte.ts                 # Svelte 5 integration
 │   ├── unum/                     # Unum identity and channels
 │   ├── adp/                      # Architectural Decision Protocol
 │   ├── state-docs/               # State-Docs documentation
 │   └── canvas/                   # CodeCanvas visual editor
+├── components/                    # Svelte components
+│   └── TerminalNode.svelte       # Terminal node component
 ├── cli/                          # Command-line interface
 │   ├── index.ts                  # CLI entry point
 │   └── commands/                 # Command implementations
 ├── templates/                     # Project templates
 │   ├── basic-app/                # Basic application template
-│   ├── fullstack-app/            # Full-stack template
-│   ├── component/                # Component template
-│   └── orchestrator/             # Distributed orchestration template
+│   └── fullstack-app/            # Full-stack template
 ├── examples/                      # Example applications
 │   ├── offline-chat/             # Offline-first chat demo
 │   ├── knowledge-canvas/         # Knowledge management with Canvas
 │   ├── distributed-node/         # Self-orchestrating node demo
+│   ├── terminal-node/            # Terminal node demo
+│   ├── terminal-canvas/          # Terminal + canvas demo
+│   ├── cloud-sync/               # Cloud sync demo
+│   ├── github-monetization/      # GitHub monetization demo
+│   ├── simple-app/               # Simple app demo
 │   ├── auth-basic/               # Login/logout example
 │   ├── cart/                     # Shopping cart example
 │   ├── svelte-counter/           # Svelte integration example
@@ -546,7 +656,7 @@ See [FRAMEWORK.md](./FRAMEWORK.md) for complete architecture documentation.
 
 ## Examples
 
-The repository includes four complete examples:
+The repository includes 12 complete examples:
 
 ### 1. Hero E-Commerce (`src/examples/hero-ecommerce`)
 **NEW!** Comprehensive example demonstrating all Praxis features in a single application:
@@ -631,6 +741,26 @@ npm run build
 node dist/examples/svelte-counter/index.js
 ```
 
+### 9. Terminal Canvas (`examples/terminal-canvas`)
+Combines terminal nodes with visual canvas features in a Svelte app.
+
+See [examples/terminal-canvas/README.md](./examples/terminal-canvas/README.md)
+
+### 10. GitHub Monetization (`examples/github-monetization`)
+Example of GitHub-based monetization integration with Praxis Cloud.
+
+See [examples/github-monetization/README.md](./examples/github-monetization/README.md)
+
+### 11. Simple App (`examples/simple-app`)
+A minimal example demonstrating basic Praxis schema usage.
+
+See [examples/simple-app/README.md](./examples/simple-app/README.md)
+
+### 12. Cloud Sync (`examples/cloud-sync`)
+Demonstrates real-time synchronization with Praxis Cloud relay service.
+
+See [examples/cloud-sync/README.md](./examples/cloud-sync/README.md)
+
 ## API Reference
 
 ### Core Types
@@ -704,34 +834,51 @@ Praxis integrates with the full Plures ecosystem:
 
 ### PluresDB Integration
 
-Local-first reactive datastore for offline-capable applications.
+Local-first reactive datastore for offline-capable applications. **Now fully implemented** with 32 tests covering all features.
 
 ```typescript
-import { createPluresDB } from '@plures/pluresdb';
-
-// Create database from schema
-const db = createPluresDB({
-  name: 'my-app',
-  version: 1,
-  stores: {
-    // Generated from Praxis schema
-    users: { keyPath: 'id', indexes: ['email'] },
-    tasks: { keyPath: 'id', indexes: ['status', 'createdAt'] },
-  },
-  sync: {
-    enabled: true,
-    endpoint: 'ws://localhost:8080/sync',
-    conflictResolution: 'last-write-wins',
-  },
+import { 
+  createInMemoryDB, 
+  createPraxisDBStore, 
+  createPluresDBAdapter,
+  attachToEngine 
+} from '@plures/praxis/pluresdb';
+
+// Create an in-memory database
+const db = createInMemoryDB();
+
+// Create a PraxisDB store for facts and events
+const store = createPraxisDBStore({ db });
+
+// Or create an adapter to attach to an engine
+const adapter = createPluresDBAdapter({ 
+  db, 
+  registry,
+  initialContext: {} 
 });
 
-// Use with Praxis logic engine
-engine.step([TaskCreated.create({ taskId, title })]);
-await db.tasks.add({ id: taskId, title, status: 'pending' });
+// Attach adapter to engine for automatic persistence
+adapter.attachEngine(engine);
+
+// Persist facts and events
+await adapter.persistFacts([{ tag: "UserLoggedIn", payload: { userId: "alice" } }]);
+await adapter.persistEvents([{ tag: "LOGIN", payload: { username: "alice" } }]);
+
+// Subscribe to changes
+adapter.subscribeToEvents((events) => {
+  console.log("New events:", events);
+});
 ```
 
-**Status**: Foundation in place (`src/integrations/pluresdb.ts`)  
-**Documentation**: [docs/guides/pluresdb.md](./docs/guides/pluresdb.md)
+**Features:**
+- **In-memory adapter**: Ready-to-use implementation for development and testing
+- **Reactive store**: Watch for changes with callbacks
+- **Schema registry**: Store and retrieve schemas in PluresDB
+- **Config generator**: Generate PluresDB configuration from Praxis schemas
+- **Engine integration**: Automatic fact/event persistence
+
+**Status**: ✅ Available (`src/core/pluresdb/`, `src/integrations/pluresdb.ts`)  
+**Tests**: 32 tests covering adapter, store, registry, and engine integration
 
 ### Unum Integration
 
@@ -887,24 +1034,69 @@ Write-Host "Count: $($result.state.context.count)"
 
 See [powershell/README.md](./powershell/README.md) for complete documentation and examples.
 
-### C# (Coming Soon)
+### C# (.NET 8+)
+
+**NEW!** Full C# implementation with functional, immutable design:
+
+```csharp
+using Praxis.Core;
+using Praxis.Dsl;
+
+// Define facts and events
+var UserLoggedIn = PraxisDsl.DefineFact<UserPayload>("UserLoggedIn");
+var Login = PraxisDsl.DefineEvent<LoginPayload>("LOGIN");
+
+record UserPayload(string UserId);
+record LoginPayload(string Username);
+
+// Define rules
+var loginRule = PraxisDsl.DefineRule<AuthContext>(
+    id: "auth.login",
+    description: "Process login event",
+    impl: (state, context, events) =>
+    {
+        var loginEvent = events.FindEvent(Login);
+        if (loginEvent != null)
+        {
+            var payload = Login.GetPayload(loginEvent);
+            return [UserLoggedIn.Create(new UserPayload(payload?.Username ?? "unknown"))];
+        }
+        return [];
+    });
 
-Cross-language adapter for C# is planned with similar JSON-based protocol.
+// Create engine
+var registry = new PraxisRegistry<AuthContext>();
+registry.RegisterRule(loginRule);
+
+var engine = PraxisEngine.Create(new PraxisEngineOptions<AuthContext>
+{
+    InitialContext = new AuthContext(null),
+    Registry = registry
+});
+
+// Dispatch events
+var result = engine.Step([Login.Create(new LoginPayload("alice"))]);
+Console.WriteLine($"Facts: {result.State.Facts.Count}"); // Facts: 1
+```
+
+See [csharp/Praxis/README.md](./csharp/Praxis/README.md) for complete documentation.
 
 ## Future Roadmap
 
-### Short Term (v0.2.0)
-- Complete CLI implementation
-- Basic project templates
-- Component generation MVP
-- Enhanced PluresDB integration
+### Short Term (v0.2.x) ✅
+- ✅ Complete CLI implementation
+- ✅ Basic project templates
+- ✅ Component generation MVP
+- ✅ C# implementation with NuGet publishing (95 tests)
+- ✅ PluresDB integration with full test coverage (32 tests)
+- ✅ Praxis Cloud with GitHub authentication and billing
 
 ### Medium Term (v0.3.0 - v0.5.0)
 - Full CodeCanvas integration
 - Unum identity support
 - State-Docs generation
 - Multi-language schemas
-- C# adapter
+- Real PluresDB sync (CRDT/offline-first)
 
 ### Long Term (v1.0.0+)
 - Mobile templates (iOS, Android)
@@ -917,26 +1109,38 @@ Cross-language adapter for C# is planned with similar JSON-based protocol.
 
 ### Ecosystem Integration
 
-- **Svelte v5**: Full reactive binding support (foundation in place)
-- **pluresdb**: Reactive datastore integration, event sourcing
-- **unum**: Identity/channels and messaging
+- **Svelte v5**: ✅ Full reactive binding support with runes and history
+- **PluresDB**: ✅ Reactive datastore integration with 32 tests
+- **Cloud**: ✅ GitHub-based auth and tier billing
+- **unum**: 🚧 Identity/channels and messaging
 - **Visualization**: VSCode extension, docs generator, canvas tools (introspection API ready)
 - **ADP**: Architectural guardrails and static checks
 
 ### Cross-Language Support
 
-The core protocol is designed to be implemented in other languages:
+The core protocol is implemented across multiple languages:
 
-**C# (future)**:
+**C# (Available):**
 ```csharp
-PraxisState Step(PraxisState state, IEnumerable<PraxisEvent> events);
+// Full functional C# implementation with immutable records
+var engine = PraxisEngine.Create(new PraxisEngineOptions<TContext> { ... });
+var result = engine.Step(events);
 ```
 
-**PowerShell (future)**:
+See [csharp/Praxis/README.md](./csharp/Praxis/README.md) for full documentation.
+
+**PowerShell (Available):**
 ```powershell
 $newState = Invoke-PraxisStep -State $state -Events $events
 ```
 
+See [powershell/README.md](./powershell/README.md) for full documentation.
+
+### Cross-Language Sync Strategy
+
+All implementations share the same protocol version and JSON format for interoperability.
+See [CROSS_LANGUAGE_SYNC.md](./CROSS_LANGUAGE_SYNC.md) for details on keeping implementations in sync.
+
 ### Advanced Features
 
 - Prolog/CLP-inspired features (facts, rules, declarative constraints, goal-style interactions)
@@ -1240,12 +1444,14 @@ if (result.effects) {
 
 ## Future Roadmap
 
-- 🌐 **Svelte v5 Integration**: First-class support for Svelte 5 runes
-- 🗄️ **pluresdb/unum Integration**: Persistent state management
-- 🔄 **C# Port**: Cross-platform compatibility
-- ⚡ **PowerShell Module**: Scripting and automation support
-- 🎭 **Advanced FSM Tools**: Internal state machine utilities
-- 📊 **Visualization**: Flow and state visualization tools
+- ✅ **Svelte v5 Integration**: First-class support for Svelte 5 runes (available)
+- ✅ **PluresDB Integration**: Reactive datastore with 32 tests (available)
+- ✅ **C# Port**: Cross-platform compatibility with 95 tests (available)
+- ✅ **PowerShell Module**: Scripting and automation support (available)
+- 🚧 **Unum Integration**: Identity and channels (in progress)
+- 🚧 **CodeCanvas**: Visual schema and logic editor (planned)
+- 🚧 **State-Docs**: Documentation generation (planned)
+- 📊 **Visualization**: Flow and state visualization tools (introspection ready)
 
 ## Development