@plures/praxis 1.0.2 → 1.1.0

package/dist/node/orchestrate-737TCL5H.js

@@ -0,0 +1,127 @@
+import "./chunk-QGM4M3NI.js";
+
+// src/cli/commands/orchestrate.ts
+import * as fs from "fs";
+async function orchestrate(options) {
+  const action = options.action || "status";
+  console.log("\n\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557");
+  console.log("\u2551   Praxis Orchestration                            \u2551");
+  console.log("\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D\n");
+  switch (action) {
+    case "init":
+      await initOrchestration(options);
+      break;
+    case "start":
+      await startOrchestration(options);
+      break;
+    case "stop":
+      await stopOrchestration(options);
+      break;
+    case "status":
+    default:
+      await showOrchestrationStatus(options);
+  }
+}
+async function initOrchestration(options) {
+  const configPath = options.config || "praxis.orchestrate.json";
+  if (fs.existsSync(configPath)) {
+    console.log(`Configuration file already exists: ${configPath}`);
+    console.log("Use --config to specify a different file.\n");
+    return;
+  }
+  const defaultConfig = {
+    nodeId: `node-${Date.now().toString(36)}`,
+    role: "primary",
+    endpoints: ["ws://localhost:8080/sync"],
+    sync: {
+      enabled: true,
+      interval: 5e3,
+      conflictResolution: "last-write-wins"
+    },
+    health: {
+      enabled: true,
+      interval: 1e4,
+      timeout: 5e3
+    }
+  };
+  fs.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2));
+  console.log(`\u2713 Created orchestration config: ${configPath}`);
+  console.log("\nConfiguration:");
+  console.log(`  Node ID: ${defaultConfig.nodeId}`);
+  console.log(`  Role: ${defaultConfig.role}`);
+  console.log(`  Endpoints: ${defaultConfig.endpoints.join(", ")}`);
+  console.log(`  Sync Enabled: ${defaultConfig.sync.enabled}`);
+  console.log(`  Health Check: ${defaultConfig.health.enabled}
+`);
+  console.log("To start orchestration:");
+  console.log(`  praxis orchestrate --action start --config ${configPath}
+`);
+}
+async function startOrchestration(options) {
+  const configPath = options.config || "praxis.orchestrate.json";
+  if (!fs.existsSync(configPath)) {
+    console.log(`Configuration file not found: ${configPath}`);
+    console.log("\nTo create a configuration:");
+    console.log("  praxis orchestrate --action init\n");
+    return;
+  }
+  const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+  console.log("Starting orchestration...\n");
+  console.log(`  Node ID: ${config.nodeId}`);
+  console.log(`  Role: ${config.role}`);
+  console.log(`  Endpoints: ${config.endpoints.join(", ")}
+`);
+  console.log("\u{1F504} Connecting to cluster...");
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  console.log("\u2713 Connected to cluster");
+  console.log("\u2713 Sync worker started");
+  console.log("\u2713 Health check enabled\n");
+  console.log("Orchestration is running.");
+  console.log("\nTo check status:");
+  console.log("  praxis orchestrate --action status\n");
+  console.log("To stop:");
+  console.log("  praxis orchestrate --action stop\n");
+}
+async function stopOrchestration(_options) {
+  console.log("Stopping orchestration...\n");
+  console.log("\u2713 Sync worker stopped");
+  console.log("\u2713 Unregistered from cluster");
+  console.log("\u2713 Connections closed\n");
+  console.log("Orchestration stopped.\n");
+}
+async function showOrchestrationStatus(options) {
+  const configPath = options.config || "praxis.orchestrate.json";
+  if (!fs.existsSync(configPath)) {
+    console.log("Orchestration not configured.\n");
+    console.log("To initialize:");
+    console.log("  praxis orchestrate --action init\n");
+    console.log("For more information on distributed coordination:");
+    console.log("  \u2022 Define orchestration in your schema");
+    console.log("  \u2022 Configure DSC nodes for state synchronization");
+    console.log("  \u2022 See docs/guides/orchestration.md for patterns\n");
+    return;
+  }
+  const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+  console.log("Orchestration Status\n");
+  console.log("\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510");
+  console.log(`\u2502 Node ID:     ${config.nodeId.padEnd(36)} \u2502`);
+  console.log(`\u2502 Role:        ${config.role.padEnd(36)} \u2502`);
+  console.log(`\u2502 Status:      ${"Configured (not running)".padEnd(36)} \u2502`);
+  console.log("\u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524");
+  console.log(`\u2502 Sync:        ${(config.sync.enabled ? "Enabled" : "Disabled").padEnd(36)} \u2502`);
+  console.log(`\u2502 Interval:    ${(config.sync.interval + "ms").padEnd(36)} \u2502`);
+  console.log(`\u2502 Resolution:  ${config.sync.conflictResolution.padEnd(36)} \u2502`);
+  console.log("\u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524");
+  console.log(`\u2502 Health:      ${(config.health.enabled ? "Enabled" : "Disabled").padEnd(36)} \u2502`);
+  console.log(`\u2502 Interval:    ${(config.health.interval + "ms").padEnd(36)} \u2502`);
+  console.log(`\u2502 Timeout:     ${(config.health.timeout + "ms").padEnd(36)} \u2502`);
+  console.log("\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n");
+  console.log("Endpoints:");
+  config.endpoints.forEach((ep) => console.log(`  \u2022 ${ep}`));
+  console.log("\nTo start orchestration:");
+  console.log(`  praxis orchestrate --action start --config ${configPath}
+`);
+}
+export {
+  orchestrate
+};

