mvc-kit 2.12.4 → 2.13.0

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

@@ -0,0 +1,297 @@
+# mvc-kit Testing Patterns
+
+These patterns are specific to testing mvc-kit classes. Follow them when writing or reviewing tests.
+
+---
+
+## Setup: Singleton Cleanup
+
+Every test file that uses singletons needs `teardownAll()` in `beforeEach`. Without this, singleton state leaks between tests.
+
+```typescript
+import { teardownAll } from 'mvc-kit';
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+beforeEach(() => {
+  teardownAll();
+  vi.restoreAllMocks();
+});
+```
+
+**Why:** Singletons persist in a module-scoped registry. After a test disposes a singleton ViewModel, the registry still holds the reference. `teardownAll()` disposes all singletons and clears the registry.
+
+---
+
+## Testing ViewModels
+
+### Basic: State and Getters
+
+Construct, init, call methods, assert `vm.state` and getter properties.
+
+```typescript
+import { UsersViewModel } from './UsersViewModel';
+
+describe('UsersViewModel', () => {
+  it('filters by search', async () => {
+    const vm = new UsersViewModel({ search: '', roleFilter: 'all', statusFilter: 'all' });
+    await vm.init();
+
+    // Wait for data to load (if onInit fetches)
+    await vi.waitFor(() => expect(vm.items.length).toBeGreaterThan(0));
+
+    vm.setSearch('alice');
+    expect(vm.filtered.every(u => u.firstName.toLowerCase().includes('alice'))).toBe(true);
+
+    vm.dispose();
+  });
+});
+```
+
+### Async Tracking Assertions
+
+After calling an async method, assert `vm.async.methodName` during and after the call.
+
+```typescript
+it('tracks loading state', async () => {
+  const vm = new UsersViewModel({ search: '', roleFilter: 'all', statusFilter: 'all' });
+  await vm.init();
+
+  // Before call
+  expect(vm.async.load.loading).toBe(false);
+  expect(vm.async.load.error).toBeNull();
+
+  // During call
+  const promise = vm.load();
+  expect(vm.async.load.loading).toBe(true);
+
+  await promise;
+
+  // After call
+  expect(vm.async.load.loading).toBe(false);
+  expect(vm.async.load.error).toBeNull();
+
+  vm.dispose();
+});
+
+it('captures errors in async tracking', async () => {
+  vi.spyOn(service, 'getAll').mockRejectedValue(new Error('Network error'));
+
+  const vm = new MyViewModel({ ... });
+  await vm.init();
+
+  await vm.load().catch(() => {}); // Swallow the re-thrown error
+
+  expect(vm.async.load.error).toBeInstanceOf(Error);
+  expect(vm.async.load.error!.message).toBe('Network error');
+
+  vm.dispose();
+});
+```
+
+### Counter-Based Getter Testing (Memoization Verification)
+
+Use a subclass override to count getter recomputations. Verifies that memoization works correctly.
+
+```typescript
+class TestableVM extends UsersViewModel {
+  filteredCallCount = 0;
+
+  get filtered(): UserState[] {
+    this.filteredCallCount++;
+    return super.filtered;
+  }
+}
+
+it('memoizes filtered getter', async () => {
+  const vm = new TestableVM({ search: '', roleFilter: 'all', statusFilter: 'all' });
+  await vm.init();
+
+  // First access — computes
+  const result1 = vm.filtered;
+  expect(vm.filteredCallCount).toBe(1);
+
+  // Second access, same state — cache hit (no recompute)
+  const result2 = vm.filtered;
+  expect(vm.filteredCallCount).toBe(1);
+
+  // State change — invalidates cache
+  vm.setSearch('test');
+  const result3 = vm.filtered;
+  expect(vm.filteredCallCount).toBe(2);
+
+  vm.dispose();
+});
+```
+
+---
+
+## Testing Collections
+
+Set up test data with `reset()`, then assert mutations.
+
+```typescript
+import { UsersResource } from './UsersResource';
+
+it('resets with data', () => {
+  const resource = new UsersResource();
+  resource.init();
+
+  resource.reset([
+    { id: '1', firstName: 'Alice', lastName: 'Smith', email: 'alice@test.com', role: 'admin', status: 'active' },
+    { id: '2', firstName: 'Bob', lastName: 'Jones', email: 'bob@test.com', role: 'viewer', status: 'inactive' },
+  ]);
+
+  expect(resource.length).toBe(2);
+  expect(resource.get('1')?.firstName).toBe('Alice');
+
+  resource.remove('1');
+  expect(resource.length).toBe(1);
+
+  resource.dispose();
+});
+```
+
+### Testing ViewModel + Collection Integration
+
+Mock the Service, let the ViewModel and Collection interact naturally.
+
+```typescript
+it('loads data through resource into getters', async () => {
+  // Mock the service
+  vi.spyOn(UserService.prototype, 'getAll').mockResolvedValue([
+    { id: '1', firstName: 'Alice', role: 'admin', status: 'active' },
+    { id: '2', firstName: 'Bob', role: 'viewer', status: 'inactive' },
+  ]);
+
+  const vm = new UsersViewModel({ search: '', roleFilter: 'all', statusFilter: 'all' });
+  await vm.init();
+
+  // Wait for onInit's load to complete
+  await vi.waitFor(() => expect(vm.items.length).toBe(2));
+
+  // Test getters
+  expect(vm.total).toBe(2);
+  expect(vm.filteredCount).toBe(2);
+
+  vm.setRoleFilter('admin');
+  expect(vm.filteredCount).toBe(1);
+  expect(vm.filtered[0].firstName).toBe('Alice');
+
+  vm.dispose();
+});
+```
+
+---
+
+## Testing Services
+
+Mock `fetch`, assert correct URL/method/body, verify `HttpError` is thrown on failures.
+
+```typescript
+import { UserService } from './UserService';
+
+it('fetches all users', async () => {
+  const mockUsers = [{ id: '1', firstName: 'Alice' }];
+  vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+    new Response(JSON.stringify(mockUsers), { status: 200 }),
+  );
+
+  const service = new UserService();
+  const result = await service.getAll();
+
+  expect(fetch).toHaveBeenCalledWith('/api/users', expect.objectContaining({ method: 'GET' }));
+  expect(result).toEqual(mockUsers);
+});
+
+it('throws HttpError on failure', async () => {
+  vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+    new Response('Not Found', { status: 404, statusText: 'Not Found' }),
+  );
+
+  const service = new UserService();
+  await expect(service.getById('999')).rejects.toThrow();
+});
+```
+
+---
+
+## Testing Models
+
+Assert validation, dirty state, commit, and rollback.
+
+```typescript
+import { LocationFormModel } from './LocationFormModel';
+
+it('validates required fields', () => {
+  const model = new LocationFormModel({ name: '', city: '', capacity: 0 });
+
+  expect(model.valid).toBe(false);
+  expect(model.errors.name).toBeDefined();
+
+  model.setName('HQ');
+  model.setCity('Austin');
+  model.setCapacity(100);
+  expect(model.valid).toBe(true);
+  expect(model.errors.name).toBeUndefined();
+
+  model.dispose();
+});
+
+it('tracks dirty state and supports commit/rollback', () => {
+  const model = new LocationFormModel({ name: 'HQ', city: 'Austin', capacity: 100 });
+
+  expect(model.dirty).toBe(false);
+
+  model.setName('New HQ');
+  expect(model.dirty).toBe(true);
+
+  model.rollback();
+  expect(model.state.name).toBe('HQ');
+  expect(model.dirty).toBe(false);
+
+  model.setName('New HQ');
+  model.commit();
+  expect(model.state.name).toBe('New HQ');
+  expect(model.dirty).toBe(false);
+
+  model.dispose();
+});
+```
+
+---
+
+## Testing React Components
+
+React tests need the jsdom environment directive. Use `renderHook` for hook tests.
+
+```typescript
+// @vitest-environment jsdom
+import { renderHook, act } from '@testing-library/react';
+import { useLocal } from 'mvc-kit/react';
+
+it('useLocal creates and disposes ViewModel', () => {
+  const { result, unmount } = renderHook(() =>
+    useLocal(CounterViewModel, { count: 0 }),
+  );
+
+  const [state, vm] = result.current;
+  expect(state.count).toBe(0);
+
+  act(() => vm.increment());
+  expect(result.current[0].count).toBe(1);
+
+  unmount(); // auto-disposes
+});
+```
+
+---
+
+## Test Checklist
+
+- [ ] `teardownAll()` in `beforeEach` (singleton cleanup)
+- [ ] `vm.dispose()` at end of each test (or rely on `afterEach` cleanup)
+- [ ] Assert `vm.state.x` for raw state, `vm.x` for getters
+- [ ] Assert `vm.async.method.loading` and `vm.async.method.error` for async methods
+- [ ] Mock Services at the `fetch` level or via `vi.spyOn(ServiceClass.prototype, 'method')`
+- [ ] React tests: add `// @vitest-environment jsdom` at top of file
+- [ ] Never test internal fields (`_state`, `_revision`) — test public API only

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

