mvc-kit 2.0.0 → 2.1.0

package/agent-config/claude-code/skills/guide/patterns.md

@@ -0,0 +1,336 @@
+# mvc-kit Prescribed Patterns
+
+These are mandatory patterns. All code using mvc-kit must follow them.
+
+---
+
+## State Design: Source of Truth Only
+
+State holds only raw values — user inputs and server data. Never derived values, never loading/error flags.
+
+```typescript
+// BAD
+interface State {
+  items: Item[];
+  filtered: Item[];      // derived — use a getter
+  loading: boolean;      // use vm.async
+  error: string | null;  // use vm.async
+}
+
+// GOOD
+interface State {
+  items: Item[];
+  search: string;
+  typeFilter: 'all' | 'office' | 'warehouse';
+}
+```
+
+---
+
+## Computed Getters
+
+TypeScript `get` accessors compute derived values from state. Auto-memoized after `init()`.
+
+```typescript
+class LocationsViewModel extends ViewModel<State> {
+  get filtered(): Item[] {
+    const { items, search, typeFilter } = this.state;
+    let result = items;
+    if (search) {
+      const q = search.toLowerCase();
+      result = result.filter(i => i.name.toLowerCase().includes(q));
+    }
+    if (typeFilter !== 'all') {
+      result = result.filter(i => i.type === typeFilter);
+    }
+    return result;
+  }
+
+  get total(): number { return this.state.items.length; }
+  get hasResults(): boolean { return this.filtered.length > 0; }
+  get isEmpty(): boolean { return this.total > 0 && !this.hasResults; }
+}
+```
+
+**Never call `set()` inside a getter.** Dev mode detects this.
+
+---
+
+## One-Liner Setters
+
+```typescript
+setSearch(search: string) { this.set({ search }); }
+setTypeFilter(typeFilter: State['typeFilter']) { this.set({ typeFilter }); }
+```
+
+The setter changes state → React re-renders → getters recompute. No manual refiltering needed.
+
+---
+
+## Encapsulating Collections
+
+ViewModels subscribe internally. Components never see Collections.
+
+```typescript
+class LocationsViewModel extends ViewModel<State> {
+  private collection = singleton(LocationsCollection);
+  private service = singleton(LocationService);
+
+  protected onInit() {
+    this.subscribeTo(this.collection, () => {
+      this.set({ items: this.collection.items });
+    });
+
+    // Smart init: use cached data or fetch fresh
+    if (this.collection.length > 0) {
+      this.set({ items: this.collection.items });
+    } else {
+      this.load();
+    }
+  }
+}
+```
+
+---
+
+## Async Methods — Happy Path Only
+
+```typescript
+async load() {
+  const data = await this.service.getAll(this.disposeSignal);
+  this.collection.reset(data);
+}
+```
+
+No try/catch. No `set({ loading: true })`. No AbortError check. The framework handles it.
+
+**Only add try/catch** for imperative events on error:
+
+```typescript
+async save() {
+  try {
+    const result = await this.service.save(this.state.draft, this.disposeSignal);
+    this.collection.update(result.id, result);
+    this.emit('saved', { id: result.id });
+  } catch (e) {
+    if (!isAbortError(e)) {
+      this.emit('error', { message: classifyError(e).message });
+    }
+    throw e; // MUST re-throw so async tracking captures it
+  }
+}
+```
+
+---
+
+## Component Pattern
+
+```tsx
+function LocationsPage() {
+  const [state, vm] = useLocal(LocationsViewModel, {
+    items: [], search: '', typeFilter: 'all',
+  });
+  const { loading, error } = vm.async.load;
+
+  return (
+    <div>
+      <input value={state.search} onChange={e => vm.setSearch(e.target.value)} />
+      {loading && <Spinner />}
+      {error && <ErrorBanner message={error} />}
+      <LocationsTable locations={vm.filtered} />
+      <p>Showing {vm.filtered.length} of {vm.total}</p>
+    </div>
+  );
+}
+```
+
+No `useEffect`. No `useState`. No `useMemo`. No `useCallback`. The ViewModel is the hook.
+
+---
+
+## ViewModel Section Order
+
+```typescript
+class MyViewModel extends ViewModel<State, Events> {
+  // --- Private fields ---
+  private service = singleton(MyService);
+  private collection = singleton(MyCollection);
+
+  // --- Computed getters ---
+  get filtered(): Item[] { /* ... */ }
+  get total(): number { /* ... */ }
+
+  // --- Lifecycle ---
+  protected onInit() { /* ... */ }
+
+  // --- Actions ---
+  async load() { /* ... */ }
+  async save() { /* ... */ }
+
+  // --- Setters ---
+  setSearch(search: string) { this.set({ search }); }
+}
+```
+
+---
+
+## Imperative Events
+
+For toasts, navigation, animations — one-shot signals that don't belong in state.
+
+```typescript
+interface SaveEvents {
+  saved: { id: string };
+  validationFailed: void;
+}
+
+class ItemViewModel extends ViewModel<State, SaveEvents> {
+  async save() {
+    const result = await this.service.save(this.state.draft, this.disposeSignal);
+    this.emit('saved', { id: result.id });
+  }
+}
+```
+
+```tsx
+// Component subscribes directly on the ViewModel
+useEvent(vm, 'saved', ({ id }) => toast.success(`Saved ${id}`));
+```
+
+---
+
+## Service Pattern
+
+```typescript
+class UserService extends Service {
+  async getAll(signal?: AbortSignal): Promise<User[]> {
+    const res = await fetch('/api/users', { signal });
+    if (!res.ok) throw new HttpError(res.status, res.statusText);
+    return res.json();
+  }
+}
+```
+
+- Stateless, singleton, accept `AbortSignal`, throw `HttpError`.
+
+---
+
+## Collection Pattern
+
+```typescript
+class UsersCollection extends Collection<UserState> {}
+```
+
+Thin subclass for singleton identity. No custom methods — query logic goes in ViewModel getters.
+
+---
+
+## Optimistic Updates
+
+```typescript
+async toggleStatus(id: string) {
+  const rollback = this.collection.optimistic(() => {
+    this.collection.update(id, { status: 'done' });
+  });
+  try {
+    await this.service.update(id, { status: 'done' }, this.disposeSignal);
+  } catch (e) {
+    if (!isAbortError(e)) rollback();
+    throw e; // re-throw for async tracking
+  }
+}
+```
+
+---
+
+## Sharing Patterns
+
+**Pattern A — Parent ViewModel with props** (default):
+```tsx
+function OrderPage() {
+  const [state, vm] = useLocal(OrderViewModel, { /* ... */ });
+  return (
+    <div>
+      <OrderItems items={vm.visibleItems} onRemove={id => vm.removeItem(id)} />
+      <OrderSummary total={vm.total} onSubmit={() => vm.submit()} />
+    </div>
+  );
+}
+```
+
+**Pattern B — Singleton ViewModel** (app-wide state):
+```tsx
+const [state, vm] = useSingleton(CartViewModel, { items: [] });
+```
+
+**Pattern C — Shared Collection** (different views of same data):
+```tsx
+// UsersTable uses UsersViewModel → subscribes to UsersCollection
+// OnDutySidebar uses OnDutyViewModel → subscribes to UsersCollection
+```
+
+---
+
+## useLocal with Dependencies
+
+Recreates instance when deps change:
+```tsx
+const [state, vm] = useLocal(UserViewModel, { userId, data: null }, [userId]);
+```
+
+---
+
+## Model Pattern
+
+```typescript
+class UserFormModel extends Model<UserFormState> {
+  setName(name: string) { this.set({ name }); }
+  setEmail(email: string) { this.set({ email }); }
+
+  protected validate(state: UserFormState) {
+    const errors: Partial<Record<keyof UserFormState, string>> = {};
+    if (!state.name.trim()) errors.name = 'Required';
+    if (!state.email.includes('@')) errors.email = 'Invalid email';
+    return errors;
+  }
+}
+```
+
+```tsx
+const { state, errors, valid, dirty, model } = useModel(() => new UserFormModel({ name: '', email: '' }));
+```
+
+---
+
+## Testing Pattern
+
+```typescript
+import { singleton, teardownAll } from 'mvc-kit';
+
+beforeEach(() => teardownAll());
+
+test('filtered getter applies search', () => {
+  const collection = singleton(UsersCollection);
+  collection.reset([
+    { id: '1', firstName: 'Alice', status: 'on_duty' },
+    { id: '2', firstName: 'Bob', status: 'off_duty' },
+  ]);
+
+  const vm = new UsersViewModel({ items: [], search: '', roleFilter: 'all' });
+  vm.init();
+
+  expect(vm.filtered).toHaveLength(2);
+  vm.setSearch('alice');
+  expect(vm.filtered).toHaveLength(1);
+
+  vm.dispose();
+});
+```
+
+---
+
+## Error Handling Layers
+
+1. **Async tracking** (automatic) — write happy path, read `vm.async.method.error`
+2. **Imperative events** (explicit) — try/catch + `emit()` + **re-throw**
+3. **Error classification** (services) — `throw HttpError`, `classifyError()`

