create-merlin-brain 3.10.0 → 3.12.0

package/files/merlin/templates/ci/docs-update.yml

@@ -0,0 +1,81 @@
+# Merlin Docs Update
+# Auto-updates documentation when code changes are pushed to main.
+# Detects stale docs, updates them, and opens a PR.
+#
+# Setup:
+#   1. Add ANTHROPIC_API_KEY to your repo secrets (Settings > Secrets > Actions)
+#   2. Copy this file to .github/workflows/docs-update.yml
+#
+name: Merlin Docs Update
+
+on:
+  push:
+    branches: [main]
+    paths:
+      # Trigger when source code changes (not docs themselves)
+      - 'src/**'
+      - 'app/**'
+      - 'lib/**'
+      - 'packages/**'
+      - '*.ts'
+      - '*.js'
+      - '*.py'
+      - '*.go'
+
+jobs:
+  docs-update:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Get changed files
+        id: changed
+        run: |
+          git diff --name-only HEAD~1 HEAD > /tmp/changed-files.txt
+          echo "Changed files:"
+          cat /tmp/changed-files.txt
+
+      - name: Merlin Docs Update
+        uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          prompt: |
+            The following files changed in the last commit (see /tmp/changed-files.txt):
+
+            Review the changed source files and identify any documentation that is now stale or missing.
+
+            Update documentation as needed:
+            - README.md — if public API, CLI commands, or setup steps changed
+            - docs/ files — if architecture, guides, or references are affected
+            - Inline JSDoc/comments — if function signatures or behavior changed
+
+            Rules:
+            - Only update docs that are genuinely stale due to the code changes
+            - Do not rewrite docs that are still accurate
+            - Keep the existing writing style and tone
+            - If no docs need updating, output: "No documentation updates needed."
+
+            After making changes, summarize what you updated and why.
+
+      - name: Create PR if docs changed
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: 'docs: auto-update documentation for recent changes'
+          title: 'docs: auto-update documentation'
+          body: |
+            Automated documentation update triggered by changes to source files.
+
+            This PR was generated by the Merlin Docs Update workflow.
+            Review the changes and merge if accurate.
+          branch: merlin/docs-update-${{ github.run_number }}
+          delete-branch: true
+          labels: documentation,automated

package/files/merlin/templates/ci/pr-review.yml

@@ -0,0 +1,50 @@
+# Merlin PR Review
+# Automatically reviews pull requests for code quality, security, and correctness.
+#
+# Setup:
+#   1. Add ANTHROPIC_API_KEY to your repo secrets (Settings > Secrets > Actions)
+#   2. Copy this file to .github/workflows/pr-review.yml
+#
+name: Merlin PR Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Merlin PR Review
+        uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          prompt: |
+            Review this pull request. Be concise and constructive.
+
+            Check for:
+            - Code quality and clarity
+            - Security issues (secrets, injections, auth gaps)
+            - Correctness (logic errors, edge cases, off-by-ones)
+            - Breaking changes or regressions
+            - Missing tests for critical paths
+
+            Format your review as:
+            **Summary:** [1-2 sentences]
+
+            **Issues:** (only list real problems, not style preferences)
+            - [file:line] [severity: critical/major/minor] [description]
+
+            **Suggestions:** (optional improvements, not blocking)
+            - [description]
+
+            If the PR looks good, say so clearly. Don't invent issues.

package/files/merlin/templates/ci/security-audit.yml

