mvc-kit 2.0.0 → 2.1.0

package/README.md

@@ -15,6 +15,25 @@ Zero-
 npm install mvc-kit
 ```
 
+## AI Agent Plugin
+
+mvc-kit ships with built-in context for AI coding assistants — stays in sync with your installed version automatically.
+
+```bash
+npx mvc-kit-setup          # Set up all agents
+npx mvc-kit-setup cursor   # Cursor only
+npx mvc-kit-setup copilot  # GitHub Copilot only
+```
+
+**Claude Code** — load directly as a plugin (no file copying, auto-updates):
+```bash
+claude --plugin-dir node_modules/mvc-kit/agent-config/claude-code
+```
+
+Skills: `/mvc-kit:guide` (framework reference), `/mvc-kit:scaffold <type> <Name>` (code generation), `/mvc-kit:review <path>` (pattern review).
+
+**Cursor** — writes `.cursorrules`. **Copilot** — writes `.github/copilot-instructions.md`. Both use idempotent markers, safe to re-run.
+
 ## Quick Start
 
 ```typescript

package/agent-config/bin/setup.mjs

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const AGENT_CONFIG_DIR = resolve(__dirname, '..');
+const PROJECT_DIR = process.cwd();
+
+const MARKER_BEGIN = '<!-- BEGIN mvc-kit -->';
+const MARKER_END = '<!-- END mvc-kit -->';
+
+const VALID_TARGETS = ['claude', 'cursor', 'copilot', 'all'];
+
+// ─── Helpers ──────────────────────────────────────────────
+
+function printUsage() {
+  console.log(`
+Usage: npx mvc-kit-setup [targets...] [options]
+
+Targets:
+  claude     Set up Claude Code plugin (prints usage instructions)
+  cursor     Copy mvc-kit rules to .cursorrules
+  copilot    Copy mvc-kit instructions to .github/copilot-instructions.md
+  all        Set up all targets (default)
+
+Options:
+  --help     Show this help message
+  --force    Overwrite existing files without prompting
+
+Examples:
+  npx mvc-kit-setup              # Set up all targets
+  npx mvc-kit-setup cursor       # Set up Cursor only
+  npx mvc-kit-setup cursor copilot  # Set up Cursor and Copilot
+  npx mvc-kit-setup --force      # Overwrite without prompting
+`);
+}
+
+function readSourceFile(relativePath) {
+  const fullPath = join(AGENT_CONFIG_DIR, relativePath);
+  return readFileSync(fullPath, 'utf-8');
+}
+
+function wrapWithMarkers(content) {
+  return `${MARKER_BEGIN}\n${content.trim()}\n${MARKER_END}`;
+}
+
+function replaceMarkerSection(existingContent, newContent) {
+  const beginIdx = existingContent.indexOf(MARKER_BEGIN);
+  const endIdx = existingContent.indexOf(MARKER_END);
+
+  if (beginIdx !== -1 && endIdx !== -1) {
+    // Replace existing section
+    const before = existingContent.slice(0, beginIdx);
+    const after = existingContent.slice(endIdx + MARKER_END.length);
+    return before + wrapWithMarkers(newContent) + after;
+  }
+
+  // Append new section
+  const separator = existingContent.trim() ? '\n\n' : '';
+  return existingContent.trim() + separator + wrapWithMarkers(newContent) + '\n';
+}
+
+async function confirm(message) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`${message} (y/N) `, (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'y');
+    });
+  });
+}
+
+// ─── Target Handlers ──────────────────────────────────────
+
+function setupClaude() {
+  const pluginDir = join(AGENT_CONFIG_DIR, 'claude-code');
+
+  console.log('\n  Claude Code');
+  console.log('  ───────────');
+  console.log('  The mvc-kit plugin is loaded directly from node_modules.');
+  console.log('  No file copying needed — it updates automatically with npm update.\n');
+  console.log('  To use, start Claude Code with the --plugin-dir flag:\n');
+  console.log(`    claude --plugin-dir ${pluginDir}\n`);
+  console.log('  Skills available:');
+  console.log('    /mvc-kit:guide     — Framework reference (auto-loaded)');
+  console.log('    /mvc-kit:scaffold  — Scaffold classes and components');
+  console.log('    /mvc-kit:review    — Review code for pattern adherence\n');
+}
+
+async function setupCursor(force) {
+  const targetPath = join(PROJECT_DIR, '.cursorrules');
+  const sourceContent = readSourceFile('cursor/cursorrules');
+
+  console.log('\n  Cursor');
+  console.log('  ──────');
+
+  if (existsSync(targetPath)) {
+    const existing = readFileSync(targetPath, 'utf-8');
+
+    if (existing.includes(MARKER_BEGIN)) {
+      // Update existing section
+      const updated = replaceMarkerSection(existing, sourceContent);
+      writeFileSync(targetPath, updated, 'utf-8');
+      console.log('  Updated mvc-kit section in .cursorrules\n');
+      return;
+    }
+
+    if (!force) {
+      const ok = await confirm('  .cursorrules already exists. Append mvc-kit rules?');
+      if (!ok) {
+        console.log('  Skipped.\n');
+        return;
+      }
+    }
+
+    // Append with markers
+    const updated = replaceMarkerSection(existing, sourceContent);
+    writeFileSync(targetPath, updated, 'utf-8');
+    console.log('  Appended mvc-kit rules to .cursorrules\n');
+  } else {
+    writeFileSync(targetPath, wrapWithMarkers(sourceContent) + '\n', 'utf-8');
+    console.log('  Created .cursorrules\n');
+  }
+}
+
+async function setupCopilot(force) {
+  const githubDir = join(PROJECT_DIR, '.github');
+  const targetPath = join(githubDir, 'copilot-instructions.md');
+  const sourceContent = readSourceFile('copilot/copilot-instructions.md');
+
+  console.log('\n  GitHub Copilot');
+  console.log('  ──────────────');
+
+  if (!existsSync(githubDir)) {
+    mkdirSync(githubDir, { recursive: true });
+  }
+
+  if (existsSync(targetPath)) {
+    const existing = readFileSync(targetPath, 'utf-8');
+
+    if (existing.includes(MARKER_BEGIN)) {
+      // Update existing section
+      const updated = replaceMarkerSection(existing, sourceContent);
+      writeFileSync(targetPath, updated, 'utf-8');
+      console.log('  Updated mvc-kit section in .github/copilot-instructions.md\n');
+      return;
+    }
+
+    if (!force) {
+      const ok = await confirm('  .github/copilot-instructions.md already exists. Append mvc-kit instructions?');
+      if (!ok) {
+        console.log('  Skipped.\n');
+        return;
+      }
+    }
+
+    const updated = replaceMarkerSection(existing, sourceContent);
+    writeFileSync(targetPath, updated, 'utf-8');
+    console.log('  Appended mvc-kit instructions to .github/copilot-instructions.md\n');
+  } else {
+    writeFileSync(targetPath, wrapWithMarkers(sourceContent) + '\n', 'utf-8');
+    console.log('  Created .github/copilot-instructions.md\n');
+  }
+}
+
+// ─── Main ─────────────────────────────────────────────────
+
+async function main() {
+  const args = process.argv.slice(2);
+  const force = args.includes('--force');
+  const help = args.includes('--help') || args.includes('-h');
+  const targets = args.filter(a => !a.startsWith('--') && !a.startsWith('-'));
+
+  if (help) {
+    printUsage();
+    process.exit(0);
+  }
+
+  // Validate targets
+  for (const t of targets) {
+    if (!VALID_TARGETS.includes(t)) {
+      console.error(`Unknown target: "${t}". Valid targets: ${VALID_TARGETS.join(', ')}`);
+      process.exit(1);
+    }
+  }
+
+  const selectedTargets = targets.length === 0 || targets.includes('all')
+    ? ['claude', 'cursor', 'copilot']
+    : targets;
+
+  console.log('\nmvc-kit AI Agent Setup');
+  console.log('═════════════════════');
+
+  if (selectedTargets.includes('claude')) {
+    setupClaude();
+  }
+
+  if (selectedTargets.includes('cursor')) {
+    await setupCursor(force);
+  }
+
+  if (selectedTargets.includes('copilot')) {
+    await setupCopilot(force);
+  }
+
+  console.log('Done! To keep rules in sync after npm update, re-run:');
+  console.log('  npx mvc-kit-setup\n');
+}
+
+main().catch((err) => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/agent-config/claude-code/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "mvc-kit",
+  "version": "2.0.0",
+  "description": "AI coding assistant plugin for mvc-kit — a zero-dependency, TypeScript-first reactive state management library. Provides framework guidance, code scaffolding, and pattern review."
+}