package/dist/{src/core/protocol.d.ts → node/protocol-Qek7ebBl.d.cts}

@@ -42,12 +42,12 @@
 /**
  * Protocol version following semantic versioning
  */
-export declare const PRAXIS_PROTOCOL_VERSION: "1.0.0";
+declare const PRAXIS_PROTOCOL_VERSION: "1.0.0";
 /**
  * A fact is a typed proposition about the domain.
  * Examples: UserLoggedIn, CartItem, NetworkOnline
  */
-export interface PraxisFact {
+interface PraxisFact {
     /** Tag identifying the fact type */
     tag: string;
     /** Payload containing the fact data */
@@ -57,7 +57,7 @@ export interface PraxisFact {
  * An event is a temporally ordered fact meant to drive change.
  * Examples: LOGIN, LOGOUT, ADD_TO_CART
  */
-export interface PraxisEvent {
+interface PraxisEvent {
     /** Tag identifying the event type */
     tag: string;
     /** Payload containing the event data */
@@ -66,7 +66,7 @@ export interface PraxisEvent {
 /**
  * The state of the Praxis engine at a point in time.
  */
-export interface PraxisState {
+interface PraxisState {
     /** Application context (domain-specific data) */
     context: unknown;
     /** Current facts about the domain */
@@ -79,9 +79,9 @@ export interface PraxisState {
 /**
  * Diagnostic information about constraint violations or rule errors.
  */
-export interface PraxisDiagnostics {
+interface PraxisDiagnostics {
     /** Kind of diagnostic */
-    kind: "constraint-violation" | "rule-error";
+    kind: 'constraint-violation' | 'rule-error';
     /** Human-readable message */
     message: string;
     /** Additional diagnostic data */
@@ -91,7 +91,7 @@ export interface PraxisDiagnostics {
  * Configuration for a step execution.
  * Specifies which rules and constraints to apply.
  */
-export interface PraxisStepConfig {
+interface PraxisStepConfig {
     /** IDs of rules to apply during this step */
     ruleIds: string[];
     /** IDs of constraints to check during this step */
@@ -100,7 +100,7 @@ export interface PraxisStepConfig {
 /**
  * Result of a step execution.
  */
-export interface PraxisStepResult {
+interface PraxisStepResult {
     /** New state after applying rules and checking constraints */
     state: PraxisState;
     /** Diagnostics from rule execution and constraint checking */
@@ -117,5 +117,6 @@ export interface PraxisStepResult {
  * Pure, deterministic, data in → data out.
  * No side effects, no global state.
  */
-export type PraxisStepFn = (state: PraxisState, events: PraxisEvent[], config: PraxisStepConfig) => PraxisStepResult;
-//# sourceMappingURL=protocol.d.ts.map
+type PraxisStepFn = (state: PraxisState, events: PraxisEvent[], config: PraxisStepConfig) => PraxisStepResult;
+
+export { type PraxisState as P, type PraxisEvent as a, type PraxisFact as b, type PraxisStepResult as c, type PraxisStepConfig as d, type PraxisDiagnostics as e, type PraxisStepFn as f, PRAXIS_PROTOCOL_VERSION as g };

package/dist/node/protocol-Qek7ebBl.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Core Praxis Protocol
+ *
+ * Language-neutral, JSON-friendly protocol that forms the foundation of Praxis.
+ * This protocol is designed to be stable and portable across languages (TypeScript, C#, PowerShell, etc.)
+ *
+ * The protocol defines the conceptual core of the engine:
+ * - Pure, deterministic, data in → data out
+ * - No side effects, no global state
+ * - All higher-level TypeScript APIs are built on top of this protocol
+ *
+ * ## Protocol Versioning
+ *
+ * The Praxis protocol follows semantic versioning (MAJOR.MINOR.PATCH):
+ * - MAJOR: Breaking changes to core protocol types or semantics
+ * - MINOR: Backward-compatible additions to protocol (new optional fields)
+ * - PATCH: Clarifications, documentation updates, no functional changes
+ *
+ * Current version: 1.0.0
+ *
+ * ### Stability Guarantees
+ *
+ * 1. **Core Types Stability**: The following types are considered stable and will not
+ *    change in backward-incompatible ways within the same major version:
+ *    - PraxisFact (tag, payload structure)
+ *    - PraxisEvent (tag, payload structure)
+ *    - PraxisState (context, facts, meta structure)
+ *    - PraxisStepFn signature
+ *
+ * 2. **JSON Compatibility**: All protocol types will remain JSON-serializable.
+ *    No non-JSON-safe types (functions, symbols, etc.) will be added to the protocol.
+ *
+ * 3. **Cross-Language Compatibility**: Protocol changes will be coordinated across
+ *    all official language implementations (TypeScript, C#, PowerShell) to ensure
+ *    interoperability.
+ *
+ * 4. **Migration Path**: Major version changes will be accompanied by:
+ *    - Migration guide
+ *    - Deprecation warnings in previous version
+ *    - Compatibility shims where possible
+ */
+/**
+ * Protocol version following semantic versioning
+ */
+declare const PRAXIS_PROTOCOL_VERSION: "1.0.0";
+/**
+ * A fact is a typed proposition about the domain.
+ * Examples: UserLoggedIn, CartItem, NetworkOnline
+ */
+interface PraxisFact {
+    /** Tag identifying the fact type */
+    tag: string;
+    /** Payload containing the fact data */
+    payload: unknown;
+}
+/**
+ * An event is a temporally ordered fact meant to drive change.
+ * Examples: LOGIN, LOGOUT, ADD_TO_CART
+ */
+interface PraxisEvent {
+    /** Tag identifying the event type */
+    tag: string;
+    /** Payload containing the event data */
+    payload: unknown;
+}
+/**
+ * The state of the Praxis engine at a point in time.
+ */
+interface PraxisState {
+    /** Application context (domain-specific data) */
+    context: unknown;
+    /** Current facts about the domain */
+    facts: PraxisFact[];
+    /** Optional metadata (timestamps, version, etc.) */
+    meta?: Record<string, unknown>;
+    /** Protocol version (for cross-language compatibility) */
+    protocolVersion?: string;
+}
+/**
+ * Diagnostic information about constraint violations or rule errors.
+ */
+interface PraxisDiagnostics {
+    /** Kind of diagnostic */
+    kind: 'constraint-violation' | 'rule-error';
+    /** Human-readable message */
+    message: string;
+    /** Additional diagnostic data */
+    data?: unknown;
+}
+/**
+ * Configuration for a step execution.
+ * Specifies which rules and constraints to apply.
+ */
+interface PraxisStepConfig {
+    /** IDs of rules to apply during this step */
+    ruleIds: string[];
+    /** IDs of constraints to check during this step */
+    constraintIds: string[];
+}
+/**
+ * Result of a step execution.
+ */
+interface PraxisStepResult {
+    /** New state after applying rules and checking constraints */
+    state: PraxisState;
+    /** Diagnostics from rule execution and constraint checking */
+    diagnostics: PraxisDiagnostics[];
+}
+/**
+ * The core step function of the Praxis engine.
+ *
+ * This is the conceptual heart of the engine:
+ * - Takes current state, events, and configuration
+ * - Applies rules and checks constraints
+ * - Returns new state and diagnostics
+ *
+ * Pure, deterministic, data in → data out.
+ * No side effects, no global state.
+ */
+type PraxisStepFn = (state: PraxisState, events: PraxisEvent[], config: PraxisStepConfig) => PraxisStepResult;
+
+export { type PraxisState as P, type PraxisEvent as a, type PraxisFact as b, type PraxisStepResult as c, type PraxisStepConfig as d, type PraxisDiagnostics as e, type PraxisStepFn as f, PRAXIS_PROTOCOL_VERSION as g };

package/dist/node/schema.cjs

@@ -0,0 +1,200 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/core/schema/types.ts
+var types_exports = {};
+__export(types_exports, {
+  createSchemaTemplate: () => createSchemaTemplate,
+  validateSchema: () => validateSchema
+});
+module.exports = __toCommonJS(types_exports);
+function validateSchema(schema) {
+  const errors = [];
+  if (!schema.version) {
+    errors.push({ path: "version", message: "Schema version is required" });
+  }
+  if (!schema.name) {
+    errors.push({ path: "name", message: "Schema name is required" });
+  }
+  if (schema.models) {
+    schema.models.forEach((model, index) => {
+      if (!model.name) {
+        errors.push({
+          path: `models[${index}].name`,
+          message: "Model name is required"
+        });
+      }
+      if (!model.fields || model.fields.length === 0) {
+        errors.push({
+          path: `models[${index}].fields`,
+          message: "Model must have at least one field"
+        });
+      }
+    });
+  }
+  if (schema.components) {
+    schema.components.forEach((component, index) => {
+      if (!component.name) {
+        errors.push({
+          path: `components[${index}].name`,
+          message: "Component name is required"
+        });
+      }
+      if (!component.type) {
+        errors.push({
+          path: `components[${index}].type`,
+          message: "Component type is required"
+        });
+      }
+    });
+  }
+  if (schema.logic) {
+    schema.logic.forEach((logic, logicIndex) => {
+      if (logic.facts) {
+        logic.facts.forEach((fact, factIndex) => {
+          if (!fact.tag) {
+            errors.push({
+              path: `logic[${logicIndex}].facts[${factIndex}].tag`,
+              message: "Fact tag is required"
+            });
+          } else if (!isValidIdentifier(fact.tag)) {
+            errors.push({
+              path: `logic[${logicIndex}].facts[${factIndex}].tag`,
+              message: `Fact tag "${fact.tag}" is not a valid JavaScript identifier. Use only letters, numbers, underscores, and dollar signs, and do not start with a number.`
+            });
+          }
+        });
+      }
+      if (logic.events) {
+        logic.events.forEach((event, eventIndex) => {
+          if (!event.tag) {
+            errors.push({
+              path: `logic[${logicIndex}].events[${eventIndex}].tag`,
+              message: "Event tag is required"
+            });
+          } else if (!isValidIdentifier(event.tag)) {
+            errors.push({
+              path: `logic[${logicIndex}].events[${eventIndex}].tag`,
+              message: `Event tag "${event.tag}" is not a valid JavaScript identifier. Use only letters, numbers, underscores, and dollar signs, and do not start with a number.`
+            });
+          }
+        });
+      }
+    });
+  }
+  if (schema.orchestration?.nodes) {
+    schema.orchestration.nodes.forEach((node, index) => {
+      if (!node.id) {
+        errors.push({
+          path: `orchestration.nodes[${index}].id`,
+          message: "Node id is required"
+        });
+      }
+      if (!node.type) {
+        errors.push({
+          path: `orchestration.nodes[${index}].type`,
+          message: "Node type is required"
+        });
+      }
+      if (node.type === "terminal" && node.props) {
+        const props = node.props;
+        if (props.inputMode && !["text", "widget"].includes(props.inputMode)) {
+          errors.push({
+            path: `orchestration.nodes[${index}].props.inputMode`,
+            message: 'Terminal node inputMode must be "text" or "widget"'
+          });
+        }
+        if (props.history && !Array.isArray(props.history)) {
+          errors.push({
+            path: `orchestration.nodes[${index}].props.history`,
+            message: "Terminal node history must be an array"
+          });
+        }
+      }
+    });
+  }
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+function isValidIdentifier(str) {
+  const identifierRegex = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+  const reservedKeywords = [
+    "break",
+    "case",
+    "catch",
+    "class",
+    "const",
+    "continue",
+    "debugger",
+    "default",
+    "delete",
+    "do",
+    "else",
+    "export",
+    "extends",
+    "finally",
+    "for",
+    "function",
+    "if",
+    "import",
+    "in",
+    "instanceof",
+    "new",
+    "return",
+    "super",
+    "switch",
+    "this",
+    "throw",
+    "try",
+    "typeof",
+    "var",
+    "void",
+    "while",
+    "with",
+    "yield",
+    "let",
+    "static",
+    "enum",
+    "await",
+    "implements",
+    "interface",
+    "package",
+    "private",
+    "protected",
+    "public"
+  ];
+  return identifierRegex.test(str) && !reservedKeywords.includes(str);
+}
+function createSchemaTemplate(name) {
+  return {
+    version: "1.0.0",
+    name,
+    description: `Schema for ${name}`,
+    models: [],
+    components: [],
+    logic: []
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createSchemaTemplate,
+  validateSchema
+});