@directive-run/claude-plugin 1.16.0

package/skills/reviewing-directive-code/anti-patterns.md

@@ -0,0 +1,382 @@
+# Anti-Patterns
+
+> Covers `@directive-run/core` and `@directive-run/react` — hallucination-prone API patterns to avoid.
+
+19 most common mistakes when generating Directive code, ranked by AI hallucination frequency. Every code generation MUST be checked against this list.
+
+## 1. Unnecessary Type Casting on Facts/Derivations
+
+```typescript
+// WRONG – schema already provides the type
+const profile = system.facts.profile as ResourceState<Profile>;
+
+// CORRECT – trust the schema
+const profile = system.facts.profile;
+```
+
+## 2. Flat Schema (Missing facts Wrapper)
+
+```typescript
+// WRONG – facts must be nested under schema.facts
+createModule("counter", {
+  schema: {
+    phase: t.string(),
+    count: t.number(),
+  },
+});
+
+// CORRECT
+createModule("counter", {
+  schema: {
+    facts: {
+      phase: t.string(),
+      count: t.number(),
+    },
+  },
+});
+```
+
+## 3. Bare `facts.*` in Multi-Module Constraints
+
+```typescript
+// WRONG – multi-module constraints use facts.self for own module
+constraints: {
+  checkItems: {
+    when: (facts) => facts.items.length > 0,
+    require: { type: "PROCESS" },
+  },
+},
+
+// CORRECT – use facts.self.* for own module facts
+constraints: {
+  checkItems: {
+    when: (facts) => facts.self.items.length > 0,
+    require: { type: "PROCESS" },
+  },
+},
+```
+
+## 4. Nonexistent Schema Builders
+
+```typescript
+// WRONG – t.map(), t.set(), t.promise() do not exist
+schema: {
+  facts: {
+    cache: t.map<string, User>(),
+    tags: t.set<string>(),
+    pending: t.promise<Data>(),
+  },
+},
+
+// CORRECT – use t.object() with type parameter
+schema: {
+  facts: {
+    cache: t.object<Map<string, User>>(),
+    tags: t.object<Set<string>>(),
+    pending: t.object<Promise<Data>>(),
+  },
+},
+```
+
+## 5. Abbreviating `context` to `ctx`
+
+```typescript
+// WRONG – never abbreviate context
+resolve: async (req, ctx) => {
+  ctx.facts.status = "done";
+},
+
+// CORRECT – always spell out context
+resolve: async (req, context) => {
+  context.facts.status = "done";
+},
+```
+
+## 6. Flat Module Config (No schema Wrapper)
+
+```typescript
+// WRONG – properties must be inside schema.facts
+createModule("timer", {
+  phase: t.string(),
+  elapsed: t.number(),
+});
+
+// CORRECT – wrap in schema: { facts: {} }
+createModule("timer", {
+  schema: {
+    facts: {
+      phase: t.string(),
+      elapsed: t.number(),
+    },
+  },
+});
+```
+
+## 7. String-Based Event Dispatch
+
+```typescript
+// WRONG – there is no two-argument string-keyed dispatch signature
+system.dispatch("login", { token: "abc" });
+
+// CORRECT – use the typed events accessor (preferred — autocomplete + payload typing)
+system.events.login({ token: "abc" });
+
+// ALSO VALID – the single-arg object form of dispatch() is supported when you
+// need to forward a programmatically-built event. Prefer the events accessor
+// for normal code.
+system.dispatch({ type: "login", token: "abc" });
+```
+
+## 8. Direct Array/Object Mutation
+
+```typescript
+// WRONG – proxy cannot detect in-place mutations
+facts.items.push(item);
+facts.config.theme = "dark";
+
+// CORRECT – replace the entire value
+facts.items = [...facts.items, item];
+facts.config = { ...facts.config, theme: "dark" };
+```
+
+## 9. Nonexistent `useDirective` Hook
+
+```typescript
+// WRONG – there is no useDirective hook
+const state = useDirective(system);
+
+// CORRECT – use useSelector with a selector function
+const count = useSelector(system, (s) => s.facts.count);
+const isLoading = useSelector(system, (s) => s.derive.isLoading);
+```
+
+## 10. Bracket Notation for Namespaced Facts
+
+```typescript
+// WRONG – internal separator is not part of the public API
+const status = facts["auth::status"];
+const token = facts["auth_token"];
+
+// CORRECT – use dot notation through the namespace proxy
+const status = facts.auth.status;
+const token = facts.auth.token;
+```
+
+## 11. Returning Data from Resolvers
+
+```typescript
+// WRONG – resolvers return void, not data
+resolve: async (req, context) => {
+  const user = await fetchUser(req.userId);
+
+  return user; // Return value is ignored
+},
+
+// CORRECT – mutate context.facts to store results
+resolve: async (req, context) => {
+  const user = await fetchUser(req.userId);
+  context.facts.user = user;
+},
+```
+
+## 12. Async Logic in `init`
+
+```typescript
+// WRONG – init is synchronous, facts assignment only
+init: async (facts) => {
+  const data = await fetch("/api/config");
+  facts.config = await data.json();
+},
+
+// CORRECT – init sets defaults; use constraints/resolvers for async work
+init: (facts) => {
+  facts.config = null;
+  facts.phase = "loading";
+},
+
+constraints: {
+  loadConfig: {
+    when: (facts) => facts.config === null,
+    require: { type: "LOAD_CONFIG" },
+  },
+},
+```
+
+## 13. Missing `settle()` After `start()`
+
+```typescript
+// WRONG – constraints fire on start, resolvers are async
+system.start();
+console.log(system.facts.data); // May still be null
+
+// CORRECT – wait for resolvers to complete
+system.start();
+await system.settle();
+console.log(system.facts.data); // Resolved
+```
+
+## 14. Missing `crossModuleDeps` Declaration
+
+```typescript
+// WRONG – accessing auth facts without declaring dependency
+const dataModule = createModule("data", {
+  schema: { facts: { items: t.array(t.string()) } },
+  constraints: {
+    fetchWhenAuth: {
+      when: (facts) => facts.auth.isAuthenticated, // Type error
+      require: { type: "FETCH" },
+    },
+  },
+});
+
+// CORRECT – declare crossModuleDeps for type-safe cross-module access
+const dataModule = createModule("data", {
+  schema: { facts: { items: t.array(t.string()) } },
+  crossModuleDeps: { auth: authSchema },
+  constraints: {
+    fetchWhenAuth: {
+      when: (facts) => facts.auth.isAuthenticated,
+      require: { type: "FETCH" },
+    },
+  },
+});
+```
+
+## 15. String Literal for `require`
+
+```typescript
+// WRONG – require must be an object with type property
+constraints: {
+  check: {
+    when: (facts) => facts.ready,
+    require: "FETCH_DATA",
+  },
+},
+
+// CORRECT – use object form with type
+constraints: {
+  check: {
+    when: (facts) => facts.ready,
+    require: { type: "FETCH_DATA" },
+  },
+},
+```
+
+## 16. Passthrough Derivations
+
+```typescript
+// WRONG – derivation just returns a fact value unchanged
+derive: {
+  count: (facts) => facts.count,
+},
+
+// CORRECT – remove it, read the fact directly instead
+// system.facts.count instead of system.derive.count
+```
+
+## 17. Deep Import Paths
+
+```typescript
+// WRONG – internal module paths are not public API
+import { createModule } from "@directive-run/core/module";
+import { createSystem } from "@directive-run/core/system";
+
+// CORRECT – import from package root
+import { createModule, createSystem } from "@directive-run/core";
+
+// Exception: plugins have their own entry point
+import { loggingPlugin } from "@directive-run/core/plugins";
+```
+
+## 18. Async `when()` Without `deps`
+
+```typescript
+// WRONG – async constraints need explicit deps for tracking
+constraints: {
+  validate: {
+    async: true,
+    when: async (facts) => {
+      const valid = await checkRemote(facts.token);
+
+      return valid;
+    },
+    require: { type: "REFRESH_TOKEN" },
+  },
+},
+
+// CORRECT – add deps array for async constraints
+constraints: {
+  validate: {
+    async: true,
+    deps: ["token"],
+    when: async (facts) => {
+      const valid = await checkRemote(facts.token);
+
+      return valid;
+    },
+    require: { type: "REFRESH_TOKEN" },
+  },
+},
+```
+
+## 19. No Error Handling on Failing Resolvers
+
+```typescript
+// WRONG – unhandled errors crash the system
+resolvers: {
+  fetchData: {
+    requirement: "FETCH",
+    resolve: async (req, context) => {
+      const res = await fetch("/api/data");
+      context.facts.data = await res.json();
+    },
+  },
+},
+
+// CORRECT – use retry policy and/or module error boundary
+resolvers: {
+  fetchData: {
+    requirement: "FETCH",
+    retry: { attempts: 3, backoff: "exponential" },
+    resolve: async (req, context) => {
+      const res = await fetch("/api/data");
+      if (!res.ok) {
+        throw new Error(`HTTP ${res.status}`);
+      }
+      context.facts.data = await res.json();
+    },
+  },
+},
+
+// Also set error boundary at system level
+const system = createSystem({
+  module: myModule,
+  errorBoundary: {
+    onResolverError: "retry-later",
+  },
+});
+```
+
+## Quick Reference Checklist
+
+Before generating any Directive code, verify:
+
+1. Schema is nested: `schema: { facts: { ... } }` (not flat)
+2. No `as` casts when reading facts or derivations
+3. Resolver params are `(req, context)` not `(req, ctx)`
+4. `require` is an object `{ type: "..." }` not a string
+5. `init()` is synchronous
+6. Resolvers return void and mutate `context.facts`
+7. Arrays/objects replaced, not mutated in place
+8. Multi-module uses `facts.self.*` for own facts
+9. Imports from `@directive-run/core`, not deep paths
+10. `await system.settle()` after `system.start()`
+
+## See also
+
+- [`naming.md`](./naming.md) — the strict canonical-term rules AND the alias map for cross-paradigm searches
+- [`constraints.md`](./constraints.md) — the constraint shape these anti-patterns reference (`facts` not in scope inside static `require:`, etc.)
+- [`resolvers.md`](./resolvers.md) — the resolver shape these anti-patterns reference (return `void`, mutate `context.facts`, `(req, context)` not `(req, ctx)`)
+- [`schema-types.md`](./schema-types.md) — the `t.*()` builders that exist and the hallucinated ones (`t.map`, `t.set`, `t.promise`, `t.date`) that don't
+- [`react-adapter.md`](./react-adapter.md) — the React hooks that exist and the hallucinated ones (`useEvent`, `useSystem`, `DirectiveProvider`) that don't
+- [`error-boundaries.md`](./error-boundaries.md) — error-handling shapes AI assistants sometimes invent