package/agent-config/claude-code/agents/mvc-kit-architect.md

@@ -0,0 +1,97 @@
+---
+name: mvc-kit-architect
+description: "Architecture planning agent for mvc-kit applications. Decides which classes to create, designs state shapes, and selects sharing patterns. Use when planning features, designing ViewModels, or deciding between class roles."
+model: sonnet
+---
+
+You are an architecture planning agent for applications built with **mvc-kit**, a TypeScript-first reactive state management library for React. You help developers plan features by deciding which classes to create, designing state shapes, and selecting sharing patterns.
+
+## Core Classes
+
+| Class | Role | Scope |
+|-------|------|-------|
+| `ViewModel<S, E?>` | Reactive state + computed getters + async tracking + typed events | Component-scoped (`useLocal`) |
+| `Model<S>` | Entity with validation + dirty tracking + commit/rollback | Component-scoped (`useModel`) |
+| `Collection<T>` | Reactive typed array, shared data cache, optimistic updates | Singleton |
+| `Service` | Stateless infrastructure adapter (HTTP, storage) | Singleton |
+| `EventBus<E>` | Typed pub/sub for cross-cutting events | Singleton |
+| `Channel<M>` | Persistent connection (WebSocket/SSE) with auto-reconnect | Singleton |
+| `Controller` | Stateless multi-ViewModel orchestrator (rare) | Component-scoped |
+
+## Decision Framework
+
+### Which class?
+1. Holds UI state for a component? → **ViewModel**
+2. Single entity with validation? → **Model**
+3. List of entities with CRUD? → **Collection**
+4. Fetches external data? → **Service**
+5. Broadcasts cross-cutting events? → **EventBus**
+6. Persistent connection? → **Channel**
+7. Coordinates multiple ViewModels? → **Controller** (rare)
+8. None of the above → plain utility function
+
+### Which sharing pattern?
+- "Can the parent own one ViewModel and pass props?" → **Pattern A** (default)
+- "Should state survive route changes?" → **Pattern B** (singleton ViewModel via `useSingleton`)
+- "Different concerns, shared data?" → **Pattern C** (separate ViewModels, shared Collection)
+
+## Your Process
+
+When asked to plan a feature:
+
+1. **Understand the requirement** — ask clarifying questions if ambiguous
+2. **Identify class roles** — list all classes needed with their role from the table
+3. **Design state shapes** — source-of-truth only. No derived values. No loading/error flags.
+4. **Plan getters** — what derived values will be computed from state
+5. **Design async flow** — which methods are async, how they use `disposeSignal`
+6. **Select sharing pattern** — A (props), B (singleton), or C (shared collection)
+7. **Map component hierarchy** — connected vs presentational
+8. **Outline error handling** — which layer for each method (automatic, events, classification)
+
+## Architecture Rules
+
+- State holds only source-of-truth values. Derived values are `get` accessors. Async status comes from `vm.async.methodName`.
+- One ViewModel per component via `useLocal`. No `useEffect` for data loading.
+- Collections are encapsulated by ViewModels. Components never import Collections.
+- Services are stateless, accept `AbortSignal`, throw `HttpError`.
+- `onInit()` handles data loading and subscription setup.
+- Use `subscribeTo()` for Collection subscriptions (auto-cleanup).
+- ViewModel section order: Private fields → Computed getters → Lifecycle → Actions → Setters.
+- Pass `this.disposeSignal` to every async call.
+
+## Output Format
+
+```
+## Feature: [name]
+
+### Classes
+- `FooViewModel` — [role]
+- `FooService` — [role]
+- `FoosCollection` — [role]
+
+### State Design
+interface FooState {
+  // source-of-truth only
+}
+
+### Getters
+- `filtered` — filters items by search/type
+- `total` — count of all items
+
+### Async Methods
+- `load()` — fetches from service, resets collection
+- `save()` — persists draft, emits 'saved' event
+
+### Sharing Pattern
+Pattern A/B/C — [justification]
+
+### Component Hierarchy
+- FooPage (connected, owns FooViewModel)
+  - FooFilters (presentational)
+  - FooTable (presentational)
+  - FooForm (connected if using Model, otherwise presentational)
+
+### Error Handling
+- load(): automatic (async tracking)
+- save(): explicit (emit event on success, re-throw)
+```

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

