@prmichaelsen/acp-visualizer 0.1.0

package/agent/commands/tanstack-cloudflare.deploy.md

@@ -0,0 +1,272 @@
+# Command: deploy
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@tanstack-cloudflare.deploy` has been invoked. Follow the steps below to execute this command.
+
+**Namespace**: tanstack-cloudflare
+**Version**: 1.0.0
+**Created**: 2026-02-21
+**Last Updated**: 2026-02-21
+**Status**: Active
+
+---
+
+**Purpose**: Build and deploy TanStack Start application to Cloudflare Workers using local environment configuration
+**Category**: Workflow
+**Frequency**: As Needed
+
+---
+
+## What This Command Does
+
+This command performs a complete build and deployment cycle for TanStack Start applications to Cloudflare Workers. It builds the application using Vite, sources the local Cloudflare environment variables, and deploys using Wrangler CLI.
+
+Use this command when you want to deploy changes to your Cloudflare Workers environment. It's particularly useful during development when you need to test changes in the actual Cloudflare environment rather than local development.
+
+The command ensures that the correct environment variables are loaded from `.env.cloudflare.local` before deployment, preventing accidental use of wrong credentials or configuration.
+
+---
+
+## Prerequisites
+
+- [ ] Node.js and npm installed
+- [ ] Wrangler CLI installed (`npm install -g wrangler`)
+- [ ] Cloudflare account configured (`wrangler login`)
+- [ ] `.env.cloudflare.local` file exists with required variables
+- [ ] Application code is ready to deploy (no syntax errors)
+- [ ] TanStack Start project properly configured
+
+---
+
+## Steps
+
+### 1. Build Application
+
+Build the application for production using Vite.
+
+**Actions**:
+- Run `npm run build`
+- Wait for build to complete
+- Verify no build errors
+
+**Expected Outcome**: Build completes successfully, `dist/` directory created
+
+**Example**:
+```bash
+npm run build
+```
+
+### 2. Deploy to Cloudflare Workers
+
+Export environment variables and deploy in a single command.
+
+**Actions**:
+- Export variables from `.env.cloudflare.local` and run `wrangler deploy` in one command
+- Environment variables loaded and immediately used for deployment
+- Wait for deployment to complete
+- Verify deployment success
+- Note the deployed URL
+
+**Expected Outcome**: Application deployed successfully to Cloudflare Workers
+
+**Example**:
+```bash
+export $(cat .env.cloudflare.local | xargs) && wrangler deploy
+```
+
+**Note**: This command reads the env file, exports all variables, and runs wrangler in the same shell session. The `&&` ensures wrangler only runs if export succeeds.
+
+### 3. Verify Deployment
+
+Confirm the deployment was successful.
+
+**Actions**:
+- Check wrangler output for deployment URL
+- Verify no deployment errors
+- Note the worker version/deployment ID
+
+**Expected Outcome**: Deployment URL displayed, no errors
+
+---
+
+## Verification
+
+- [ ] Build completed without errors
+- [ ] Environment variables sourced successfully
+- [ ] Wrangler deployment completed
+- [ ] Deployment URL displayed
+- [ ] No error messages in output
+- [ ] Application accessible at deployment URL
+
+---
+
+## Expected Output
+
+### Files Modified
+None - this is a deployment command (reads files, doesn't modify them)
+
+### Console Output
+```
+> build
+> vite build
+
+vite v7.3.1 building client environment for production...
+✓ 2126 modules transformed.
+✓ built in 6.60s
+
+vite v7.3.1 building ssr environment for production...
+✓ 5861 modules transformed.
+✓ built in 12.07s
+
+ ⛅️ wrangler 3.x.x
+-------------------
+Total Upload: xx.xx KiB / gzip: xx.xx KiB
+Uploaded your-app (x.xx sec)
+Published your-app (x.xx sec)
+  https://your-app.your-subdomain.workers.dev
+Current Deployment ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+```
+
+### Status Update
+- Application built successfully
+- Deployed to Cloudflare Workers
+- Accessible at deployment URL
+
+---
+
+## Examples
+
+### Example 1: Deploy After Feature Implementation
+
+**Context**: Just completed implementing a new feature and want to test in production
+
+**Invocation**: `@tanstack-cloudflare.deploy`
+
+**Result**: Application builds, environment variables loaded, deployed to Cloudflare Workers, deployment URL displayed
+
+### Example 2: Deploy After Bug Fix
+
+**Context**: Fixed a critical bug and need to deploy immediately
+
+**Invocation**: `@tanstack-cloudflare.deploy`
+
+**Result**: Quick build and deployment cycle, bug fix live in production
+
+### Example 3: Deploy for Testing
+
+**Context**: Need to test WebSocket functionality in actual Cloudflare environment
+
+**Invocation**: `@tanstack-cloudflare.deploy`
+
+**Result**: Application deployed with latest changes, can test real-world behavior
+
+---
+
+## Related Commands
+
+- [`@git.commit`](git.commit.md) - Commit changes before deploying
+- [`@acp.status`](acp.status.md) - Check project status before deploying
+
+---
+
+## Troubleshooting
+
+### Issue 1: Build fails with TypeScript errors
+
+**Symptom**: `npm run build` fails with TypeScript compilation errors
+
+**Cause**: Type errors in source code
+
+**Solution**: Fix TypeScript errors before deploying. Run `npm run typecheck` to see all errors.
+
+### Issue 2: Environment file not found
+
+**Symptom**: Error "No such file or directory: .env.cloudflare.local"
+
+**Cause**: `.env.cloudflare.local` file doesn't exist
+
+**Solution**: Create `.env.cloudflare.local` file with required Cloudflare variables. Copy from `.env.example` if available.
+
+### Issue 3: Wrangler authentication error
+
+**Symptom**: "Not authenticated" or "Invalid API token"
+
+**Cause**: Not logged in to Wrangler or token expired
+
+**Solution**: Run `wrangler login` to authenticate with Cloudflare account
+
+### Issue 4: Deployment fails with "Script too large"
+
+**Symptom**: Error about worker script size exceeding limits
+
+**Cause**: Bundle size too large for Cloudflare Workers free tier
+
+**Solution**: 
+- Optimize bundle size with code splitting
+- Remove unused dependencies
+- Consider upgrading to Workers Paid plan
+- Use dynamic imports for large dependencies
+
+### Issue 5: Environment variables not loaded
+
+**Symptom**: Deployment succeeds but application doesn't work correctly
+
+**Cause**: Environment variables not properly sourced or wrong file used
+
+**Solution**: Verify `.env.cloudflare.local` exists and contains correct variables. Ensure you're using `export $(cat .env.cloudflare.local | xargs) && wrangler deploy` (single command with &&).
+
+### Issue 6: TanStack Start build errors
+
+**Symptom**: Build fails with TanStack-specific errors
+
+**Cause**: Misconfigured TanStack Start project or incompatible dependencies
+
+**Solution**: 
+- Check `app.config.ts` is properly configured
+- Verify `@tanstack/start` version compatibility
+- Review TanStack Start documentation for breaking changes
+
+---
+
+## Security Considerations
+
+### File Access
+- **Reads**: All source files in `src/`, `dist/` directory after build, `.env.cloudflare.local`
+- **Writes**: `dist/` directory (build output)
+- **Executes**: `npm run build`, `wrangler deploy`
+
+### Network Access
+- **APIs**: Cloudflare API (for deployment)
+- **Repositories**: None
+
+### Sensitive Data
+- **Secrets**: Sources `.env.cloudflare.local` which may contain API tokens
+- **Credentials**: Wrangler uses stored Cloudflare credentials
+- **⚠️ Warning**: Never commit `.env.cloudflare.local` to version control
+- **⚠️ Warning**: Ensure `.env.cloudflare.local` is in `.gitignore`
+
+---
+
+## Notes
+
+- This command is for local development/testing deployments
+- For production deployments, use CI/CD pipeline
+- Always test locally before deploying (`npm run dev`)
+- Deployment typically takes 15-30 seconds
+- Old deployments are automatically replaced (not versioned)
+- Use `wrangler deployments list` to see deployment history
+- Use `wrangler rollback` to revert to previous deployment if needed
+- The environment variables must be sourced in the same command as wrangler deploy (using `&&`)
+- If deployment fails, check wrangler logs with `wrangler tail`
+- TanStack Start builds both client and SSR bundles - both are deployed
+- Cloudflare Workers have a 1MB compressed size limit for free tier
+
+---
+
+**Namespace**: tanstack-cloudflare
+**Command**: deploy
+**Version**: 1.0.0
+**Created**: 2026-02-21
+**Last Updated**: 2026-02-21
+**Status**: Active
+**Compatibility**: TanStack Start, Cloudflare Workers, Wrangler 3.x+
+**Author**: Patrick Michaelsen

package/agent/commands/tanstack-cloudflare.tail.md

@@ -0,0 +1,275 @@
+# Command: tail
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@tanstack-cloudflare.tail` has been invoked. Follow the steps below to execute this command.
+
+**Namespace**: tanstack-cloudflare
+**Version**: 1.0.0
+**Created**: 2026-02-21
+**Last Updated**: 2026-02-21
+**Status**: Active
+
+---
+
+**Purpose**: Stream real-time logs from deployed TanStack Start application on Cloudflare Workers
+**Category**: Debugging
+**Frequency**: As Needed
+
+---
+
+## What This Command Does
+
+This command streams real-time logs from your deployed TanStack Start application on Cloudflare Workers using Wrangler's tail functionality. It shows console.log statements, errors, and request information as they happen in production.
+
+Use this command when you need to debug production issues, monitor application behavior, or verify that deployed changes are working correctly. It's particularly useful after deployment to confirm everything is functioning as expected.
+
+The command loads environment variables from `.env.cloudflare.local` to authenticate with Cloudflare, then starts streaming logs from your worker.
+
+---
+
+## Prerequisites
+
+- [ ] Node.js and npm installed
+- [ ] Wrangler CLI installed (`npm install -g wrangler`)
+- [ ] Cloudflare account configured (`wrangler login`)
+- [ ] `.env.cloudflare.local` file exists with required variables
+- [ ] TanStack Start application deployed to Cloudflare Workers
+
+---
+
+## Steps
+
+### 1. Stream Worker Logs
+
+Export environment variables and start tailing logs in a single command.
+
+**Actions**:
+- Export variables from `.env.cloudflare.local`
+- Run `wrangler tail` to stream logs
+- Watch for console.log statements, errors, and requests
+- Press Ctrl+C to stop tailing
+
+**Expected Outcome**: Real-time logs streaming from deployed worker
+
+**Example**:
+```bash
+export $(cat .env.cloudflare.local | xargs) && wrangler tail
+```
+
+**Note**: This command will run continuously until you stop it with Ctrl+C. The logs will show all console.log, console.error, and console.warn statements from your worker, plus request information.
+
+### 2. Monitor Logs
+
+Watch the streaming logs for relevant information.
+
+**Actions**:
+- Look for console.log statements from your code
+- Watch for errors or warnings
+- Monitor request patterns
+- Check SSR rendering logs
+- Observe API route handling
+- Monitor beforeLoad execution
+
+**Expected Outcome**: Real-time visibility into worker behavior
+
+### 3. Stop Tailing
+
+Stop the log stream when done.
+
+**Actions**:
+- Press Ctrl+C to stop tailing
+- Logs stop streaming
+
+**Expected Outcome**: Command exits cleanly
+
+---
+
+## Verification
+
+- [ ] Environment variables loaded successfully
+- [ ] Wrangler tail started without errors
+- [ ] Logs are streaming in real-time
+- [ ] Can see console.log statements from worker
+- [ ] Can see SSR rendering logs
+- [ ] Can see API route logs
+- [ ] Can stop tailing with Ctrl+C
+
+---
+
+## Expected Output
+
+### Files Modified
+None - this is a read-only monitoring command
+
+### Console Output
+```
+ ⛅️ wrangler 4.x.x
+─────────────────────────────────────────────
+Tailing logs for your-app...
+
+[2026-02-21 05:20:00] GET https://your-app.workers.dev/
+[2026-02-21 05:20:00] [SSR] Rendering route: /
+[2026-02-21 05:20:00] [beforeLoad] Fetching user session
+[2026-02-21 05:20:01] [DatabaseService] getUserData: user123
+[2026-02-21 05:20:01] [SSR] Route rendered successfully
+[2026-02-21 05:20:05] GET https://your-app.workers.dev/api/data
+[2026-02-21 05:20:05] [API] /api/data - Processing request
+[2026-02-21 05:20:05] [DatabaseService] Query completed in 45ms
+[2026-02-21 05:20:05] [API] /api/data - Response sent (200)
+
+^C (Press Ctrl+C to stop)
+```
+
+### Status Update
+- Monitoring production logs in real-time
+- Can see all console.log/error/warn statements
+- Can observe request patterns and performance
+- Can debug SSR issues
+- Can monitor API route behavior
+
+---
+
+## Examples
+
+### Example 1: Debug SSR Issue
+
+**Context**: Users reporting blank pages, need to see SSR rendering logs
+
+**Invocation**: `@tanstack-cloudflare.tail`
+
+**Result**: Stream logs, see SSR errors, identify which route is failing
+
+### Example 2: Verify Deployment
+
+**Context**: Just deployed new feature, want to confirm it's working
+
+**Invocation**: `@tanstack-cloudflare.tail`
+
+**Result**: Watch logs as you test the feature, see console.log statements confirming behavior
+
+### Example 3: Monitor API Performance
+
+**Context**: Want to see how long database queries take in production
+
+**Invocation**: `@tanstack-cloudflare.tail`
+
+**Result**: See timing logs from database services, identify slow queries
+
+### Example 4: Debug beforeLoad Issues
+
+**Context**: Data not loading on SSR, need to see beforeLoad execution
+
+**Invocation**: `@tanstack-cloudflare.tail`
+
+**Result**: See beforeLoad logs, identify data fetching issues
+
+---
+
+## Related Commands
+
+- [`@tanstack-cloudflare.deploy`](tanstack-cloudflare.deploy.md) - Deploy before tailing logs
+- [`@git.commit`](git.commit.md) - Commit changes before deploying
+
+---
+
+## Troubleshooting
+
+### Issue 1: Environment file not found
+
+**Symptom**: Error "No such file or directory: .env.cloudflare.local"
+
+**Cause**: `.env.cloudflare.local` file doesn't exist
+
+**Solution**: Create `.env.cloudflare.local` file with required Cloudflare variables. Copy from `.env.example` if available.
+
+### Issue 2: Wrangler authentication error
+
+**Symptom**: "Not authenticated" or "Invalid API token"
+
+**Cause**: Not logged in to Wrangler or token expired
+
+**Solution**: Run `wrangler login` to authenticate with Cloudflare account
+
+### Issue 3: No logs appearing
+
+**Symptom**: Tail starts but no logs show up
+
+**Cause**: No requests being made to worker, or console.log statements removed
+
+**Solution**: Make requests to your worker (visit the URL, send API requests), or add console.log statements to your code
+
+### Issue 4: Too many logs
+
+**Symptom**: Logs scrolling too fast to read
+
+**Cause**: High traffic or verbose logging
+
+**Solution**: 
+- Use `wrangler tail --format pretty` for better formatting
+- Filter logs with grep: `export $(cat .env.cloudflare.local | xargs) && wrangler tail | grep "ERROR"`
+- Reduce console.log verbosity in code
+- Filter by specific service: `wrangler tail | grep "DatabaseService"`
+
+### Issue 5: Can't stop tailing
+
+**Symptom**: Ctrl+C doesn't stop the command
+
+**Cause**: Terminal not responding to interrupt signal
+
+**Solution**: Close the terminal tab, or use `kill` command from another terminal
+
+### Issue 6: SSR logs not showing
+
+**Symptom**: Only seeing client-side logs
+
+**Cause**: SSR console.log statements may be filtered or not present
+
+**Solution**: Add explicit console.log statements in beforeLoad and server-side code to verify SSR execution
+
+---
+
+## Security Considerations
+
+### File Access
+- **Reads**: `.env.cloudflare.local`
+- **Writes**: None
+- **Executes**: `wrangler tail`
+
+### Network Access
+- **APIs**: Cloudflare API (for log streaming)
+- **Repositories**: None
+
+### Sensitive Data
+- **Secrets**: Sources `.env.cloudflare.local` which may contain API tokens
+- **Credentials**: Wrangler uses stored Cloudflare credentials
+- **⚠️ Warning**: Logs may contain sensitive data (user IDs, API responses) - be careful when sharing logs
+- **⚠️ Warning**: Never commit logs to version control
+- **⚠️ Warning**: Avoid logging sensitive user data (passwords, tokens, PII)
+
+---
+
+## Notes
+
+- This command runs continuously until stopped with Ctrl+C
+- Logs are streamed in real-time (not historical)
+- Only shows logs from the current moment forward
+- For historical logs, use Cloudflare dashboard
+- Logs include console.log, console.error, console.warn from your worker
+- Also shows request information (method, URL, status code)
+- Useful for debugging production issues
+- Can be combined with grep to filter specific logs
+- Environment variables must be exported in the same command (using `&&`)
+- TanStack Start logs both SSR (server) and client-side code
+- beforeLoad executes on server, so logs appear in tail
+- API routes execute on server, so logs appear in tail
+- Client-side useEffect logs won't appear (only server-side)
+
+---
+
+**Namespace**: tanstack-cloudflare
+**Command**: tail
+**Version**: 1.0.0
+**Created**: 2026-02-21
+**Last Updated**: 2026-02-21
+**Status**: Active
+**Compatibility**: TanStack Start, Cloudflare Workers, Wrangler 3.x+
+**Author**: Patrick Michaelsen

