start-vibing 2.0.2 → 2.0.4

package/template/.claude/skills/bun-runtime/SKILL.md

@@ -0,0 +1,430 @@
+---
+name: bun-runtime
+description: Bun runtime patterns and best practices. Package management, bundling, testing, scripts. Use when working with Bun as the JavaScript runtime.
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Bun Runtime - Fast JavaScript Runtime
+
+## Purpose
+
+Expert guidance for Bun:
+
+- **Package Management** - Fast installation
+- **Bundling** - Built-in bundler
+- **Testing** - Vitest-compatible runner
+- **Scripts** - Task runner
+- **APIs** - Bun-specific features
+
+---
+
+## Package Management
+
+### Install Dependencies
+
+```bash
+# Install all dependencies
+bun install
+
+# Add dependency
+bun add zod mongoose
+
+# Add dev dependency
+bun add -D typescript @types/node
+
+# Add exact version
+bun add react@18.2.0
+
+# Add from GitHub
+bun add github:user/repo
+
+# Remove dependency
+bun remove lodash
+
+# Update dependencies
+bun update
+
+# Update specific package
+bun update react
+```
+
+### bunfig.toml
+
+```toml
+# bunfig.toml
+[install]
+# Disable postinstall scripts for security
+ignorescripts = true
+
+# Registry configuration
+registry = "https://registry.npmjs.org"
+
+# Install settings
+frozen-lockfile = true
+
+[run]
+# Shell for scripts
+shell = "bash"
+```
+
+---
+
+## Script Commands
+
+### package.json Scripts
+
+```json
+{
+  "scripts": {
+    "dev": "bun run --hot src/index.ts",
+    "start": "bun run src/index.ts",
+    "build": "bun build src/index.ts --outdir dist",
+    "typecheck": "bunx tsc --noEmit",
+    "lint": "bunx eslint . --ext .ts,.tsx",
+    "lint:fix": "bunx eslint . --ext .ts,.tsx --fix",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage"
+  }
+}
+```
+
+### Running Scripts
+
+```bash
+# Run script
+bun run dev
+bun run build
+
+# Shorthand (without "run")
+bun dev
+bun build
+
+# Run TypeScript directly
+bun run src/index.ts
+
+# Hot reload
+bun run --hot src/index.ts
+
+# Watch mode
+bun run --watch src/index.ts
+```
+
+---
+
+## Bundling
+
+### Basic Bundle
+
+```bash
+# Bundle for browser
+bun build ./src/index.ts --outdir ./dist
+
+# Minify
+bun build ./src/index.ts --outdir ./dist --minify
+
+# Source maps
+bun build ./src/index.ts --outdir ./dist --sourcemap
+
+# Target
+bun build ./src/index.ts --outdir ./dist --target=browser
+bun build ./src/index.ts --outdir ./dist --target=node
+bun build ./src/index.ts --outdir ./dist --target=bun
+```
+
+### Build API
+
+```typescript
+// build.ts
+const result = await Bun.build({
+  entrypoints: ['./src/index.ts'],
+  outdir: './dist',
+  target: 'browser',
+  minify: true,
+  sourcemap: 'external',
+  splitting: true,
+  format: 'esm',
+  define: {
+    'process.env.NODE_ENV': '"production"',
+  },
+  external: ['react', 'react-dom'],
+});
+
+if (!result.success) {
+  console.error('Build failed:');
+  for (const log of result.logs) {
+    console.error(log);
+  }
+  process.exit(1);
+}
+```
+
+---
+
+## Testing (Vitest-compatible)
+
+### Test Configuration
+
+```typescript
+// bunfig.toml
+[test]
+preload = ["./tests/setup.ts"]
+coverage = true
+```
+
+### Test File
+
+```typescript
+// tests/example.test.ts
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+
+describe('Feature', () => {
+  beforeEach(() => {
+    // Setup
+  });
+
+  afterEach(() => {
+    // Cleanup
+  });
+
+  test('should work correctly', () => {
+    const result = 1 + 1;
+    expect(result).toBe(2);
+  });
+
+  test('async operations', async () => {
+    const data = await fetchData();
+    expect(data).toBeDefined();
+  });
+});
+```
+
+### Mocking
+
+```typescript
+import { mock, spyOn } from 'bun:test';
+
+// Mock function
+const mockFn = mock((x: number) => x * 2);
+mockFn(5);
+expect(mockFn).toHaveBeenCalledWith(5);
+expect(mockFn).toHaveReturnedWith(10);
+
+// Spy on existing function
+const spy = spyOn(console, 'log');
+console.log('test');
+expect(spy).toHaveBeenCalledWith('test');
+```
+
+---
+
+## Bun APIs
+
+### File System
+
+```typescript
+// Read file
+const text = await Bun.file('path/to/file.txt').text();
+const json = await Bun.file('path/to/file.json').json();
+const buffer = await Bun.file('path/to/file.bin').arrayBuffer();
+
+// Write file
+await Bun.write('output.txt', 'Hello, World!');
+await Bun.write('output.json', JSON.stringify({ hello: 'world' }));
+
+// File info
+const file = Bun.file('file.txt');
+console.log(file.size);
+console.log(file.type);
+```
+
+### HTTP Server
+
+```typescript
+// Simple server
+Bun.serve({
+  port: 3000,
+  fetch(request) {
+    const url = new URL(request.url);
+
+    if (url.pathname === '/api/hello') {
+      return Response.json({ message: 'Hello!' });
+    }
+
+    return new Response('Not Found', { status: 404 });
+  },
+});
+
+// With WebSocket
+Bun.serve({
+  port: 3000,
+  fetch(request, server) {
+    if (server.upgrade(request)) {
+      return;
+    }
+    return new Response('Upgrade failed', { status: 500 });
+  },
+  websocket: {
+    open(ws) {
+      console.log('Client connected');
+    },
+    message(ws, message) {
+      ws.send(`Echo: ${message}`);
+    },
+    close(ws) {
+      console.log('Client disconnected');
+    },
+  },
+});
+```
+
+### Subprocess
+
+```typescript
+// Run command
+const result = Bun.spawn(['echo', 'Hello']);
+await result.exited;
+
+// Capture output
+const proc = Bun.spawn(['git', 'status'], {
+  stdout: 'pipe',
+});
+const output = await new Response(proc.stdout).text();
+
+// With stdin
+const proc = Bun.spawn(['cat'], {
+  stdin: 'pipe',
+  stdout: 'pipe',
+});
+proc.stdin.write('Hello from stdin!');
+proc.stdin.end();
+```
+
+### Password Hashing
+
+```typescript
+// Hash password
+const hash = await Bun.password.hash('my-password', {
+  algorithm: 'bcrypt',
+  cost: 10,
+});
+
+// Verify password
+const isValid = await Bun.password.verify('my-password', hash);
+```
+
+### Environment Variables
+
+```typescript
+// Access env vars
+const apiKey = Bun.env['API_KEY'];
+const nodeEnv = Bun.env['NODE_ENV'] ?? 'development';
+
+// Set env vars
+Bun.env['CUSTOM_VAR'] = 'value';
+```
+
+---
+
+## Performance Tips
+
+### Use Native APIs
+
+```typescript
+// Prefer Bun APIs over Node.js equivalents
+
+// File reading
+// Node.js way (slower)
+import { readFile } from 'fs/promises';
+const content = await readFile('file.txt', 'utf-8');
+
+// Bun way (faster)
+const content = await Bun.file('file.txt').text();
+```
+
+### Import Optimization
+
+```typescript
+// Use namespace imports for tree-shaking
+import * as z from 'zod';
+
+// Avoid dynamic imports in hot paths
+// Bad:
+async function validate(data: unknown) {
+  const { z } = await import('zod');
+  return z.object({}).parse(data);
+}
+
+// Good:
+import { z } from 'zod';
+function validate(data: unknown) {
+  return z.object({}).parse(data);
+}
+```
+
+### Bundle for Production
+
+```bash
+# Compile to single executable
+bun build --compile ./src/index.ts --outfile myapp
+
+# Run compiled binary
+./myapp
+```
+
+---
+
+## Docker Integration
+
+```dockerfile
+# Use Bun official image
+FROM oven/bun:1-alpine AS base
+
+# Install dependencies
+FROM base AS deps
+WORKDIR /app
+COPY package.json bun.lockb ./
+RUN bun install --frozen-lockfile
+
+# Build
+FROM base AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN bun run build
+
+# Runtime
+FROM base AS runner
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/package.json ./
+
+EXPOSE 3000
+CMD ["bun", "run", "dist/index.js"]
+```
+
+---
+
+## Agent Integration
+
+This skill is used by:
+
+- **bun-runtime-expert** agent
+- **quality-checker** for running tests
+- **build-error-fixer** for build issues
+- **dockerfile-optimizer** for Docker builds
+
+---
+
+## FORBIDDEN
+
+1. **`npm` commands** - Use `bun` instead
+2. **Node.js fs when Bun.file works** - Use native APIs
+3. **Ignoring lockfile** - Always use `--frozen-lockfile` in CI
+4. **Skipping typecheck** - Run `bunx tsc --noEmit`
+
+---
+
+## Version
+
+- **v1.0.0** - Initial implementation based on Bun 1.x patterns

