@plures/praxis 1.4.4 → 2.0.3

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

@@ -0,0 +1,281 @@
+# RuneBook Roadmap - Task 1 COMPLETE ✅
+
+## Overview
+
+Task 1 of the RuneBook Roadmap has been successfully completed with full implementation, validation, and documentation.
+
+---
+
+## ✅ Task 1: Add TerminalNode Type to Praxis
+
+### All Requirements Met
+
+```
+✅ 1. Extend node registry and YAML schema
+✅ 2. Add TerminalNode.svelte component
+✅ 3. Support props: inputMode, history, lastOutput
+✅ 4. Create runtime adapter stub for command execution
+✅ 5. Ensure proper canvas rendering, drag/resize, and context menu integration
+```
+
+---
+
+## Component Architecture
+
+```
+praxis/
+├── src/
+│   ├── components/
+│   │   ├── TerminalNode.svelte      ← NEW: Main Svelte component
+│   │   ├── index.ts                 ← NEW: Type definitions
+│   │   └── README.md               ← NEW: Documentation
+│   ├── runtime/
+│   │   └── terminal-adapter.ts     ← EXISTING: Runtime adapter
+│   └── core/
+│       └── schema/
+│           └── types.ts            ← EXISTING: Schema types
+├── examples/
+│   └── terminal-canvas/             ← NEW: Example application
+│       ├── App.svelte
+│       ├── README.md
+│       └── package.json
+├── docs/
+│   └── TERMINAL_NODE.md            ← UPDATED: Full documentation
+└── package.json                     ← UPDATED: Added components export
+```
+
+---
+
+## Component Features
+
+### Visual Interface
+
+```
+┌─────────────────────────────────────────┐
+│ Terminal: terminal-1     Mode: text     │  ← Title bar (draggable)
+├─────────────────────────────────────────┤
+│                                         │
+│  $ echo "Hello World"                   │
+│  [Stub] Command received: echo...       │  ← Output area
+│                                         │
+│  $ ls -la                               │
+│  [Stub] Command received: ls...         │
+│                                         │
+├─────────────────────────────────────────┤
+│ $ [Enter command...]          [Run]     │  ← Input area
+└─────────────────────────────────────────┘
+                                         ◢  ← Resize handle
+```
+
+### Interactions
+
+- **Drag**: Click title bar and move
+- **Resize**: Drag bottom-right corner
+- **Context Menu**: Right-click for operations
+- **Execute**: Type command and press Enter
+- **Keyboard**: Enter key to execute
+
+---
+
+## Code Quality Validation
+
+### ✅ Code Review
+
+```
+Status: PASSED (0 issues)
+
+Fixed:
+- ✅ Hardcoded element IDs removed
+- ✅ Event listener cleanup implemented
+- ✅ onDestroy lifecycle added
+- ✅ Memory leak prevention
+```
+
+### ✅ Security Check (CodeQL)
+
+```
+Status: PASSED (0 alerts)
+
+JavaScript Analysis: 0 vulnerabilities
+```
+
+### ✅ Build & Test
+
+```
+Status: PASSED
+
+Build:  ✅ Successful (no TypeScript errors)
+Tests:  ✅ 149/149 passing
+Files:  ✅ 12/12 test files passing
+```
+
+---
+
+## Usage Example
+
+```svelte
+<script lang="ts">
+  import TerminalNode from '@plures/praxis/components/TerminalNode.svelte';
+  import { createTerminalAdapter } from '@plures/praxis';
+
+  // Create terminal adapter
+  const terminal = createTerminalAdapter({
+    nodeId: 'my-terminal',
+    props: {
+      inputMode: 'text',
+      history: [],
+      lastOutput: null,
+    },
+  });
+</script>
+
+<!-- Render on canvas -->
+<div class="canvas">
+  <TerminalNode
+    adapter={terminal}
+    x={100}
+    y={100}
+    width={600}
+    height={400}
+    draggable={true}
+    resizable={true}
+  />
+</div>
+
+<style>
+  .canvas {
+    position: relative;
+    width: 100%;
+    height: 100vh;
+    background: #1a1a1a;
+  }
+</style>
+```
+
+---
+
+## Component Props API
+
+| Prop              | Type              | Default  | Description                |
+| ----------------- | ----------------- | -------- | -------------------------- |
+| `adapter`         | `TerminalAdapter` | required | Terminal adapter instance  |
+| `x`               | `number`          | `0`      | X position on canvas       |
+| `y`               | `number`          | `0`      | Y position on canvas       |
+| `width`           | `number`          | `600`    | Component width in pixels  |
+| `height`          | `number`          | `400`    | Component height in pixels |
+| `draggable`       | `boolean`         | `true`   | Enable drag to move        |
+| `resizable`       | `boolean`         | `true`   | Enable resize handle       |
+| `showContextMenu` | `boolean`         | `false`  | Show context menu          |
+
+---
+
+## Documentation
+
+All documentation is complete and accurate:
+
+1. **API Reference**: `docs/TERMINAL_NODE.md`
+   - Schema definitions
+   - Runtime adapter usage
+   - Svelte component API
+   - Complete examples
+
+2. **Component Guide**: `src/components/README.md`
+   - Component features
+   - Usage patterns
+   - Canvas integration
+   - Future components roadmap
+
+3. **Example Application**: `examples/terminal-canvas/README.md`
+   - Setup instructions
+   - Multiple terminals example
+   - State management patterns
+   - Integration with RuneBook
+
+4. **Completion Summary**: `TASK_1_COMPLETE.md`
+   - Requirements checklist
+   - Implementation details
+   - Validation results
+   - Next steps
+
+---
+
+## Statistics
+
+### Code Metrics
+
+- **New Files**: 7 files created
+- **Modified Files**: 2 files updated
+- **Total Lines**: ~1,424 lines of code and documentation
+- **Component Size**: 459 lines (TerminalNode.svelte)
+- **Test Coverage**: 16 terminal-specific tests + 133 core tests
+
+### Validation Metrics
+
+- **Code Review**: 0 issues (all resolved)
+- **Security Scan**: 0 vulnerabilities
+- **Test Pass Rate**: 100% (149/149)
+- **Build Success**: 100%
+- **TypeScript Errors**: 0
+
+---
+
+## Foundation for RuneBook
+
+This implementation provides the foundation for the remaining 9 tasks:
+
+### Ready For Task 2: Reactive Stdout → Props Pipeline
+
+- ✅ Terminal adapter with execute stub
+- ✅ Props structure defined
+- ✅ Component ready for reactive updates
+- ✅ PluresDB bindings prepared
+
+### Pattern Established For Tasks 3-9
+
+The TerminalNode component establishes patterns for:
+
+- **Task 3**: InputNode - Similar canvas integration
+- **Task 4**: DisplayNode - Similar reactive props
+- **Task 5**: Node Wiring - Connection points ready
+- **Task 6**: Execution Engine - Adapter structure ready
+- **Task 7**: AgentNode - Similar component pattern
+- **Task 8**: SudolangNode - Same canvas approach
+- **Task 9**: CustomNode - Component loading pattern
+
+### Ready For Task 10: Tauri Shell
+
+- ✅ Component can be embedded in Tauri app
+- ✅ Canvas layout ready for full application
+- ✅ Context menu pattern established
+- ✅ Multiple node support working
+
+---
+
+## Conclusion
+
+**Task 1 is COMPLETE** with:
+
+- ✅ All requirements met
+- ✅ Production-ready code quality
+- ✅ Comprehensive documentation
+- ✅ Working example application
+- ✅ Zero security issues
+- ✅ All tests passing
+- ✅ Code review approved
+
+**Ready to proceed with Task 2** and subsequent RuneBook development.
+
+---
+
+## Quick Links
+
+- **Component**: `src/components/TerminalNode.svelte`
+- **Docs**: `docs/TERMINAL_NODE.md`
+- **Example**: `examples/terminal-canvas/App.svelte`
+- **Tests**: `src/__tests__/terminal-node.test.ts`
+- **Adapter**: `src/runtime/terminal-adapter.ts`
+
+---
+
+_Task completed: 2025-11-21_
+_All validation passed: Code Review ✅ | Security ✅ | Tests ✅_

