@cloudstreamsoftware/claude-tools 1.0.0 → 1.1.0

package/skills/tutorial/lessons/07-hooks-system.md

@@ -0,0 +1,277 @@
+# Lesson 7: Hooks System
+
+Automate quality checks and enforce workflows before and after Claude Code actions.
+
+## Concept
+
+Hooks are scripts that run automatically at specific lifecycle events:
+
+| Hook Type | When It Runs | Use Cases |
+|-----------|--------------|-----------|
+| **UserPromptSubmit** | When user sends a message | Real-time correction detection, intent analysis |
+| **PreToolUse** | Before a tool executes | Block dangerous operations, validate inputs, credential scanning |
+| **PostToolUse** | After a tool completes | Auto-format code, run type checks, warn about issues |
+| **Stop** | When Claude response ends | Final validation before user sees result |
+| **SessionStart** | When session begins | Load context, detect environment |
+| **SessionEnd** | When session closes | Persist state, capture patterns |
+| **PreCompact** | Before context compaction | Save important state before memory trim |
+
+## Why This Matters
+
+Without hooks, you must manually:
+- Check for credentials before every edit
+- Run Prettier after every file change
+- Verify TypeScript after every `.ts` modification
+- Remember to save session state
+
+Hooks automate these guardrails, making quality enforcement invisible.
+
+## Current Hooks in This System
+
+The system includes these production hooks in `hooks/hooks.json`:
+
+### UserPromptSubmit Hook (Real-Time Learning)
+
+| Hook | What It Does | Trigger |
+|------|--------------|---------|
+| **Prompt Analyzer** | Detects corrections and learning opportunities in your messages | Every user message |
+
+This hook powers the system's **real-time learning**. When you say things like "no, actually use X instead", the prompt analyzer:
+1. Detects the correction pattern
+2. Extracts what was wrong vs. what's right
+3. Records it in session memory
+4. After 2+ occurrences, it becomes a persistent learned pattern
+
+### PreToolUse Hooks (Before Actions)
+
+| Hook | What It Does | Trigger |
+|------|--------------|---------|
+| **Credential Check** | Scans for hardcoded Zoho/GCP credentials | Edit/Write operations |
+| **Tmux Reminder** | Suggests tmux for long-running commands | npm install, docker, pytest, etc. |
+| **Dev Server Block** | BLOCKS dev servers outside tmux | `npm run dev` and variants |
+| **Git Push Review** | Reminds to review before push | `git push` commands |
+| **Doc Blocker** | BLOCKS random .md file creation | Write to non-README .md files |
+| **Suggest Compact** | Suggests context compaction at intervals | Edit/Write operations |
+
+### PostToolUse Hooks (After Actions)
+
+| Hook | What It Does | Trigger |
+|------|--------------|---------|
+| **PR Logger** | Logs PR URL and provides review command | After `gh pr create` |
+| **Prettier Format** | Auto-formats JS/TS files | After editing .js/.jsx/.ts/.tsx |
+| **TypeScript Check** | Runs `tsc --noEmit` and reports errors | After editing .ts/.tsx |
+| **Console.log Warning** | Warns about console.log in code | After editing JS/TS files |
+
+### Stop Hook (End of Response)
+
+| Hook | What It Does | Trigger |
+|------|--------------|---------|
+| **Console.log Audit** | Checks all modified files for console.log | Every response |
+
+### Session Hooks (Lifecycle)
+
+| Hook | What It Does | Trigger |
+|------|--------------|---------|
+| **SessionStart** | Loads previous context, detects package manager | New session |
+| **SessionEnd** | Persists session state | Session closes |
+| **Evaluate Session** | Extracts reusable patterns from work | Session closes |
+| **PreCompact** | Saves state before compaction | Before memory trim |
+
+## Hook Configuration Format
+
+Hooks are defined in `hooks/hooks.json` with this structure:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "tool == \"Edit\" || tool == \"Write\"",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node scripts/hooks/credential-check.js"
+          }
+        ],
+        "description": "Scan for hardcoded credentials in edits"
+      }
+    ]
+  }
+}
+```
+
+### Matcher Syntax
+
+Matchers are expressions that determine when a hook runs:
+
+| Matcher | Meaning |
+|---------|---------|
+| `*` | Always run |
+| `tool == "Edit"` | Only on Edit tool |
+| `tool == "Bash" && tool_input.command matches "git push"` | Bash with specific command |
+| `tool_input.file_path matches "\\.ts$"` | Files ending in .ts |
+
+### Hook Types
+
+| Type | Description |
+|------|-------------|
+| `command` | Run a shell command |
+
+The command receives tool input via stdin (JSON) and outputs modified JSON via stdout.
+
+## Exercise
+
+### Exercise 7.1: Examine Hook Configuration
+
+**Step 1**: View the hooks configuration:
+```bash
+cat hooks/hooks.json
+```
+
+**Step 2**: Count the hooks:
+- How many PreToolUse hooks?
+- How many PostToolUse hooks?
+- What session hooks exist?
+
+### Exercise 7.2: See a Hook in Action
+
+**Step 1**: Create a test TypeScript file with an issue:
+```typescript
+// Create: test-hook.ts
+const x = 1;
+console.log(x);
+```
+
+**Step 2**: When you edit a TypeScript file, observe the PostToolUse hooks fire:
+1. Prettier formats the file
+2. TypeScript check runs
+3. Console.log warning appears
+
+**Step 3**: Notice how you didn't have to run these manually - hooks automated it.
+
+### Exercise 7.3: Understanding Hook Scripts
+
+**Step 1**: View a hook script:
+```bash
+cat scripts/hooks/credential-check.js
+```
+
+**What to observe:**
+- Scripts receive tool input via stdin (JSON)
+- Scripts output modified JSON via stdout
+- Scripts can `process.exit(1)` to BLOCK the operation
+- Scripts log to stderr for user visibility
+
+### Exercise 7.4: Blocking vs. Warning Hooks
+
+Some hooks BLOCK operations (exit code 1), others just WARN:
+
+| Hook | Behavior |
+|------|----------|
+| Credential Check | BLOCKS if secrets found |
+| Dev Server Block | BLOCKS outside tmux |
+| Doc Blocker | BLOCKS random .md files |
+| Console.log Warning | WARNS but allows |
+| Tmux Reminder | WARNS but allows |
+
+## Verification
+
+You've completed this exercise successfully if:
+- [ ] You found `hooks/hooks.json` and understand its structure
+- [ ] You know the 6 hook lifecycle events
+- [ ] You saw hooks fire when editing a file
+- [ ] You understand the difference between blocking and warning hooks
+
+## Creating Custom Hooks
+
+To add a custom hook:
+
+**Step 1**: Create script in `scripts/hooks/your-hook.js`:
+```javascript
+#!/usr/bin/env node
+let data = '';
+process.stdin.on('data', chunk => data += chunk);
+process.stdin.on('end', () => {
+  const input = JSON.parse(data);
+
+  // Your validation logic
+  if (somethingBad) {
+    console.error('[Hook] BLOCKED: Reason');
+    process.exit(1);  // Block the operation
+  }
+
+  // Pass through the data
+  console.log(data);
+});
+```
+
+**Step 2**: Add entry to `hooks/hooks.json`:
+```json
+{
+  "matcher": "tool == \"Bash\" && tool_input.command matches \"deploy\"",
+  "hooks": [
+    {
+      "type": "command",
+      "command": "node scripts/hooks/your-hook.js"
+    }
+  ],
+  "description": "What this hook does"
+}
+```
+
+**Step 3**: Restart Claude Code session for hooks to load.
+
+### Example: Block Commits on Friday Afternoons
+
+```json
+{
+  "matcher": "tool == \"Bash\" && tool_input.command matches \"git commit\"",
+  "hooks": [
+    {
+      "type": "command",
+      "command": "node -e \"const d=new Date();if(d.getDay()===5&&d.getHours()>=14){console.error('[Hook] BLOCKED: No commits after 2pm Friday!');process.exit(1)}\""
+    }
+  ],
+  "description": "Prevent Friday afternoon commits (you'll thank yourself)"
+}
+```
+
+## Key Takeaway
+
+Hooks are invisible guardrails. They enforce quality standards without requiring manual intervention. The system includes 12+ production hooks that:
+- Scan for secrets before edits
+- Auto-format code after changes
+- Catch TypeScript errors immediately
+- Persist context across sessions
+
+You don't run these manually - they just work.
+
+## Hooks Quick Reference
+
+```
+BLOCKING HOOKS (exit 1):
+  - Credential check (secrets in code)
+  - Dev server block (outside tmux)
+  - Doc blocker (random .md files)
+
+WARNING HOOKS (stderr only):
+  - Console.log warning
+  - Tmux reminder
+  - Git push review
+
+LIFECYCLE HOOKS:
+  - SessionStart: Load context
+  - SessionEnd: Persist state
+  - PreCompact: Save before trim
+  - Stop: Final validation
+```
+
+## Next Steps
+
+In Lesson 8, you'll learn about MCP Servers - external capabilities like memory persistence and live documentation lookup.
+
+---
+
+**Concepts learned**: Hook lifecycle events, PreToolUse/PostToolUse/Stop/Session hooks, blocking vs. warning
+**Key file**: `hooks/hooks.json`
+**Progress**: 8 of 15 lessons complete

package/skills/tutorial/lessons/08-mcp-servers.md

@@ -0,0 +1,316 @@
+# Lesson 8: MCP Servers
+
+Model Context Protocol (MCP) servers extend Claude Code with external capabilities.
+
+## Concept
+
+MCPs are plugins that give Claude Code access to external systems:
+
+| Tier | MCPs | Purpose |
+|------|------|---------|
+| **Core** | memory, sequential-thinking, context7 | Always active - essential functionality |
+| **Per-Client** | zoho-analytics, zoho-books, gcloud, bigquery, dbt | Enabled based on client tech stack |
+| **Optional** | magic, firecrawl, github, filesystem | Project-specific needs |
+
+## Why This Matters
+
+Without MCPs:
+- Claude forgets everything between sessions
+- You manually look up library documentation
+- No direct access to GitHub, GCP, or Zoho APIs
+- Limited to what Claude knows at training time
+
+With MCPs:
+- Memory persists across all sessions
+- Up-to-date docs fetched on demand
+- Direct API access to external systems
+- Extended capabilities via plugins
+
+## The 12 Available MCPs
+
+### Core MCPs (Always Enabled)
+
+These three MCPs are configured in `.mcp.json` by default:
+
+#### 1. Memory MCP
+
+Persists knowledge across sessions using a knowledge graph structure:
+- **Entities**: Things (projects, decisions, patterns)
+- **Relations**: Connections between entities
+- **Observations**: Facts about entities
+
+```json
+{
+  "memory": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-memory"],
+    "env": {
+      "MEMORY_FILE_PATH": "~/.claude/memory/cloudstream-memory.json"
+    }
+  }
+}
+```
+
+**Use case**: "Remember that Client X prefers morning standups" persists across sessions.
+
+#### 2. Sequential Thinking MCP
+
+Enables multi-step reasoning for complex architecture decisions. Breaks down problems into logical steps before acting.
+
+```json
+{
+  "sequential-thinking": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+  }
+}
+```
+
+**Use case**: Complex architecture decisions, compliance analysis, debugging sessions.
+
+#### 3. Context7 MCP
+
+Fetches live documentation for libraries. Never work with outdated API references.
+
+```json
+{
+  "context7": {
+    "command": "npx",
+    "args": ["-y", "@upstash/context7-mcp"]
+  }
+}
+```
+
+**Pro tip**: Add Zoho SDKs to Context7 at [context7.com/add-library](https://context7.com/add-library)
+
+### Per-Client MCPs (Enable Based on Tech Stack)
+
+These MCPs are documented in `mcp-configs/mcp-servers.json`:
+
+#### 4. Zoho Analytics MCP (Docker)
+
+Official Zoho Analytics integration for reporting and dashboards.
+
+| Requirement | Value |
+|-------------|-------|
+| Runtime | Docker |
+| Credentials | ZOHO_ANALYTICS_CLIENT_ID, CLIENT_SECRET, REFRESH_TOKEN, ORG_ID |
+| Status | Beta |
+
+#### 5. Zoho Books MCP (Python)
+
+Accounting integrations for financial workflows.
+
+| Requirement | Value |
+|-------------|-------|
+| Runtime | uvx (Python) |
+| Credentials | ZOHO_CLIENT_ID, CLIENT_SECRET, REFRESH_TOKEN, ORGANIZATION_ID |
+| Region | US/EU/IN/AU |
+
+#### 6. Google Cloud MCP (Official Preview)
+
+GCP resource management for cloud infrastructure projects.
+
+| Requirement | Value |
+|-------------|-------|
+| Runtime | npx |
+| Credentials | GOOGLE_APPLICATION_CREDENTIALS (service account key path) |
+
+#### 7. BigQuery MCP
+
+Read-only data warehouse queries for analytics projects.
+
+| Requirement | Value |
+|-------------|-------|
+| Runtime | npx |
+| Credentials | GOOGLE_APPLICATION_CREDENTIALS |
+| Access | Read-only (secure) |
+
+#### 8. dbt MCP (Official)
+
+Data transformation workflows for medallion architecture (bronze/silver/gold layers).
+
+| Requirement | Value |
+|-------------|-------|
+| Runtime | uvx (Python) |
+| Credentials | DBT_HOST, DBT_TOKEN |
+
+### Optional MCPs (Project-Specific)
+
+#### 9. GitHub MCP
+
+PR management, issue tracking, repository operations.
+
+| Requirement | Value |
+|-------------|-------|
+| Runtime | npx |
+| Credentials | GITHUB_PERSONAL_ACCESS_TOKEN |
+
+#### 10. Filesystem MCP
+
+Project file operations scoped to a specific directory.
+
+| Requirement | Value |
+|-------------|-------|
+| Runtime | npx |
+| Arg | Project directory path |
+
+#### 11. Magic UI MCP
+
+150+ animated React components for widget development.
+
+| Requirement | Value |
+|-------------|-------|
+| Runtime | npx |
+| Credentials | None |
+
+#### 12. Firecrawl MCP
+
+Web data extraction for consulting projects.
+
+| Requirement | Value |
+|-------------|-------|
+| Runtime | npx |
+| Credentials | FIRECRAWL_API_KEY |
+
+## MCP Configuration
+
+MCPs are configured in two places:
+
+| File | Purpose |
+|------|---------|
+| `.mcp.json` | Active MCPs for current project |
+| `mcp-configs/mcp-servers.json` | Full catalog with documentation |
+
+### Adding an MCP to Your Project
+
+**Step 1**: Find the MCP in the catalog:
+```bash
+cat mcp-configs/mcp-servers.json
+```
+
+**Step 2**: Copy the configuration to `.mcp.json`:
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
+      }
+    }
+  }
+}
+```
+
+**Step 3**: Restart Claude Code session for MCPs to load.
+
+## Exercise
+
+### Exercise 8.1: Check Active MCPs
+
+**Step 1**: View current MCP configuration:
+```bash
+cat .mcp.json
+```
+
+**Step 2**: You should see three MCPs: memory, sequential-thinking, context7.
+
+### Exercise 8.2: View MCP Catalog
+
+**Step 1**: View all available MCPs:
+```bash
+cat mcp-configs/mcp-servers.json
+```
+
+**Step 2**: Notice the different tiers:
+- Core (always enabled)
+- Per-client (based on tech stack)
+- Optional (project-specific)
+
+### Exercise 8.3: Verify Memory MCP
+
+**Step 1**: Ask Claude to store something:
+```
+Remember that the preferred deployment day is Tuesday.
+```
+
+**Step 2**: In a NEW session, ask:
+```
+What's the preferred deployment day?
+```
+
+If memory is working, Claude will recall the preference.
+
+### Exercise 8.4: Use Context7
+
+**Step 1**: Ask for live documentation:
+```
+Using context7, show me the current React useState hook signature.
+```
+
+**Step 2**: Notice that Context7 fetches live documentation, not training data.
+
+## Troubleshooting
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| MCP won't start | Package not found | Run `npx -y @package/name` manually first |
+| Auth errors | Invalid credentials | Check environment variables in .mcp.json |
+| Docker MCPs fail | Docker not running | Start Docker Desktop |
+| uvx MCPs fail | Python not installed | Install Python 3.10+ with pip |
+| Memory not persisting | Invalid file path | Check MEMORY_FILE_PATH exists |
+
+## Security Best Practices
+
+1. **Never commit credentials** - Use environment variables, not hardcoded values
+2. **Separate tokens per client** - Don't share credentials across clients
+3. **Rotate GCP keys quarterly** - Service account best practice
+4. **Minimum scopes** - Only request the API permissions you need
+5. **Read-only where possible** - BigQuery is read-only for safety
+
+## Verification
+
+You've completed this exercise successfully if:
+- [ ] You found `.mcp.json` and `mcp-configs/mcp-servers.json`
+- [ ] You understand the 3 MCP tiers (Core, Per-Client, Optional)
+- [ ] You know what each of the 12 MCPs does
+- [ ] You tested memory persistence (or understand why it might not work if not configured)
+
+## Key Takeaway
+
+MCPs extend Claude Code's capabilities beyond text generation. The three core MCPs (memory, sequential-thinking, context7) should always be configured. Add per-client MCPs based on the tech stack.
+
+## MCP Quick Reference
+
+```
+CORE (always enabled):
+  - memory: Knowledge graph persistence
+  - sequential-thinking: Complex reasoning
+  - context7: Live documentation
+
+PER-CLIENT:
+  - zoho-analytics: Dashboards (Docker)
+  - zoho-books: Accounting (Python)
+  - gcloud: GCP resources
+  - bigquery: Data warehouse (read-only)
+  - dbt: Data transformation
+
+OPTIONAL:
+  - github: PR/issue management
+  - filesystem: File operations
+  - magic: UI components
+  - firecrawl: Web extraction
+```
+
+## Next Steps
+
+In Lesson 9, you'll learn about client management commands for multi-client context switching and handoff documentation.
+
+---
+
+**MCPs learned**: 12 MCPs across 3 tiers
+**Key files**: `.mcp.json`, `mcp-configs/mcp-servers.json`
+**Reference**: MCP-SETUP-GUIDE.md for detailed installation
+**Progress**: 9 of 15 lessons complete