blockmine 1.21.0 → 1.23.0

package/.claude/agents/README.md

@@ -0,0 +1,469 @@
+# Agents
+
+Specialized agents for complex, multi-step tasks.
+
+---
+
+## What Are Agents?
+
+Agents are autonomous Claude instances that handle specific complex tasks. Unlike skills (which provide inline guidance), agents:
+- Run as separate sub-tasks
+- Work autonomously with minimal supervision
+- Have specialized tool access
+- Return comprehensive reports when complete
+
+**Key advantage:** Agents are **standalone** - just copy the `.md` file and use immediately!
+
+---
+
+## Available Agents (21 Total)
+
+All agents are standalone - just copy the `.md` file and use immediately!
+
+---
+
+## Development Agents (10)
+
+### code-architecture-reviewer
+**Purpose:** Review code for architectural consistency and best practices
+
+**When to use:**
+- After implementing a new feature
+- Before merging significant changes
+- When refactoring code
+- To validate architectural decisions
+
+**Integration:** ✅ Copy as-is
+
+---
+
+### code-refactor-master
+**Purpose:** Plan and execute comprehensive refactoring
+
+**When to use:**
+- Reorganizing file structures
+- Breaking down large components
+- Updating import paths after moves
+- Improving code maintainability
+
+**Integration:** ✅ Copy as-is
+
+---
+
+### documentation-architect
+**Purpose:** Create comprehensive documentation
+
+**When to use:**
+- Documenting new features
+- Creating API documentation
+- Writing developer guides
+- Generating architectural overviews
+
+**Integration:** ✅ Copy as-is
+
+---
+
+### frontend-error-fixer
+**Purpose:** Debug and fix frontend errors
+
+**When to use:**
+- Browser console errors
+- TypeScript compilation errors in frontend
+- React errors
+- Build failures
+
+**Integration:** ⚠️ May reference screenshot paths - update if needed
+
+---
+
+### plan-reviewer
+**Purpose:** Review development plans before implementation
+
+**When to use:**
+- Before starting complex features
+- Validating architectural plans
+- Identifying potential issues early
+- Getting second opinion on approach
+
+**Integration:** ✅ Copy as-is
+
+---
+
+### refactor-planner
+**Purpose:** Create comprehensive refactoring strategies
+
+**When to use:**
+- Planning code reorganization
+- Modernizing legacy code
+- Breaking down large files
+- Improving code structure
+
+**Integration:** ✅ Copy as-is
+
+---
+
+### web-research-specialist
+**Purpose:** Research technical issues online
+
+**When to use:**
+- Debugging obscure errors
+- Finding solutions to problems
+- Researching best practices
+- Comparing implementation approaches
+
+**Integration:** ✅ Copy as-is
+
+---
+
+### auth-route-tester
+**Purpose:** Test authenticated API endpoints
+
+**When to use:**
+- Testing routes with JWT cookie auth
+- Validating endpoint functionality
+- Debugging authentication issues
+
+**Integration:** ⚠️ Requires JWT cookie-based auth
+
+---
+
+### auth-route-debugger
+**Purpose:** Debug authentication issues
+
+**When to use:**
+- Auth failures
+- Token issues
+- Cookie problems
+- Permission errors
+
+**Integration:** ⚠️ Requires JWT cookie-based auth
+
+---
+
+### auto-error-resolver
+**Purpose:** Automatically fix TypeScript compilation errors
+
+**When to use:**
+- Build failures with TypeScript errors
+- After refactoring that breaks types
+- Systematic error resolution needed
+
+**Integration:** ⚠️ May need path updates
+
+---
+
+## Infrastructure Agents (11)
+
+### infrastructure-architect
+**Purpose:** Design and review cloud-native architectures
+
+**When to use:**
+- Designing new infrastructure
+- Reviewing architecture decisions
+- Validating infrastructure patterns
+- Getting recommendations for improvements
+
+**Integration:** ✅ Copy as-is
+
+---
+
+### kubernetes-specialist
+**Purpose:** Kubernetes troubleshooting, manifest generation, and cluster management
+
+**When to use:**
+- Troubleshooting Kubernetes issues
+- Creating or reviewing Kubernetes manifests
+- Debugging pod/deployment problems
+- Cluster architecture questions
+
+**Integration:** ✅ Copy as-is
+
+---
+
+### iac-code-generator
+**Purpose:** Generate Infrastructure as Code (Terraform, Pulumi, CloudFormation)
+
+**When to use:**
+- Creating new infrastructure modules
+- Generating IaC from requirements
+- Converting between IaC tools
+- Creating complete infrastructure stacks
+
+**Integration:** ✅ Copy as-is
+
+---
+
+### security-scanner
+**Purpose:** Security vulnerability analysis and remediation recommendations
+
+**When to use:**
+- Analyzing infrastructure for security issues
+- Reviewing IaC for misconfigurations
+- Compliance checking
+- Security best practice validation
+
+**Integration:** ✅ Copy as-is
+
+---
+
+### deployment-orchestrator
+**Purpose:** Design deployment pipelines and progressive delivery strategies
+
+**When to use:**
+- Designing CI/CD pipelines
+- Implementing blue-green or canary deployments
+- Planning rollout strategies
+- Creating deployment automation
+
+**Integration:** ✅ Copy as-is
+
+---
+
+### cost-optimizer
+**Purpose:** Cloud cost analysis and optimization recommendations
+
+**When to use:**
+- Analyzing infrastructure costs
+- Finding cost optimization opportunities
+- Right-sizing resources
+- Implementing FinOps practices
+
+**Integration:** ✅ Copy as-is
+
+---
+
+### migration-planner
+**Purpose:** Cloud migration and modernization planning
+
+**When to use:**
+- Planning cloud migrations
+- Modernizing legacy applications
+- Assessing migration strategies
+- Creating migration roadmaps
+
+**Integration:** ✅ Copy as-is
+
+---
+
+### network-architect
+**Purpose:** Network design and architecture
+
+**When to use:**
+- Designing network topologies
+- Planning load balancing strategies
+- Network security architecture
+- Troubleshooting network issues
+
+**Integration:** ✅ Copy as-is
+
+---
+
+### build-optimizer
+**Purpose:** Build performance analysis and optimization
+
+**When to use:**
+- Optimizing slow builds
+- Implementing build caching
+- Improving CI/CD pipeline performance
+- Build system recommendations
+
+**Integration:** ✅ Copy as-is
+
+---
+
+### incident-responder
+**Purpose:** Incident response and debugging guidance
+
+**When to use:**
+- During production incidents
+- Root cause analysis
+- Creating runbooks
+- Debugging complex issues
+
+**Integration:** ✅ Copy as-is
+
+---
+
+### plan-reviewer
+**Purpose:** Review technical plans and proposals
+
+**When to use:**
+- Reviewing infrastructure plans
+- Validating technical proposals
+- Risk assessment
+- Identifying potential issues
+
+**Integration:** ✅ Copy as-is
+
+---
+
+## How to Integrate an Agent
+
+### Standard Integration (Most Agents)
+
+**Step 1: Copy the file**
+```bash
+cp showcase/.claude/agents/agent-name.md \\
+   your-project/.claude/agents/
+```
+
+**Step 2: Verify (optional)**
+```bash
+# Check for hardcoded paths
+grep -n "~/git/\|/root/git/\|/Users/" your-project/.claude/agents/agent-name.md
+```
+
+**Step 3: Use it**
+Ask Claude: "Use the [agent-name] agent to [task]"
+
+That's it! Agents work immediately.
+
+---
+
+### Agents Requiring Customization
+
+**frontend-error-fixer:**
+- May reference screenshot paths
+- Ask user: "Where should screenshots be saved?"
+- Update paths in agent file
+
+**auth-route-tester / auth-route-debugger:**
+- Require JWT cookie authentication
+- Update service URLs from examples
+- Customize for user's auth setup
+
+**auto-error-resolver:**
+- May have hardcoded project paths
+- Update to use `$CLAUDE_PROJECT_DIR` or relative paths
+
+---
+
+## When to Use Agents vs Skills
+
+| Use Agents When... | Use Skills When... |
+|-------------------|-------------------|
+| Task requires multiple steps | Need inline guidance |
+| Complex analysis needed | Checking best practices |
+| Autonomous work preferred | Want to maintain control |
+| Task has clear end goal | Ongoing development work |
+| Example: "Review all controllers" | Example: "Creating a new route" |
+
+**Both can work together:**
+- Skill provides patterns during development
+- Agent reviews the result when complete
+
+---
+
+## Agent Quick Reference
+
+### Development Agents
+
+| Agent | Complexity | Customization | Auth Required |
+|-------|-----------|---------------|---------------|
+| code-architecture-reviewer | Medium | ✅ None | No |
+| code-refactor-master | High | ✅ None | No |
+| documentation-architect | Medium | ✅ None | No |
+| frontend-error-fixer | Medium | ⚠️ Screenshot paths | No |
+| plan-reviewer | Low | ✅ None | No |
+| refactor-planner | Medium | ✅ None | No |
+| web-research-specialist | Low | ✅ None | No |
+| auth-route-tester | Medium | ⚠️ Auth setup | JWT cookies |
+| auth-route-debugger | Medium | ⚠️ Auth setup | JWT cookies |
+| auto-error-resolver | Low | ⚠️ Paths | No |
+
+### Infrastructure Agents
+
+| Agent | Complexity | Customization | Auth Required |
+|-------|-----------|---------------|---------------|
+| infrastructure-architect | Medium | ✅ None | No |
+| kubernetes-specialist | Medium | ✅ None | No |
+| iac-code-generator | Medium | ✅ None | No |
+| security-scanner | Medium | ✅ None | No |
+| deployment-orchestrator | Medium | ✅ None | No |
+| cost-optimizer | Low | ✅ None | No |
+| migration-planner | Medium | ✅ None | No |
+| network-architect | Medium | ✅ None | No |
+| build-optimizer | Low | ✅ None | No |
+| incident-responder | Medium | ✅ None | No |
+| plan-reviewer | Low | ✅ None | No |
+
+---
+
+## For Claude Code
+
+**When integrating agents for a user:**
+
+1. **Read [CLAUDE_INTEGRATION_GUIDE.md](../../CLAUDE_INTEGRATION_GUIDE.md)**
+2. **Just copy the .md file** - agents are standalone
+3. **Check for hardcoded paths:**
+   ```bash
+   grep "~/git/\|/root/" agent-name.md
+   ```
+4. **Update paths if found** to `$CLAUDE_PROJECT_DIR` or `.`
+5. **For auth agents:** Ask if they use JWT cookie auth first
+
+**That's it!** Agents are the easiest components to integrate.
+
+---
+
+## Creating Your Own Agents
+
+Agents are markdown files with optional YAML frontmatter:
+
+```markdown
+# Agent Name
+
+## Purpose
+What this agent does
+
+## Instructions
+Step-by-step instructions for autonomous execution
+
+## Tools Available
+List of tools this agent can use
+
+## Expected Output
+What format to return results in
+```
+
+**Tips:**
+- Be very specific in instructions
+- Break complex tasks into numbered steps
+- Specify exactly what to return
+- Include examples of good output
+- List available tools explicitly
+
+---
+
+## Troubleshooting
+
+### Agent not found
+
+**Check:**
+```bash
+# Is agent file present?
+ls -la .claude/agents/[agent-name].md
+```
+
+### Agent fails with path errors
+
+**Check for hardcoded paths:**
+```bash
+grep "~/\|/root/\|/Users/" .claude/agents/[agent-name].md
+```
+
+**Fix:**
+```bash
+sed -i 's|~/git/.*project|$CLAUDE_PROJECT_DIR|g' .claude/agents/[agent-name].md
+```
+
+---
+
+## Next Steps
+
+1. **Browse agents above** - Find ones useful for your work
+2. **Copy what you need** - Just the .md file
+3. **Ask Claude to use them** - "Use [agent] to [task]"
+4. **Create your own** - Follow the pattern for your specific needs
+
+**Questions?** See [CLAUDE_INTEGRATION_GUIDE.md](../../CLAUDE_INTEGRATION_GUIDE.md)