package/agent/design/design.template.md

@@ -0,0 +1,154 @@
+# {Feature/Pattern Name}
+
+**Concept**: [One-line description of what this design addresses]
+**Created**: YYYY-MM-DD
+**Status**: Proposal | Design Specification | Implemented
+
+---
+
+## Overview
+
+[High-level description of what this design document covers and why it exists. Provide context about the problem space and the importance of this design decision.]
+
+**Example**: "This document describes the authentication flow for multi-tenant access, enabling secure per-user data isolation across the system."
+
+---
+
+## Problem Statement
+
+[Clearly articulate the problem this design solves. Include:]
+- What challenge or limitation exists?
+- Why is this a problem worth solving?
+- What are the consequences of not solving it?
+
+**Example**: "Without proper multi-tenant isolation, users could potentially access each other's data, creating security vulnerabilities and privacy concerns."
+
+---
+
+## Solution
+
+[Describe the proposed solution at a conceptual level. Include:]
+- High-level approach
+- Key components involved
+- How the solution addresses the problem
+- Alternative approaches considered (and why they were rejected)
+
+**Example**: "Implement row-level security using user_id as a tenant identifier, enforced at both the database and application layers."
+
+---
+
+## Implementation
+
+[Provide technical details needed to implement this design. Include:]
+- Architecture diagrams (as ASCII art or references)
+- Data structures and schemas
+- API interfaces
+- Code examples (use placeholder names)
+- Configuration requirements
+- Dependencies
+
+**Example**:
+```typescript
+interface TenantContext {
+  userId: string;
+  permissions: string[];
+}
+
+class DataService {
+  constructor(private context: TenantContext) {}
+  
+  async getData(id: string): Promise<Data> {
+    // Implementation with tenant filtering
+  }
+}
+```
+
+---
+
+## Benefits
+
+[List the advantages of this approach:]
+- Benefit 1: [Description]
+- Benefit 2: [Description]
+- Benefit 3: [Description]
+
+**Example**:
+- **Security**: Complete data isolation between tenants
+- **Scalability**: Horizontal scaling without data mixing concerns
+- **Compliance**: Meets data privacy regulations (GDPR, etc.)
+
+---
+
+## Trade-offs
+
+[Honestly assess the downsides and limitations:]
+- Trade-off 1: [Description and mitigation strategy]
+- Trade-off 2: [Description and mitigation strategy]
+- Trade-off 3: [Description and mitigation strategy]
+
+**Example**:
+- **Performance**: Additional filtering adds query overhead (mitigated by proper indexing)
+- **Complexity**: More complex queries and testing requirements
+- **Migration**: Existing data requires backfill with tenant identifiers
+
+---
+
+## Dependencies
+
+[List any dependencies this design has:]
+- External services or APIs
+- Other design documents
+- Infrastructure requirements
+- Third-party libraries
+
+---
+
+## Testing Strategy
+
+[Describe how to verify this design works correctly:]
+- Unit test requirements
+- Integration test scenarios
+- Security test cases
+- Performance benchmarks
+
+---
+
+## Migration Path
+
+[If this changes existing functionality, describe the migration strategy:]
+1. Step 1: [Description]
+2. Step 2: [Description]
+3. Step 3: [Description]
+
+---
+
+## Key Design Decisions (Optional)
+
+<!-- This section is populated by @acp.clarification-capture when
+     create commands are invoked with --from-clar, --from-chat, or
+     --from-context. It can also be manually authored.
+     Omit this section entirely if no decisions to capture.
+
+     Group decisions by agent-inferred category using tables:
+
+### {Category}
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| {decision} | {choice} | {rationale} |
+-->
+
+---
+
+## Future Considerations
+
+[Note any future enhancements or related work:]
+- Future enhancement 1
+- Future enhancement 2
+- Related design documents to create
+
+---
+
+**Status**: [Current implementation status]
+**Recommendation**: [What should be done next - implement, review, revise, etc.]
+**Related Documents**: [Links to related design docs, milestones, or tasks]