@directive-run/knowledge 0.2.0 → 0.4.2

package/examples/contact-form.ts

@@ -1,12 +1,19 @@
 // Example: contact-form
-// Source: examples/contact-form/src/main.ts
-// Extracted for AI rules — DOM wiring stripped
+// Source: examples/contact-form/src/module.ts
+// Pure module file — no DOM wiring
 
 /**
- * Contact Form — DOM Rendering & System Wiring
+ * Contact Form — Directive Module
  *
- * Creates the Directive system, subscribes to state changes,
- * renders the form and event timeline.
+ * Multi-field contact form showcasing validation, constraints, and resolvers:
+ * - Facts: name, email, subject, message, touched, status, errorMessage, etc.
+ * - Derivations: field errors, isValid, canSubmit, messageCharCount
+ * - Events: updateField, touchField, submit, reset
+ * - Constraints: submitForm, resetAfterSuccess
+ * - Resolvers: simulated async send, auto-reset after delay
+ * - Effects: logging status transitions
+ *
+ * Uses a simulated setTimeout instead of a real API so no account is needed.
  */
 
 import {
@@ -25,23 +32,35 @@ const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 const RATE_LIMIT_MS = 10_000; // 10 seconds (shorter for demo)
 
 // ============================================================================
-// Timeline
+// Types
 // ============================================================================
 
-interface TimelineEntry {
+export interface TimelineEntry {
   time: number;
   event: string;
   detail: string;
   type: string;
 }
 
-const timeline: TimelineEntry[] = [];
+// ============================================================================
+// Timeline (external mutable array, same pattern as fraud-analysis)
+// ============================================================================
+
+export const timeline: TimelineEntry[] = [];
 
-function addTimelineEntry(event: string, detail: string, type: string) {
+export function addTimelineEntry(
+  event: string,
+  detail: string,
+  type: string,
+): void {
   timeline.unshift({ time: Date.now(), event, detail, type });
 }
 
-function log(msg: string) {
+// ============================================================================
+// Logs helper
+// ============================================================================
+
+export function log(msg: string): void {
   console.log(`[contact-form] ${msg}`);
 
   // Classify and add to timeline
@@ -66,7 +85,7 @@ function log(msg: string) {
 // Schema
 // ============================================================================
 
-const schema = {
+export const schema = {
   facts: {
     name: t.string(),
     email: t.string(),
@@ -103,74 +122,206 @@ const schema = {
 // Module
 // ============================================================================
 
+const contactForm = createModule("contact-form", {
+  schema,
 
-// ============================================================================
-// System
-// ============================================================================
+  init: (facts) => {
+    facts.name = "";
+    facts.email = "";
+    facts.subject = "";
+    facts.message = "";
+    facts.touched = {};
+    facts.status = "idle";
+    facts.errorMessage = "";
+    facts.lastSubmittedAt = 0;
+    facts.submissionCount = 0;
+  },
 
-const system = createSystem({
-  module: contactForm,
-  debug: { runHistory: true },
-  plugins: [devtoolsPlugin({ name: "contact-form" })],
-});
-system.start();
+  derive: {
+    nameError: (facts) => {
+      if (!facts.touched.name) {
+        return "";
+      }
+      if (!facts.name.trim()) {
+        return "Name is required";
+      }
+      if (facts.name.trim().length < 2) {
+        return "Name must be at least 2 characters";
+      }
 
-// ============================================================================
-// DOM References
-// ============================================================================
+      return "";
+    },
 
-// Form inputs
+    emailError: (facts) => {
+      if (!facts.touched.email) {
+        return "";
+      }
+      if (!facts.email.trim()) {
+        return "Email is required";
+      }
+      if (!EMAIL_REGEX.test(facts.email)) {
+        return "Enter a valid email address";
+      }
 
-// Timeline
+      return "";
+    },
 
-// ============================================================================
-// Input Handlers
-// ============================================================================
+    subjectError: (facts) => {
+      if (!facts.touched.subject) {
+        return "";
+      }
+      if (!facts.subject) {
+        return "Please select a subject";
+      }
 
-for (const [el, field] of [
-  [nameInput, "name"],
-  [emailInput, "email"],
-  [subjectInput, "subject"],
-  [messageInput, "message"],
-] as const) {
-}
+      return "";
+    },
 
+    messageError: (facts) => {
+      if (!facts.touched.message) {
+        return "";
+      }
+      if (!facts.message.trim()) {
+        return "Message is required";
+      }
+      if (facts.message.trim().length < 10) {
+        return "Message must be at least 10 characters";
+      }
 
-// ============================================================================
-// Render
-// ============================================================================
+      return "";
+    },
 
-function escapeHtml(text: string): string {
+    isValid: (facts) =>
+      facts.name.trim().length >= 2 &&
+      EMAIL_REGEX.test(facts.email) &&
+      facts.subject !== "" &&
+      facts.message.trim().length >= 10,
 
-  return div.innerHTML;
-}
+    canSubmit: (facts, derive) => {
+      if (!derive.isValid) {
+        return false;
+      }
+      if (facts.status !== "idle") {
+        return false;
+      }
+      if (
+        facts.lastSubmittedAt > 0 &&
+        Date.now() - facts.lastSubmittedAt < RATE_LIMIT_MS
+      ) {
+        return false;
+      }
+
+      return true;
+    },
 
+    messageCharCount: (facts) => facts.message.length,
+  },
+
+  events: {
+    updateField: (facts, { field, value }) => {
+      const key = field as "name" | "email" | "subject" | "message";
+      if (key in facts && typeof facts[key] === "string") {
+        (facts as unknown as Record<string, string>)[key] = value;
+      }
+    },
 
-// Subscribe to all relevant facts and derivations
-system.subscribe(
-  [
-    "name",
-    "email",
-    "subject",
-    "message",
-    "touched",
-    "status",
-    "errorMessage",
-    "lastSubmittedAt",
-    "submissionCount",
-    "nameError",
-    "emailError",
-    "subjectError",
-    "messageError",
-    "isValid",
-    "canSubmit",
-    "messageCharCount",
-  ],
-  render,
-);
-
-// Initial render
-render();
-log("Contact form ready. Fill in all fields and submit.");
-
-// Signal to tests that initialization is complete
+    touchField: (facts, { field }) => {
+      facts.touched = { ...facts.touched, [field]: true };
+    },
+
+    submit: (facts) => {
+      facts.touched = { name: true, email: true, subject: true, message: true };
+      facts.status = "submitting";
+    },
+
+    reset: (facts) => {
+      facts.name = "";
+      facts.email = "";
+      facts.subject = "";
+      facts.message = "";
+      facts.touched = {};
+      facts.status = "idle";
+      facts.errorMessage = "";
+    },
+  },
+
+  constraints: {
+    submitForm: {
+      when: (facts) => facts.status === "submitting",
+      require: { type: "SEND_MESSAGE" },
+    },
+
+    resetAfterSuccess: {
+      when: (facts) => facts.status === "success",
+      require: { type: "RESET_AFTER_DELAY" },
+    },
+  },
+
+  resolvers: {
+    sendMessage: {
+      requirement: "SEND_MESSAGE",
+      resolve: async (req, context) => {
+        log(
+          `Sending: ${context.facts.name} <${context.facts.email}> [${context.facts.subject}]`,
+        );
+
+        await new Promise((resolve) => setTimeout(resolve, 1500));
+
+        if (Math.random() < 0.2) {
+          context.facts.status = "error";
+          context.facts.errorMessage =
+            "Simulated error — try again (20% failure rate for demo).";
+          log("Submission failed (simulated)");
+
+          return;
+        }
+
+        context.facts.status = "success";
+        context.facts.lastSubmittedAt = Date.now();
+        context.facts.submissionCount++;
+        log(`Submission #${context.facts.submissionCount} succeeded`);
+      },
+    },
+
+    resetAfterDelay: {
+      requirement: "RESET_AFTER_DELAY",
+      resolve: async (req, context) => {
+        log("Auto-resetting in 3 seconds...");
+        await new Promise((resolve) => setTimeout(resolve, 3000));
+        context.facts.name = "";
+        context.facts.email = "";
+        context.facts.subject = "";
+        context.facts.message = "";
+        context.facts.touched = {};
+        context.facts.status = "idle";
+        context.facts.errorMessage = "";
+        log("Form reset");
+      },
+    },
+  },
+
+  effects: {
+    logSubmission: {
+      deps: ["status", "submissionCount"],
+      run: (facts, prev) => {
+        if (!prev) {
+          return;
+        }
+
+        if (facts.status !== prev.status) {
+          log(`Status: ${prev.status} → ${facts.status}`);
+        }
+      },
+    },
+  },
+});
+
+// ============================================================================
+// System
+// ============================================================================
+
+export const system = createSystem({
+  module: contactForm,
+  debug: { runHistory: true },
+  plugins: [devtoolsPlugin({ name: "contact-form" })],
+});

package/examples/counter.ts

@@ -1,12 +1,12 @@
 // Example: counter
-// Source: examples/counter/src/main.ts
-// Extracted for AI rules — DOM wiring stripped
+// Source: examples/counter/src/module.ts
+// Pure module file — no DOM wiring
 
 /**
- * Number Match — DOM Rendering & System Wiring
+ * Number Match — Directive Module
  *
- * Creates the Directive system, subscribes to state changes,
- * renders the game grid and event timeline.
+ * Types, schema, helpers, module definition, timeline, and system creation
+ * for a tile-matching game where pairs must add to 10.
  */
 
 import {
@@ -21,18 +21,22 @@ import { devtoolsPlugin } from "@directive-run/core/plugins";
 // Types
 // ============================================================================
 
-interface Tile {
+export interface Tile {
   id: string;
   value: number;
 }
 
-interface TimelineEntry {
+export interface TimelineEntry {
   time: number;
   event: string;
   detail: string;
   type: string;
 }
 
+// ============================================================================
+// Helpers
+// ============================================================================
+
 // Create a pool of numbered tiles (1-9, four of each = 36 tiles)
 function createPool(): Tile[] {
   const tiles: Tile[] = [];
@@ -55,9 +59,9 @@ function createPool(): Tile[] {
 // Timeline
 // ============================================================================
 
-const timeline: TimelineEntry[] = [];
+export const timeline: TimelineEntry[] = [];
 
-function log(msg: string) {
+export function addLog(msg: string) {
   console.log(`[NumberMatch] ${msg}`);
 
   // Classify and add significant events to the timeline
@@ -101,15 +105,15 @@ function log(msg: string) {
 }
 
 // ============================================================================
-// Schema - same structure as eleven-up
+// Schema
 // ============================================================================
 
-const schema = {
+export const schema = {
   facts: {
-    pool: t.object<Tile[]>(),
-    table: t.object<Tile[]>(),
-    removed: t.object<Tile[]>(),
-    selected: t.object<string[]>(),
+    pool: t.array<Tile>(),
+    table: t.array<Tile>(),
+    removed: t.array<Tile>(),
+    selected: t.array<string>(),
     message: t.string(),
     moveCount: t.number(),
     gameOver: t.boolean(),
@@ -117,7 +121,7 @@ const schema = {
   derivations: {
     poolCount: t.number(),
     removedCount: t.number(),
-    selectedTiles: t.object<Tile[]>(),
+    selectedTiles: t.array<Tile>(),
     hasValidMoves: t.boolean(),
   },
   events: {
@@ -127,7 +131,7 @@ const schema = {
     clearSelection: {},
   },
   requirements: {
-    REMOVE_TILES: { tileIds: t.object<string[]>() },
+    REMOVE_TILES: { tileIds: t.array<string>() },
     REFILL_TABLE: { count: t.number() },
     END_GAME: { reason: t.string() },
   },
@@ -160,9 +164,12 @@ const numberMatch = createModule("number-match", {
       const nums = facts.table.map((t: Tile) => t.value);
       for (let i = 0; i < nums.length; i++) {
         for (let j = i + 1; j < nums.length; j++) {
-          if (nums[i] + nums[j] === 10) return true;
+          if (nums[i] + nums[j] === 10) {
+            return true;
+          }
         }
       }
+
       return false;
     },
   },
@@ -181,7 +188,9 @@ const numberMatch = createModule("number-match", {
     selectTile: (facts, { tileId }) => {
       if (!facts.selected.includes(tileId) && !facts.gameOver) {
         facts.selected = [...facts.selected, tileId];
-        log(`EVENT selectTile: ${tileId}, selected now: [${facts.selected}]`);
+        addLog(
+          `EVENT selectTile: ${tileId}, selected now: [${facts.selected}]`,
+        );
       }
     },
     deselectTile: (facts, { tileId }) => {
@@ -193,27 +202,34 @@ const numberMatch = createModule("number-match", {
   },
 
   // ============================================================================
-  // Constraints - same pattern as eleven-up
+  // Constraints
   // ============================================================================
   constraints: {
     // When two selected tiles add to 10 -> remove them
     pairAddsTen: {
       priority: 100,
       when: (facts) => {
-        if (facts.gameOver) return false;
+        if (facts.gameOver) {
+          return false;
+        }
         const selected = facts.table.filter((tile: Tile) =>
           facts.selected.includes(tile.id),
         );
-        if (selected.length !== 2) return false;
+        if (selected.length !== 2) {
+          return false;
+        }
         const result = selected[0].value + selected[1].value === 10;
-        if (result)
-          log(
+        if (result) {
+          addLog(
             `CONSTRAINT pairAddsTen: TRUE (${selected[0].value} + ${selected[1].value})`,
           );
+        }
+
         return result;
       },
       require: (facts) => {
-        log("CONSTRAINT pairAddsTen: producing REMOVE_TILES");
+        addLog("CONSTRAINT pairAddsTen: producing REMOVE_TILES");
+
         return {
           type: "REMOVE_TILES",
           tileIds: [...facts.selected],
@@ -227,15 +243,18 @@ const numberMatch = createModule("number-match", {
       when: (facts) => {
         const result =
           !facts.gameOver && facts.table.length < 9 && facts.pool.length > 0;
-        if (result)
-          log(
+        if (result) {
+          addLog(
             `CONSTRAINT refillTable: TRUE (table: ${facts.table.length}, pool: ${facts.pool.length})`,
           );
+        }
+
         return result;
       },
       require: (facts) => {
         const count = Math.min(9 - facts.table.length, facts.pool.length);
-        log(`CONSTRAINT refillTable: producing REFILL_TABLE count=${count}`);
+        addLog(`CONSTRAINT refillTable: producing REFILL_TABLE count=${count}`);
+
         return { type: "REFILL_TABLE", count };
       },
     },
@@ -244,16 +263,25 @@ const numberMatch = createModule("number-match", {
     noMovesLeft: {
       priority: 190,
       when: (facts) => {
-        if (facts.gameOver) return false;
-        if (facts.table.length === 0) return false;
-        if (facts.pool.length > 0) return false;
+        if (facts.gameOver) {
+          return false;
+        }
+        if (facts.table.length === 0) {
+          return false;
+        }
+        if (facts.pool.length > 0) {
+          return false;
+        }
         const nums = facts.table.map((t: Tile) => t.value);
         for (let i = 0; i < nums.length; i++) {
           for (let j = i + 1; j < nums.length; j++) {
-            if (nums[i] + nums[j] === 10) return false;
+            if (nums[i] + nums[j] === 10) {
+              return false;
+            }
           }
         }
-        log("CONSTRAINT noMovesLeft: TRUE");
+        addLog("CONSTRAINT noMovesLeft: TRUE");
+
         return true;
       },
       require: (facts) => ({
@@ -270,7 +298,10 @@ const numberMatch = createModule("number-match", {
           !facts.gameOver &&
           facts.table.length === 0 &&
           facts.pool.length === 0;
-        if (result) log("CONSTRAINT allCleared: TRUE");
+        if (result) {
+          addLog("CONSTRAINT allCleared: TRUE");
+        }
+
         return result;
       },
       require: (facts) => ({
@@ -281,42 +312,42 @@ const numberMatch = createModule("number-match", {
   },
 
   // ============================================================================
-  // Resolvers - same multi-fact mutation pattern as eleven-up
+  // Resolvers
   // ============================================================================
   resolvers: {
     removeTiles: {
       requirement: "REMOVE_TILES",
       resolve: async (req, context) => {
-        log("RESOLVER removeTiles: START");
+        addLog("RESOLVER removeTiles: START");
         const tilesToRemove = context.facts.table.filter((tile: Tile) =>
           req.tileIds.includes(tile.id),
         );
 
         // Multiple fact mutations
-        log("RESOLVER removeTiles: setting table");
+        addLog("RESOLVER removeTiles: setting table");
         context.facts.table = context.facts.table.filter(
           (tile: Tile) => !req.tileIds.includes(tile.id),
         );
-        log("RESOLVER removeTiles: setting removed");
+        addLog("RESOLVER removeTiles: setting removed");
         context.facts.removed = [...context.facts.removed, ...tilesToRemove];
-        log("RESOLVER removeTiles: clearing selected");
+        addLog("RESOLVER removeTiles: clearing selected");
         context.facts.selected = [];
-        log("RESOLVER removeTiles: incrementing moveCount");
+        addLog("RESOLVER removeTiles: incrementing moveCount");
         context.facts.moveCount++;
-        log("RESOLVER removeTiles: setting message");
+        addLog("RESOLVER removeTiles: setting message");
         context.facts.message = `Removed ${tilesToRemove[0].value} + ${tilesToRemove[1].value} = 10!`;
-        log("RESOLVER removeTiles: DONE");
+        addLog("RESOLVER removeTiles: DONE");
       },
     },
 
     refillTable: {
       requirement: "REFILL_TABLE",
       resolve: async (req, context) => {
-        log(`RESOLVER refillTable: START (count: ${req.count})`);
+        addLog(`RESOLVER refillTable: START (count: ${req.count})`);
         const newTiles = context.facts.pool.slice(0, req.count);
         context.facts.pool = context.facts.pool.slice(req.count);
         context.facts.table = [...context.facts.table, ...newTiles];
-        log(
+        addLog(
           `RESOLVER refillTable: DONE (table now: ${context.facts.table.length})`,
         );
       },
@@ -325,7 +356,7 @@ const numberMatch = createModule("number-match", {
     endGame: {
       requirement: "END_GAME",
       resolve: async (req, context) => {
-        log(`RESOLVER endGame: ${req.reason}`);
+        addLog(`RESOLVER endGame: ${req.reason}`);
         context.facts.gameOver = true;
         context.facts.message = req.reason;
       },
@@ -337,57 +368,8 @@ const numberMatch = createModule("number-match", {
 // System
 // ============================================================================
 
-const system = createSystem({
+export const system = createSystem({
   module: numberMatch,
   plugins: [devtoolsPlugin({ name: "number-match" })],
   debug: { timeTravel: true, runHistory: true },
 });
-system.start();
-
-// ============================================================================
-// DOM References
-// ============================================================================
-
-// Stats
-
-// Timeline
-
-// ============================================================================
-// Render
-// ============================================================================
-
-function escapeHtml(text: string): string {
-
-  return div.innerHTML;
-}
-
-
-// ============================================================================
-// Subscribe
-// ============================================================================
-
-system.subscribe(
-  [
-    "table",
-    "selected",
-    "pool",
-    "removed",
-    "moveCount",
-    "message",
-    "gameOver",
-    "poolCount",
-    "removedCount",
-    "selectedTiles",
-    "hasValidMoves",
-  ],
-  render,
-);
-
-// Button handlers
-
-
-// Initial render
-render();
-log("Game started. Select two numbers that add to 10.");
-
-// Signal to tests that initialization is complete