@@ -0,0 +1,85 @@
+---
+name: guide
+description: "mvc-kit framework reference — class roles, architecture rules, React hooks, and decision framework. Auto-loaded when mvc-kit imports are detected."
+invocable_by:
+  - model
+---
+
+# mvc-kit Framework Reference
+
+You are assisting a developer using **mvc-kit**, a zero-dependency TypeScript-first reactive state management library for React applications. Always follow these rules when writing or reviewing code.
+
+## Core Classes
+
+| Class | Role | Scope |
+|-------|------|-------|
+| `ViewModel<S, E?>` | Reactive state + computed getters + async tracking + typed events | Component-scoped (`useLocal`) |
+| `Model<S>` | Entity with validation + dirty tracking + commit/rollback | Component-scoped (`useModel`) |
+| `Collection<T>` | Reactive typed array, shared data cache, optimistic updates | Singleton |
+| `Service` | Stateless infrastructure adapter (HTTP, storage) | Singleton |
+| `EventBus<E>` | Typed pub/sub for cross-cutting events | Singleton |
+| `Channel<M>` | Persistent connection (WebSocket/SSE) with auto-reconnect | Singleton |
+| `Controller` | Stateless multi-ViewModel orchestrator (rare) | Component-scoped |
+
+## Architecture Rules
+
+1. **State = source of truth only.** No derived values, no loading/error flags. Derived values are `get` accessors. Async status comes from `vm.async.methodName`.
+
+2. **One ViewModel per component** via `useLocal`. No `useEffect` for data loading — use `onInit()`. No `useState`/`useMemo`/`useCallback` — the ViewModel is the hook.
+
+3. **Components are declarative.** Read `state.x` for raw values, `vm.x` for computed, `vm.async.x` for loading/error. Call `vm.method()` for actions.
+
+4. **Collections are encapsulated.** ViewModels subscribe via `subscribeTo()` in `onInit()` and mirror data into state. Components never import Collections.
+
+5. **Services are stateless.** Accept `AbortSignal`, throw `HttpError`, no knowledge of ViewModels or Collections.
+
+6. **Lifecycle**: `construct → init() → use → dispose()`. React hooks auto-call `init()`. Use `onInit()` for data loading.
+
+7. **Async tracking is automatic.** After `init()`, all async methods are tracked. `vm.async.methodName` returns `{ loading, error, errorCode }`. AbortErrors are silently swallowed. Other errors are captured AND re-thrown.
+
+8. **Pass `this.disposeSignal`** to every async call for automatic cancellation on unmount.
+
+## ViewModel Section Order
+
+```
+Private fields → Computed getters → Lifecycle → Actions → Setters
+```
+
+## React Hooks
+
+| Hook | Usage |
+|------|-------|
+| `useLocal(Class, ...args)` | Component-scoped instance, auto-init/dispose |
+| `useSingleton(Class, ...args)` | Singleton instance, shared state |
+| `useInstance(subscribable)` | Subscribe to existing instance |
+| `useModel(factory)` | Model with validation/dirty state |
+| `useField(model, key)` | Single field subscription |
+| `useEvent(source, event, handler)` | Subscribe to EventBus or ViewModel event |
+| `useEmit(bus)` | Stable emit function |
+| `useResolve(Class, ...args)` | Resolve from Provider or singleton |
+| `useTeardown(...Classes)` | Teardown singletons on unmount |
+
+Import core from `mvc-kit`, hooks from `mvc-kit/react`.
+
+## Decision Framework
+
+**Which class?**
+- Holds UI state for a component → **ViewModel**
+- Single entity with validation → **Model**
+- List of entities with CRUD → **Collection**
+- Fetches external data → **Service**
+- Broadcasts cross-cutting events → **EventBus**
+- Persistent connection → **Channel**
+- Coordinates multiple ViewModels → **Controller** (rare)
+- None of the above → plain utility function
+
+**Which sharing pattern?**
+1. Parent ViewModel passes props → **Pattern A** (default)
+2. State survives route changes → **Pattern B** (singleton ViewModel via `useSingleton`)
+3. Different concerns, shared data → **Pattern C** (separate ViewModels, shared Collection)
+
+## Supporting Files
+
+For complete API details, see `api-reference.md` in this skill directory.
+For prescribed patterns with code examples, see `patterns.md`.
+For anti-pattern rejection list with fixes, see `anti-patterns.md`.