@nebulit/embuilder 0.1.39

package/README.md

@@ -0,0 +1,254 @@
+# EMBuilder
+
+Event-Model driven development toolkit for Claude Code. Generate code slices from event model specifications using simple slash commands.
+
+## Installation
+
+Super simple - install from GitHub Packages:
+
+```bash
+npx @dilgerma/embuilder install
+```
+
+That's it! The skills are now available in Claude Code.
+
+### Manual Installation (Alternative)
+
+If you want to install from a local directory:
+
+```bash
+cd /path/to/embuilder
+npm install
+npm run build
+npm link
+embuilder install
+```
+
+## What This Does
+
+This package adds powerful skills to Claude Code for event-model driven development:
+
+### Event Model Skills
+- `/automation-slice` - Generate automation slices (background processes with CRON)
+- `/state-change-slice` - Generate command handlers (business logic)
+- `/state-view-slice` - Generate read models/projections (queries and views)
+
+### Configuration Skills
+- `/fetch-config` - Fetch config.json from your event model app (localhost:3001)
+
+### Yeoman Generator Skills
+- `/gen-skeleton` - Generate a Supabase backend skeleton app
+- `/gen-state-change` - Generate state change slices from config.json
+- `/gen-state-view` - Generate state view slices from config.json
+- `/gen-automation` - Generate automation slices from config.json
+- `/gen-ui` - Set up a React UI project with shadcn/ui and Supabase
+
+All based on your event model specifications and configuration!
+
+## Quick Start
+
+### From GitHub Packages
+
+```bash
+npx @dilgerma/embuilder install
+```
+
+### From Local Directory
+
+```bash
+./install.sh
+```
+
+### Using the Skills
+
+In Claude Code, just type one of these commands:
+
+**Event Model Skills:**
+```
+/state-change-slice   # Generate a command handler
+/state-view-slice     # Generate a read model
+/automation-slice     # Generate a background automation
+```
+
+**Configuration:**
+```
+/fetch-config         # Fetch config from event model app
+```
+
+**Yeoman Generator Skills:**
+```
+/gen-skeleton         # Generate Supabase backend skeleton
+/gen-state-change     # Generate state change slices from config
+/gen-state-view       # Generate state view slices from config
+/gen-automation       # Generate automation slices from config
+/gen-ui               # Set up React UI project
+```
+
+Claude will:
+- Guide you through the generation process
+- Find your event model or config.json
+- Generate TypeScript code following best practices
+- Create tests automatically
+- Run the tests to verify everything works
+
+## Skills Overview
+
+### Event Model Skills
+
+#### `/automation-slice`
+Builds background automations that:
+- Read from TODO lists (work queues)
+- Fire commands on a CRON schedule
+- Process items automatically
+
+**Use case:** Auto-confirm invitations, process checkouts, send notifications
+
+#### `/state-change-slice`
+Builds command handlers that:
+- Accept commands (user actions)
+- Validate against current state
+- Emit events (facts about what happened)
+
+**Use case:** Register clerk, activate feature, submit timesheet
+
+#### `/state-view-slice`
+Builds read models that:
+- Subscribe to events
+- Build queryable views
+- Support UI and reporting
+
+**Use case:** Active shifts dashboard, clerk directory, event calendar
+
+### Yeoman Generator Skills
+
+#### `/gen-skeleton`
+Generates a complete Supabase backend skeleton app:
+- Event store setup
+- Basic project structure
+- Common utilities and helpers
+- Supabase configuration
+
+**Use case:** Bootstrap a new event-sourced application
+
+#### `/gen-state-change`, `/gen-state-view`, `/gen-automation`
+Generate slices from your `config.json` file:
+- Reads slice definitions from config
+- Generates complete TypeScript implementations
+- Creates API routes and tests
+- Works with Yeoman's template system
+
+**Use case:** Generate code from pre-defined slice configurations
+
+#### `/gen-ui`
+Sets up a modern React UI project:
+- Vite + React + TypeScript
+- shadcn/ui component library (Radix UI + Tailwind)
+- Supabase client integration
+- React Router and React Query
+- Full suite of pre-built UI components
+
+**Use case:** Quickly scaffold a frontend for your Supabase backend
+
+## Event Model Structure
+
+Your event model (JSON) typically defines:
+
+```json
+{
+  "commands": [
+    {
+      "title": "Register Clerk",
+      "fields": [
+        {"name": "clerkId", "type": "UUID"},
+        {"name": "name", "type": "String"}
+      ]
+    }
+  ],
+  "events": [
+    {
+      "title": "Clerk Registered",
+      "fields": [...]
+    }
+  ],
+  "processors": [...],
+  "readmodels": [...]
+}
+```
+
+## Generated Code Structure
+
+```
+src/slices/{slice-name}/
+├── CommandHandler.ts    # Business logic (state-change)
+├── Projection.ts        # Read model (state-view)
+├── processor.ts         # CRON automation (automation)
+├── routes.ts            # HTTP API endpoints
+├── {SliceName}.test.ts  # Automated tests
+└── ui/                  # UI components (optional)
+```
+
+## Commands
+
+```bash
+# Install skills only
+npx @dilgerma/embuilder install
+
+# Install skills + template files (ralph.sh, AGENTS.md, Claude.md, prompt.md)
+npx @dilgerma/embuilder install --with-templates
+
+# Uninstall
+npx @dilgerma/embuilder uninstall
+
+# Check status
+npx @dilgerma/embuilder status
+```
+
+### Template Files
+
+When you use `--with-templates`, you get:
+
+- **`ralph.sh`** - Autonomous agent loop for continuous development
+- **`AGENTS.md`** - Track learnings and patterns from development
+- **`Claude.md`** - Project-specific configuration for Claude Code
+- **`prompt.md`** - Agent instructions for automated development
+- **`.claude/hooks/`** - Pre-commit hooks that analyze git diffs before commits
+  - Includes built-in analyzers for code quality and event model validation
+  - Extensible with custom TypeScript analyzers
+
+These files enable the full event-model driven development workflow with autonomous agents.
+
+### Git Commit Hooks
+
+The template includes a pre-commit hook system that automatically analyzes changes before commits:
+
+**Built-in Analyzers:**
+- **Code Quality Checker** - Detects console.log, debugger statements, TODOs, and potential secrets
+- **Event Model Validator** - Ensures event naming conventions and slice structure
+- **Logger** - Displays commit statistics and changed files
+
+**Features:**
+- Written in TypeScript for type safety
+- Extensible - add your own analyzers
+- Non-blocking by default
+- Integrates seamlessly with Claude Code
+
+See `.claude/hooks/README.md` for full documentation on creating custom analyzers.
+
+## Philosophy
+
+This toolkit follows **event-model driven development**:
+
+1. **Design first** - Define your event model (events, commands, aggregates)
+2. **Generate code** - Use Claude skills to generate implementation
+3. **Test automatically** - Generated code includes tests
+4. **Iterate quickly** - Change the model, regenerate
+
+## Requirements
+
+- Node.js 18+
+- Claude Code CLI
+- TypeScript knowledge (for understanding generated code)
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { existsSync, chmodSync, cpSync, rmSync, readdirSync, statSync } from 'fs';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const program = new Command();
+const SKILLS_DIR = join(process.cwd(), '.claude', 'skills');
+program
+    .name('embuilder')
+    .description('EMBuilder - Event-Model driven development toolkit for Claude Code')
+    .version('0.1.22');
+program
+    .command('install')
+    .description('Install event-model skills into Claude Code')
+    .option('--with-templates', 'Also copy template files (ralph.sh, AGENTS.md, Claude.md, prompt.md, README.md) and generators to current directory')
+    .action((options) => {
+    console.log('📦 Installing EMBuilder...\n');
+    try {
+        // Copy template files if requested
+        console.log('\n📄 Copying all templates to current directory...');
+        const templatesSource = join(__dirname, '..', 'templates');
+        const targetDir = process.cwd();
+        if (!existsSync(templatesSource)) {
+            console.error('❌ Templates directory not found!');
+            console.error(`   Expected location: ${templatesSource}`);
+            console.error(`   Package location: ${__dirname}`);
+            console.error('');
+            console.error('This might be caused by:');
+            console.error('  1. Old cached version - try: npx --yes @dilgerma/embuilder@latest install --with-templates');
+            console.error('  2. Package not published correctly - reinstall with: npm install -g @dilgerma/embuilder@latest');
+            console.error('');
+            console.error('If the problem persists, please report at:');
+            console.error('  https://github.com/dilgerma/embuilder/issues');
+            process.exit(1);
+        }
+        // Copy everything from templates/ to current directory
+        try {
+            // Read all items in templates directory and copy each one
+            // We copy items individually instead of the entire directory to have better control
+            const items = readdirSync(templatesSource);
+            for (const item of items) {
+                const sourcePath = join(templatesSource, item);
+                const targetPath = join(targetDir, item);
+                // Skip node_modules if present
+                if (item === 'node_modules') {
+                    continue;
+                }
+                try {
+                    const stat = statSync(sourcePath);
+                    if (stat.isDirectory()) {
+                        // For directories, copy with filter to skip node_modules
+                        cpSync(sourcePath, targetPath, {
+                            recursive: true,
+                            filter: (source) => {
+                                // Get the relative path from the source directory to avoid matching
+                                // 'node_modules' in the npx cache path itself
+                                const relativePath = source.replace(sourcePath, '');
+                                return !relativePath.includes('node_modules');
+                            }
+                        });
+                    }
+                    else {
+                        // For files, copy directly
+                        cpSync(sourcePath, targetPath);
+                    }
+                }
+                catch (itemError) {
+                    console.error(`  ❌ Error copying ${item}:`, itemError?.message);
+                }
+                // Verify this item was copied
+                if (!existsSync(targetPath)) {
+                    console.error(`  ❌ Failed to copy: ${item}`);
+                }
+            }
+        }
+        catch (copyError) {
+            console.error('  ❌ Error during copy:', copyError);
+            throw copyError;
+        }
+        // Verify files were actually copied
+        const copiedFiles = existsSync(join(targetDir, 'README.md'));
+        // Make ralph.sh executable if it exists
+        const ralphPath = join(targetDir, 'ralph.sh');
+        if (existsSync(ralphPath)) {
+            chmodSync(ralphPath, 0o755);
+            console.log('  ✓ Made ralph.sh executable');
+        }
+        if (!copiedFiles) {
+            console.error('  ❌ Files were not copied! This is a bug.');
+            console.error('  Please report this at: https://github.com/dilgerma/embuilder/issues');
+            process.exit(1);
+        }
+        console.log('  ✓ All template files and directories copied');
+        console.log('    - README.md, Claude.md, AGENTS.md, prompt.md, ralph.sh');
+        console.log('    - .claude/ directory with skills and generators');
+        console.log('    - All other template contents');
+        console.log('\n📝 Templates copied! You can now:');
+        console.log('  - Read README.md for detailed usage instructions');
+        console.log('  - Edit Claude.md with project-specific settings');
+        console.log('  - Run ./ralph.sh for automated development loops');
+        console.log('  - Track learnings in AGENTS.md');
+        console.log('  - Use skills in .claude/skills/ for code generation');
+        console.log('\n✅ Installation complete with templates!');
+        console.log("\n💡Want to initialize the project? Just run this command:");
+        console.log("\ndocker run -v $PWD:/workspace nebulit/generators");
+    }
+    catch (error) {
+        console.error('❌ Installation failed:', error);
+        process.exit(1);
+    }
+});
+program
+    .command('uninstall')
+    .description('Remove event-model skills from Claude Code')
+    .action(() => {
+    if (existsSync(SKILLS_DIR)) {
+        rmSync(SKILLS_DIR, { recursive: true, force: true });
+        console.log('✅ EMBuilder skills uninstalled');
+    }
+    else {
+        console.log('ℹ️  Skills not currently installed');
+    }
+});
+program
+    .command('status')
+    .description('Check installation status')
+    .action(() => {
+    console.log('EMBuilder Skills Status\n');
+    console.log(`Installation path: ${SKILLS_DIR}`);
+    console.log(`Installed: ${existsSync(SKILLS_DIR) ? '✅ Yes' : '❌ No'}`);
+    if (existsSync(SKILLS_DIR)) {
+        const skillsSource = join(__dirname, '..', 'skills');
+        console.log(`Source: ${skillsSource}`);
+    }
+});
+program.parse();

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@nebulit/embuilder",
+  "version": "0.1.39",
+  "description": "Event-model driven development toolkit for Claude Code",
+  "type": "module",
+  "bin": {
+    "embuilder": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x dist/cli.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "event-model",
+    "code-generation",
+    "ddd",
+    "event-sourcing",
+    "event-driven",
+    "cqrs",
+    "yeoman-generator"
+  ],
+  "files": [
+    "dist",
+    "templates",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dilgerma/embuilder.git"
+  },
+  "author": "Martin Dilger",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "^12.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/templates/.claude/hooks/QUICKSTART.md