package/docs/archive/1.x/VERSION_0.2.0_RELEASE_NOTES.md

@@ -0,0 +1,288 @@
+# Praxis 0.2.0 Release Notes
+
+**Release Date:** November 24, 2025  
+**Previous Version:** 0.1.0 (November 15, 2025)
+
+## Overview
+
+Praxis 0.2.0 represents a major expansion of the framework from a logic engine into a **complete application framework**. This release includes 165 passing tests (up from 9), comprehensive documentation, and ready-to-use publishing workflows for both npm and JSR (Deno).
+
+## What's New
+
+### 🏗️ Framework Infrastructure
+
+#### Complete Schema System
+
+- **Location:** `src/core/schema/`
+- Type definitions for models, components, logic, and orchestration
+- Schema validation and normalization
+- YAML/JSON schema loading
+- Multi-target code generation (PluresDB, Svelte, State-Docs, Canvas, DSC)
+
+#### Component Generation
+
+- **Location:** `src/core/component/generator.ts`
+- Automatic Svelte component generation from schemas
+- Support for form, display, list, and navigation components
+- TypeScript type generation
+- Test scaffolding and documentation generation
+
+#### CLI Tools
+
+- **Location:** `src/cli/`
+- `praxis create app|component` - Project scaffolding
+- `praxis generate` - Code generation from schemas
+- `praxis canvas` - Visual schema editor integration
+- `praxis orchestrate` - Distributed system orchestration
+- `praxis login|logout|whoami` - GitHub authentication
+- `praxis cloud` - Cloud service management
+
+### 🎨 Svelte 5 Integration
+
+- **Location:** `src/integrations/svelte.ts`
+- `usePraxisState` - Reactive state management with Svelte 5 runes
+- `usePraxisHistory` - Time-travel debugging with undo/redo
+- `usePraxisComputed` - Derived state computations
+- Full TypeScript generics support
+- Working Svelte 5 counter example
+
+### ☁️ Cloud & Monetization
+
+- **Location:** `src/cloud/`
+- GitHub-based authentication (OAuth device flow + Personal Access Tokens)
+- Tier-based billing system:
+  - **Free:** 1K syncs/month, 10MB storage, 1 app
+  - **Solo:** $5/mo - 50K syncs/month, 1GB storage, 10 apps
+  - **Team:** $20/mo - 500K syncs/month, 10GB storage, 50 apps, 10 members
+  - **Enterprise:** $50/mo - 5M syncs/month, 100GB storage, 1K apps, unlimited members
+- Usage tracking and limit validation
+- Tenant provisioning with storage namespaces
+- Azure Functions relay endpoints
+
+### 🔄 Cross-Language Support
+
+#### PowerShell Adapter
+
+- **Location:** `powershell/Praxis.psm1`
+- Complete cmdlet library for Praxis operations
+- JSON bridge to TypeScript engine
+- Protocol version compatibility checking
+- Working counter example included
+
+### 🔍 Introspection & Visualization
+
+- **Location:** `src/core/introspection.ts`
+- Registry statistics and metrics
+- JSON schema generation
+- Graph representation (nodes and edges)
+- Graphviz DOT export
+- Mermaid diagram export
+- Rule and constraint search
+- Module dependency tracking
+
+### 📋 Protocol Versioning
+
+- **Location:** `src/core/protocol.ts`
+- Explicit protocol version: **v1.0.0**
+- Semantic versioning with stability guarantees
+- Cross-language compatibility checks
+- Migration path documentation in `PROTOCOL_VERSIONING.md`
+
+### 📚 Examples & Templates
+
+#### Hero E-Commerce Example
+
+- **Location:** `src/examples/hero-ecommerce/`
+- Full authentication system with session management
+- Shopping cart with dynamic pricing
+- Discount code system (SAVE10, SAVE20, FREESHIP)
+- Feature flags and A/B testing
+- Loyalty points system (1 point per dollar)
+- Order history tracking
+
+#### Other Examples
+
+- Advanced TODO app with Svelte integration
+- Basic authentication example
+- Svelte counter with runes
+- Basic and fullstack app templates
+
+### 🧪 Testing
+
+**Test Suite Expansion:** 9 tests → 165 tests (1733% increase!)
+
+New test files:
+
+- `actors.test.ts` - Actor lifecycle and behavior (12 tests)
+- `edge-cases.test.ts` - Edge cases and error handling (19 tests)
+- `introspection.test.ts` - Registry introspection (14 tests)
+- `billing.test.ts` - Billing system validation (16 tests)
+- `cloud.test.ts` - Cloud integration (10 tests)
+- `provisioning.test.ts` - Tenant provisioning (18 tests)
+- `generators.test.ts` - Code generation (15 tests)
+- `schema.test.ts` - Schema validation (11 tests)
+- `svelte-integration.test.ts` - Svelte integration (16 tests)
+- `terminal-node.test.ts` - Terminal node functionality (16 tests)
+- `protocol.test.ts` - Protocol versioning (3 tests)
+
+### 📖 Documentation
+
+#### Framework Documentation
+
+- `FRAMEWORK.md` - Complete architecture guide (420 lines)
+- `GETTING_STARTED.md` - Comprehensive getting started guide (290 lines)
+- `PROTOCOL_VERSIONING.md` - Protocol versioning specification (275 lines)
+- `FEATURE_SUMMARY.md` - Major features overview (223 lines)
+- `ELEVATION_SUMMARY.md` - Framework transformation summary (222 lines)
+
+#### Guides
+
+- `docs/guides/getting-started.md` - Quick start guide
+- `docs/guides/canvas.md` - Canvas integration guide
+- `docs/guides/orchestration.md` - Orchestration guide (DSC/MCP)
+- `docs/guides/svelte-integration.md` - Svelte integration guide
+- `docs/guides/history-state-pattern.md` - Time-travel debugging
+- `docs/guides/parallel-state-pattern.md` - Parallel state management
+
+### 🔧 Infrastructure
+
+#### CI/CD Workflows
+
+- Node.js CI with multiple versions (18.x, 20.x)
+- Deno compatibility checks
+- CodeQL security scanning
+- Automated release workflow
+- JSR publishing workflow (enabled)
+- npm publishing workflow (enabled)
+- Stale issue management
+
+#### GitHub Configuration
+
+- Issue templates (bug, enhancement, proposal, integration, generator)
+- Pull request template with comprehensive checklist
+- Funding configuration
+- Label system
+- Dependabot configuration
+- Pre-commit hooks template
+
+## Breaking Changes
+
+**None!** This release is fully backward compatible with 0.1.0.
+
+## Bug Fixes
+
+- Fixed duplicate "types" key in tsconfig.json
+- Fixed deprecated `nodeModulesDir: false` to `nodeModulesDir: "none"` in deno.json
+- Removed `"private": true` from jsr.json to enable JSR publishing
+
+## Installation
+
+### npm
+
+```bash
+npm install @plures/praxis@0.2.0
+```
+
+### Deno/JSR
+
+```typescript
+import { createPraxisEngine } from 'jsr:@plures/praxis@0.2.0';
+```
+
+## Upgrading from 0.1.0
+
+Since there are no breaking changes, upgrading is straightforward:
+
+```bash
+npm install @plures/praxis@latest
+```
+
+All existing code using 0.1.0 APIs will continue to work without modification.
+
+## Publishing Status
+
+### npm Publishing
+
+✅ **Enabled** - Will publish to npm when a version tag (e.g., `v0.2.0`) is pushed
+
+- Workflow: `.github/workflows/release.yml`
+- Requires: `NPM_TOKEN` secret configured in repository
+
+### JSR Publishing
+
+✅ **Enabled** - Will publish to JSR when a GitHub release is published
+
+- Workflow: `.github/workflows/publish-jsr.yml`
+- Uses: GitHub OIDC token (no secret needed)
+- Note: Some Deno lint warnings exist but don't block publishing
+
+## How to Release
+
+To create a release for this version:
+
+1. **Create and push a git tag:**
+
+   ```bash
+   git tag v0.2.0
+   git push origin v0.2.0
+   ```
+
+2. **The release workflow will automatically:**
+   - Run tests and build
+   - Create a GitHub Release with changelog
+   - Publish to npm (if NPM_TOKEN is configured)
+
+3. **The JSR publish workflow will automatically:**
+   - Trigger when the GitHub release is published
+   - Publish to JSR using GitHub OIDC
+
+## Next Steps
+
+### For Users
+
+- Read the [Getting Started Guide](./GETTING_STARTED.md)
+- Explore the [hero e-commerce example](./src/examples/hero-ecommerce/)
+- Try the [Svelte integration](./docs/guides/svelte-integration.md)
+- Set up [GitHub authentication](./src/cloud/README.md) for cloud features
+
+### For Contributors
+
+- Review the [Framework Guide](./FRAMEWORK.md)
+- Check the [Contributing Guide](./CONTRIBUTING.md)
+- Explore the [introspection tools](./src/core/introspection.ts)
+- Add new [project templates](./templates/)
+
+## Statistics
+
+- **Total Tests:** 165 (all passing)
+- **Test Coverage:** 13 test files covering all major features
+- **Documentation:** 15+ comprehensive documentation files
+- **Examples:** 6 working examples with detailed READMEs
+- **Code Quality:** 0 TypeScript errors, 0 CodeQL security alerts
+- **Lines of Code:** ~30,000+ lines added since 0.1.0
+
+## Acknowledgments
+
+This release represents a massive collaborative effort to transform Praxis from a logic engine into a complete application framework. Special thanks to all contributors and the Plures community!
+
+## Resources
+
+- **GitHub Repository:** https://github.com/plures/praxis
+- **Documentation:** https://github.com/plures/praxis/tree/main/docs
+- **Issues:** https://github.com/plures/praxis/issues
+- **Discussions:** https://github.com/plures/praxis/discussions
+- **npm Package:** https://www.npmjs.com/package/@plures/praxis
+- **JSR Package:** https://jsr.io/@plures/praxis
+
+## Support
+
+If you encounter any issues or have questions:
+
+1. Check the [documentation](./docs/)
+2. Search [existing issues](https://github.com/plures/praxis/issues)
+3. Open a [new issue](https://github.com/plures/praxis/issues/new/choose)
+4. Join the [discussions](https://github.com/plures/praxis/discussions)
+
+---
+
+**Happy Building with Praxis! 🚀**

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

@@ -0,0 +1,7 @@
+# Validation Checklist
+
+| Date       | Validation                                                                  | Status | Notes                                                    |
+| ---------- | --------------------------------------------------------------------------- | ------ | -------------------------------------------------------- |
+| 2025-11-28 | Ensure `flashNode` restores each node's background color based on its type. | ⚠️     | Requires manual verification in the canvas inspector UI. |
+| 2026-01-28 | Reuse `getObjectHasContract` within `hasContractProperty` logic.            | ✅     | Refactor only; no behavior change expected.              |
+| 2026-01-28 | Avoid duplicate rule file parsing in decision ledger scan.                  | ✅     | Reused parsed source for analysis.                       |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plures/praxis",
-  "version": "1.4.4",
+  "version": "2.0.3",
   "description": "The Full Plures Application Framework - declarative schemas, logic engine, component generation, and local-first data",
   "type": "module",
   "packageManager": "pnpm@9.15.1",
@@ -107,6 +107,18 @@
         "import": "./dist/browser/project/index.js"
       },
       "default": "./dist/node/project/index.js"
+    },
+    "./unified": {
+      "node": {
+        "types": "./dist/node/unified/index.d.ts",
+        "import": "./dist/node/unified/index.js",
+        "require": "./dist/node/unified/index.cjs"
+      },
+      "browser": {
+        "types": "./dist/browser/unified/index.d.ts",
+        "import": "./dist/browser/unified/index.js"
+      },
+      "default": "./dist/node/unified/index.js"
     }
   },
   "files": [

package/src/index.browser.ts

@@ -303,3 +303,23 @@ export type {
   BranchRulesConfig,
   PredefinedGateConfig,
 } from './project/index.js';
+
+// ── Unified Reactive Layer (v2.0) ───────────────────────────────────────────
+export { createApp } from './unified/core.js';
+export type { PraxisApp } from './unified/core.js';
+export {
+  definePath,
+  defineRule as defineUnifiedRule,
+  defineConstraint as defineUnifiedConstraint,
+  defineModule as defineUnifiedModule,
+} from './unified/index.js';
+export type {
+  PathSchema,
+  QueryOptions,
+  ReactiveRef,
+  MutationResult,
+  UnifiedRule,
+  UnifiedConstraint,
+  LivenessConfig,
+  PraxisAppConfig,
+} from './unified/types.js';

package/src/index.ts

@@ -487,3 +487,24 @@ export type {
   FullBehavioralDiff,
 } from './chronos/index.js';
 
+
+// ── Unified Reactive Layer (v2.0) ───────────────────────────────────────────
+// The zero-boilerplate API: createApp → query() + mutate()
+export { createApp } from './unified/core.js';
+export type { PraxisApp } from './unified/core.js';
+export {
+  definePath,
+  defineRule as defineUnifiedRule,
+  defineConstraint as defineUnifiedConstraint,
+  defineModule as defineUnifiedModule,
+} from './unified/index.js';
+export type {
+  PathSchema,
+  QueryOptions,
+  ReactiveRef,
+  MutationResult,
+  UnifiedRule,
+  UnifiedConstraint,
+  LivenessConfig,
+  PraxisAppConfig,
+} from './unified/types.js';