@plures/praxis 2.0.0 → 2.0.3

package/docs/archive/1.x/GOLDEN_PATH_IMPLEMENTATION.md

@@ -0,0 +1,280 @@
+# Praxis v0.2 — Golden Path Implementation
+
+## Overview
+
+This document summarizes the implementation of the Praxis v0.2 "Golden Path" — a complete pipeline from schema definition to runnable application.
+
+## What Was Implemented
+
+### 1. Schema System (✅ Complete)
+
+**Files:**
+
+- `src/core/schema/types.ts` (existing, already complete)
+- `src/core/schema/loader.ts` (new)
+- `src/core/schema/normalize.ts` (new)
+
+**Features:**
+
+- Schema validation with clear error messages
+- Schema loading from JavaScript files
+- Schema normalization with model resolution
+- Reference expansion and dependency tracking
+
+### 2. Code Generators (✅ Complete)
+
+**Logic Generator** (`src/core/logic/generator.ts`)
+
+- Generates `facts.ts` with typed fact definitions
+- Generates `events.ts` with typed event definitions
+- Generates `rules.ts` with rule scaffolds and TODOs
+- Generates `engine.ts` with context types and engine setup
+- Generates `index.ts` for convenient imports
+
+**Component Generator** (`src/core/component/generator.ts`)
+
+- Already existed, integrated into pipeline
+- Generates Svelte components from schema
+- Includes TypeScript types and documentation
+- Supports form, list, display, and custom components
+
+**PluresDB Generator** (`src/core/pluresdb/generator.ts`)
+
+- Generates database configuration
+- Creates stores for each model
+- Defines indexes based on schema
+- Supports sync configuration
+
+### 3. CLI Command (✅ Complete)
+
+**File:** `src/cli/commands/generate.ts`
+
+**Usage:**
+
+```bash
+# Generate all code from schema
+praxis generate --schema praxis.schema.js
+
+# Generate specific target
+praxis generate --schema praxis.schema.js --target logic
+praxis generate --schema praxis.schema.js --target components
+praxis generate --schema praxis.schema.js --target pluresdb
+
+# Custom output directory
+praxis generate --schema praxis.schema.js --output ./src/generated
+```
+
+**Features:**
+
+- Loads and validates schema
+- Normalizes schema for generation
+- Generates all artifacts or specific targets
+- Clear progress output with ✓ checkmarks
+- Helpful error messages
+
+### 4. Tests (✅ Complete)
+
+**Schema Tests** (`src/__tests__/schema.test.ts`)
+
+- 8 tests covering validation and normalization
+- Tests schema templates
+- Tests model dependency resolution
+- Tests component-model resolution
+
+**Generator Tests** (`src/__tests__/generators.test.ts`)
+
+- 12 tests covering all generators
+- Tests logic file generation
+- Tests component generation
+- Tests PluresDB config generation
+- Tests options and configuration
+
+**Test Results:**
+
+- 83 total tests passing
+- 8 test files
+- No failing tests
+- No security vulnerabilities (CodeQL clean)
+
+### 5. Example Application (✅ Complete)
+
+**Location:** `examples/simple-app/`
+
+**Contents:**
+
+- `praxis.schema.js` - Complete TodoApp schema
+- `README.md` - Comprehensive guide
+- Generated code demonstrating full pipeline
+
+**Schema Includes:**
+
+- Models: Todo with typed fields
+- Components: TodoForm, TodoList, TodoItem
+- Logic: Events, facts, rules, and constraints
+- Full CRUD operations
+
+## Generated Code Structure
+
+When you run `praxis generate`, you get:
+
+```
+generated/
+├── logic/
+│   ├── facts.ts        # Typed fact definitions
+│   ├── events.ts       # Typed event definitions
+│   ├── rules.ts        # Rule implementations (with TODOs)
+│   ├── engine.ts       # Engine setup with context types
+│   └── index.ts        # Convenient exports
+├── components/
+│   ├── [Component].svelte      # Svelte component
+│   ├── [Component].types.ts    # TypeScript types
+│   └── [Component].md          # Documentation
+└── pluresdb-config.ts          # Database configuration
+```
+
+## Example Workflow
+
+### 1. Define Schema
+
+```javascript
+// praxis.schema.js
+export const schema = {
+  version: '1.0.0',
+  name: 'MyApp',
+  models: [
+    {
+      name: 'User',
+      fields: [
+        { name: 'id', type: 'string' },
+        { name: 'name', type: 'string' },
+      ],
+    },
+  ],
+  components: [
+    {
+      name: 'UserForm',
+      type: 'form',
+      model: 'User',
+    },
+  ],
+  logic: [
+    {
+      id: 'user-logic',
+      events: [{ tag: 'CREATE_USER', payload: { name: 'string' } }],
+      facts: [{ tag: 'UserCreated', payload: { userId: 'string' } }],
+    },
+  ],
+};
+```
+
+### 2. Generate Code
+
+```bash
+praxis generate --schema praxis.schema.js
+```
+
+Output:
+
+```
+✓ Schema loaded successfully
+✓ Schema normalized
+✓ Logic module generated
+✓ Components generated
+✓ PluresDB config generated
+✅ Generation complete! 12 files generated.
+```
+
+### 3. Use Generated Code
+
+```typescript
+import { createEngine } from './generated/logic/engine.js';
+import { CREATE_USER } from './generated/logic/events.js';
+
+const engine = createEngine();
+const result = engine.step([CREATE_USER.create({ name: 'Alice' })]);
+```
+
+## Technical Decisions
+
+### TypeScript Compilation
+
+- Schema files must be JavaScript (.js) or pre-compiled TypeScript
+- This avoids runtime TypeScript compilation complexity
+- Users can compile their schemas with `tsc` if needed
+
+### Code Generation Strategy
+
+- Generate complete but minimal code
+- Include helpful TODOs where manual work is needed
+- Preserve existing patterns (e.g., defineFact, defineEvent)
+- Type-safe by default
+
+### File Organization
+
+- Separate files for facts, events, rules
+- Single engine.ts for setup and types
+- Components get separate files per component
+- PluresDB config in single file
+
+## Validation & Safety
+
+### Schema Validation
+
+- Required fields checked (version, name, models)
+- Model fields validated
+- Clear error messages with paths
+
+### Generation Validation
+
+- Checks for at least one model
+- Validates model fields
+- Type-safe TypeScript output
+
+### Security
+
+- CodeQL scan: 0 vulnerabilities
+- No eval or dynamic code execution
+- Pure file generation from AST
+
+## Next Steps (Future Work)
+
+1. **Watch Mode**: Implement file watching for auto-regeneration
+2. **TypeScript Schemas**: Add tsx loader for .ts schema files
+3. **Incremental Generation**: Only regenerate changed files
+4. **Templates**: Custom code templates
+5. **Migrations**: Schema version migrations
+6. **Visual Editor**: CodeCanvas integration
+
+## Breaking Changes
+
+None - this is a new feature set.
+
+## Migration Guide
+
+No migration needed. This is v0.2 adding new functionality.
+
+## Documentation
+
+- Schema types: `src/core/schema/types.ts`
+- Usage examples: `examples/simple-app/README.md`
+- Test examples: `src/__tests__/schema.test.ts`
+
+## Metrics
+
+- **Files Added**: 8 new source files
+- **Lines of Code**: ~2,500 lines
+- **Tests Added**: 20 new tests
+- **Test Coverage**: All new code tested
+- **Build Time**: <5 seconds
+- **Generation Time**: <1 second
+
+## Conclusion
+
+The Praxis v0.2 Golden Path is complete and functional. Developers can now:
+
+1. Define a schema in JavaScript
+2. Run `praxis generate`
+3. Get complete logic modules, components, and database config
+4. Build and run their application
+
+This establishes Praxis as a true full-stack framework with a schema-driven development workflow.