@@ -0,0 +1,256 @@
+# Git Commit Hooks - Quick Start
+
+This guide gets you up and running with git commit hooks in 5 minutes.
+
+## Installation
+
+If you installed EMBuilder with `--with-templates`, the hooks are already set up!
+
+```bash
+npx @dilgerma/embuilder install --with-templates
+```
+
+## Prerequisites
+
+Install `tsx` to run TypeScript analyzers:
+
+```bash
+npm install -g tsx
+```
+
+## What You Get
+
+When Claude commits code, these analyzers run automatically:
+
+### 1. Code Quality Checker
+Warns about:
+- `console.log` statements
+- `debugger` statements
+- TODO/FIXME comments
+- Potential secrets (API keys, passwords)
+
+### 2. Event Model Validator
+Validates:
+- Event names use past-tense
+- Tests are updated with logic changes
+- Slice structure follows conventions
+
+### 3. Example Logger
+Shows:
+- Branch name
+- Files changed
+- Staged/unstaged status
+
+## Try It Out
+
+1. **Make a change and commit**
+
+```bash
+echo "console.log('test')" >> test.ts
+git add test.ts
+git commit -m "test commit"
+```
+
+2. **See the hook in action**
+
+You'll see output like:
+
+```
+🔍 Running git diff analyzers...
+  → Running analyzer: code-quality-checker.ts
+🔍 Code Quality Analysis:
+   ⚠️  Warnings:
+      - Found 1 console.log statement(s) - consider removing debug code
+✅ Analyzers completed
+```
+
+## Customizing
+
+### Disable an analyzer
+
+```bash
+# Rename to disable
+mv .claude/hooks/analyzers/example-logger.ts \
+   .claude/hooks/analyzers/example-logger.ts.disabled
+```
+
+### Create your own analyzer
+
+```bash
+# Create new analyzer
+cat > .claude/hooks/analyzers/my-check.ts << 'EOF'
+#!/usr/bin/env node
+import { readFileSync } from 'fs';
+
+interface HookData {
+  changed_files: string[];
+  staged_diff: string;
+}
+
+async function main() {
+  const data: HookData = JSON.parse(readFileSync(0, 'utf-8'));
+
+  console.log('🔍 My Custom Check:');
+
+  // Check if package.json changed
+  if (data.changed_files.includes('package.json')) {
+    console.log('   ⚠️  package.json changed - remember to run npm install');
+  }
+}
+
+main();
+EOF
+
+# Test it
+echo '{"changed_files":["package.json"],"staged_diff":""}' | \
+  tsx .claude/hooks/analyzers/my-check.ts
+```
+
+## Advanced Configuration
+
+Edit `.claude/settings.local.json` to customize:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash(*git commit*)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/analyze-commit.sh",
+            "statusMessage": "Analyzing changes before commit",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Common Use Cases
+
+### Enforce Commit Message Format
+
+Create `.claude/hooks/analyzers/commit-msg-validator.ts`:
+
+```typescript
+import { readFileSync } from 'fs';
+import { execSync } from 'child_process';
+
+async function main() {
+  // Get the last commit message from git
+  const msg = execSync('git log -1 --pretty=%B').toString().trim();
+
+  // Check format: "type: description"
+  const pattern = /^(feat|fix|docs|style|refactor|test|chore):\s.{10,}$/;
+
+  if (!pattern.test(msg)) {
+    console.error('❌ Invalid commit message format');
+    console.error('   Expected: "type: description" (at least 10 chars)');
+    console.error('   Types: feat, fix, docs, style, refactor, test, chore');
+    process.exit(1); // Block commit
+  }
+
+  console.log('✅ Commit message format valid');
+}
+
+main();
+```
+
+### Check for Breaking Changes
+
+Create `.claude/hooks/analyzers/breaking-changes.ts`:
+
+```typescript
+import { readFileSync } from 'fs';
+
+interface HookData {
+  changed_files: string[];
+  staged_diff: string;
+}
+
+async function main() {
+  const data: HookData = JSON.parse(readFileSync(0, 'utf-8'));
+
+  // Check if public API files changed
+  const apiFiles = data.changed_files.filter(f =>
+    f.includes('/api/') ||
+    f.includes('public') ||
+    f.endsWith('types.ts')
+  );
+
+  if (apiFiles.length > 0) {
+    console.log('⚠️  Public API files changed:');
+    apiFiles.forEach(f => console.log(`   - ${f}`));
+    console.log('\n💡 Consider:');
+    console.log('   - Updating CHANGELOG.md');
+    console.log('   - Bumping version number');
+    console.log('   - Adding migration guide');
+  }
+}
+
+main();
+```
+
+### Run Tests Before Commit
+
+Create `.claude/hooks/analyzers/run-tests.ts`:
+
+```typescript
+import { execSync } from 'child_process';
+
+async function main() {
+  console.log('🧪 Running tests...');
+
+  try {
+    execSync('npm test', { stdio: 'inherit' });
+    console.log('✅ All tests passed');
+  } catch (error) {
+    console.error('❌ Tests failed - commit blocked');
+    process.exit(1);
+  }
+}
+
+main();
+```
+
+## Troubleshooting
+
+### Hook not running?
+
+1. Check configuration in `.claude/settings.local.json`
+2. Verify hook script is executable:
+   ```bash
+   chmod +x .claude/hooks/analyze-commit.sh
+   ```
+
+### TypeScript errors?
+
+1. Install tsx: `npm install -g tsx`
+2. Check TypeScript syntax in your analyzer
+3. Test manually:
+   ```bash
+   echo '{}' | tsx .claude/hooks/analyzers/your-analyzer.ts
+   ```
+
+### Analyzer not executing?
+
+1. Verify file is in `.claude/hooks/analyzers/`
+2. Check file has `.ts` extension
+3. Look for error messages in hook output
+
+## Next Steps
+
+- Read full documentation: `.claude/hooks/README.md`
+- Explore built-in analyzers in `.claude/hooks/analyzers/`
+- Share your custom analyzers with the team
+- Configure blocking behavior for critical checks
+
+## Help & Support
+
+- Full docs: `.claude/hooks/README.md`
+- Report issues: https://github.com/dilgerma/embuilder/issues
+- Examples: See `.claude/hooks/analyzers/` directory