package/template/.claude/skills/codebase-knowledge/domains/claude-system.md

@@ -2,9 +2,9 @@
 
 ## Last Update
 
-- **Date:** 2026-01-02
-- **Commit:** 70ca50f
-- **Session:** Enhanced start-vibing CLI with auto-install Claude Code and self-update
+- **Date:** 2026-01-03
+- **Commit:** d429772
+- **Session:** Universal hook runner with multi-runtime fallback support
 
 ## Files
 
@@ -27,8 +27,15 @@
 
 ### Hooks
 
+- `.claude/hooks/run-hook.ts` - **NEW** Universal hook runner with multi-runtime fallback (python3 -> python -> bun -> npx tsx)
+- `.claude/hooks/run-hook.sh` - **NEW** Shell wrapper for Unix/Linux/Mac
+- `.claude/hooks/run-hook.cmd` - **NEW** Batch wrapper for Windows
 - `.claude/hooks/stop-validator.py` - Stop hook enforcement: branch protection + documentation check
+- `.claude/hooks/stop-validator.ts` - **NEW** TypeScript fallback version of stop-validator
 - `.claude/hooks/user-prompt-submit.py` - Agent selection guidance before prompt processing
+- `.claude/hooks/user-prompt-submit.ts` - **NEW** TypeScript fallback version of user-prompt-submit
+- `.claude/hooks/check-documentation.py` - Documentation verification hook
+- `.claude/hooks/SETUP.md` - Hook system documentation
 
 ### Skills (with Progressive Disclosure)
 