package/agent-config/claude-code/skills/review/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: review
+description: "Review code for mvc-kit pattern adherence. Usage: /mvc-kit:review <path>"
+invocable_by:
+  - user
+  - model
+user_instructions: |
+  Usage: /mvc-kit:review <path>
+
+  Reviews files at the given path for mvc-kit pattern adherence.
+  Accepts a file path or directory.
+
+  Examples:
+    /mvc-kit:review src/viewmodels/
+    /mvc-kit:review src/viewmodels/OrderViewModel.ts
+---
+
+# Review mvc-kit Code
+
+Parse `$ARGUMENTS` as a file or directory path. If a directory, review all `.ts` and `.tsx` files within it.
+
+## Instructions
+
+1. Read the target file(s).
+2. Identify mvc-kit imports (`mvc-kit`, `mvc-kit/react`) to determine file types.
+3. Check each file against the categorized checklist in `checklist.md`.
+4. Output findings grouped by severity.
+
+## Output Format
+
+For each finding:
+
+```
+[SEVERITY] file:line — Violation
+  Problem: What's wrong
+  Fix: Concrete before/after code
+```
+
+Severity levels:
+- **CRITICAL** — Will cause bugs, memory leaks, infinite loops, or state desync. Must fix.
+- **WARNING** — Anti-pattern that hurts maintainability. Should fix.
+- **SUGGESTION** — Improvement for readability or DX. Nice to have.
+
+## Summary
+
+After individual findings, provide:
+- Total findings by severity
+- Overall assessment (healthy / needs attention / significant issues)
+- Top 3 priorities to address
+
+## Reference
+
+See `checklist.md` for the complete categorized checklist by file type.