package/docs/archive/1.x/IMPLEMENTATION.md

@@ -0,0 +1,166 @@
+# Praxis Implementation Summary
+
+This document summarizes the initial implementation of the Praxis TypeScript library.
+
+## What Was Implemented
+
+### Core Architecture
+
+1. **Language-Neutral Protocol** (`src/core/protocol.ts`)
+   - `PraxisFact` - Typed propositions about the domain
+   - `PraxisEvent` - Temporally ordered facts for state changes
+   - `PraxisState` - Current state with context and facts
+   - `PraxisStepFn` - Pure, deterministic step function
+   - JSON-friendly types for cross-language compatibility
+
+2. **Rules and Constraints System** (`src/core/rules.ts`)
+   - `RuleFn` - Pure functions that derive new facts
+   - `ConstraintFn` - Predicates that check invariants
+   - `PraxisRegistry` - Registry for rules and constraints with stable IDs
+   - `PraxisModule` - Bundles of rules and constraints
+
+3. **Logic Engine** (`src/core/engine.ts`)
+   - `LogicEngine<TContext>` - Main engine with strongly-typed context
+   - `createPraxisEngine` - Factory function
+   - Pure, immutable state updates
+   - Automatic rule application and constraint checking
+
+4. **Actor System** (`src/core/actors.ts`)
+   - `Actor<TContext>` - Interface for effectful units
+   - `ActorManager` - Lifecycle management for actors
+   - `createTimerActor` - Helper for timer-based actors
+   - Bridge between pure logic and side effects
+
+### DSL and Helpers
+
+5. **DSL Helpers** (`src/dsl/index.ts`)
+   - `defineFact<TTag, TPayload>` - Define typed facts with type guards
+   - `defineEvent<TTag, TPayload>` - Define typed events with type guards
+   - `defineRule` - Define rules with descriptors
+   - `defineConstraint` - Define constraints with descriptors
+   - `defineModule` - Bundle rules and constraints
+   - Helper functions: `findEvent`, `findFact`, `filterEvents`, `filterFacts`
+
+### Integrations
+
+6. **Svelte v5 Integration** (`src/integrations/svelte.ts`)
+   - `createPraxisStore` - Convert engine to Svelte store
+   - `createContextStore` - Extract context as store
+   - `createDerivedStore` - Derive specific values from context
+   - Reactive bindings for Svelte v5
+
+7. **PluresDB Integration** (`src/integrations/pluresdb.ts`)
+   - Placeholder implementation
+   - Interface definitions for future event sourcing
+   - Designed for reactive queries and subscriptions
+
+### Examples
+
+8. **Auth Basic Example** (`src/examples/auth-basic/`)
+   - Login/logout logic with facts and events
+   - Session management
+   - Constraint checking for single sessions
+   - Demonstrates basic Praxis usage
+
+9. **Cart Example** (`src/examples/cart/`)
+   - Shopping cart with multiple items
+   - Discount application
+   - Complex state derivation
+   - Multiple rules and constraints
+   - Module composition
+
+10. **Svelte Counter Example** (`src/examples/svelte-counter/`)
+    - Simple counter with increment/decrement
+    - Svelte v5 store integration
+    - Reactive state updates
+    - History tracking
+
+### Testing
+
+11. **Test Suite** (`src/__tests__/`)
+    - Protocol type tests
+    - DSL helper tests
+    - Engine integration tests
+    - 18 tests, all passing
+    - Coverage of core functionality
+
+### Documentation
+
+12. **README.md**
+    - Comprehensive introduction
+    - Core concepts explanation
+    - Quick start guide
+    - API reference
+    - Future directions
+    - Examples and usage patterns
+
+13. **Package Configuration**
+    - `package.json` - NPM package metadata
+    - `tsconfig.json` - TypeScript configuration
+    - `vitest.config.ts` - Test configuration
+    - `.gitignore` - Git ignore rules
+    - `.npmignore` - NPM publish exclusions
+    - `LICENSE` - MIT License
+
+## Design Principles Implemented
+
+✓ **Strong typing and functional programming**
+
+- All core types are strongly typed
+- Rules and constraints are pure functions
+- Immutable state updates
+
+✓ **Logic-first architecture**
+
+- User-facing API expressed in terms of facts, events, rules, constraints
+- FSMs are an internal implementation detail
+
+✓ **Language-agnostic core protocol**
+
+- JSON-friendly types
+- Pure, deterministic step function
+- Designed for future C#, PowerShell support
+
+✓ **Provable, analyzable, testable**
+
+- Pure functions easy to test
+- Comprehensive test coverage
+- Type-safe at compile time
+
+✓ **Ecosystem integration ready**
+
+- Svelte v5 integration implemented
+- PluresDB integration placeholder
+- Extensible actor system
+
+## Build and Test Status
+
+- ✅ TypeScript compilation succeeds
+- ✅ All 18 tests pass
+- ✅ Type checking passes (strict mode)
+- ✅ Examples run successfully
+- ✅ Ready for npm publish
+
+## Next Steps
+
+1. Enhance examples to demonstrate more complex flows
+2. Implement PluresDB integration
+3. Add visualization tools (state graphs, rule graphs)
+4. Create ADP static analysis integration
+5. Develop C# and PowerShell bindings
+6. Add property-based testing
+7. Create documentation site
+8. Build code-canvas integration
+
+## File Statistics
+
+- Total source files: 11
+- Total test files: 3
+- Lines of TypeScript: ~1,500+
+- Examples: 3
+- Integrations: 2
+- Core modules: 4
+
+## API Stability
+
+The core protocol (`PraxisFact`, `PraxisEvent`, `PraxisState`, `PraxisStepFn`) is designed to be stable and is the foundation for cross-language support. Higher-level TypeScript APIs may evolve but will maintain backward compatibility where possible.