@@ -75,14 +82,47 @@
 
 | Hash | Date | Description |
 | ---- | ---- | ----------- |
+| d429772 | 2026-01-03 | feat(agents): restructure agent system with 82 specialized sub-agents |
 | 70ca50f | 2026-01-02 | feat(start-vibing): auto-install Claude Code and self-update |
 | 5c74c95 | 2026-01-02 | feat: add specialized agents and progressive disclosure to skills |
 | b5c483b | 2026-01-02 | docs: add agents/skills comparison research with industry benchmarks |
 | 0f2c1ff | 2026-01-02 | fix: block ALL changes on main branch, not just protected files |
-| 1f6f35f | 2026-01-02 | feat: enhance stop hook with system config file protection |
 
 ## Problems & Solutions
 
+### 2026-01-03 - Universal Hook Runner with Multi-Runtime Fallback
+
+**Problem:**
+Stop hook was failing with `/bin/sh: 1: python: not found` error when Python was not installed on the user's system.
+
+**Root Cause:**
+Hooks were hardcoded to use `python .claude/hooks/*.py` which fails if Python is not in PATH.
+
+**Solution:**
+Created a universal hook runner (`run-hook.ts`) that:
+1. Tries multiple runtimes in priority order: python3 -> python -> bun -> npx tsx
+2. Python remains primary (user preference)
+3. TypeScript versions of hooks serve as fallback
+4. Returns safe default if no runtime available (doesn't block user)
+
+**Files Added:**
+- `.claude/hooks/run-hook.ts` - Universal runner with runtime detection
+- `.claude/hooks/run-hook.sh` - Shell wrapper for Unix
+- `.claude/hooks/run-hook.cmd` - Batch wrapper for Windows
+- `.claude/hooks/stop-validator.ts` - TypeScript fallback
+- `.claude/hooks/user-prompt-submit.ts` - TypeScript fallback
+
+**Files Modified:**
+- `.claude/settings.json` - Updated hook commands to use `bun .claude/hooks/run-hook.ts <hook-name>`
+- `.claude/hooks/SETUP.md` - Updated documentation
+
+**Prevention:**
+- Always provide TypeScript fallbacks for Python hooks
+- Use runtime detection instead of hardcoded interpreter paths
+- Return safe defaults instead of failing
+
+---
+
 ### 2026-01-02 - start-vibing v2.0.0 with Auto-install and Self-update
 
 **Context:**
@@ -212,6 +252,8 @@ To make an agent invokable via Task tool, it needs to be registered in Claude Co
 
 ## Attention Points
 
+- [2026-01-03] **Hooks use universal runner** - `bun .claude/hooks/run-hook.ts <hook-name>` tries python3 -> python -> bun -> npx tsx
+- [2026-01-03] **TypeScript hook fallbacks** - All Python hooks have `.ts` versions for when Python unavailable
 - [2026-01-02] **System files protected alongside source** - CLAUDE.md, .claude/, PROJECT.md require branch protection
 - [2026-01-02] **CLAUDE.md fallback instruction** - If Task tool fails, read agent files directly from .claude/agents/
 - [2024-12-18] **Workflow is enforced by hooks** - Cannot skip steps, hooks will block