package/agent-config/claude-code/skills/review/checklist.md

@@ -0,0 +1,89 @@
+# mvc-kit Review Checklist
+
+## ViewModel Checks (15)
+
+### Critical
+1. **No loading/error in State** — State interface must not contain `loading`, `error`, `isLoading`, or similar. Use `vm.async.method`.
+2. **No derived state in State** — State must not contain values computable from other state (filtered lists, counts, flags). Use getters.
+3. **No `set()` inside getters** — Creates infinite loop. Derived values must be pure computations.
+4. **`disposeSignal` on async calls** — Every `fetch()`, service call, or async operation must receive `this.disposeSignal` or a composed signal.
+5. **Re-throw in try/catch** — Any explicit try/catch must re-throw the error so async tracking captures it. Only guard with `isAbortError()`.
+
+### Warning
+6. **Section order** — Must follow: Private fields → Computed getters → Lifecycle → Actions → Setters.
+7. **No two-step setters** — Setters should be one-liners (`this.set({ x })`). No manual refilter/rederive calls after `set()`.
+8. **Smart init pattern** — When subscribing to a Collection, check `collection.length > 0` before fetching.
+9. **Use `subscribeTo`** — Collection subscriptions must use `subscribeTo()` (auto-cleanup), not manual `subscribe()` + `addCleanup()`.
+10. **Use `collection.optimistic()`** — No manual snapshot/restore for optimistic updates.
+11. **Singleton resolution as property** — Dependencies resolved via `private service = singleton(MyService)`, not in `onInit()`.
+
+### Suggestion
+12. **Action naming** — Public methods should use user-intent verbs (`load`, `save`, `submit`), not implementation names (`fetchFromApi`).
+13. **ViewModel events vs separate EventBus** — Use the second generic parameter for component-scoped events, not a separate EventBus instance.
+14. **Giant ViewModel** — Flag >10 state properties or >8 public methods. Consider splitting.
+15. **Getter composition** — Getters should compose from other getters where natural (e.g., `get isEmpty()` uses `this.filtered`).
+
+---
+
+## Component Checks (10)
+
+### Critical
+1. **One `useLocal` per component** — Multiple `useLocal` calls must be split into separate components.
+2. **No `useEffect` for data loading** — Data loading belongs in `onInit()`, not `useEffect`.
+3. **No direct Collection/Service imports** — Components import only their ViewModel and React hooks.
+
+### Warning
+4. **No `useState`/`useMemo`/`useCallback`** — The ViewModel replaces these hooks. UI state belongs in the ViewModel.
+5. **No logic/filtering in components** — Derivation belongs in ViewModel getters. Components should only read `vm.x`.
+6. **Correct state access** — Raw values via `state.x`, computed via `vm.x`, async via `vm.async.x`.
+7. **Connected vs presentational** — Connected components own a ViewModel. Presentational components receive props with no mvc-kit imports.
+
+### Suggestion
+8. **Destructure async** — `const { loading, error } = vm.async.load` for readability.
+9. **Presentational ratio** — Many presentational, few connected. Components doing too much should extract presentational children.
+10. **`useLocal` deps** — When tied to route params or props that change, pass `deps` array to `useLocal`.
+
+---
+
+## Service Checks (5)
+
+### Critical
+1. **Accept `AbortSignal`** — Every async method must accept an optional `signal` parameter.
+2. **Throw `HttpError`** — Non-OK responses must throw `HttpError(status, statusText)` for error classification.
+
+### Warning
+3. **Stateless** — Services must not cache data. That's a Collection's job.
+4. **No ViewModel/Collection knowledge** — Services sit at the bottom. No imports from viewmodels or collections.
+
+### Suggestion
+5. **Method naming** — `getAll`, `getById`, `create`, `update`, `delete` — standard REST verbs.
+
+---
+
+## Collection Checks (5)
+
+### Critical
+1. **Thin subclass** — Collections should be `class MyCollection extends Collection<MyType> {}` with no custom methods.
+2. **Never component-facing** — Components must not import or subscribe to Collections.
+
+### Warning
+3. **One per entity type** — Don't reuse a Collection for different entity types.
+4. **Items have `id: string`** — Collection items must have an `id` field of type `string`.
+
+### Suggestion
+5. **Query in ViewModel** — Filtering/sorting logic belongs in ViewModel getters, not Collection methods.
+
+---
+
+## Test Checks (5)
+
+### Critical
+1. **`teardownAll()` in beforeEach** — Singleton registry must be reset between tests.
+2. **Dispose after test** — ViewModel/Model instances created in tests must be disposed.
+
+### Warning
+3. **Test state and getters** — Tests should assert `vm.state.x` and `vm.x` (getters), not internal fields.
+4. **Test async tracking** — For async methods, assert `vm.async.method.loading` and `vm.async.method.error`.
+
+### Suggestion
+5. **Counter-based getter testing** — Use subclass override pattern for verifying getter memoization.