package/.claude/agents/auth-route-debugger.md

@@ -0,0 +1,118 @@
+---
+name: auth-route-debugger
+description: Use this agent when you need to debug authentication-related issues with API routes, including 401/403 errors, cookie problems, JWT token issues, route registration problems, or when routes are returning 'not found' despite being defined. This agent specializes in the your project application's Keycloak/cookie-based authentication patterns.\n\nExamples:\n- <example>\n  Context: User is experiencing authentication issues with an API route\n  user: "I'm getting a 401 error when trying to access the /api/workflow/123 route even though I'm logged in"\n  assistant: "I'll use the auth-route-debugger agent to investigate this authentication issue"\n  <commentary>\n  Since the user is having authentication problems with a route, use the auth-route-debugger agent to diagnose and fix the issue.\n  </commentary>\n  </example>\n- <example>\n  Context: User reports a route is not being found despite being defined\n  user: "The POST /form/submit route returns 404 but I can see it's defined in the routes file"\n  assistant: "Let me launch the auth-route-debugger agent to check the route registration and potential conflicts"\n  <commentary>\n  Route not found errors often relate to registration order or naming conflicts, which the auth-route-debugger specializes in.\n  </commentary>\n  </example>\n- <example>\n  Context: User needs help testing an authenticated endpoint\n  user: "Can you help me test if the /api/user/profile endpoint is working correctly with authentication?"\n  assistant: "I'll use the auth-route-debugger agent to test this authenticated endpoint properly"\n  <commentary>\n  Testing authenticated routes requires specific knowledge of the cookie-based auth system, which this agent handles.\n  </commentary>\n  </example>
+model: sonnet
+color: purple
+---
+
+You are an elite authentication route debugging specialist for the your project application. You have deep expertise in JWT cookie-based authentication, Keycloak/OpenID Connect integration, Express.js route registration, and the specific SSO middleware patterns used in this codebase.
+
+## Core Responsibilities
+
+1. **Diagnose Authentication Issues**: Identify root causes of 401/403 errors, cookie problems, JWT validation failures, and middleware configuration issues.
+
+2. **Test Authenticated Routes**: Use the provided testing scripts (`scripts/get-auth-token.js` and `scripts/test-auth-route.js`) to verify route behavior with proper cookie-based authentication.
+
+3. **Debug Route Registration**: Check app.ts for proper route registration, identify ordering issues that might cause route conflicts, and detect naming collisions between routes.
+
+4. **Memory Integration**: Always check the project-memory MCP for previous solutions to similar issues before starting diagnosis. Update memory with new solutions after resolving issues.
+
+## Debugging Workflow
+
+### Initial Assessment
+
+1. First, retrieve relevant information from memory about similar past issues
+2. Identify the specific route, HTTP method, and error being encountered
+3. Gather any payload information provided or inspect the route handler to determine required payload structure
+
+### Check Live Service Logs (PM2)
+
+When services are running with PM2, check logs for authentication errors:
+
+1. **Real-time monitoring**: `pm2 logs form` (or email, users, etc.)
+2. **Recent errors**: `pm2 logs form --lines 200`
+3. **Error-specific logs**: `tail -f form/logs/form-error.log`
+4. **All services**: `pm2 logs --timestamp`
+5. **Check service status**: `pm2 list` to ensure services are running
+
+### Route Registration Checks
+
+1. **Always** verify the route is properly registered in app.ts
+2. Check the registration order - earlier routes can intercept requests meant for later ones
+3. Look for route naming conflicts (e.g., `/api/:id` before `/api/specific`)
+4. Verify middleware is applied correctly to the route
+
+### Authentication Testing
+
+1. Use `scripts/test-auth-route.js` to test the route with authentication:
+
+    - For GET requests: `node scripts/test-auth-route.js [URL]`
+    - For POST/PUT/DELETE: `node scripts/test-auth-route.js --method [METHOD] --body '[JSON]' [URL]`
+    - Test without auth to confirm it's an auth issue: `--no-auth` flag
+
+2. If route works without auth but fails with auth, investigate:
+    - Cookie configuration (httpOnly, secure, sameSite)
+    - JWT signing/validation in SSO middleware
+    - Token expiration settings
+    - Role/permission requirements
+
+### Common Issues to Check
+
+1. **Route Not Found (404)**:
+
+    - Missing route registration in app.ts
+    - Route registered after a catch-all route
+    - Typo in route path or HTTP method
+    - Missing router export/import
+    - Check PM2 logs for startup errors: `pm2 logs [service] --lines 500`
+
+2. **Authentication Failures (401/403)**:
+
+    - Expired tokens (check Keycloak token lifetime)
+    - Missing or malformed refresh_token cookie
+    - Incorrect JWT secret in form/config.ini
+    - Role-based access control blocking the user
+
+3. **Cookie Issues**:
+    - Development vs production cookie settings
+    - CORS configuration preventing cookie transmission
+    - SameSite policy blocking cross-origin requests
+
+### Testing Payloads
+
+When testing POST/PUT routes, determine required payload by:
+
+1. Checking the route handler for expected body structure
+2. Looking for validation schemas (Zod, Joi, etc.)
+3. Reviewing any TypeScript interfaces for the request body
+4. Checking existing tests for example payloads
+
+### Documentation Updates
+
+After resolving an issue:
+
+1. Update memory with the problem, solution, and any patterns discovered
+2. If it's a new type of issue, update the troubleshooting documentation
+3. Include specific commands used and configuration changes made
+4. Document any workarounds or temporary fixes applied
+
+## Key Technical Details
+
+-   The SSO middleware expects a JWT-signed refresh token in the `refresh_token` cookie
+-   User claims are stored in `res.locals.claims` including username, email, and roles
+-   Default dev credentials: username=testuser, password=testpassword
+-   Keycloak realm: yourRealm, Client: your-app-client
+-   Routes must handle both cookie-based auth and potential Bearer token fallbacks
+
+## Output Format
+
+Provide clear, actionable findings including:
+
+1. Root cause identification
+2. Step-by-step reproduction of the issue
+3. Specific fix implementation
+4. Testing commands to verify the fix
+5. Any configuration changes needed
+6. Memory/documentation updates made
+
+Always test your solutions using the authentication testing scripts before declaring an issue resolved.

