mvc-kit 2.1.0 → 2.2.0

package/README.md

@@ -21,16 +21,12 @@ mvc-kit ships with built-in context for AI coding assistants — stays in sync w
 
 ```bash
 npx mvc-kit-setup          # Set up all agents
+npx mvc-kit-setup claude   # Claude Code only
 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).
+**Claude Code** — installs `.claude/rules/` and `.claude/commands/`. Auto-updates on subsequent `npm install`/`npm update`.
 
 **Cursor** — writes `.cursorrules`. **Copilot** — writes `.github/copilot-instructions.md`. Both use idempotent markers, safe to re-run.
 

package/agent-config/bin/postinstall.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+import { existsSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// INIT_CWD is set by npm/yarn/pnpm during lifecycle scripts — points to the project root
+const projectRoot = process.env.INIT_CWD;
+
+if (!projectRoot) {
+  process.exit(0);
+}
+
+// Detect self-install (developing mvc-kit itself) — skip
+const ownPackageRoot = resolve(__dirname, '../..');
+if (resolve(projectRoot) === ownPackageRoot) {
+  process.exit(0);
+}
+
+// If the developer previously opted in (files exist), auto-update them
+const rulesFile = join(projectRoot, '.claude', 'rules', 'mvc-kit.md');
+
+if (existsSync(rulesFile)) {
+  try {
+    const { installClaude } = await import('../lib/install-claude.mjs');
+    installClaude(projectRoot);
+    console.log('');
+    console.log('  mvc-kit — Claude Code rules updated');
+    console.log('');
+  } catch {
+    // Never break npm install
+  }
+} else {
+  console.log('');
+  console.log('  mvc-kit — AI agent setup available');
+  console.log('  Run: npx mvc-kit-setup');
+  console.log('');
+}

package/agent-config/bin/setup.mjs

@@ -4,6 +4,7 @@ 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';
+import { installClaude } from '../lib/install-claude.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -22,7 +23,7 @@ function printUsage() {
 Usage: npx mvc-kit-setup [targets...] [options]
 
 Targets:
-  claude     Set up Claude Code plugin (prints usage instructions)
+  claude     Install Claude Code rules and commands into .claude/
   cursor     Copy mvc-kit rules to .cursorrules
   copilot    Copy mvc-kit instructions to .github/copilot-instructions.md
   all        Set up all targets (default)
@@ -77,18 +78,17 @@ async function confirm(message) {
 // ─── Target Handlers ──────────────────────────────────────
 
 function setupClaude() {
-  const pluginDir = join(AGENT_CONFIG_DIR, 'claude-code');
+  const { files } = installClaude(PROJECT_DIR);
 
   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');
+  console.log('  Installed (updates automatically on npm install/update):\n');
+  for (const f of files) {
+    console.log(`    ${f}`);
+  }
+  console.log('');
+  console.log('  Commands:  /project:mvc-kit-scaffold, /project:mvc-kit-review');
+  console.log('  Reference: Auto-loaded via .claude/rules/mvc-kit.md\n');
 }
 
 async function setupCursor(force) {
@@ -207,8 +207,7 @@ async function main() {
     await setupCopilot(force);
   }
 
-  console.log('Done! To keep rules in sync after npm update, re-run:');
-  console.log('  npx mvc-kit-setup\n');
+  console.log('Done!\n');
 }
 
 main().catch((err) => {

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

@@ -0,0 +1,87 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const SKILLS_DIR = join(__dirname, '..', 'claude-code', 'skills');
+
+const AUTO_HEADER = '<!-- Auto-generated by mvc-kit. Updated on npm install/update. Do not edit. -->\n\n';
+
+function stripFrontmatter(content) {
+  const match = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
+  return match ? match[1].trim() : content.trim();
+}
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Install Claude Code integration files into a project's .claude/ directory.
+ *
+ * Creates:
+ *   .claude/rules/mvc-kit.md          — Framework reference (always loaded in context)
+ *   .claude/commands/mvc-kit-scaffold.md — Scaffold command (/project:mvc-kit-scaffold)
+ *   .claude/commands/mvc-kit-review.md   — Review command (/project:mvc-kit-review)
+ *
+ * @param {string} projectRoot — Absolute path to the consuming project's root
+ * @returns {{ files: string[] }} — List of created/updated file paths (relative to projectRoot)
+ */
+export function installClaude(projectRoot) {
+  const claudeDir = join(projectRoot, '.claude');
+  const rulesDir = join(claudeDir, 'rules');
+  const commandsDir = join(claudeDir, 'commands');
+
+  ensureDir(rulesDir);
+  ensureDir(commandsDir);
+
+  const files = [];
+
+  // 1. Rules file — framework reference (always loaded in context)
+  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
+    .replace(/\n## Supporting Files[\s\S]*$/, '');
+
+  const rulesContent = AUTO_HEADER + guideBody + `
+
+## 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
+`;
+
+  writeFileSync(join(rulesDir, 'mvc-kit.md'), rulesContent, 'utf-8');
+  files.push('.claude/rules/mvc-kit.md');
+
+  // 2. Scaffold command
+  const scaffoldSkill = readFileSync(join(SKILLS_DIR, 'scaffold', 'SKILL.md'), 'utf-8');
+  const scaffoldBody = stripFrontmatter(scaffoldSkill)
+    .replace(
+      'Read the template file from `templates/<type>.md` in this skill directory.',
+      'Read the template file from `node_modules/mvc-kit/agent-config/claude-code/skills/scaffold/templates/<type>.md`.'
+    );
+
+  writeFileSync(join(commandsDir, 'mvc-kit-scaffold.md'), AUTO_HEADER + scaffoldBody, 'utf-8');
+  files.push('.claude/commands/mvc-kit-scaffold.md');
+
+  // 3. Review command
+  const reviewSkill = readFileSync(join(SKILLS_DIR, 'review', 'SKILL.md'), 'utf-8');
+  const reviewBody = stripFrontmatter(reviewSkill)
+    .replaceAll(
+      '`checklist.md`',
+      '`node_modules/mvc-kit/agent-config/claude-code/skills/review/checklist.md`'
+    );
+
+  writeFileSync(join(commandsDir, 'mvc-kit-review.md'), AUTO_HEADER + reviewBody, 'utf-8');
+  files.push('.claude/commands/mvc-kit-review.md');
+
+  return { files };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mvc-kit",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Zero-magic, class-based reactive ViewModel library",
   "type": "module",
   "main": "./dist/mvc-kit.cjs",
@@ -40,6 +40,7 @@
     "dev": "vite",
     "dev:fullapp": "vite --config examples/react/FullApp/vite.config.ts",
     "build": "rm -rf dist && tsc -p tsconfig.build.json && vite build",
+    "postinstall": "node agent-config/bin/postinstall.mjs",
     "test": "vitest run",
     "test:watch": "vitest"
   },