threewzrd 1.0.4 → 1.0.6

package/dist/core/AgentEngine.js

@@ -58,14 +58,17 @@ export class AgentEngine {
     }
     async runAgentLoop() {
         let continueLoop = true;
+        let turn = 1;
         while (continueLoop) {
-            continueLoop = await this.runSingleTurn();
+            continueLoop = await this.runSingleTurn(turn);
+            turn++;
         }
     }
-    async runSingleTurn(retryCount = 0) {
+    async runSingleTurn(turn, retryCount = 0) {
         try {
-            // Show thinking indicator
-            this.ui.startThinking('Thinking');
+            // Show thinking indicator with turn info
+            const thinkingMessage = turn === 1 ? 'Thinking' : 'Processing';
+            this.ui.startThinking(thinkingMessage, turn);
             // Create the API request with streaming
             const stream = this.client.messages.stream({
                 model: MODEL_MAP[this.model],
@@ -110,8 +113,13 @@ export class AgentEngine {
             }
             // Execute all tool calls
             const toolResults = [];
-            for (const toolUse of toolUseBlocks) {
+            const totalTools = toolUseBlocks.length;
+            for (let i = 0; i < toolUseBlocks.length; i++) {
+                const toolUse = toolUseBlocks[i];
+                const toolProgress = totalTools > 1 ? ` (${i + 1}/${totalTools})` : '';
+                this.ui.startThinking(`Executing ${toolUse.name}${toolProgress}`, turn);
                 const result = await this.toolExecutor.execute(toolUse.name, toolUse.input);
+                this.ui.stopThinking();
                 // Truncate large outputs to save tokens
                 let output = result.success ? result.output : `Error: ${result.error}`;
                 if (output.length > 2000) {
@@ -140,7 +148,7 @@ export class AgentEngine {
                     const delay = RETRY_DELAY_MS * Math.pow(2, retryCount);
                     this.ui.printWarning(`Rate limited. Retrying in ${delay / 1000}s...`);
                     await this.sleep(delay);
-                    return this.runSingleTurn(retryCount + 1);
+                    return this.runSingleTurn(turn, retryCount + 1);
                 }
                 this.ui.printError('Rate limit exceeded. Please wait a moment and try again.');
                 return false;

package/dist/core/ThreeJsWizard.d.ts

@@ -9,6 +9,7 @@ export declare class ThreeJsWizard {
     private workingDirectory;
     private isRunning;
     private hasOnboarded;
+    private currentMode;
     constructor(options?: WizardOptions);
     start(): Promise<void>;
     private handleCommand;

package/dist/core/ThreeJsWizard.js

@@ -9,6 +9,7 @@ export class ThreeJsWizard {
     workingDirectory;
     isRunning = false;
     hasOnboarded = false;
+    currentMode = 'single-shot';
     constructor(options) {
         this.workingDirectory = process.cwd();
         this.ui = new TerminalUI();
@@ -42,6 +43,7 @@ export class ThreeJsWizard {
         if (!this.hasOnboarded && isEmptyDir) {
             const preferences = await runOnboarding(this.ui);
             this.hasOnboarded = true;
+            this.currentMode = preferences.mode;
             // Process the initial project request
             const contextMessage = buildContextMessage(preferences);
             await this.engine.processMessage(contextMessage);
@@ -53,7 +55,8 @@ export class ThreeJsWizard {
         // Main REPL loop
         while (this.isRunning) {
             try {
-                const input = await this.ui.prompt();
+                const { text: input, mode } = await this.ui.promptWithMode(this.currentMode);
+                this.currentMode = mode;
                 if (!input) {
                     continue;
                 }
@@ -62,8 +65,13 @@ export class ThreeJsWizard {
                     await this.handleCommand(input);
                     continue;
                 }
+                // Build message with mode context
+                const modePrefix = mode === 'planning'
+                    ? '[PLANNING MODE] Output a detailed implementation plan before coding.\n\n'
+                    : '';
+                const fullMessage = modePrefix + input;
                 // Process user message through agent
-                await this.engine.processMessage(input);
+                await this.engine.processMessage(fullMessage);
                 // Track created files
                 for (const file of this.engine.getCreatedFiles()) {
                     this.projectManager.addFile(file);

package/dist/core/types.d.ts

@@ -4,10 +4,12 @@ export declare const MODEL_MAP: Record<ModelId, string>;
 export declare const DEFAULT_MODEL: ModelId;
 export type ProjectLanguage = 'javascript' | 'typescript';
 export type ProjectTarget = 'browser' | 'mobile' | 'desktop';
+export type ExecutionMode = 'single-shot' | 'planning';
 export interface ProjectPreferences {
     language: ProjectLanguage;
     target: ProjectTarget;
     description: string;
+    mode: ExecutionMode;
 }
 export interface ProjectConfig {
     name: string;

package/dist/tools/ToolExecutor.js

@@ -1,6 +1,7 @@
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import { spawn } from 'child_process';
+import chalk from 'chalk';
 import { shouldValidate, validate } from './CodeValidator.js';
 // Whitelist of allowed commands for security
 const ALLOWED_COMMANDS = new Set([
@@ -64,12 +65,29 @@ export class ToolExecutor {
         if (typeof obj.path !== 'string' || !obj.path.trim()) {
             throw new Error('Invalid input: path must be a non-empty string');
         }
-        if (typeof obj.content !== 'string') {
-            throw new Error('Invalid input: content must be a string');
+        // Coerce content to string - handle various types the model might return
+        let content;
+        if (typeof obj.content === 'string') {
+            content = obj.content;
+        }
+        else if (obj.content === null || obj.content === undefined) {
+            content = '';
+        }
+        else if (Array.isArray(obj.content)) {
+            // Model sometimes returns content as an array of strings
+            content = obj.content.map(item => String(item)).join('\n');
+        }
+        else if (typeof obj.content === 'object') {
+            // Fallback: stringify objects
+            content = JSON.stringify(obj.content, null, 2);
+        }
+        else {
+            // Fallback for numbers, booleans, etc.
+            content = String(obj.content);
         }
         return {
             path: obj.path.trim(),
-            content: obj.content,
+            content,
             skipValidation: obj.skipValidation === true
         };
     }
@@ -215,6 +233,7 @@ export class ToolExecutor {
         try {
             // Validate input structure
             const validatedInput = this.validateWriteFileInput(input);
+            this.ui.startToolSpinner('write_file', `Writing ${validatedInput.path}`);
             // Validate path doesn't escape working directory
             const fullPath = this.validatePath(validatedInput.path);
             const dir = path.dirname(fullPath);
@@ -224,8 +243,7 @@ export class ToolExecutor {
                 // If there are errors, don't write the file
                 if (!validationResult.valid) {
                     const errorDetails = validationResult.errors.join('\n  - ');
-                    this.ui.printToolCall('write_file', `Writing: ${validatedInput.path}`);
-                    this.ui.printToolResult(false, 'Syntax validation failed');
+                    this.ui.failToolSpinner('Syntax validation failed');
                     return {
                         success: false,
                         output: '',
@@ -244,8 +262,7 @@ export class ToolExecutor {
             // Write the file
             await fs.writeFile(fullPath, validatedInput.content, 'utf-8');
             this.createdFiles.add(validatedInput.path);
-            this.ui.printToolCall('write_file', `Writing: ${validatedInput.path}`);
-            this.ui.printToolResult(true, '');
+            this.ui.succeedToolSpinner(`Wrote ${validatedInput.path}`);
             return {
                 success: true,
                 output: `Successfully wrote ${validatedInput.path}`,
@@ -253,9 +270,7 @@ export class ToolExecutor {
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
-            const displayPath = input?.path || 'unknown';
-            this.ui.printToolCall('write_file', `Writing: ${displayPath}`);
-            this.ui.printToolResult(false, errorMessage);
+            this.ui.failToolSpinner(`Failed to write: ${errorMessage}`);
             return {
                 success: false,
                 output: '',
@@ -267,11 +282,11 @@ export class ToolExecutor {
         try {
             // Validate input structure
             const validatedInput = this.validateReadFileInput(input);
+            this.ui.startToolSpinner('read_file', `Reading ${validatedInput.path}`);
             // Validate path doesn't escape working directory
             const fullPath = this.validatePath(validatedInput.path);
             const content = await fs.readFile(fullPath, 'utf-8');
-            this.ui.printToolCall('read_file', `Reading: ${validatedInput.path}`);
-            this.ui.printToolResult(true, '');
+            this.ui.succeedToolSpinner(`Read ${validatedInput.path}`);
             return {
                 success: true,
                 output: content,
@@ -279,9 +294,7 @@ export class ToolExecutor {
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
-            const displayPath = input?.path || 'unknown';
-            this.ui.printToolCall('read_file', `Reading: ${displayPath}`);
-            this.ui.printToolResult(false, errorMessage);
+            this.ui.failToolSpinner(`Failed to read: ${errorMessage}`);
             return {
                 success: false,
                 output: '',
@@ -301,17 +314,20 @@ export class ToolExecutor {
             if (validatedInput.cwd) {
                 cwd = this.validatePath(validatedInput.cwd);
             }
-            this.ui.printToolCall('run_command', `Command: ${validatedInput.command}`);
+            // Show command for user confirmation
+            console.log();
+            console.log(chalk.yellow(`[Command] `) + chalk.gray(validatedInput.command));
             // Ask for user confirmation before running any command
             const approved = await this.ui.confirm(`Run this command?`);
             if (!approved) {
-                this.ui.printToolResult(false, 'User declined');
+                console.log(chalk.red('  ✗ Declined'));
                 return {
                     success: false,
                     output: '',
                     error: 'User declined to run this command',
                 };
             }
+            this.ui.startToolSpinner('run_command', `Running: ${validatedInput.command}`);
             // For piped commands, use shell with pre-validated command string
             // For non-piped commands, use spawn without shell for security
             return new Promise((resolve) => {
@@ -338,14 +354,14 @@ export class ToolExecutor {
                 child.on('close', (code) => {
                     const output = stdout + (stderr ? `\nStderr: ${stderr}` : '');
                     if (code === 0) {
-                        this.ui.printToolResult(true, '');
+                        this.ui.succeedToolSpinner('Command completed');
                         resolve({
                             success: true,
                             output: output || 'Command completed successfully',
                         });
                     }
                     else {
-                        this.ui.printToolResult(false, `Exit code: ${code}`);
+                        this.ui.failToolSpinner(`Exit code: ${code}`);
                         resolve({
                             success: false,
                             output: '',
@@ -354,7 +370,7 @@ export class ToolExecutor {
                     }
                 });
                 child.on('error', (error) => {
-                    this.ui.printToolResult(false, error.message);
+                    this.ui.failToolSpinner(error.message);
                     resolve({
                         success: false,
                         output: '',
@@ -365,9 +381,7 @@ export class ToolExecutor {
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
-            const displayCmd = input?.command || 'unknown';
-            this.ui.printToolCall('run_command', `Command: ${displayCmd}`);
-            this.ui.printToolResult(false, errorMessage);
+            this.ui.failToolSpinner(`Failed: ${errorMessage}`);
             return {
                 success: false,
                 output: '',
@@ -379,15 +393,16 @@ export class ToolExecutor {
         try {
             // Validate input structure
             const validatedInput = this.validateListFilesInput(input);
+            const displayPath = validatedInput.path || '.';
+            this.ui.startToolSpinner('list_files', `Listing ${displayPath}`);
             // Validate path doesn't escape working directory
             const targetPath = validatedInput.path
                 ? this.validatePath(validatedInput.path)
                 : this.workingDirectory;
-            this.ui.printToolCall('list_files', `Listing: ${validatedInput.path || '.'}`);
             const files = await this.listFilesRecursive(targetPath, validatedInput.recursive ?? false);
             // Format output
             const relativePaths = files.map(f => path.relative(this.workingDirectory, f));
-            this.ui.printToolResult(true, '');
+            this.ui.succeedToolSpinner(`Listed ${relativePaths.length} items`);
             return {
                 success: true,
                 output: relativePaths.length > 0
@@ -397,9 +412,7 @@ export class ToolExecutor {
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
-            const displayPath = input?.path || '.';
-            this.ui.printToolCall('list_files', `Listing: ${displayPath}`);
-            this.ui.printToolResult(false, errorMessage);
+            this.ui.failToolSpinner(`Failed to list: ${errorMessage}`);
             return {
                 success: false,
                 output: '',

package/dist/ui/TerminalUI.d.ts

@@ -1,4 +1,4 @@
-import { ModelId } from '../core/types.js';
+import { ModelId, ExecutionMode } from '../core/types.js';
 export interface SelectOption {
     label: string;
     value: string;
@@ -7,9 +7,15 @@ export declare class TerminalUI {
     private rl;
     private isStreaming;
     private thinkingSpinner;
+    private toolSpinner;
     constructor();
-    startThinking(message?: string): void;
+    startThinking(message?: string, turn?: number): void;
+    updateThinking(message: string, turn?: number): void;
     stopThinking(): void;
+    startToolSpinner(toolName: string, detail: string): void;
+    succeedToolSpinner(message?: string): void;
+    failToolSpinner(message: string): void;
+    stopToolSpinner(): void;
     confirm(message: string): Promise<boolean>;
     select(question: string, options: SelectOption[]): Promise<string>;
     printBanner(): void;
@@ -31,6 +37,11 @@ export declare class TerminalUI {
     streamText(text: string): void;
     endStreaming(): void;
     prompt(): Promise<string>;
+    promptWithMode(defaultMode?: ExecutionMode): Promise<{
+        text: string;
+        mode: ExecutionMode;
+    }>;
+    printModeInfo(mode: ExecutionMode): void;
     close(): void;
     clearScreen(): void;
 }

package/dist/ui/TerminalUI.js

@@ -5,20 +5,28 @@ export class TerminalUI {
     rl;
     isStreaming = false;
     thinkingSpinner = null;
+    toolSpinner = null;
     constructor() {
         this.rl = readline.createInterface({
             input: process.stdin,
             output: process.stdout,
         });
     }
-    // Thinking indicator
-    startThinking(message = 'Thinking') {
+    // Thinking indicator with turn info
+    startThinking(message = 'Thinking', turn) {
+        const turnInfo = turn ? chalk.gray(` [Turn ${turn}]`) : '';
         this.thinkingSpinner = ora({
-            text: chalk.cyan(message),
+            text: chalk.cyan(message) + turnInfo,
             spinner: 'dots',
             discardStdin: false, // Don't interfere with readline
         }).start();
     }
+    updateThinking(message, turn) {
+        if (this.thinkingSpinner) {
+            const turnInfo = turn ? chalk.gray(` [Turn ${turn}]`) : '';
+            this.thinkingSpinner.text = chalk.cyan(message) + turnInfo;
+        }
+    }
     stopThinking() {
         if (this.thinkingSpinner) {
             this.thinkingSpinner.stop();
@@ -29,6 +37,32 @@ export class TerminalUI {
             process.stdin.resume();
         }
     }
+    // Tool execution spinner
+    startToolSpinner(toolName, detail) {
+        this.toolSpinner = ora({
+            text: chalk.yellow(`${toolName}: `) + chalk.gray(detail),
+            spinner: 'dots',
+            discardStdin: false,
+        }).start();
+    }
+    succeedToolSpinner(message) {
+        if (this.toolSpinner) {
+            this.toolSpinner.succeed(message ? chalk.green(message) : undefined);
+            this.toolSpinner = null;
+        }
+    }
+    failToolSpinner(message) {
+        if (this.toolSpinner) {
+            this.toolSpinner.fail(chalk.red(message));
+            this.toolSpinner = null;
+        }
+    }
+    stopToolSpinner() {
+        if (this.toolSpinner) {
+            this.toolSpinner.stop();
+            this.toolSpinner = null;
+        }
+    }
     // Confirmation prompt for dangerous actions
     async confirm(message) {
         // Ensure any spinner is stopped
@@ -78,12 +112,18 @@ export class TerminalUI {
         console.log(chalk.gray('  lighting, animations, and more - just describe what'));
         console.log(chalk.gray('  you want in plain English.'));
         console.log();
+        console.log(chalk.gray('  Modes: ') + chalk.cyan('⚡ Quick') + chalk.gray(' | ') + chalk.magenta('📋 Plan') + chalk.gray('  (Tab to switch)'));
         console.log(chalk.gray('  Commands: ') + chalk.yellow('/help') + chalk.gray(' | ') + chalk.yellow('/clear') + chalk.gray(' | ') + chalk.yellow('/exit'));
         console.log();
         console.log(chalk.gray('  ─────────────────────────────────────────'));
         console.log();
     }
     printHelp() {
+        console.log();
+        console.log(chalk.yellow('Execution Modes:'));
+        console.log(chalk.cyan('  ⚡ Quick Mode') + chalk.gray('        - Direct implementation (default)'));
+        console.log(chalk.magenta('  📋 Plan Mode') + chalk.gray('         - Detailed architecture plan first'));
+        console.log(chalk.gray('  Press Tab while typing to switch modes'));
         console.log();
         console.log(chalk.yellow('Commands:'));
         console.log(chalk.cyan('  /help') + chalk.gray('              - Show this help message'));
@@ -176,6 +216,100 @@ export class TerminalUI {
             });
         });
     }
+    // Mode-aware prompt with Tab toggle for execution mode
+    async promptWithMode(defaultMode = 'single-shot') {
+        let currentMode = defaultMode;
+        // Print mode indicator and instructions
+        const printModeBar = () => {
+            const singleShot = currentMode === 'single-shot'
+                ? chalk.bgCyan.black(' ⚡ Quick ')
+                : chalk.gray(' ⚡ Quick ');
+            const planning = currentMode === 'planning'
+                ? chalk.bgMagenta.white(' 📋 Plan ')
+                : chalk.gray(' 📋 Plan ');
+            // Clear line and reprint
+            process.stdout.write('\r\x1b[K');
+            process.stdout.write(`  ${singleShot} ${planning}  ${chalk.gray('Tab to switch')}\n`);
+        };
+        return new Promise((resolve) => {
+            printModeBar();
+            console.log();
+            // Close the existing readline interface to fully release stdin
+            this.rl.close();
+            // Store the current input
+            let inputBuffer = '';
+            // Set up raw mode for keypress detection
+            if (process.stdin.isTTY) {
+                process.stdin.setRawMode(true);
+            }
+            process.stdin.resume();
+            const promptPrefix = chalk.magenta('  › ');
+            process.stdout.write(promptPrefix);
+            const handleKeypress = (chunk) => {
+                const key = chunk.toString();
+                // Tab key - toggle mode
+                if (key === '\t') {
+                    currentMode = currentMode === 'single-shot' ? 'planning' : 'single-shot';
+                    // Move cursor up, clear the mode bar, reprint it, move back down
+                    process.stdout.write('\x1b[2A'); // Move up 2 lines
+                    printModeBar();
+                    console.log();
+                    process.stdout.write(promptPrefix + inputBuffer);
+                    return;
+                }
+                // Enter key - submit
+                if (key === '\r' || key === '\n') {
+                    process.stdout.write('\n');
+                    cleanup();
+                    resolve({ text: inputBuffer.trim(), mode: currentMode });
+                    return;
+                }
+                // Ctrl+C - exit
+                if (key === '\x03') {
+                    cleanup();
+                    process.exit(0);
+                }
+                // Backspace
+                if (key === '\x7f' || key === '\b') {
+                    if (inputBuffer.length > 0) {
+                        inputBuffer = inputBuffer.slice(0, -1);
+                        process.stdout.write('\b \b');
+                    }
+                    return;
+                }
+                // Escape sequences (arrow keys, etc.) - ignore for simplicity
+                if (key.startsWith('\x1b')) {
+                    return;
+                }
+                // Regular character
+                if (key.length === 1 && key.charCodeAt(0) >= 32) {
+                    inputBuffer += key;
+                    process.stdout.write(key);
+                }
+            };
+            const cleanup = () => {
+                process.stdin.removeListener('data', handleKeypress);
+                if (process.stdin.isTTY) {
+                    process.stdin.setRawMode(false);
+                }
+                // Recreate readline interface
+                this.rl = readline.createInterface({
+                    input: process.stdin,
+                    output: process.stdout,
+                });
+            };
+            process.stdin.on('data', handleKeypress);
+        });
+    }
+    printModeInfo(mode) {
+        if (mode === 'single-shot') {
+            console.log(chalk.cyan('  ⚡ Quick Mode: ') + chalk.gray('Direct implementation without formal planning'));
+        }
+        else {
+            console.log(chalk.magenta('  📋 Plan Mode: ') + chalk.gray('Detailed architecture plan before implementation'));
+        }
+        console.log();
+    }
     close() {
         this.rl.close();
     }

package/dist/ui/onboarding.js

@@ -12,27 +12,33 @@ export async function runOnboarding(ui) {
         { label: 'Mobile (React Native, etc.)', value: 'mobile' },
         { label: 'Desktop (Electron, etc.)', value: 'desktop' },
     ]);
-    // Ask for project description
+    // Ask for project description with mode toggle
     console.log();
-    console.log(chalk.cyan('  Now describe what you\'d like to build:'));
+    console.log(chalk.cyan('  Describe what you\'d like to build:'));
     console.log(chalk.gray('  (e.g., "A 3D solar system with orbiting planets")'));
     console.log();
-    const description = await ui.prompt();
+    const { text: description, mode } = await ui.promptWithMode('single-shot');
     console.log();
+    ui.printModeInfo(mode);
     console.log(chalk.gray('  ─────────────────────────────────────────'));
     console.log();
     return {
         language,
         target,
         description,
+        mode,
     };
 }
 export function buildContextMessage(prefs) {
+    const modeInstruction = prefs.mode === 'planning'
+        ? `\n\nIMPORTANT: The user has requested Planning Mode. You MUST output a detailed implementation plan with Architecture Overview, Dependencies, File Structure, and Execution Steps BEFORE writing any code.`
+        : `\n\nThe user has requested Single-Shot Mode. Plan internally and proceed directly to implementation without outputting a formal plan.`;
     return `The user wants to create a Three.js project with these preferences:
 - Language: ${prefs.language}
 - Target platform: ${prefs.target}
+- Execution mode: ${prefs.mode === 'planning' ? 'Planning Mode (detailed plan first)' : 'Single-Shot Mode (direct implementation)'}
 
-Their project description: ${prefs.description}
+Their project description: ${prefs.description}${modeInstruction}
 
 Please create the project structure and initial files based on these requirements. Start by setting up the basic Three.js scene.`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "threewzrd",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "AI-powered CLI for generating Three.js projects from natural language",
   "main": "dist/cli.js",
   "bin": {