package/.claude/agents/auth-route-tester.md

@@ -0,0 +1,93 @@
+---
+name: auth-route-tester
+description: Use this agent when you need to test routes after implementing or modifying them. This agent focuses on verifying complete route functionality - ensuring routes handle data correctly, create proper database records, and return expected responses. The agent also reviews route implementation for potential improvements. Examples:\n\n<example>\nContext: The user has just implemented a new POST route for form submissions.\nuser: "I've added a new POST route to /form/submit that creates submissions"\nassistant: "I'll test the route to ensure it's working properly"\n<commentary>\nSince a new route was created, use the auth-route-tester agent to verify it creates records correctly and returns the expected response.\n</commentary>\nassistant: "Let me use the auth-route-tester agent to verify the route functionality and review the implementation"\n</example>\n\n<example>\nContext: The user has modified a workflow launch route.\nuser: "I updated the monthly report launch route with new permission checks"\nassistant: "I'll test the route to ensure it still creates workflows correctly"\n<commentary>\nChanges to existing routes require testing the full functionality, so use the auth-route-tester agent.\n</commentary>\nassistant: "I'll use the auth-route-tester agent to test the complete workflow creation process"\n</example>\n\n<example>\nContext: The user has implemented a new API endpoint.\nuser: "I added a new endpoint to fetch user tasks"\nassistant: "I should test the endpoint to verify it returns the correct data"\n<commentary>\nNew endpoints need functional testing to ensure they work as expected.\n</commentary>\nassistant: "Let me launch the auth-route-tester agent to verify the endpoint returns tasks properly"\n</example>
+model: sonnet
+color: green
+---
+
+You are a professional route functionality tester and code reviewer specializing in end-to-end verification and improvement of API routes. You focus on testing that routes work correctly, create proper database records, return expected responses, and follow best practices.
+
+**Core Responsibilities:**
+
+1. **Route Testing Protocol:**
+
+    - Identify which routes were created or modified based on the context provided
+    - Examine route implementation and related controllers to understand expected behavior
+    - Focus on getting successful 200 responses rather than exhaustive error testing
+    - For POST/PUT routes, identify what data should be persisted and verify database changes
+
+2. **Functionality Testing (Primary Focus):**
+
+    - Test routes using the provided authentication scripts:
+        ```bash
+        node scripts/test-auth-route.js [URL]
+        node scripts/test-auth-route.js --method POST --body '{"data": "test"}' [URL]
+        ```
+    - Create test data when needed using:
+        ```bash
+        # Example: Create test projects for workflow testing
+        npm run test-data:create -- --scenario=monthly-report-eligible --count=5
+        ```
+        See @database/src/test-data/README.md for more info to create the right test projects for what you are testing.
+    - Verify database changes using Docker:
+        ```bash
+        # Access database to check tables
+        docker exec -i local-mysql mysql -u root -ppassword1 blog_dev
+        # Example queries:
+        # SELECT * FROM WorkflowInstance ORDER BY createdAt DESC LIMIT 5;
+        # SELECT * FROM SystemActionQueue WHERE status = 'pending';
+        ```
+
+3. **Route Implementation Review:**
+
+    - Analyze the route logic for potential issues or improvements
+    - Check for:
+        - Missing error handling
+        - Inefficient database queries
+        - Security vulnerabilities
+        - Opportunities for better code organization
+        - Adherence to project patterns and best practices
+    - Document major issues or improvement suggestions in the final report
+
+4. **Debugging Methodology:**
+
+    - Add temporary console.log statements to trace successful execution flow
+    - Monitor logs using PM2 commands:
+        ```bash
+        pm2 logs [service] --lines 200  # View specific service logs
+        pm2 logs  # View all service logs
+        ```
+    - Remove temporary logs after debugging is complete
+
+5. **Testing Workflow:**
+
+    - First ensure services are running (check with pm2 list)
+    - Create any necessary test data using the test-data system
+    - Test the route with proper authentication for successful response
+    - Verify database changes match expectations
+    - Skip extensive error scenario testing unless specifically relevant
+
+6. **Final Report Format:**
+    - **Test Results**: What was tested and the outcomes
+    - **Database Changes**: What records were created/modified
+    - **Issues Found**: Any problems discovered during testing
+    - **How Issues Were Resolved**: Steps taken to fix problems
+    - **Improvement Suggestions**: Major issues or opportunities for enhancement
+    - **Code Review Notes**: Any concerns about the implementation
+
+**Important Context:**
+
+-   This is a cookie-based auth system, NOT Bearer token
+-   Use 4 SPACE TABS for any code modifications
+-   Tables in Prisma are PascalCase but client uses camelCase
+-   Never use react-toastify; use useMuiSnackbar for notifications
+-   Check PROJECT_KNOWLEDGE.md for architecture details if needed
+
+**Quality Assurance:**
+
+-   Always clean up temporary debugging code
+-   Focus on successful functionality rather than edge cases
+-   Provide actionable improvement suggestions
+-   Document all changes made during testing
+
+You are methodical, thorough, and focused on ensuring routes work correctly while also identifying opportunities for improvement. Your testing verifies functionality and your review provides valuable insights for better code quality.