@@ -1,18 +1,8 @@
 ---
-name: review
+name: mvc-kit-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
+argument-hint: "<path>"
+allowed-tools: Read Grep Glob
 ---
 
 # Review mvc-kit Code

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

@@ -129,7 +129,7 @@
 
 ---
 
-## Composable Helper Checks (5)
+## Composable Helper Checks (9)
 
 ### Critical
 1. **Correct ownership** — Sorting, Pagination, Selection belong on ViewModel. Pending belongs on singleton Resource (survives unmount).
@@ -139,18 +139,43 @@
 3. **`apply()` in getters** — Helpers should be composed via `apply()` in getter pipelines: `pagination.apply(sorting.apply(filtered))`.
 4. **Feed uses `setResult()` with Resource** — When items live in a Resource, Feed tracks only cursor/hasMore via `setResult()`. Use `appendPage()` only for component-scoped item accumulation.
 5. **No `disposeSignal` in Pending execute** — Pending's `enqueue` callback receives its own signal. Do not pass `vm.disposeSignal` (would abort on component unmount).
+6. **Pagination reset on filter changes** — Every setter that changes filter/sort criteria must call `pagination.reset()`. Without this, users can land on invalid pages after filtering.
+7. **Helpers are `readonly` public** — Sorting, Pagination, Selection should be `readonly` public properties. DataTable and headless components need direct access.
+8. **Getter pipeline order** — Pipeline should be `items → filtered → sorted → paged`. Selection operates on `filtered` (not `paged`) for cross-page selection.
+
+### Suggestion
+9. **Pass `filteredCount` as pagination total** — DataTable/pagination components need the filtered count, not the total item count.
 
 ---
 
