blockmine 1.21.0 → 1.22.0

package/.claude/skills/route-tester/SKILL.md

@@ -0,0 +1,392 @@
+---
+name: route-tester
+description: Test authenticated routes in the your project using cookie-based authentication. Use this skill when testing API endpoints, validating route functionality, or debugging authentication issues. Includes patterns for using test-auth-route.js and mock authentication.
+---
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🎯 SKILL ACTIVATED: route-tester
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+
+# your project Route Tester Skill
+
+## Purpose
+This skill provides patterns for testing authenticated routes in the your project using cookie-based JWT authentication.
+
+## When to Use This Skill
+- Testing new API endpoints
+- Validating route functionality after changes
+- Debugging authentication issues
+- Testing POST/PUT/DELETE operations
+- Verifying request/response data
+
+## your project Authentication Overview
+
+The your project uses:
+- **Keycloak** for SSO (realm: yourRealm)
+- **Cookie-based JWT** tokens (not Bearer headers)
+- **Cookie name**: `refresh_token`
+- **JWT signing**: Using secret from `config.ini`
+
+## Testing Methods
+
+### Method 1: test-auth-route.js (RECOMMENDED)
+
+The `test-auth-route.js` script handles all authentication complexity automatically.
+
+**Location**: `/root/git/your project_pre/scripts/test-auth-route.js`
+
+#### Basic GET Request
+
+```bash
+node scripts/test-auth-route.js http://localhost:3000/blog-api/api/endpoint
+```
+
+#### POST Request with JSON Data
+
+```bash
+node scripts/test-auth-route.js \
+    http://localhost:3000/blog-api/777/submit \
+    POST \
+    '{"responses":{"4577":"13295"},"submissionID":5,"stepInstanceId":"11"}'
+```
+
+#### What the Script Does
+
+1. Gets a refresh token from Keycloak
+   - Username: `testuser`
+   - Password: `testpassword`
+2. Signs the token with JWT secret from `config.ini`
+3. Creates cookie header: `refresh_token=<signed-token>`
+4. Makes the authenticated request
+5. Shows the exact curl command to reproduce manually
+
+#### Script Output
+
+The script outputs:
+- The request details
+- The response status and body
+- A curl command for manual reproduction
+
+**Note**: The script is verbose - look for the actual response in the output.
+
+### Method 2: Manual curl with Token
+
+Use the curl command from the test-auth-route.js output:
+
+```bash
+# The script outputs something like:
+# 💡 To test manually with curl:
+# curl -b "refresh_token=eyJhbGci..." http://localhost:3000/blog-api/api/endpoint
+
+# Copy and modify that curl command:
+curl -X POST http://localhost:3000/blog-api/777/submit \
+  -H "Content-Type: application/json" \
+  -b "refresh_token=<COPY_TOKEN_FROM_SCRIPT_OUTPUT>" \
+  -d '{"your": "data"}'
+```
+
+### Method 3: Mock Authentication (Development Only - EASIEST)
+
+For development, bypass Keycloak entirely using mock auth.
+
+#### Setup
+
+```bash
+# Add to service .env file (e.g., blog-api/.env)
+MOCK_AUTH=true
+MOCK_USER_ID=test-user
+MOCK_USER_ROLES=admin,operations
+```
+
+#### Usage
+
+```bash
+curl -H "X-Mock-Auth: true" \
+     -H "X-Mock-User: test-user" \
+     -H "X-Mock-Roles: admin,operations" \
+     http://localhost:3002/api/protected
+```
+
+#### Mock Auth Requirements
+
+Mock auth ONLY works when:
+- `NODE_ENV` is `development` or `test`
+- The `mockAuth` middleware is added to the route
+- Will NEVER work in production (security feature)
+
+## Common Testing Patterns
+
+### Test Form Submission
+
+```bash
+node scripts/test-auth-route.js \
+    http://localhost:3000/blog-api/777/submit \
+    POST \
+    '{"responses":{"4577":"13295"},"submissionID":5,"stepInstanceId":"11"}'
+```
+
+### Test Workflow Start
+
+```bash
+node scripts/test-auth-route.js \
+    http://localhost:3002/api/workflow/start \
+    POST \
+    '{"workflowCode":"DHS_CLOSEOUT","entityType":"Submission","entityID":123}'
+```
+
+### Test Workflow Step Completion
+
+```bash
+node scripts/test-auth-route.js \
+    http://localhost:3002/api/workflow/step/complete \
+    POST \
+    '{"stepInstanceID":789,"answers":{"decision":"approved","comments":"Looks good"}}'
+```
+
+### Test GET with Query Parameters
+
+```bash
+node scripts/test-auth-route.js \
+    "http://localhost:3002/api/workflows?status=active&limit=10"
+```
+
+### Test File Upload
+
+```bash
+# Get token from test-auth-route.js first, then:
+curl -X POST http://localhost:5000/upload \
+  -H "Content-Type: multipart/form-data" \
+  -b "refresh_token=<TOKEN>" \
+  -F "file=@/path/to/file.pdf" \
+  -F "metadata={\"description\":\"Test file\"}"
+```
+
+## Hardcoded Test Credentials
+
+The `test-auth-route.js` script uses these credentials:
+
+- **Username**: `testuser`
+- **Password**: `testpassword`
+- **Keycloak URL**: From `config.ini` (usually `http://localhost:8081`)
+- **Realm**: `yourRealm`
+- **Client ID**: From `config.ini`
+
+## Service Ports
+
+| Service | Port | Base URL |
+|---------|------|----------|
+| Users   | 3000 | http://localhost:3000 |
+| Projects| 3001 | http://localhost:3001 |
+| Form    | 3002 | http://localhost:3002 |
+| Email   | 3003 | http://localhost:3003 |
+| Uploads | 5000 | http://localhost:5000 |
+
+## Route Prefixes
+
+Check `/src/app.ts` in each service for route prefixes:
+
+```typescript
+// Example from blog-api/src/app.ts
+app.use('/blog-api/api', formRoutes);          // Prefix: /blog-api/api
+app.use('/api/workflow', workflowRoutes);  // Prefix: /api/workflow
+```
+
+**Full Route** = Base URL + Prefix + Route Path
+
+Example:
+- Base: `http://localhost:3002`
+- Prefix: `/form`
+- Route: `/777/submit`
+- **Full URL**: `http://localhost:3000/blog-api/777/submit`
+
+## Testing Checklist
+
+Before testing a route:
+
+- [ ] Identify the service (form, email, users, etc.)
+- [ ] Find the correct port
+- [ ] Check route prefixes in `app.ts`
+- [ ] Construct the full URL
+- [ ] Prepare request body (if POST/PUT)
+- [ ] Determine authentication method
+- [ ] Run the test
+- [ ] Verify response status and data
+- [ ] Check database changes if applicable
+
+## Verifying Database Changes
+
+After testing routes that modify data:
+
+```bash
+# Connect to MySQL
+docker exec -i local-mysql mysql -u root -ppassword1 blog_dev
+
+# Check specific table
+mysql> SELECT * FROM WorkflowInstance WHERE id = 123;
+mysql> SELECT * FROM WorkflowStepInstance WHERE instanceId = 123;
+mysql> SELECT * FROM WorkflowNotification WHERE recipientUserId = 'user-123';
+```
+
+## Debugging Failed Tests
+
+### 401 Unauthorized
+
+**Possible causes**:
+1. Token expired (regenerate with test-auth-route.js)
+2. Incorrect cookie format
+3. JWT secret mismatch
+4. Keycloak not running
+
+**Solutions**:
+```bash
+# Check Keycloak is running
+docker ps | grep keycloak
+
+# Regenerate token
+node scripts/test-auth-route.js http://localhost:3002/api/health
+
+# Verify config.ini has correct jwtSecret
+```
+
+### 403 Forbidden
+
+**Possible causes**:
+1. User lacks required role
+2. Resource permissions incorrect
+3. Route requires specific permissions
+
+**Solutions**:
+```bash
+# Use mock auth with admin role
+curl -H "X-Mock-Auth: true" \
+     -H "X-Mock-User: test-admin" \
+     -H "X-Mock-Roles: admin" \
+     http://localhost:3002/api/protected
+```
+
+### 404 Not Found
+
+**Possible causes**:
+1. Incorrect URL
+2. Missing route prefix
+3. Route not registered
+
+**Solutions**:
+1. Check `app.ts` for route prefixes
+2. Verify route registration
+3. Check service is running (`pm2 list`)
+
+### 500 Internal Server Error
+
+**Possible causes**:
+1. Database connection issue
+2. Missing required fields
+3. Validation error
+4. Application error
+
+**Solutions**:
+1. Check service logs (`pm2 logs <service>`)
+2. Check Sentry for error details
+3. Verify request body matches expected schema
+4. Check database connectivity
+
+## Using auth-route-tester Agent
+
+For comprehensive route testing after making changes:
+
+1. **Identify affected routes**
+2. **Gather route information**:
+   - Full route path (with prefix)
+   - Expected POST data
+   - Tables to verify
+3. **Invoke auth-route-tester agent**
+
+The agent will:
+- Test the route with proper authentication
+- Verify database changes
+- Check response format
+- Report any issues
+
+## Example Test Scenarios
+
+### After Creating a New Route
+
+```bash
+# 1. Test with valid data
+node scripts/test-auth-route.js \
+    http://localhost:3002/api/my-new-route \
+    POST \
+    '{"field1":"value1","field2":"value2"}'
+
+# 2. Verify database
+docker exec -i local-mysql mysql -u root -ppassword1 blog_dev \
+    -e "SELECT * FROM MyTable ORDER BY createdAt DESC LIMIT 1;"
+
+# 3. Test with invalid data
+node scripts/test-auth-route.js \
+    http://localhost:3002/api/my-new-route \
+    POST \
+    '{"field1":"invalid"}'
+
+# 4. Test without authentication
+curl http://localhost:3002/api/my-new-route
+# Should return 401
+```
+
+### After Modifying a Route
+
+```bash
+# 1. Test existing functionality still works
+node scripts/test-auth-route.js \
+    http://localhost:3002/api/existing-route \
+    POST \
+    '{"existing":"data"}'
+
+# 2. Test new functionality
+node scripts/test-auth-route.js \
+    http://localhost:3002/api/existing-route \
+    POST \
+    '{"new":"field","existing":"data"}'
+
+# 3. Verify backward compatibility
+# Test with old request format (if applicable)
+```
+
+## Configuration Files
+
+### config.ini (each service)
+
+```ini
+[keycloak]
+url = http://localhost:8081
+realm = yourRealm
+clientId = app-client
+
+[jwt]
+jwtSecret = your-jwt-secret-here
+```
+
+### .env (each service)
+
+```bash
+NODE_ENV=development
+MOCK_AUTH=true           # Optional: Enable mock auth
+MOCK_USER_ID=test-user   # Optional: Default mock user
+MOCK_USER_ROLES=admin    # Optional: Default mock roles
+```
+
+## Key Files
+
+- `/root/git/your project_pre/scripts/test-auth-route.js` - Main testing script
+- `/blog-api/src/app.ts` - Form service routes
+- `/notifications/src/app.ts` - Email service routes
+- `/auth/src/app.ts` - Users service routes
+- `/config.ini` - Service configuration
+- `/.env` - Environment variables
+
+## Related Skills
+
+- Use **database-verification** to verify database changes
+- Use **error-tracking** to check for captured errors
+- Use **workflow-builder** for workflow route testing
+- Use **notification-sender** to verify notifications sent

