@plures/praxis 1.3.0 → 1.4.4

package/dist/browser/{chunk-N63K4KWS.js → chunk-4IRUGWR3.js}

@@ -1,6 +1,6 @@
 import {
   createPraxisEngine
-} from "./chunk-MJK3IYTJ.js";
+} from "./chunk-JZDJU2DO.js";
 
 // src/core/rules.ts
 var PraxisRegistry = class {

package/dist/browser/chunk-6SJ44Q64.js

@@ -0,0 +1,473 @@
+import {
+  RuleResult,
+  fact
+} from "./chunk-IG5BJ2MT.js";
+
+// src/factory/factory.ts
+var SANITIZE_PATTERNS = {
+  "sql-injection": /('|"|;|--|\/\*|\*\/|xp_|exec\s|union\s+select|drop\s+table|insert\s+into|delete\s+from)/i,
+  "xss": /(<script|javascript:|on\w+\s*=|<iframe|<object|<embed|<img[^>]+onerror)/i,
+  "path-traversal": /(\.\.[/\\]|~\/|\/etc\/|\/proc\/)/i,
+  "command-injection": /([;&|`$]|\$\(|>\s*\/)/i
+};
+function inputRules(config = {}) {
+  const {
+    sanitize = [],
+    maxLength = 0,
+    required = false,
+    fieldName = "input"
+  } = config;
+  const rules = [];
+  const constraints = [];
+  if (sanitize.length > 0) {
+    rules.push({
+      id: `factory/input.sanitize-${fieldName}`,
+      description: `Validates ${fieldName} against ${sanitize.join(", ")} patterns`,
+      eventTypes: [`${fieldName}.submit`, `${fieldName}.change`],
+      contract: {
+        ruleId: `factory/input.sanitize-${fieldName}`,
+        behavior: `Checks ${fieldName} for dangerous patterns: ${sanitize.join(", ")}`,
+        examples: [
+          { given: `${fieldName} contains safe text`, when: "input submitted", then: "input.valid emitted" },
+          { given: `${fieldName} contains <script> tag`, when: "input submitted", then: "input.violation emitted" }
+        ],
+        invariants: [
+          `Dangerous ${fieldName} patterns must never pass validation`,
+          "All violations must include the violation type"
+        ]
+      },
+      impl: (state, events) => {
+        const inputEvent = events.find(
+          (e) => e.tag === `${fieldName}.submit` || e.tag === `${fieldName}.change`
+        );
+        if (!inputEvent) return RuleResult.skip("No input event");
+        const value = inputEvent.payload?.value ?? state.context.input?.value ?? "";
+        const violations = [];
+        for (const type of sanitize) {
+          const pattern = SANITIZE_PATTERNS[type];
+          if (pattern && pattern.test(value)) {
+            violations.push(type);
+          }
+        }
+        if (violations.length > 0) {
+          return RuleResult.emit([
+            fact(`${fieldName}.violation`, {
+              field: fieldName,
+              violations,
+              message: `Input failed sanitization: ${violations.join(", ")}`
+            })
+          ]);
+        }
+        return RuleResult.emit([
+          fact(`${fieldName}.valid`, { field: fieldName, sanitized: true })
+        ]);
+      }
+    });
+  }
+  if (maxLength > 0) {
+    constraints.push({
+      id: `factory/input.max-length-${fieldName}`,
+      description: `${fieldName} must not exceed ${maxLength} characters`,
+      contract: {
+        ruleId: `factory/input.max-length-${fieldName}`,
+        behavior: `Enforces max length of ${maxLength} for ${fieldName}`,
+        examples: [
+          { given: `${fieldName} is 10 chars`, when: `maxLength is ${maxLength}`, then: maxLength >= 10 ? "passes" : "violation" }
+        ],
+        invariants: [`${fieldName} length must never exceed ${maxLength}`]
+      },
+      impl: (state) => {
+        const value = state.context.input?.value ?? "";
+        if (value.length > maxLength) {
+          return `${fieldName} exceeds maximum length of ${maxLength} (got ${value.length})`;
+        }
+        return true;
+      }
+    });
+  }
+  if (required) {
+    constraints.push({
+      id: `factory/input.required-${fieldName}`,
+      description: `${fieldName} is required and must not be empty`,
+      contract: {
+        ruleId: `factory/input.required-${fieldName}`,
+        behavior: `Enforces that ${fieldName} is non-empty`,
+        examples: [
+          { given: `${fieldName} is "hello"`, when: "checked", then: "passes" },
+          { given: `${fieldName} is empty`, when: "checked", then: "violation" }
+        ],
+        invariants: [`${fieldName} must never be empty when required`]
+      },
+      impl: (state) => {
+        const value = state.context.input?.value ?? "";
+        if (value.trim().length === 0) {
+          return `${fieldName} is required but empty`;
+        }
+        return true;
+      }
+    });
+  }
+  return { rules, constraints };
+}
+function toastRules(config = {}) {
+  const {
+    requireDiff = false,
+    autoDismissMs = 0,
+    deduplicate = false
+  } = config;
+  const rules = [];
+  const constraints = [];
+  rules.push({
+    id: "factory/toast.show",
+    description: "Emits toast notification with content and config",
+    eventTypes: ["toast.request"],
+    contract: {
+      ruleId: "factory/toast.show",
+      behavior: "Shows toast when requested, respecting diff requirement and auto-dismiss",
+      examples: [
+        { given: "toast requested with message", when: "toast.request fires", then: "toast.show emitted" },
+        ...requireDiff ? [{ given: "no diff present", when: "toast.request fires", then: "toast skipped" }] : []
+      ],
+      invariants: [
+        "Toast message must be non-empty",
+        ...requireDiff ? ["Toast must not appear when diff is empty"] : []
+      ]
+    },
+    impl: (state, events) => {
+      const toastEvent = events.find((e) => e.tag === "toast.request");
+      if (!toastEvent) return RuleResult.skip("No toast request");
+      const payload = toastEvent.payload;
+      const message = payload.message ?? "";
+      if (!message) return RuleResult.skip("Empty toast message");
+      if (requireDiff) {
+        const diff = state.context.diff;
+        if (!diff || Object.keys(diff).length === 0) {
+          return RuleResult.skip("No diff \u2014 toast suppressed");
+        }
+      }
+      return RuleResult.emit([
+        fact("toast.show", {
+          message,
+          type: payload.type ?? "info",
+          autoDismissMs: autoDismissMs > 0 ? autoDismissMs : void 0,
+          timestamp: Date.now()
+        })
+      ]);
+    }
+  });
+  if (deduplicate) {
+    constraints.push({
+      id: "factory/toast.no-duplicates",
+      description: "Prevents duplicate toast messages",
+      contract: {
+        ruleId: "factory/toast.no-duplicates",
+        behavior: "Rejects toast if identical message is already showing",
+        examples: [
+          { given: "same toast already visible", when: "duplicate toast requested", then: "violation" }
+        ],
+        invariants: ["No two toasts may have the same message simultaneously"]
+      },
+      impl: (state) => {
+        const toasts = state.context.toasts ?? [];
+        const messages = toasts.map((t) => t.message);
+        const uniqueMessages = new Set(messages);
+        if (uniqueMessages.size < messages.length) {
+          return "Duplicate toast detected";
+        }
+        return true;
+      }
+    });
+  }
+  return { rules, constraints };
+}
+function formRules(config = {}) {
+  const {
+    validateOnBlur = false,
+    submitGate = false,
+    formName = "form"
+  } = config;
+  const rules = [];
+  const constraints = [];
+  if (validateOnBlur) {
+    rules.push({
+      id: `factory/${formName}.validate-on-blur`,
+      description: `Triggers field validation when a ${formName} field loses focus`,
+      eventTypes: [`${formName}.blur`],
+      contract: {
+        ruleId: `factory/${formName}.validate-on-blur`,
+        behavior: `Validates the blurred field and emits validation result`,
+        examples: [
+          { given: `${formName} field has value`, when: "field loses focus", then: "validation result emitted" }
+        ],
+        invariants: ["Validation must run for every blur event on a registered field"]
+      },
+      impl: (_state, events) => {
+        const blurEvent = events.find((e) => e.tag === `${formName}.blur`);
+        if (!blurEvent) return RuleResult.skip("No blur event");
+        const payload = blurEvent.payload;
+        const field = payload.field ?? "unknown";
+        const value = payload.value;
+        const valid = value !== null && value !== void 0 && value !== "";
+        return RuleResult.emit([
+          fact(`${formName}.field-validated`, {
+            field,
+            valid,
+            error: valid ? null : `${field} is required`
+          })
+        ]);
+      }
+    });
+  }
+  if (submitGate) {
+    constraints.push({
+      id: `factory/${formName}.submit-gate`,
+      description: `Prevents ${formName} submission when validation has not passed`,
+      contract: {
+        ruleId: `factory/${formName}.submit-gate`,
+        behavior: `Blocks form submission until all fields are valid`,
+        examples: [
+          { given: `${formName} is invalid`, when: "submit attempted", then: "violation \u2014 submission blocked" },
+          { given: `${formName} is valid`, when: "submit attempted", then: "passes" }
+        ],
+        invariants: ["Form must not submit while any field has errors"]
+      },
+      impl: (state) => {
+        const form = state.context.form;
+        if (!form) return true;
+        if (form.submitting && !form.valid) {
+          return `${formName} cannot submit: validation has not passed`;
+        }
+        return true;
+      }
+    });
+  }
+  rules.push({
+    id: `factory/${formName}.dirty-tracking`,
+    description: `Tracks whether ${formName} has unsaved changes`,
+    eventTypes: [`${formName}.change`, `${formName}.reset`],
+    contract: {
+      ruleId: `factory/${formName}.dirty-tracking`,
+      behavior: "Emits dirty state when form fields change, clears on reset",
+      examples: [
+        { given: "field value changed", when: "form.change fires", then: "form.dirty emitted" },
+        { given: "form reset", when: "form.reset fires", then: "form.dirty retracted" }
+      ],
+      invariants: ["Dirty state must reflect actual field changes"]
+    },
+    impl: (_state, events) => {
+      const resetEvent = events.find((e) => e.tag === `${formName}.reset`);
+      if (resetEvent) {
+        return RuleResult.retract([`${formName}.dirty`], "Form reset");
+      }
+      const changeEvent = events.find((e) => e.tag === `${formName}.change`);
+      if (changeEvent) {
+        return RuleResult.emit([
+          fact(`${formName}.dirty`, { dirty: true })
+        ]);
+      }
+      return RuleResult.skip("No form event");
+    }
+  });
+  return { rules, constraints };
+}
+function navigationRules(config = {}) {
+  const {
+    dirtyGuard = false,
+    authRequired = false
+  } = config;
+  const rules = [];
+  const constraints = [];
+  rules.push({
+    id: "factory/navigation.handle",
+    description: "Processes navigation requests and emits navigation facts",
+    eventTypes: ["navigation.request"],
+    contract: {
+      ruleId: "factory/navigation.handle",
+      behavior: "Emits navigation.allowed or navigation.blocked based on guards",
+      examples: [
+        { given: "no guards active", when: "navigation requested", then: "navigation.allowed emitted" },
+        ...dirtyGuard ? [{ given: "form is dirty", when: "navigation requested", then: "navigation.blocked emitted" }] : [],
+        ...authRequired ? [{ given: "user not authenticated", when: "navigation requested", then: "navigation.blocked emitted" }] : []
+      ],
+      invariants: [
+        "Every navigation request must result in either allowed or blocked",
+        ...dirtyGuard ? ["Navigation must be blocked when dirty data exists"] : [],
+        ...authRequired ? ["Navigation must be blocked when not authenticated"] : []
+      ]
+    },
+    impl: (state, events) => {
+      const navEvent = events.find((e) => e.tag === "navigation.request");
+      if (!navEvent) return RuleResult.skip("No navigation request");
+      const target = navEvent.payload?.target ?? "/";
+      const reasons = [];
+      if (dirtyGuard && state.context.dirty) {
+        reasons.push("Unsaved changes will be lost");
+      }
+      if (authRequired && !state.context.authenticated) {
+        reasons.push("Authentication required");
+      }
+      if (reasons.length > 0) {
+        return RuleResult.emit([
+          fact("navigation.blocked", { target, reasons })
+        ]);
+      }
+      return RuleResult.emit([
+        fact("navigation.allowed", { target })
+      ]);
+    }
+  });
+  if (dirtyGuard) {
+    constraints.push({
+      id: "factory/navigation.dirty-guard",
+      description: "Prevents silent navigation when unsaved changes exist",
+      contract: {
+        ruleId: "factory/navigation.dirty-guard",
+        behavior: "Blocks navigation when dirty state is true",
+        examples: [
+          { given: "dirty is true", when: "navigation attempted", then: "violation" },
+          { given: "dirty is false", when: "navigation attempted", then: "passes" }
+        ],
+        invariants: ["Must never silently lose unsaved changes"]
+      },
+      impl: (state) => {
+        if (state.context.dirty && state.facts.some((f) => f.tag === "navigation.allowed")) {
+          return "Navigation allowed while dirty \u2014 unsaved changes may be lost";
+        }
+        return true;
+      }
+    });
+  }
+  return { rules, constraints };
+}
+function dataRules(config = {}) {
+  const {
+    optimisticUpdate = false,
+    rollbackOnError = false,
+    cacheInvalidation = false,
+    entityName = "data"
+  } = config;
+  const rules = [];
+  const constraints = [];
+  if (optimisticUpdate) {
+    rules.push({
+      id: `factory/${entityName}.optimistic-update`,
+      description: `Applies optimistic update for ${entityName} while request is pending`,
+      eventTypes: [`${entityName}.mutate`],
+      contract: {
+        ruleId: `factory/${entityName}.optimistic-update`,
+        behavior: `Immediately emits updated ${entityName} state before server confirmation`,
+        examples: [
+          { given: `${entityName} mutation requested`, when: "mutate event fires", then: "optimistic state emitted" }
+        ],
+        invariants: [
+          "Optimistic state must store original for rollback",
+          "Optimistic update must be distinguishable from confirmed state"
+        ]
+      },
+      impl: (_state, events) => {
+        const mutateEvent = events.find((e) => e.tag === `${entityName}.mutate`);
+        if (!mutateEvent) return RuleResult.skip("No mutation event");
+        const payload = mutateEvent.payload;
+        return RuleResult.emit([
+          fact(`${entityName}.optimistic`, {
+            id: payload.id,
+            data: payload.data,
+            pending: true,
+            timestamp: Date.now()
+          })
+        ]);
+      }
+    });
+  }
+  if (rollbackOnError) {
+    rules.push({
+      id: `factory/${entityName}.rollback`,
+      description: `Rolls back optimistic ${entityName} update on error`,
+      eventTypes: [`${entityName}.error`],
+      contract: {
+        ruleId: `factory/${entityName}.rollback`,
+        behavior: `Reverts to original ${entityName} state when mutation fails`,
+        examples: [
+          { given: "optimistic update was applied", when: "server returns error", then: "rollback emitted, optimistic retracted" }
+        ],
+        invariants: [
+          "Rollback must restore original state exactly",
+          "Optimistic facts must be retracted on rollback"
+        ]
+      },
+      impl: (_state, events) => {
+        const errorEvent = events.find((e) => e.tag === `${entityName}.error`);
+        if (!errorEvent) return RuleResult.skip("No error event");
+        const payload = errorEvent.payload;
+        const result = RuleResult.emit([
+          fact(`${entityName}.rollback`, {
+            id: payload.id,
+            error: payload.error,
+            timestamp: Date.now()
+          })
+        ]);
+        return result;
+      }
+    });
+  }
+  if (cacheInvalidation) {
+    rules.push({
+      id: `factory/${entityName}.cache-invalidate`,
+      description: `Invalidates ${entityName} cache when data changes are confirmed`,
+      eventTypes: [`${entityName}.confirmed`, `${entityName}.deleted`],
+      contract: {
+        ruleId: `factory/${entityName}.cache-invalidate`,
+        behavior: `Emits cache invalidation signal when ${entityName} is confirmed or deleted`,
+        examples: [
+          { given: `${entityName} mutation confirmed`, when: "confirmed event fires", then: "cache.invalidate emitted" }
+        ],
+        invariants: ["Stale cache entries must be invalidated after confirmed mutations"]
+      },
+      impl: (_state, events) => {
+        const confirmEvent = events.find(
+          (e) => e.tag === `${entityName}.confirmed` || e.tag === `${entityName}.deleted`
+        );
+        if (!confirmEvent) return RuleResult.skip("No confirmation event");
+        const payload = confirmEvent.payload;
+        return RuleResult.emit([
+          fact(`${entityName}.cache-invalidate`, {
+            id: payload.id,
+            timestamp: Date.now()
+          })
+        ]);
+      }
+    });
+  }
+  constraints.push({
+    id: `factory/${entityName}.integrity`,
+    description: `Ensures ${entityName} state integrity \u2014 no orphaned optimistic updates`,
+    contract: {
+      ruleId: `factory/${entityName}.integrity`,
+      behavior: "Detects orphaned optimistic updates without pending confirmation",
+      examples: [
+        { given: "optimistic update exists without pending request", when: "checked", then: "violation" }
+      ],
+      invariants: [`Every optimistic ${entityName} update must have a corresponding pending request`]
+    },
+    impl: (state) => {
+      const pending = state.context.pending ?? {};
+      const optimisticFacts = state.facts.filter((f) => f.tag === `${entityName}.optimistic`);
+      for (const optFact of optimisticFacts) {
+        const id = optFact.payload?.id;
+        if (id && !pending[id]) {
+          return `Orphaned optimistic update for ${entityName} id=${id} \u2014 no pending request`;
+        }
+      }
+      return true;
+    }
+  });
+  return { rules, constraints };
+}
+
+export {
+  inputRules,
+  toastRules,
+  formRules,
+  navigationRules,
+  dataRules
+};