-## Test Checks (5)
+## Test Checks (8)
 
 ### 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.
+3. **Test file exists** — Every ViewModel, Resource, and Service should have a colocated `.test.ts` file.
+
+### Warning
+4. **Test state and getters** — Tests should assert `vm.state.x` and `vm.x` (getters), not internal fields.
+5. **Test async tracking** — For async methods, assert `vm.async.method.loading` and `vm.async.method.error`.
+6. **Mock at Service boundary** — Mock `fetch` or `vi.spyOn(ServiceClass.prototype, 'method')`. Don't mock Collections or Resources — let them interact naturally.
+7. **React tests use jsdom** — React test files need `// @vitest-environment jsdom` directive at top of file.
+
+### Suggestion
+8. **Counter-based getter testing** — Use subclass override pattern for verifying getter memoization.
+
+---
+
+## Composition Checks (6)
+
+### Critical
+1. **Model lifecycle pairing** — If a ViewModel creates a Model in `onInit()` or an action, it must dispose it in `onDispose()`.
 
 ### 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`.
+2. **Per-call cancellation for rapid interactions** — When users can switch contexts rapidly (conversations, search-as-you-type), use `AbortSignal.any([this.disposeSignal, controller.signal])` instead of `disposeSignal` alone.
+3. **Two-tier events** — ViewModel `.emit()` for component-scoped reactions (navigate, show error). EventBus `.emit()` for app-wide side effects (toasts, analytics). Don't use EventBus for single-component concerns.
+4. **Singleton DEFAULT_STATE** — Singleton ViewModels used with `useSingleton()` should have `static DEFAULT_STATE` to avoid repeating initial state at every call site.
+5. **Smart init** — `onInit()` should check `if (this.collection.length === 0)` before fetching to prevent re-fetching when component re-mounts and data is already loaded.
 
 ### Suggestion
-5. **Counter-based getter testing** — Use subclass override pattern for verifying getter memoization.
+6. **File naming convention** — Files should follow `{Name}{Role}.ts` pattern: `UsersViewModel.ts`, `UserService.ts`, `UsersCollection.ts`, `UsersResource.ts`, `LocationFormModel.ts`, `AppEventBus.ts`.

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