@@ -0,0 +1,74 @@
+# Merlin Security Audit
+# Runs a weekly security scan across the codebase using Claude Code.
+# Also runs on demand via workflow_dispatch.
+#
+# Setup:
+#   1. Add ANTHROPIC_API_KEY to your repo secrets (Settings > Secrets > Actions)
+#   2. Copy this file to .github/workflows/security-audit.yml
+#
+name: Merlin Security Audit
+
+on:
+  schedule:
+    # Every Monday at 09:00 UTC
+    - cron: '0 9 * * 1'
+  workflow_dispatch:
+    inputs:
+      scope:
+        description: 'Audit scope (all, auth, api, deps)'
+        required: false
+        default: 'all'
+
+jobs:
+  security-audit:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run dependency vulnerability scan
+        run: |
+          if [ -f package.json ]; then npm audit --json > /tmp/npm-audit.json 2>&1 || true; fi
+          if [ -f requirements.txt ]; then pip install safety && safety check --json > /tmp/pip-audit.json 2>&1 || true; fi
+
+      - name: Merlin Security Analysis
+        uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          prompt: |
+            Perform a security audit of this codebase. Scope: ${{ github.event.inputs.scope || 'all' }}.
+
+            Focus on:
+            1. **Secrets and credentials** — hardcoded API keys, tokens, passwords
+            2. **Injection vulnerabilities** — SQL, command, path traversal
+            3. **Authentication and authorization gaps** — missing auth checks, privilege escalation
+            4. **Dependency vulnerabilities** — check /tmp/npm-audit.json or /tmp/pip-audit.json if present
+            5. **Data exposure** — PII in logs, unencrypted sensitive data
+
+            For each finding:
+            - File and line number
+            - Severity: critical / high / medium / low
+            - Description of the vulnerability
+            - Recommended fix
+
+            Output a structured report. If no issues found in a category, say "None found."
+            Focus on real vulnerabilities, not theoretical ones.
+
+      - name: Create issue if critical findings
+        if: failure()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: 'Security audit found critical issues',
+              body: 'The weekly Merlin security audit found critical issues. See the workflow run for details.',
+              labels: ['security', 'automated']
+            })

package/files/merlin/templates/config.json

@@ -29,5 +29,13 @@
   "safety": {
     "always_confirm_destructive": true,
     "always_confirm_external_services": true
-  }
+  },
+  "notifications": {
+    "desktop": true,
+    "sound": false,
+    "slack_webhook": "",
+    "discord_webhook": "",
+    "notify_on": ["stop", "needs_input", "error"]
+  },
+  "voice_mode_concise": false
 }

package/files/rules/api-rules.md

@@ -0,0 +1,30 @@
+---
+paths: ["apps/api/**"]
+---
+
+# API Rules (apps/api)
+
+## Route Patterns
+- Use Express.js route patterns: `router.get('/path', middleware, handler)`
+- Group related routes in dedicated router files under `src/routes/`
+- Use route-level middleware for auth and validation before business logic
+
+## Error Handling
+- All routes must have error handling — either try/catch or a next(err) pattern
+- Use a centralized error middleware at the app level (`src/middleware/error.ts`)
+- Never let unhandled promise rejections reach the client
+
+## Database Access
+- All database access must go through the services layer (`src/services/`)
+- No raw DB queries in route handlers
+- Services are responsible for data mapping and business logic
+
+## Authentication
+- All non-public routes must verify auth via the auth middleware
+- Public routes must be explicitly marked with a comment: `// public route`
+- Never trust client-supplied user IDs — derive from verified session/token
+
+## Validation
+- Use Zod for request body, query param, and path param validation
+- Define schemas alongside the route or in a shared `src/schemas/` folder
+- Return 400 with structured errors on validation failure — never 500

package/files/rules/frontend-rules.md

@@ -0,0 +1,25 @@
+---
+paths: ["apps/web/**"]
+---
+
+# Frontend Rules (apps/web)
+
+## Next.js App Router
+- Use the App Router (`app/` directory) — not the Pages Router
+- Prefer Server Components by default; add `'use client'` only when interactivity requires it
+- Use `loading.tsx` and `error.tsx` conventions for async boundaries
+
+## Component Boundaries
+- Mark client components explicitly with `'use client'` at the top of the file
+- Keep client components small and push data fetching to server components
+- Shared UI primitives go in `components/ui/`; page-specific components stay co-located
+
+## Styling
+- Use Tailwind CSS for all styling — no inline styles, no CSS modules unless forced
+- Follow the project's existing Tailwind class ordering convention
+- Use `cn()` (clsx/tailwind-merge helper) for conditional class concatenation
+
+## Data Fetching
+- Never call backend APIs directly from components — use the api client module
+- The api client lives in `lib/api/` — add new methods there, not ad-hoc fetch calls
+- Server components can call services directly; client components must go through the api client

package/files/rules/hooks-rules.md

