opencode-effect-enforcer 0.2.2 → 0.2.4

package/skills/effect-react-vm/SKILL.md

@@ -1,675 +0,0 @@
----
-name: effect-react-vm
-description: Implement the VM pattern using Effect and Effect-Atom for reactive, testable frontend state management. Use this skill when building React applications with View Models that bridge domain services and UI.
----
-
-# Effectful View Model Architecture Guide
-
-## Effect Source Reference
-
-The Effect v4 source is available at `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/`.
-Browse and read files there directly to look up APIs, types, and implementations.
-
-Reference this for:
-
-- Atom reactivity: `packages/effect/src/unstable/reactivity/`
-- Context source: `packages/effect/src/Context.ts`
-- Layer source: `packages/effect/src/Layer.ts`
-- Effect source: `packages/effect/src/`
-
-## The Golden Rule: Zero UI Logic
-
-**VMs take domain input → VMs produce UI-ready output → Components are pure renderers**
-
-VM transforms domain to UI-ready:
-
-- `User` entity → `displayName: "John D."`
-- `timestamp: 1702425600` → `formattedDate: "Dec 13, 2024"`
-- `balance: 1000000n` → `displayBalance: "$1,000,000"`
-- `isActive && hasAccess` → `canEdit: true`
-- `error.code` → `errorMessage: "Network failed"`
-
-**Components must NEVER:** format strings/dates/numbers, compute derived values, contain business logic, transform entities
-
-**Components ONLY:** subscribe via `useAtomValue`, invoke via `useAtomSet`, pattern match with `$match`, render UI-ready values
-
-**Error handling:** Components CAN pattern match on error states (to render different UI per error type), but MUST render `error.message` as-is—VM is responsible for producing user-friendly messages
-
----
-
-## File Structure
-
-Every **parent component** needs a VM:
-
-```
-components/
-  Wallet/
-    Wallet.tsx       # Component - pure renderer
-    Wallet.vm.ts     # VM - interface, tag, default layer export
-    index.ts         # Re-exports
-```
-
-Child components used for UI composition receive VM as props—only parent components define their own VM.
-
----
-
-## VMs vs Regular Layers
-
-**VMs are strictly UI constructs.** A VM only exists if a component for that exact VM exists.
-
-| Pattern           | When to Use                         | Location                                   |
-| ----------------- | ----------------------------------- | ------------------------------------------ |
-| **VM**            | Layer serves a React component      | `components/X/X.vm.ts` paired with `X.tsx` |
-| **Service Layer** | Non-UI logic, shared business rules | `services/`, `lib/`, etc.                  |
-
-```typescript
-// ❌ WRONG - No component uses this, not a VM
-// components/Analytics/Analytics.vm.ts  (but no Analytics.tsx!)
-
-// ✅ CORRECT - Just a service layer
-// services/Analytics.ts
-export class AnalyticsService extends Context.Service<
-	AnalyticsService,
-	{ track: (event: string) => Effect.Effect<void> }
->()('AnalyticsService') {}
-```
-
-**When VMs share logic**: Use standard Effect layer composition. Shared logic lives in service layers, VMs compose over them:
-
-```typescript
-import { Context, Effect, Layer } from 'effect';
-import { AtomRegistry } from 'effect/unstable/reactivity';
-interface Consent {
-	id: string;
-}
-declare var ConsentListVM: Context.Service<ConsentListVM, ConsentListVM>;
-interface ConsentListVM {}
-
-// services/ConsentService.ts - shared business logic
-export class ConsentService extends Context.Service<
-	ConsentService,
-	{ getConsents: Effect.Effect<Consent[]> }
->()('ConsentService') {}
-
-// components/ConsentList/ConsentList.vm.ts - UI-specific, uses service
-const layer = Layer.effect(
-	ConsentListVM,
-	Effect.gen(function* () {
-		const consentService = yield* ConsentService; // Compose over service
-		const registry = yield* AtomRegistry.AtomRegistry;
-		// ... VM-specific UI state
-	})
-);
-```
-
----
-
-## Architecture Flow
-
-- Component calls `useVM(tag, layer)` → VMRuntime lazily builds VM via `Layer.buildWithMemoMap` → VM yields services from infrastructure layers
-- VMRuntime provides render-stable scope for all VMs
-- User action → VM action (updates atom via registry) → atom notifies → `useAtomValue` re-renders
-
----
-
-## VM File Pattern
-
-Each VM file contains: interface, tag, and default `{ tag, layer }` export.
-
-```typescript
-// components/Wallet/Wallet.vm.ts
-import * as Atom from 'effect/unstable/reactivity/Atom';
-import { AtomRegistry } from 'effect/unstable/reactivity';
-import { Context, Layer, Effect, pipe, Data } from 'effect';
-
-// State machine
-export type WalletState = Data.TaggedEnum<{
-	Disconnected: {};
-	Connecting: {};
-	Connected: { displayAddress: string; fullAddress: string };
-}>;
-export const WalletState = Data.taggedEnum<WalletState>();
-
-// 1. Interface - atoms use camelCase with $ suffix
-export interface WalletVM {
-	readonly state$: Atom.Atom<WalletState>;
-	readonly isConnected$: Atom.Atom<boolean>; // Derived, UI-ready
-	readonly connect: () => void; // Actions return void
-	readonly disconnect: () => void;
-}
-
-// 2. Tag
-export const WalletVM = Context.Service<WalletVM>('WalletVM');
-
-// 3. Layer - atoms ONLY defined inside the layer
-// VMRuntime provides scope, so Layer.effect is the default
-const layer = Layer.effect(
-	WalletVM,
-	Effect.gen(function* () {
-		const registry = yield* AtomRegistry.AtomRegistry;
-		const walletService = yield* WalletService;
-
-		// Atoms defined here, inside the layer
-		const state$ = Atom.make<WalletState>(WalletState.Disconnected());
-		const isConnected$ = pipe(
-			state$,
-			Atom.map(WalletState.$is('Connected'))
-		);
-
-		const connect = () => {
-			registry.set(state$, WalletState.Connecting());
-			Effect.runPromise(
-				walletService.connect.pipe(
-					Effect.match({
-						onFailure: () =>
-							registry.set(state$, WalletState.Disconnected()),
-						onSuccess: (addr) =>
-							registry.set(
-								state$,
-								WalletState.Connected({
-									displayAddress: `${addr.slice(0, 6)}...${addr.slice(-4)}`,
-									fullAddress: addr
-								})
-							)
-					})
-				)
-			);
-		};
-
-		const disconnect = () => {
-			registry.set(state$, WalletState.Disconnected());
-		};
-
-		return { state$, isConnected$, connect, disconnect };
-	})
-);
-
-// 4. Default export
-export default { tag: WalletVM, layer };
-```
-
----
-
-## Component Pattern
-
-```tsx
-// components/Wallet/Wallet.tsx
-'use client';
-import { useVM } from '@/lib/VMRuntime';
-import { useAtomValue } from '@effect/atom-react';
-import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
-import WalletVM, {
-	WalletState,
-	type WalletVM as WalletVMType
-} from './Wallet.vm';
-
-// Child components receive VM as prop - no own VM needed
-function WalletStatus({ vm }: { vm: WalletVMType }) {
-	const state = useAtomValue(vm.state$);
-
-	return WalletState.$match(state, {
-		Disconnected: () => <span>Not connected</span>,
-		Connecting: () => <Spinner />,
-		Connected: ({ displayAddress }) => <span>{displayAddress}</span>
-	});
-}
-
-function WalletActions({ vm }: { vm: WalletVMType }) {
-	const isConnected = useAtomValue(vm.isConnected$);
-
-	return isConnected ? (
-		<button onClick={vm.disconnect}>Disconnect</button>
-	) : (
-		<button onClick={vm.connect}>Connect</button>
-	);
-}
-
-// Parent component owns VM
-export default function Wallet() {
-	const vmResult = useVM(WalletVM.tag, WalletVM.layer);
-
-	return AsyncResult.match(vmResult, {
-		onInitial: () => <Spinner />,
-		onSuccess: ({ value: vm }) => (
-			<div className="wallet">
-				<WalletStatus vm={vm} />
-				<WalletActions vm={vm} />
-			</div>
-		),
-		onFailure: ({ cause }) => <Alert>{String(cause)}</Alert>
-	});
-}
-```
-
----
-
-## Core Pattern: Atom.fn for Async Actions
-
-**Key insight**: Use `Atom.fn` with `Effect.fnUntraced` for effect-based actions. This gives you:
-
-1. Automatic `waiting` flag for loading state
-2. `AsyncResult<Success, Error>` with `Initial`, `Success`, and `Failure` variants plus a top-level `waiting` overlay
-3. No manual state management or void wrappers
-
-```tsx
-import * as Atom from 'effect/unstable/reactivity/Atom';
-import { useAtomValue, useAtomSet } from '@effect/atom-react';
-import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
-import { Effect, Exit } from 'effect';
-
-// Define action with Atom.fn + Effect.fnUntraced
-const refreshAtom = Atom.fn(
-	Effect.fnUntraced(function* () {
-		const consents = yield* consentService.getOwnConsents;
-		return consents;
-	})
-);
-
-// In component - useAtom for result and trigger
-function ConsentList() {
-	const [result, refresh] = useAtom(refreshAtom);
-
-	// result.waiting is true while the effect runs
-	const isLoading = result.waiting;
-
-	return (
-		<div>
-			<button onClick={() => refresh()} disabled={isLoading}>
-				{isLoading ? 'Loading...' : 'Refresh'}
-			</button>
-			{AsyncResult.matchWithWaiting(result, {
-				onWaiting: () => <Loading />,
-				onSuccess: ({ value }) => <List items={value} />,
-				onError: (error) => <Error message={String(error)} />,
-				onDefect: (defect) => <Error message={String(defect)} />
-			})}
-		</div>
-	);
-}
-```
-
-**With services using Atom.runtime:**
-
-```tsx
-class ConsentService extends Context.Service<ConsentService>()(
-	'ConsentService',
-	{
-		make: Effect.gen(function* () {
-			const getAll = Effect.succeed([{ id: '1', name: 'Terms' }]);
-			return { getAll } as const;
-		})
-	}
-) {}
-
-const runtimeAtom = Atom.runtime(ConsentService.layer);
-
-const refreshAtom = runtimeAtom.fn(
-	Effect.fnUntraced(function* () {
-		const service = yield* ConsentService;
-		return yield* service.getAll;
-	})
-);
-```
-
-**With promiseExit for async handlers:**
-
-```tsx
-function CreateUser() {
-	// mode: "promiseExit" returns Promise<Exit<...>> for await
-	const createUser = useAtomSet(createUserAtom, { mode: 'promiseExit' });
-
-	return (
-		<button
-			onClick={async () => {
-				const exit = await createUser('John');
-				if (Exit.isSuccess(exit)) {
-					// exit.value contains the created user
-				}
-			}}
-		>
-			Create
-		</button>
-	);
-}
-```
-
-**Anti-pattern: Manual void wrappers**
-
-```typescript
-// ❌ DON'T - manual state management loses waiting control
-const loading$ = Atom.make(false);
-const data$ = Atom.make<Data | null>(null);
-
-const refresh = (): void => {
-	registry.set(loading$, true);
-	Effect.runPromise(fetchData).then((data) => {
-		registry.set(data$, data);
-		registry.set(loading$, false);
-	});
-};
-
-// ✅ DO - Atom.fn handles everything
-const refreshAtom = Atom.fn(
-	Effect.fnUntraced(function* () {
-		return yield* fetchData;
-	})
-);
-// result.waiting, AsyncResult.matchWithWaiting - all built-in
-```
-
----
-
-## Building Blocks
-
-### Atoms & Registry
-
-Atoms are ONLY defined inside VM layers:
-
-```typescript
-// Inside Layer.effect
-const registry = yield* AtomRegistry.AtomRegistry;
-
-// Writable atom - camelCase with $ suffix
-const count$ = Atom.make(0);
-
-// Derived atom (read-only)
-const doubled$ = pipe(
-	count$,
-	Atom.map((n) => n * 2)
-);
-
-// Read/write via registry
-registry.get(count$); // read
-registry.set(count$, 42); // write
-```
-
-For UI-ready object values rebuilt from multiple atoms, use `Atom.withEquality` when semantic equality should suppress a React notification. The comparator must compare the complete rendered meaning of the value; omitting a rendered field can leave the UI stale.
-
-```typescript
-declare const HeaderViewEquivalence: (left: HeaderView, right: HeaderView) => boolean;
-
-const header$ = Atom.make((get) => {
-	const state = get(state$);
-	return toHeaderView(state);
-}).pipe(Atom.withEquality(HeaderViewEquivalence));
-```
-
-### Data.TaggedEnum - State Machines
-
-```tsx
-export type WalletState = Data.TaggedEnum<{
-	Disconnected: {};
-	Connecting: {};
-	Connected: { displayAddress: string; fullAddress: string };
-}>;
-export const WalletState = Data.taggedEnum<WalletState>();
-
-// Pattern match in UI
-WalletState.$match(state, {
-	Disconnected: () => <ConnectButton />,
-	Connecting: () => <Spinner />,
-	Connected: ({ displayAddress }) => <span>{displayAddress}</span>
-});
-```
-
-### VMs with Lists (Atom.family)
-
-```typescript
-const makeConsentItemVM = Atom.family((consent: Consent): ConsentItemVM => {
-	const status$ = pipe(
-		consentsState$,
-		Atom.map((either) =>
-			Either.match(either, {
-				onLeft: () => ConsentStatus.Active(),
-				onRight: (consents) => {
-					const c = consents.find(
-						(x) => x.consentId === consent.consentId
-					);
-					return c?.isRevoked
-						? ConsentStatus.Revoked()
-						: ConsentStatus.Active();
-				}
-			})
-		)
-	);
-
-	// Close over consent.consentId - UI never sees it
-	const revoke = () => {
-		Effect.gen(function* () {
-			yield* consentService.revokeById(consent.consentId);
-			yield* refresh();
-		}).pipe(Effect.runFork);
-	};
-
-	return { key: consent.consentId, status$, revoke };
-});
-```
-
-### Event Listeners → Atom with Finalizer
-
-Instead of `useEffect` for event listeners, use `Atom.make` with `get.addFinalizer`:
-
-```typescript
-// Window scroll position - auto-cleanup when atom is no longer used
-const scrollY$ = Atom.make((get) => {
-	const onScroll = () => get.setSelf(window.scrollY);
-	window.addEventListener('scroll', onScroll);
-	get.addFinalizer(() => window.removeEventListener('scroll', onScroll));
-	return window.scrollY;
-});
-
-// Resize observer
-const windowSize$ = Atom.make((get) => {
-	const update = () =>
-		get.setSelf({ width: window.innerWidth, height: window.innerHeight });
-	window.addEventListener('resize', update);
-	get.addFinalizer(() => window.removeEventListener('resize', update));
-	return { width: window.innerWidth, height: window.innerHeight };
-});
-```
-
-### URL Search Params → Atom.searchParam
-
-Instead of `useEffect` + `useSearchParams`, use `Atom.searchParam`:
-
-```typescript
-// Simple string param
-const filter$ = Atom.searchParam('filter'); // Atom.Writable<string>
-
-// With schema parsing
-const page$ = Atom.searchParam('page', {
-	schema: Schema.NumberFromString
-}); // Atom.Writable<Option<number>>
-
-// Multiple params for a search form
-const search$ = Atom.searchParam('q');
-const sort$ = Atom.searchParam('sort');
-const limit$ = Atom.searchParam('limit', { schema: Schema.NumberFromString });
-```
-
----
-
-## VMRuntime Hook
-
-```typescript
-// lib/VMRuntime.ts
-const memoMap = Layer.makeMemoMap.pipe(Effect.runSync);
-
-const vmAtom = Atom.family(<Id, Value, E>(key: VmKey<Id, Value, E>) =>
-	Atom.make(
-		Effect.gen(function* () {
-			const scope = yield* Scope.Scope;
-			const ctx = yield* Layer.buildWithMemoMap(
-				key.layer,
-				memoMap,
-				scope
-			);
-			return Context.get(ctx, key.tag);
-		})
-	)
-);
-
-export const useVM = <Id, Value, E>(
-	tag: Context.Service<Id, Value>,
-	layer: Layer.Layer<Id, E, Scope.Scope | AtomRegistry.AtomRegistry>
-): AsyncResult.AsyncResult<Value, E> =>
-	useAtomValue(vmAtom(makeVmKey(tag, layer)));
-```
-
----
-
-## React Integration
-
-### Provider Setup
-
-```tsx
-// app/providers.tsx
-import { RegistryProvider } from '@effect/atom-react';
-
-export function Providers({ children }: { children: React.ReactNode }) {
-	return <RegistryProvider>{children}</RegistryProvider>;
-}
-```
-
-### Hooks Reference
-
-| Hook                                           | Purpose                                                            |
-| ---------------------------------------------- | ------------------------------------------------------------------ |
-| `useAtomValue(atom$)`                          | Subscribe to value                                                 |
-| `useAtomSet(atom$)`                            | Get setter function and mount writable atom                        |
-| `useAtom(atom$)`                               | Get `[value, setter]`                                              |
-| `useAtomMount(atom$)`                          | Mount side-effect atoms without reading                            |
-| `useAtomRefresh(atom$)`                        | Mount and get a refresh callback                                   |
-| `useAtomSuspense(asyncResultAtom$, options?)`  | Read `AsyncResult` atoms through React Suspense                    |
-| `useAtomInitialValues(values)`                 | Seed initial atom values in the current registry                   |
-| `useAtomSubscribe(atom$, callback, options?)`  | Subscribe to changes without rendering from the atom               |
-| `useAtomRef(ref)`                              | Subscribe to an `AtomRef` value directly                           |
-| `useAtomRefProp(ref, key)`                     | Memoize an `AtomRef` for an object property                        |
-| `useAtomRefPropValue(ref, key)`                | Subscribe to one property value from an object-shaped `AtomRef`    |
-
----
-
-## Testing VMs
-
-```typescript
-describe('WalletVM', () => {
-	const WalletServiceMock = Layer.succeed(
-		WalletService,
-		WalletService.of({
-			connect: Effect.succeed('0x1234...'),
-			disconnect: Effect.succeed(undefined)
-		})
-	);
-
-	const makeVM = () => {
-		const r = AtomRegistry.make();
-		const vm = Layer.build(WalletVM.layer).pipe(
-			Effect.map((ctx) => Context.get(ctx, WalletVM.tag)),
-			Effect.scoped,
-			Effect.provideService(AtomRegistry.AtomRegistry, r),
-			Effect.provide(WalletServiceMock),
-			Effect.runSync
-		);
-		return { r, vm };
-	};
-
-	it('should start disconnected', () => {
-		const { r, vm } = makeVM();
-		expect(WalletState.$is('Disconnected')(r.get(vm.state$))).toBe(true);
-	});
-
-	it('should connect wallet', async () => {
-		const { r, vm } = makeVM();
-		vm.connect();
-		await new Promise((r) => setTimeout(r, 10));
-		expect(WalletState.$is('Connected')(r.get(vm.state$))).toBe(true);
-	});
-});
-```
-
----
-
-## Best Practices
-
-**Core Pattern**
-
-- Use `Atom.fn()` for async actions—gives you `AtomResultFn` with automatic `waiting` flag
-- Use `useAtom(action$)` to get `[result, trigger]` tuple
-- `AsyncResult.matchWithWaiting` for rendering async states (onWaiting/onSuccess/onError/onDefect)
-- `AsyncResult.match` for one-time builds like VM initialization (onInitial/onSuccess/onFailure)
-- Never manually wrap Effects in void functions—you lose `waiting` control
-
-**Naming & Structure**
-
-- Atoms use `camelCase$` suffix
-- Every parent component: `Component.tsx` + `Component.vm.ts`
-- Child components receive VM as prop (no own VM)
-- VM file exports: interface, tag, default `{ tag, layer }`
-
-**Interface Design**
-
-- ALL formatting happens in VM—components receive ready-to-render strings
-- Use `key` for React, close over IDs in callbacks
-
-### UI-Ready Output Examples
-
-```tsx
-// WRONG - Logic in component
-function UserCard({ vm }: { vm: UserVM }) {
-	const user = useAtomValue(vm.user$);
-	const balance = useAtomValue(vm.balance$);
-
-	// NO! Formatting in component
-	const displayName = `${user.firstName} ${user.lastName.charAt(0)}.`;
-	const formattedBalance = new Intl.NumberFormat('en-US', {
-		style: 'currency',
-		currency: 'USD'
-	}).format(balance / 100);
-	const isVip =
-		balance > 10000 && user.memberSince < Date.now() - 31536000000;
-
-	return (
-		<div>
-			<h2>{displayName}</h2>
-			<span>{formattedBalance}</span>
-			{isVip && <VipBadge />} {/* NO! Conditional logic */}
-		</div>
-	);
-}
-
-// CORRECT - VM produces UI-ready values
-interface UserVM {
-	readonly displayName$: Atom.Atom<string>; // "John D."
-	readonly formattedBalance$: Atom.Atom<string>; // "$1,234.56"
-	readonly showVipBadge$: Atom.Atom<boolean>; // true/false
-}
-
-function UserCard({ vm }: { vm: UserVM }) {
-	const displayName = useAtomValue(vm.displayName$);
-	const formattedBalance = useAtomValue(vm.formattedBalance$);
-	const showVipBadge = useAtomValue(vm.showVipBadge$);
-
-	return (
-		<div>
-			<h2>{displayName}</h2>
-			<span>{formattedBalance}</span>
-			{showVipBadge && <VipBadge />} {/* OK - just reading a boolean */}
-		</div>
-	);
-}
-```
-
-**Implementation**
-
-- Atoms ONLY defined inside VM layers
-- `Layer.effect` is the default (VMRuntime provides scope)
-- Use `Atom.family` for list item sub-VMs
-- Use `Effect.forkScoped` for background tasks
-- Handle all errors in actions (update atom on failure)
-- Use `Atom.withEquality` for rebuilt UI-ready objects only when a complete semantic equivalence is available
-
-**Testing**
-
-- Test VMs without UI using registry directly
-- Create fresh VM per test
-- Mock services with `Layer.succeed`