package/agent-config/claude-code/skills/scaffold/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: scaffold
+description: "Scaffold mvc-kit classes with correct patterns. Usage: /mvc-kit:scaffold <type> <Name>"
+invocable_by:
+  - user
+  - model
+user_instructions: |
+  Usage: /mvc-kit:scaffold <type> <Name>
+
+  Types: viewmodel, model, collection, service, eventbus, channel, controller, page-component
+
+  Examples:
+    /mvc-kit:scaffold viewmodel OrderList
+    /mvc-kit:scaffold service Payment
+    /mvc-kit:scaffold page-component Users
+---
+
+# Scaffold mvc-kit Class
+
+Parse `$ARGUMENTS` as `<type> <Name>` (case-insensitive type, PascalCase Name).
+
+## Instructions
+
+1. Parse the arguments. If missing, ask the user for `<type>` and `<Name>`.
+2. Read the template file from `templates/<type>.md` in this skill directory.
+3. Replace all `{{Name}}` placeholders with the provided Name.
+4. Generate the implementation file(s) following the template exactly.
+5. Also generate a colocated test file following mvc-kit test conventions.
+
+## Valid Types
+
+| Type | Template | Files Generated |
+|------|----------|----------------|
+| `viewmodel` | `templates/viewmodel.md` | `{{Name}}ViewModel.ts`, `{{Name}}ViewModel.test.ts` |
+| `model` | `templates/model.md` | `{{Name}}Model.ts`, `{{Name}}Model.test.ts` |
+| `collection` | `templates/collection.md` | `{{Name}}Collection.ts` |
+| `service` | `templates/service.md` | `{{Name}}Service.ts`, `{{Name}}Service.test.ts` |
+| `eventbus` | `templates/eventbus.md` | `{{Name}}EventBus.ts` |
+| `channel` | `templates/channel.md` | `{{Name}}Channel.ts` |
+| `controller` | `templates/controller.md` | `{{Name}}Controller.ts` |
+| `page-component` | `templates/page-component.md` | `{{Name}}Page.tsx` |
+
+## Rules
+
+- Follow the ViewModel section order: Private fields → Computed getters → Lifecycle → Actions → Setters.
+- State interfaces hold only source-of-truth values. No derived values, no loading/error flags.
+- Services are stateless, accept `AbortSignal`, throw `HttpError`.
+- Collections are thin subclasses — no custom methods.
+- Use `singleton()` for dependency resolution in ViewModels.
+- Use `subscribeTo()` for Collection subscriptions with smart init pattern.
+- Pass `this.disposeSignal` to every async call.
+- Test files use `teardownAll()` in `beforeEach`.

