threewzrd 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dogmandcl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# threewzrd
+
+AI-powered CLI for generating Three.js projects from natural language.
+
+Describe what you want to build and let the AI create complete, runnable Three.js scenes for you.
+
+## Installation
+
+```bash
+npm install -g threewzrd
+```
+
+Requires Node.js 18 or higher.
+
+## Quick Start
+
+1. Get an API key from [Anthropic Console](https://console.anthropic.com/)
+
+2. Start the wizard:
+   ```bash
+   threewzrd start
+   ```
+
+3. Enter your API key when prompted (it will be saved securely for future sessions)
+
+4. Describe what you want to build:
+   ```
+   > Create a rotating cube with a gradient shader
+   ```
+
+The wizard will generate all necessary files (HTML, JavaScript, shaders) and guide you through running them.
+
+## Commands
+
+### `threewzrd start [directory]`
+
+Start an interactive session in the specified directory (defaults to current directory).
+
+```bash
+threewzrd start
+threewzrd start ./my-project
+```
+
+### `threewzrd config`
+
+View current configuration.
+
+```bash
+threewzrd config
+```
+
+### `threewzrd config --set`
+
+Set or update your API key.
+
+```bash
+threewzrd config --set
+```
+
+### `threewzrd config --delete`
+
+Delete your saved API key.
+
+```bash
+threewzrd config --delete
+```
+
+### `threewzrd config --path`
+
+Show the config file location.
+
+```bash
+threewzrd config --path
+```
+
+## API Key Setup
+
+Your API key is stored securely at `~/.threewzrd/.env` with restricted permissions (owner read/write only).
+
+You can also set it via environment variable:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+threewzrd start
+```
+
+Or create a `.env` file in your project directory:
+
+```
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+## Features
+
+- **Natural Language Input**: Describe 3D scenes in plain English
+- **Complete Project Generation**: Creates HTML, JavaScript, and shader files
+- **Interactive REPL**: Iterate on your designs with follow-up requests
+- **File Management**: Automatically organizes generated files
+- **Secure**: API keys are masked during input and stored with restricted permissions
+- **Command Safety**: Only whitelisted commands can be executed
+
+## Examples
+
+```
+> Create a particle system that looks like falling snow
+
+> Make a 3D solar system with orbiting planets
+
+> Build a terrain with procedural noise and water
+
+> Create a first-person camera controller
+```
+
+## Security
+
+- API keys are stored with `0600` permissions (owner read/write only)
+- Input is masked when entering API keys
+- Commands are restricted to a safe whitelist (npm, npx, node, git, etc.)
+- File operations are sandboxed to the working directory
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { homedir } from 'os';
+import { startCommand } from './commands/start.js';
+import { configCommand } from './commands/config.js';
+// Safely get current working directory, fallback to home
+function safeGetCwd() {
+    try {
+        return process.cwd();
+    }
+    catch {
+        // If cwd is inaccessible (deleted directory, etc.), use home
+        return homedir();
+    }
+}
+const program = new Command();
+program
+    .name('threewzrd')
+    .description('AI-powered CLI for generating Three.js projects from natural language')
+    .version('1.0.0');
+program
+    .command('start')
+    .description('Start the wizard REPL')
+    .option('-d, --directory <path>', 'Working directory for the wizard', safeGetCwd())
+    .action(startCommand);
+program
+    .command('config')
+    .description('Manage API key and configuration')
+    .option('-s, --set', 'Set or update API key')
+    .option('-d, --delete', 'Delete saved API key')
+    .option('-p, --path', 'Show config file path')
+    .action(configCommand);
+program.parse();

package/dist/commands/config.d.ts

@@ -0,0 +1,7 @@
+interface ConfigOptions {
+    set?: boolean;
+    delete?: boolean;
+    path?: boolean;
+}
+export declare function configCommand(options: ConfigOptions): Promise<void>;
+export {};

package/dist/commands/config.js

@@ -0,0 +1,159 @@
+import { homedir } from 'os';
+import { join } from 'path';
+import { mkdir, writeFile, readFile, unlink } from 'fs/promises';
+import * as readline from 'readline';
+import chalk from 'chalk';
+const CONFIG_DIR = join(homedir(), '.threewzrd');
+const CONFIG_PATH = join(CONFIG_DIR, '.env');
+async function promptInput(question, masked = false) {
+    if (!masked) {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        return new Promise((resolve) => {
+            rl.question(question, (answer) => {
+                rl.close();
+                resolve(answer.trim());
+            });
+        });
+    }
+    // Masked input for sensitive data
+    return new Promise((resolve) => {
+        const stdin = process.stdin;
+        const stdout = process.stdout;
+        stdout.write(question);
+        const wasRaw = stdin.isRaw;
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding('utf8');
+        let input = '';
+        const onData = (char) => {
+            const code = char.charCodeAt(0);
+            // Enter key
+            if (code === 13 || code === 10) {
+                stdin.setRawMode(wasRaw ?? false);
+                stdin.removeListener('data', onData);
+                stdin.pause();
+                stdout.write('\n');
+                resolve(input.trim());
+                return;
+            }
+            // Ctrl+C
+            if (code === 3) {
+                stdin.setRawMode(wasRaw ?? false);
+                stdin.removeListener('data', onData);
+                stdout.write('\n');
+                process.exit(1);
+            }
+            // Backspace
+            if (code === 127 || code === 8) {
+                if (input.length > 0) {
+                    input = input.slice(0, -1);
+                    stdout.write('\b \b');
+                }
+                return;
+            }
+            // Regular character
+            if (code >= 32 && code <= 126) {
+                input += char;
+                stdout.write('*');
+            }
+        };
+        stdin.on('data', onData);
+    });
+}
+async function showConfig() {
+    console.log();
+    console.log(chalk.cyan('  Configuration'));
+    console.log(chalk.gray('  ─────────────────────────────────────────'));
+    console.log();
+    console.log(chalk.gray('  Config location: ') + CONFIG_PATH);
+    console.log();
+    try {
+        const content = await readFile(CONFIG_PATH, 'utf-8');
+        const hasKey = content.includes('ANTHROPIC_API_KEY=');
+        if (hasKey) {
+            // Extract and mask the key (show first 7 and last 4 chars only)
+            const match = content.match(/ANTHROPIC_API_KEY=(.+)/);
+            if (match && match[1]) {
+                const key = match[1].trim();
+                const masked = key.length > 11
+                    ? key.substring(0, 7) + '...' + key.substring(key.length - 4)
+                    : '***configured***';
+                console.log(chalk.gray('  API Key: ') + chalk.green(masked));
+            }
+        }
+        else {
+            console.log(chalk.yellow('  No API key configured'));
+        }
+    }
+    catch {
+        console.log(chalk.yellow('  No config file found'));
+    }
+    console.log();
+}
+async function setApiKey() {
+    console.log();
+    const apiKey = await promptInput(chalk.magenta('  Enter new API key: '), true);
+    if (!apiKey) {
+        console.log(chalk.red('  No key provided. Cancelled.'));
+        return;
+    }
+    if (!apiKey.startsWith('sk-ant-')) {
+        console.log(chalk.yellow('  Warning: Key doesn\'t look like an Anthropic key (expected sk-ant-...)'));
+        const proceed = await promptInput(chalk.gray('  Save anyway? [y/N] '));
+        if (proceed.toLowerCase() !== 'y') {
+            console.log(chalk.gray('  Cancelled.'));
+            return;
+        }
+    }
+    try {
+        await mkdir(CONFIG_DIR, { recursive: true, mode: 0o700 });
+        await writeFile(CONFIG_PATH, `ANTHROPIC_API_KEY=${apiKey}\n`, { mode: 0o600 });
+        console.log();
+        console.log(chalk.green('  API key updated successfully'));
+    }
+    catch (error) {
+        console.log(chalk.red('  Failed to save API key'));
+    }
+    console.log();
+}
+async function deleteConfig() {
+    console.log();
+    const confirm = await promptInput(chalk.yellow('  Delete API key? This cannot be undone. [y/N] '));
+    if (confirm.toLowerCase() !== 'y') {
+        console.log(chalk.gray('  Cancelled.'));
+        return;
+    }
+    try {
+        await unlink(CONFIG_PATH);
+        console.log(chalk.green('  API key deleted'));
+    }
+    catch {
+        console.log(chalk.yellow('  No config file to delete'));
+    }
+    console.log();
+}
+async function showPath() {
+    console.log();
+    console.log(chalk.gray('  Config file: ') + CONFIG_PATH);
+    console.log();
+    console.log(chalk.gray('  To edit manually:'));
+    console.log(chalk.cyan(`    nano ${CONFIG_PATH}`));
+    console.log();
+}
+export async function configCommand(options) {
+    if (options.set) {
+        await setApiKey();
+    }
+    else if (options.delete) {
+        await deleteConfig();
+    }
+    else if (options.path) {
+        await showPath();
+    }
+    else {
+        await showConfig();
+    }
+}

package/dist/commands/start.d.ts

@@ -0,0 +1,5 @@
+interface StartOptions {
+    directory: string;
+}
+export declare function startCommand(options: StartOptions): Promise<void>;
+export {};

package/dist/commands/start.js

@@ -0,0 +1,151 @@
+import dotenv from 'dotenv';
+import { homedir } from 'os';
+import { join } from 'path';
+import { mkdir, writeFile } from 'fs/promises';
+import * as readline from 'readline';
+import chalk from 'chalk';
+import { ThreeJsWizard } from '../core/ThreeJsWizard.js';
+function loadEnvFiles(workingDir) {
+    // Load from multiple locations (later ones don't override earlier)
+    // 1. Current working directory
+    dotenv.config({ path: join(workingDir, '.env') });
+    // 2. User's home config directory
+    dotenv.config({ path: join(homedir(), '.threewzrd', '.env') });
+}
+async function promptForApiKey() {
+    console.log();
+    console.log(chalk.yellow('  No API key found!'));
+    console.log();
+    console.log(chalk.gray('  To use Three.js Wizard, you need an Anthropic API key.'));
+    console.log(chalk.gray('  Get one at: ') + chalk.cyan('https://console.anthropic.com/'));
+    console.log();
+    // Use masked input for security
+    return new Promise((resolve) => {
+        const stdin = process.stdin;
+        const stdout = process.stdout;
+        stdout.write(chalk.magenta('  Enter your API key: '));
+        // Save original terminal state
+        const wasRaw = stdin.isRaw;
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding('utf8');
+        let input = '';
+        const onData = (char) => {
+            const code = char.charCodeAt(0);
+            // Enter key
+            if (code === 13 || code === 10) {
+                stdin.setRawMode(wasRaw ?? false);
+                stdin.removeListener('data', onData);
+                stdin.pause();
+                stdout.write('\n');
+                resolve(input.trim());
+                return;
+            }
+            // Ctrl+C
+            if (code === 3) {
+                stdin.setRawMode(wasRaw ?? false);
+                stdin.removeListener('data', onData);
+                stdout.write('\n');
+                process.exit(1);
+            }
+            // Backspace
+            if (code === 127 || code === 8) {
+                if (input.length > 0) {
+                    input = input.slice(0, -1);
+                    stdout.write('\b \b');
+                }
+                return;
+            }
+            // Regular character - show asterisk
+            if (code >= 32 && code <= 126) {
+                input += char;
+                stdout.write('*');
+            }
+        };
+        stdin.on('data', onData);
+    });
+}
+async function saveApiKey(apiKey) {
+    const configDir = join(homedir(), '.threewzrd');
+    const configPath = join(configDir, '.env');
+    try {
+        // Create directory with restricted permissions (owner only)
+        await mkdir(configDir, { recursive: true, mode: 0o700 });
+        // Write file with restricted permissions (owner read/write only)
+        await writeFile(configPath, `ANTHROPIC_API_KEY=${apiKey}\n`, { mode: 0o600 });
+        console.log();
+        console.log(chalk.green('  API key saved securely to ') + chalk.gray(configPath));
+        console.log(chalk.gray('  (permissions: owner read/write only)'));
+        console.log();
+    }
+    catch (error) {
+        console.log(chalk.yellow('  Could not save API key to config file.'));
+        console.log(chalk.gray('  You can manually create: ') + configPath);
+    }
+}
+export async function startCommand(options) {
+    const workingDir = options.directory;
+    // Always try to change to the working directory
+    try {
+        process.chdir(workingDir);
+    }
+    catch (error) {
+        console.error(chalk.red(`Error: Could not access directory "${workingDir}"`));
+        console.error(chalk.gray('Make sure the directory exists and you have permission to access it.'));
+        process.exit(1);
+    }
+    // Load .env files from working directory and home config
+    loadEnvFiles(workingDir);
+    // Check for API key, prompt if missing
+    if (!process.env.ANTHROPIC_API_KEY) {
+        const apiKey = await promptForApiKey();
+        if (!apiKey) {
+            console.log();
+            console.log(chalk.red('  No API key provided. Exiting.'));
+            process.exit(1);
+        }
+        // Validate key format (basic check)
+        if (!apiKey.startsWith('sk-ant-')) {
+            console.log();
+            console.log(chalk.yellow('  Warning: API key doesn\'t look like an Anthropic key.'));
+            console.log(chalk.gray('  Expected format: sk-ant-...'));
+        }
+        // Set the key for this session
+        process.env.ANTHROPIC_API_KEY = apiKey;
+        // Offer to save it
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        const shouldSave = await new Promise((resolve) => {
+            rl.question(chalk.gray('  Save this key for future sessions? ') + chalk.gray('[Y/n] '), (answer) => {
+                rl.close();
+                const normalized = answer.trim().toLowerCase();
+                resolve(normalized !== 'n' && normalized !== 'no');
+            });
+        });
+        if (shouldSave) {
+            await saveApiKey(apiKey);
+        }
+    }
+    // Create and start the wizard
+    const wizard = new ThreeJsWizard();
+    // Handle graceful shutdown
+    process.on('SIGINT', () => {
+        console.log('\nShutting down...');
+        wizard.stop();
+        process.exit(0);
+    });
+    process.on('SIGTERM', () => {
+        wizard.stop();
+        process.exit(0);
+    });
+    // Start the REPL
+    try {
+        await wizard.start();
+    }
+    catch (error) {
+        console.error('Fatal error:', error);
+        process.exit(1);
+    }
+}

package/dist/core/AgentEngine.d.ts

@@ -0,0 +1,19 @@
+import { ModelId } from './types.js';
+import { TerminalUI } from '../ui/TerminalUI.js';
+export declare class AgentEngine {
+    private client;
+    private model;
+    private conversationHistory;
+    private toolExecutor;
+    private ui;
+    constructor(ui: TerminalUI, workingDirectory: string);
+    private trimHistory;
+    private sleep;
+    setModel(model: ModelId): void;
+    getModel(): ModelId;
+    clearHistory(): void;
+    getCreatedFiles(): string[];
+    processMessage(userMessage: string): Promise<void>;
+    private runAgentLoop;
+    private runSingleTurn;
+}

package/dist/core/AgentEngine.js

@@ -0,0 +1,157 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { MODEL_MAP } from './types.js';
+import { toolDefinitions } from '../tools/definitions.js';
+import { ToolExecutor } from '../tools/ToolExecutor.js';
+import { THREEJS_SYSTEM_PROMPT } from '../prompts/system.js';
+// Limits to prevent hitting rate limits
+const MAX_HISTORY_MESSAGES = 20; // Keep last N messages
+const MAX_TOKENS = 4096; // Reduced from 8192
+const MAX_RETRIES = 3;
+const RETRY_DELAY_MS = 5000; // 5 seconds base delay
+export class AgentEngine {
+    client;
+    model = 'sonnet';
+    conversationHistory = [];
+    toolExecutor;
+    ui;
+    constructor(ui, workingDirectory) {
+        this.client = new Anthropic();
+        this.ui = ui;
+        this.toolExecutor = new ToolExecutor(workingDirectory, ui);
+    }
+    // Trim conversation history to prevent token overflow
+    trimHistory() {
+        if (this.conversationHistory.length > MAX_HISTORY_MESSAGES) {
+            // Keep the first message (initial context) and the last N-1 messages
+            const first = this.conversationHistory[0];
+            const recent = this.conversationHistory.slice(-(MAX_HISTORY_MESSAGES - 1));
+            this.conversationHistory = [first, ...recent];
+        }
+    }
+    // Sleep helper for retry delays
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    setModel(model) {
+        this.model = model;
+    }
+    getModel() {
+        return this.model;
+    }
+    clearHistory() {
+        this.conversationHistory = [];
+        this.toolExecutor.clearCreatedFiles();
+    }
+    getCreatedFiles() {
+        return this.toolExecutor.getCreatedFiles();
+    }
+    async processMessage(userMessage) {
+        // Add user message to history
+        this.conversationHistory.push({
+            role: 'user',
+            content: userMessage,
+        });
+        // Trim history to prevent token overflow
+        this.trimHistory();
+        // Run the agentic loop
+        await this.runAgentLoop();
+    }
+    async runAgentLoop() {
+        let continueLoop = true;
+        while (continueLoop) {
+            continueLoop = await this.runSingleTurn();
+        }
+    }
+    async runSingleTurn(retryCount = 0) {
+        try {
+            // Show thinking indicator
+            this.ui.startThinking('Thinking');
+            // Create the API request with streaming
+            const stream = this.client.messages.stream({
+                model: MODEL_MAP[this.model],
+                max_tokens: MAX_TOKENS,
+                system: THREEJS_SYSTEM_PROMPT,
+                tools: toolDefinitions,
+                messages: this.conversationHistory,
+            });
+            // Collect response content
+            const contentBlocks = [];
+            let isFirstText = true;
+            // Handle streaming events
+            stream.on('text', (text) => {
+                if (isFirstText) {
+                    this.ui.stopThinking();
+                    this.ui.startStreaming();
+                    isFirstText = false;
+                }
+                this.ui.streamText(text);
+            });
+            // Wait for the complete response
+            const response = await stream.finalMessage();
+            // Make sure to stop thinking if no text was streamed
+            this.ui.stopThinking();
+            if (!isFirstText) {
+                this.ui.endStreaming();
+            }
+            // Process all content blocks
+            for (const block of response.content) {
+                contentBlocks.push(block);
+            }
+            // Add assistant response to history
+            this.conversationHistory.push({
+                role: 'assistant',
+                content: contentBlocks,
+            });
+            // Check if we need to process tool calls
+            const toolUseBlocks = contentBlocks.filter((block) => block.type === 'tool_use');
+            if (toolUseBlocks.length === 0) {
+                // No tool calls, we're done
+                return false;
+            }
+            // Execute all tool calls
+            const toolResults = [];
+            for (const toolUse of toolUseBlocks) {
+                const result = await this.toolExecutor.execute(toolUse.name, toolUse.input);
+                // Truncate large outputs to save tokens
+                let output = result.success ? result.output : `Error: ${result.error}`;
+                if (output.length > 2000) {
+                    output = output.substring(0, 2000) + '\n... (truncated)';
+                }
+                toolResults.push({
+                    type: 'tool_result',
+                    tool_use_id: toolUse.id,
+                    content: output,
+                    is_error: !result.success,
+                });
+            }
+            // Add tool results to history
+            this.conversationHistory.push({
+                role: 'user',
+                content: toolResults,
+            });
+            // Continue the loop if we have tool results to process
+            return response.stop_reason === 'tool_use';
+        }
+        catch (error) {
+            this.ui.stopThinking();
+            // Handle rate limit errors with retry
+            if (error instanceof Anthropic.RateLimitError) {
+                if (retryCount < MAX_RETRIES) {
+                    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);
+                }
+                this.ui.printError('Rate limit exceeded. Please wait a moment and try again.');
+                return false;
+            }
+            if (error instanceof Anthropic.APIError) {
+                this.ui.printError(`API Error: ${error.message}`);
+            }
+            else {
+                this.ui.printError(`Error: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            return false;
+        }
+    }
+}