@@ -1,18 +1,9 @@
 ---
-name: scaffold
+name: mvc-kit-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, persistent-collection, resource, service, eventbus, channel, controller, page-component
-
-  Examples:
-    /mvc-kit:scaffold viewmodel OrderList
-    /mvc-kit:scaffold service Payment
-    /mvc-kit:scaffold page-component Users
+argument-hint: "<type> <Name>"
+disable-model-invocation: true
+allowed-tools: Read Write Edit
 ---
 
 # Scaffold mvc-kit Class

package/agent-config/lib/install-claude.mjs

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, copyFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -7,13 +7,22 @@ const __dirname = dirname(__filename);
 const SKILLS_DIR = join(__dirname, '..', 'claude-code', 'skills');
 const AGENTS_DIR = join(__dirname, '..', 'claude-code', 'agents');
 
-const AUTO_HEADER = '<!-- Auto-generated by mvc-kit. Updated on npm install/update. Do not edit. -->\n\n';
+const AUTO_HEADER = '<!-- Auto-generated by mvc-kit. Updated on npm install/update. Do not edit. -->';
 
 function stripFrontmatter(content) {
   const match = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
   return match ? match[1].trim() : content.trim();
 }
 
+/** Insert auto-generated header after YAML frontmatter (preserves parsing). */
+function addHeader(content) {
+  const match = content.match(/^(---\n[\s\S]*?\n---\n)([\s\S]*)$/);
+  if (match) {
+    return match[1] + '\n' + AUTO_HEADER + '\n\n' + match[2].trim() + '\n';
+  }
+  return AUTO_HEADER + '\n\n' + content;
+}
+
 function ensureDir(dir) {
   if (!existsSync(dir)) {
     mkdirSync(dir, { recursive: true });
@@ -24,7 +33,9 @@ function ensureDir(dir) {
  * Install Claude Code integration files into a project's .claude/ directory.
  *
  * Creates:
- *   .claude/skills/mvc-kit.md           — Framework reference skill (on-demand, model-invocable)
+ *   .claude/skills/mvc-kit/            — Framework reference skill + supporting docs
+ *   .claude/skills/mvc-kit-review/     — Code review skill + checklist
+ *   .claude/skills/mvc-kit-scaffold/   — Scaffolding skill + templates
  *   .claude/agents/mvc-kit-architect.md — Architecture planning agent
  *
  * @param {string} projectRoot — Absolute path to the consuming project's root
@@ -32,50 +43,98 @@ function ensureDir(dir) {
  */
 export function installClaude(projectRoot) {
   const claudeDir = join(projectRoot, '.claude');
-  const skillsDir = join(claudeDir, 'skills');
+  const guideDir = join(claudeDir, 'skills', 'mvc-kit');
+  const reviewDir = join(claudeDir, 'skills', 'mvc-kit-review');
+  const scaffoldDir = join(claudeDir, 'skills', 'mvc-kit-scaffold');
+  const templatesDir = join(scaffoldDir, 'templates');
   const agentsDir = join(claudeDir, 'agents');
 
-  ensureDir(skillsDir);
+  ensureDir(guideDir);
+  ensureDir(reviewDir);
+  ensureDir(scaffoldDir);
+  ensureDir(templatesDir);
   ensureDir(agentsDir);
 
   const files = [];
 
-  // 1. Guide skill — framework reference (on-demand, model-invocable)
+  // ─── 1. Guide skill — framework reference (model-invocable, auto-loaded) ───
+
   const guideSkill = readFileSync(join(SKILLS_DIR, 'guide', 'SKILL.md'), 'utf-8');
   const guideBody = stripFrontmatter(guideSkill)
-    // Remove the "Supporting Files" section — replaced by "Detailed Reference" below
+    // Remove the "Supporting Files" section — replaced with colocated file references below
     .replace(/\n## Supporting Files[\s\S]*$/, '');
 
-  const SKILL_FRONTMATTER = `---
+  const GUIDE_FRONTMATTER = `---
 name: mvc-kit
 description: "mvc-kit framework reference — class roles, architecture rules, React hooks, and decision framework. Loaded on-demand when working with mvc-kit code."
-invocable_by:
-  - model
----
+user-invocable: false
+---`;
 
-`;
+  const skillContent = GUIDE_FRONTMATTER + '\n\n' + AUTO_HEADER + '\n\n' + guideBody + `
 
-  const skillContent = SKILL_FRONTMATTER + AUTO_HEADER + guideBody + `
+## Supporting Files
 
-## Detailed Reference
-
-For complete API details, patterns, and anti-patterns, read the files in:
-\`node_modules/mvc-kit/agent-config/claude-code/skills/guide/\`
-
-- \`api-reference.md\` — Full API reference for all classes and hooks
-- \`patterns.md\` — Prescribed patterns with code examples
-- \`anti-patterns.md\` — Anti-patterns to reject with fixes
+- [api-reference.md](api-reference.md) — Full API reference for all classes and hooks
+- [patterns.md](patterns.md) — Prescribed patterns with code examples
+- [anti-patterns.md](anti-patterns.md) — Anti-patterns to reject with fixes
+- [recipes.md](recipes.md) — Composition recipes for real-world features
+- [testing.md](testing.md) — Testing patterns (teardownAll, async assertions, memoization verification)
 
 For detailed per-class documentation, read the \`.md\` files colocated with source in:
 \`node_modules/mvc-kit/src/\`
 `;
 
-  writeFileSync(join(skillsDir, 'mvc-kit', 'SKILL.md'), skillContent, 'utf-8');
+  writeFileSync(join(guideDir, 'SKILL.md'), skillContent, 'utf-8');
   files.push('.claude/skills/mvc-kit/SKILL.md');
 
-  // 2. Architect agent
-  const architectAgent = readFileSync(join(AGENTS_DIR, 'mvc-kit-architect.md'), 'utf-8');
-  writeFileSync(join(agentsDir, 'mvc-kit-architect.md'), AUTO_HEADER + architectAgent, 'utf-8');
+  // Copy supporting files alongside SKILL.md
+  const guideSupportFiles = ['api-reference.md', 'patterns.md', 'anti-patterns.md', 'recipes.md', 'testing.md'];
+  for (const file of guideSupportFiles) {
+    const src = join(SKILLS_DIR, 'guide', file);
+    if (existsSync(src)) {
+      copyFileSync(src, join(guideDir, file));
+      files.push(`.claude/skills/mvc-kit/${file}`);
+    }
+  }
+
+  // ─── 2. Review skill — code review with checklist ──────────────────────────
+
+  const reviewSkill = readFileSync(join(SKILLS_DIR, 'review', 'SKILL.md'), 'utf-8');
+  writeFileSync(join(reviewDir, 'SKILL.md'), addHeader(reviewSkill), 'utf-8');
+  files.push('.claude/skills/mvc-kit-review/SKILL.md');
+
+  copyFileSync(
+    join(SKILLS_DIR, 'review', 'checklist.md'),
+    join(reviewDir, 'checklist.md'),
+  );
+  files.push('.claude/skills/mvc-kit-review/checklist.md');
+
+  // ─── 3. Scaffold skill — code generation with templates ────────────────────
+
+  const scaffoldSkill = readFileSync(join(SKILLS_DIR, 'scaffold', 'SKILL.md'), 'utf-8');
+  writeFileSync(join(scaffoldDir, 'SKILL.md'), addHeader(scaffoldSkill), 'utf-8');
+  files.push('.claude/skills/mvc-kit-scaffold/SKILL.md');
+
+  const templatesSrc = join(SKILLS_DIR, 'scaffold', 'templates');
+  if (existsSync(templatesSrc)) {
+    for (const file of readdirSync(templatesSrc)) {
+      if (file.endsWith('.md')) {
+        copyFileSync(join(templatesSrc, file), join(templatesDir, file));
+        files.push(`.claude/skills/mvc-kit-scaffold/templates/${file}`);
+      }
+    }
+  }
+
+  // ─── 4. Architect agent ────────────────────────────────────────────────────
+
+  let architectAgent = readFileSync(join(AGENTS_DIR, 'mvc-kit-architect.md'), 'utf-8');
+  // The source agent preloads "mvc-kit-guide" (the source skill name).
+  // In the installed context the guide skill is named "mvc-kit", so fix the reference.
+  architectAgent = architectAgent.replace(
+    /^(\s*- )mvc-kit-guide$/m,
+    '$1mvc-kit',
+  );
+  writeFileSync(join(agentsDir, 'mvc-kit-architect.md'), addHeader(architectAgent), 'utf-8');
   files.push('.claude/agents/mvc-kit-architect.md');
 
   return { files };