@@ -0,0 +1,36 @@
+---
+paths: ["**/hooks/**", "**/files/hooks/**"]
+---
+
+# Hook Rules (hooks/)
+
+## Language Constraints
+- Pure bash only — no Python, no Node.js, no Ruby or other runtimes
+- No npm packages, no pip installs, no external dependencies beyond standard Unix tools
+- Assume only: bash, jq (optional), curl, grep, sed, awk, cat, date are available
+
+## Performance
+- Hooks must complete in under 50ms — they run on every tool call
+- No synchronous network calls — if you need network, fire-and-forget with `&` and move on
+- Avoid spawning subshells in tight loops; process data with built-in bash constructs
+
+## Exit Codes
+- Exit 0: allow the action / pass (default for all advisory hooks)
+- Exit 2: block the action with a reason — output `{"decision":"block","reason":"..."}` to stdout
+- Any other exit code is treated as 0 (pass) — never exit 1 to block, it's reserved for errors
+
+## Input Handling
+- Read event data from stdin as JSON: `input=$(cat)`
+- Use jq when available; always provide a grep/sed fallback for when jq is missing:
+  ```bash
+  if command -v jq >/dev/null 2>&1; then
+    tool_name=$(echo "$input" | jq -r '.tool_name // empty')
+  else
+    tool_name=$(echo "$input" | grep -o '"tool_name":"[^"]*"' | cut -d'"' -f4)
+  fi
+  ```
+
+## Output
+- Blocking hooks: output valid JSON to stdout (`{"decision":"block","reason":"..."}`)
+- Non-blocking hooks: output `{}` to stdout; all messages go to stderr
+- Never output plain text to stdout — it breaks JSON parsing by Claude Code

package/files/rules/mcp-rules.md

@@ -0,0 +1,30 @@
+---
+paths: ["**/src/server/**", "**/packages/create-merlin-brain/src/**"]
+---
+
+# MCP Server Rules (src/server)
+
+## TypeScript
+- Strict mode is required — `"strict": true` in tsconfig, no exceptions
+- No `any` types; use `unknown` and narrow with guards when type is truly dynamic
+- All exported functions and types must have explicit type annotations
+
+## Tool Descriptions
+- MCP tool descriptions must be keyword-rich for LLM discoverability
+- Include: what it does, when to use it, what it returns, example use cases
+- Bad: `"Gets context"` — Good: `"Fetches codebase context for a task, returns relevant files, patterns, and architecture notes to guide implementation"`
+
+## Tool Loading Strategy
+- Core tools (5-6 maximum): always loaded at server startup — these are the must-haves
+- All other tools: deferred — loaded only when the core tools route to them or are explicitly requested
+- This keeps the MCP tool list small and the LLM's tool selection fast
+
+## Input Validation
+- Every MCP tool handler must validate its input with Zod before processing
+- Define the Zod schema inline with the tool registration (co-location aids readability)
+- On validation failure, return a user-friendly error message — not a stack trace
+
+## Error Responses
+- All errors returned to the caller must be user-friendly (English prose, actionable)
+- Internal errors (unexpected exceptions) should be caught and returned as structured text
+- Never let an unhandled exception crash the MCP server process

package/files/rules/worker-rules.md

@@ -0,0 +1,29 @@
+---
+paths: ["workers/**"]
+---
+
+# Worker Rules (workers/)
+
+## Idempotency
+- All worker jobs must be idempotent — running the same job twice must not cause side effects
+- Use job IDs or content hashes to detect and skip already-processed work
+- Store processing state in the database, not in memory
+
+## Shared Infrastructure
+- Use shared utilities from `workers/src/shared/` — database, queue, logger, config
+- Never duplicate database connection logic — import from the shared db module
+- Worker-specific code stays in the worker's own directory; cross-cutting code goes in shared
+
+## AI Call Cost Control
+- Every AI/LLM call must include a cost estimate in the log before execution
+- Use `estimateCost(model, inputTokens, outputTokens)` from the shared cost module
+- Log: model name, estimated tokens, estimated cost — so runaway jobs are caught early
+
+## Database Connections
+- Use connection pooling — never open a new connection per job
+- Import the shared pool from `workers/src/shared/database.ts`
+- Always release connections back to the pool — use pool.connect() with try/finally
+
+## Cleanup
+- Wrap all job logic in try/finally — cleanup (connection release, temp files, locks) must run even on failure
+- Log the final state (completed / failed / skipped) before exiting the job handler

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-merlin-brain",
-  "version": "3.10.0",
+  "version": "3.12.0",
   "description": "Merlin - The Ultimate AI Brain for Claude Code. One install: workflows, agents, loop, and Sights MCP server.",
   "type": "module",
   "main": "./dist/server/index.js",