create-debug-script

Purpose

Create a one-off TypeScript debug script for quick testing and debugging. The script should be self-contained with minimal external dependencies.

Philosophy (CRITICAL - Read before every execution)

• FACTS FIRST: Real results always trump user expectations
• CELEBRATE CONTRADICTIONS: When results ≠ expectations, highlight this as the key finding
• COMPLETE NEUTRALITY: Report observations without bias toward user hypotheses
• NEVER RATIONALIZE UNEXPECTED RESULTS: They are the most valuable discoveries

Constraints

• Minimal imports - Prefer Node.js built-ins and existing packages when possible
• Single file - Everything in one TypeScript file
• Temporary nature - Script may be deleted after use

Decision Criteria

Location Selection

IF debugging agent-related code:
  → frontend/internal-packages/agent/scripts/
ELSE IF debugging specific package:
  → [package-root]/scripts/
ELSE:
  → frontend/scripts/

Naming Convention

• Pattern: debug-[specific-purpose].ts
• Examples:
  • debug-multi-agent-supervisor.ts
  • debug-api-connection.ts
  • debug-memory-usage.ts

Implementation Steps

1. Create directory (if not exists):

   mkdir -p [chosen-location]/scripts
   

2. Generate script with this structure:

   // How to run this script:
   // pnpm dlx tsx scripts/debug-[purpose].ts
   
   // === Configuration ===
   // If env vars needed, calculate path from script to root .env:
   // import { config } from 'dotenv'
   // import { resolve } from 'node:path'
   // config({ path: resolve(__dirname, '../../.env') }) // Adjust '../' count based on script depth
   // if (!process.env.REQUIRED_VAR) throw new Error('Failed to load .env')
   
   // === Debug Logic ===
   async function debug() {
     console.log('🔍 Debug execution:', '[purpose]')
     console.log('─'.repeat(50))
   
     // User's debug logic here
   
     console.log('─'.repeat(50))
     console.log('📊 Debug execution finished')
   }
   
   // === Execute ===
   debug().catch(err => {
     console.error('❌ Debug execution encountered exception:', err)
     process.exit(1)
   })