package/.claude/skills/skill-developer/ADVANCED.md

@@ -0,0 +1,197 @@
+# Advanced Topics & Future Enhancements
+
+Ideas and concepts for future improvements to the skill system.
+
+---
+
+## Dynamic Rule Updates
+
+**Current State:** Requires Claude Code restart to pick up changes to skill-rules.json
+
+**Future Enhancement:** Hot-reload configuration without restart
+
+**Implementation Ideas:**
+- Watch skill-rules.json for changes
+- Reload on file modification
+- Invalidate cached compiled regexes
+- Notify user of reload
+
+**Benefits:**
+- Faster iteration during skill development
+- No need to restart Claude Code
+- Better developer experience
+
+---
+
+## Skill Dependencies
+
+**Current State:** Skills are independent
+
+**Future Enhancement:** Specify skill dependencies and load order
+
+**Configuration Idea:**
+```json
+{
+  "my-advanced-skill": {
+    "dependsOn": ["prerequisite-skill", "base-skill"],
+    "type": "domain",
+    ...
+  }
+}
+```
+
+**Use Cases:**
+- Advanced skill builds on base skill knowledge
+- Ensure foundational skills loaded first
+- Chain skills for complex workflows
+
+**Benefits:**
+- Better skill composition
+- Clearer skill relationships
+- Progressive disclosure
+
+---
+
+## Conditional Enforcement
+
+**Current State:** Enforcement level is static
+
+**Future Enhancement:** Enforce based on context or environment
+
+**Configuration Idea:**
+```json
+{
+  "enforcement": {
+    "default": "suggest",
+    "when": {
+      "production": "block",
+      "development": "suggest",
+      "ci": "block"
+    }
+  }
+}
+```
+
+**Use Cases:**
+- Stricter enforcement in production
+- Relaxed rules during development
+- CI/CD pipeline requirements
+
+**Benefits:**
+- Environment-appropriate enforcement
+- Flexible rule application
+- Context-aware guardrails
+
+---
+
+## Skill Analytics
+
+**Current State:** No usage tracking
+
+**Future Enhancement:** Track skill usage patterns and effectiveness
+
+**Metrics to Collect:**
+- Skill trigger frequency
+- False positive rate
+- False negative rate
+- Time to skill usage after suggestion
+- User override rate (skip markers, env vars)
+- Performance metrics (execution time)
+
+**Dashbord Ideas:**
+- Most/least used skills
+- Skills with highest false positive rate
+- Performance bottlenecks
+- Skill effectiveness scores
+
+**Benefits:**
+- Data-driven skill improvement
+- Identify problems early
+- Optimize patterns based on real usage
+
+---
+
+## Skill Versioning
+
+**Current State:** No version tracking
+
+**Future Enhancement:** Version skills and track compatibility
+
+**Configuration Idea:**
+```json
+{
+  "my-skill": {
+    "version": "2.1.0",
+    "minClaudeVersion": "1.5.0",
+    "changelog": "Added support for new workflow patterns",
+    ...
+  }
+}
+```
+
+**Benefits:**
+- Track skill evolution
+- Ensure compatibility
+- Document changes
+- Support migration paths
+
+---
+
+## Multi-Language Support
+
+**Current State:** English only
+
+**Future Enhancement:** Support multiple languages for skill content
+
+**Implementation Ideas:**
+- Language-specific SKILL.md variants
+- Automatic language detection
+- Fallback to English
+
+**Use Cases:**
+- International teams
+- Localized documentation
+- Multi-language projects
+
+---
+
+## Skill Testing Framework
+
+**Current State:** Manual testing with npx tsx commands
+
+**Future Enhancement:** Automated skill testing
+
+**Features:**
+- Test cases for trigger patterns
+- Assertion framework
+- CI/CD integration
+- Coverage reports
+
+**Example Test:**
+```typescript
+describe('database-verification', () => {
+  it('triggers on Prisma imports', () => {
+    const result = testSkill({
+      prompt: "add user tracking",
+      file: "services/user.ts",
+      content: "import { PrismaService } from './prisma'"
+    });
+
+    expect(result.triggered).toBe(true);
+    expect(result.skill).toBe('database-verification');
+  });
+});
+```
+
+**Benefits:**
+- Prevent regressions
+- Validate patterns before deployment
+- Confidence in changes
+
+---
+
+## Related Files
+
+- [SKILL.md](SKILL.md) - Main skill guide
+- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Current debugging guide
+- [HOOK_MECHANISMS.md](HOOK_MECHANISMS.md) - How hooks work today