package/agent-config/claude-code/skills/scaffold/templates/channel.md

@@ -0,0 +1,88 @@
+# Channel Template: {{Name}}
+
+## {{Name}}Channel.ts
+
+```typescript
+import { Channel } from 'mvc-kit';
+
+export interface {{Name}}Messages {
+  // TODO: Define your message types
+  // message: { id: string; text: string; timestamp: number };
+  // status: { userId: string; online: boolean };
+}
+
+export class {{Name}}Channel extends Channel<{{Name}}Messages> {
+  private ws: WebSocket | null = null;
+
+  protected connect(): void {
+    // TODO: Set your WebSocket URL
+    this.ws = new WebSocket('wss://example.com/ws');
+
+    this.ws.onopen = () => {
+      this.setConnected();
+    };
+
+    this.ws.onclose = () => {
+      this.setDisconnected();
+    };
+
+    this.ws.onerror = () => {
+      this.setDisconnected();
+    };
+
+    this.ws.onmessage = (event) => {
+      const data = JSON.parse(event.data);
+      // TODO: Route messages by type
+      // this.receive('message', data);
+    };
+  }
+
+  protected disconnect(): void {
+    this.ws?.close();
+    this.ws = null;
+  }
+
+  // Optional: send messages
+  send(data: unknown): void {
+    this.ws?.send(JSON.stringify(data));
+  }
+}
+```
+
+## Usage in a ViewModel
+
+```typescript
+import { ViewModel, singleton } from 'mvc-kit';
+import { {{Name}}Channel } from '../channels/{{Name}}Channel';
+
+interface State {
+  connectionStatus: string;
+  messages: any[];
+}
+
+class {{Name}}ViewModel extends ViewModel<State> {
+  private channel = singleton({{Name}}Channel);
+
+  protected onInit() {
+    // Mirror connection status
+    this.subscribeTo(this.channel, () => {
+      this.set({ connectionStatus: this.channel.state });
+    });
+
+    // Listen to messages (manual cleanup needed for channel.on)
+    const unsub = this.channel.on('message', (msg) => {
+      this.set({ messages: [...this.state.messages, msg] });
+    });
+    this.addCleanup(unsub);
+
+    this.channel.open();
+  }
+}
+```
+
+## Notes
+
+- Channels are **singletons** — shared across ViewModels
+- `subscribeTo(channel)` tracks connection status changes (auto-cleanup)
+- `channel.on(event)` subscriptions need manual `addCleanup` registration
+- Auto-reconnect is built-in: configure via static `RECONNECT_DELAY`, `MAX_RECONNECT_DELAY`, `MAX_RECONNECT_ATTEMPTS`

package/agent-config/claude-code/skills/scaffold/templates/collection.md

@@ -0,0 +1,49 @@
+# Collection Template: {{Name}}
+
+## {{Name}}Collection.ts
+
+```typescript
+import { Collection } from 'mvc-kit';
+
+export interface {{Name}}Item {
+  id: string;
+  // TODO: Add your fields
+}
+
+export class {{Name}}Collection extends Collection<{{Name}}Item> {}
+```
+
+Collections are thin subclasses — singleton identity only. Query logic belongs in ViewModel getters.
+
+## Usage in a ViewModel
+
+```typescript
+import { ViewModel, singleton } from 'mvc-kit';
+import { {{Name}}Collection } from '../collections/{{Name}}Collection';
+import type { {{Name}}Item } from '../collections/{{Name}}Collection';
+
+interface State {
+  items: {{Name}}Item[];
+}
+
+class {{Name}}ViewModel extends ViewModel<State> {
+  private collection = singleton({{Name}}Collection);
+
+  protected onInit() {
+    this.subscribeTo(this.collection, () => {
+      this.set({ items: this.collection.items });
+    });
+
+    if (this.collection.length > 0) {
+      this.set({ items: this.collection.items });
+    } else {
+      this.load();
+    }
+  }
+
+  async load() {
+    // const data = await this.service.getAll(this.disposeSignal);
+    // this.collection.reset(data);
+  }
+}
+```