package/skills/reviewing-directive-code/api-skeleton.md

@@ -0,0 +1,5 @@
+# API Skeleton
+
+> Auto-generated. Do not edit.
+
+> Source JSON not found. Build website docs first.

package/skills/reviewing-directive-code/core-patterns.md

@@ -0,0 +1,240 @@
+# Core Patterns
+
+> Covers `@directive-run/core` — modules, facts, derivations, effects, events, and the constraint-resolver loop.
+
+How to think about building with Directive: modules, systems, and the constraint-resolver pattern.
+
+## Decision Tree: "Where does this logic go?"
+
+```
+User wants to...
+├── Store state → schema.facts + init()
+├── Compute derived values → schema.derivations + derive
+├── React to state changes → effects
+├── Trigger side effects when conditions are met → constraints + resolvers
+├── Handle user actions → schema.events + events handlers
+└── Coordinate multiple modules → createSystem({ modules: {} })
+```
+
+## Module Shape (Canonical Object Syntax)
+
+```typescript
+// CORRECT – full module definition
+import { createModule, t } from "@directive-run/core";
+
+const myModule = createModule("name", {
+  schema: {
+    facts: {
+      count: t.number(),
+      phase: t.string<"idle" | "loading" | "done">(),
+      user: t.object<{ id: string; name: string } | null>(),
+    },
+    derivations: {
+      isLoading: t.boolean(),
+      displayName: t.string(),
+    },
+    events: {
+      increment: {},
+      setUser: { user: t.object<{ id: string; name: string }>() },
+    },
+    requirements: {
+      FETCH_USER: { userId: t.string() },
+    },
+  },
+
+  init: (facts) => {
+    facts.count = 0;
+    facts.phase = "idle";
+    facts.user = null;
+  },
+
+  derive: {
+    isLoading: (facts) => facts.phase === "loading",
+    displayName: (facts) => {
+      if (!facts.user) {
+        return "Guest";
+      }
+
+      return facts.user.name;
+    },
+  },
+
+  effects: {
+    logPhase: {
+      run: (facts, prev) => {
+        if (prev?.phase !== facts.phase) {
+          console.log(`Phase: ${facts.phase}`);
+        }
+      },
+    },
+  },
+
+  constraints: {
+    fetchWhenReady: {
+      when: (facts) => facts.phase === "idle" && facts.count > 0,
+      require: (facts) => ({ type: "FETCH_USER", userId: "user-1" }),
+    },
+  },
+
+  resolvers: {
+    fetchUser: {
+      requirement: "FETCH_USER",
+      resolve: async (req, context) => {
+        context.facts.phase = "loading";
+        const res = await fetch(`/api/users/${req.userId}`);
+        const data = await res.json();
+        context.facts.user = data;
+        context.facts.phase = "done";
+      },
+    },
+  },
+
+  events: {
+    increment: (facts) => {
+      facts.count += 1;
+    },
+    setUser: (facts, payload) => {
+      facts.user = payload.user;
+    },
+  },
+});
+```
+
+## System Creation
+
+```typescript
+import { createSystem } from "@directive-run/core";
+import { loggingPlugin, devtoolsPlugin } from "@directive-run/core/plugins";
+
+// Single module – direct access: system.facts.count
+const system = createSystem({
+  module: myModule,
+  plugins: [loggingPlugin(), devtoolsPlugin()],
+  history: { maxSnapshots: 100 },
+});
+
+// Multi-module – namespaced access: system.facts.auth.token
+const system = createSystem({
+  modules: { auth: authModule, cart: cartModule },
+  plugins: [devtoolsPlugin()],
+});
+
+// Lifecycle
+system.start();
+await system.settle(); // Wait for all resolvers to complete
+// ... use the system ...
+system.stop();
+system.destroy();
+```
+
+## Decision Tree: "User says 'fetch data when authenticated'"
+
+WRONG thinking: "I'll put the fetch call in a resolver that checks auth."
+
+```typescript
+// WRONG – resolver doing condition checking + data fetching
+resolvers: {
+  fetchData: {
+    requirement: "FETCH_DATA",
+    resolve: async (req, context) => {
+      if (!context.facts.isAuthenticated) {
+        return; // Resolver should not check conditions
+      }
+      const data = await fetch("/api/data");
+      context.facts.data = await data.json();
+    },
+  },
+},
+```
+
+CORRECT thinking: "Constraint declares WHEN, resolver declares HOW."
+
+```typescript
+// CORRECT – constraint declares the need, resolver fulfills it
+constraints: {
+  fetchWhenAuthenticated: {
+    when: (facts) => facts.isAuthenticated && !facts.data,
+    require: { type: "FETCH_DATA" },
+  },
+},
+
+resolvers: {
+  fetchData: {
+    requirement: "FETCH_DATA",
+    resolve: async (req, context) => {
+      const data = await fetch("/api/data");
+      context.facts.data = await data.json();
+    },
+  },
+},
+```
+
+## Reading System State
+
+```typescript
+// Facts – mutable state
+system.facts.count = 5;
+const val = system.facts.count;
+
+// Derivations – read-only computed values
+const loading = system.derive.isLoading;
+
+// Events – dispatch user actions
+system.events.increment();
+system.events.setUser({ user: { id: "1", name: "Alice" } });
+
+// Subscribe to changes
+const unsub = system.subscribe(["count", "isLoading"], () => {
+  console.log(system.facts.count, system.derive.isLoading);
+});
+
+// Watch individual values
+system.watch("count", (newVal, oldVal) => {
+  console.log(`Count: ${oldVal} -> ${newVal}`);
+});
+
+// Wait for a condition
+await system.when((facts) => facts.phase === "done");
+await system.when((facts) => facts.phase === "done", { timeout: 5000 });
+```
+
+## Schema Patterns
+
+Only `facts` is required in the schema. Other sections are optional:
+
+```typescript
+// Minimal module – facts only
+const minimal = createModule("minimal", {
+  schema: {
+    facts: { count: t.number() },
+  },
+  init: (facts) => {
+    facts.count = 0;
+  },
+});
+
+// Type assertion pattern (alternative to t.* builders)
+const typed = createModule("typed", {
+  schema: {
+    facts: {} as { count: number; name: string },
+    derivations: {} as { doubled: number },
+  },
+  init: (facts) => {
+    facts.count = 0;
+    facts.name = "";
+  },
+  derive: {
+    doubled: (facts) => facts.count * 2,
+  },
+});
+```
+
+## See also
+
+- [`constraints.md`](./constraints.md) — the demand side of the constraint-resolver loop
+- [`resolvers.md`](./resolvers.md) — the supply side that fulfills requirements
+- [`schema-types.md`](./schema-types.md) — the `t.*()` builders that define fact and derivation types
+- [`multi-module.md`](./multi-module.md) — when a single module isn't enough
+- [`system-api.md`](./system-api.md) — `createSystem` and the runtime instance once your module is defined
+- [`naming.md`](./naming.md) — terminology conventions every example here follows
+- [`testing.md`](./testing.md) — `createTestSystem` for the modules you're learning to write