kyawthiha-nextjs-agent-cli 1.0.0

package/README.md

@@ -0,0 +1,188 @@
+# Next.js Fullstack Agent CLI
+
+Gemini 3 Hackathon Entry 2026
+
+**Gemini Next.js Agent CLI** is an autonomous, tool-driven developer agent that transforms natural language into verified, production-ready Next.js fullstack applications.
+
+The agent plans tasks, executes real commands, verifies results, attempts repairs, and asks for manual input only when automation is unsafe.
+
+---
+
+## Overview
+
+This CLI is designed to behave like a real developer inside a real project environment.
+
+Instead of only generating code, the agent:
+- Creates and modifies files directly
+- Runs installs and builds
+- Verifies results through execution
+- Attempts automated fixes when failures occur
+- Pauses for human input when decisions require clarity
+
+The focus is reliability, correctness, and real execution.
+
+---
+
+## Features
+
+- Runtime: Node.js
+- Language: TypeScript
+- CLI Framework: Commander, Inquirer
+- Agent: Gemini-powered agentic workflow
+- Planning before execution
+- Real filesystem operations
+- Build and runtime verification
+- Targeted self-repair for failures
+
+---
+
+## Requirements
+
+Before installing, ensure you have:
+
+- Node.js 18 or later
+- npm or pnpm
+- PostgreSQL (optional, only required if your project uses a database)
+- A Gemini API key
+
+---
+
+## Installation (Step by Step)
+
+1. Clone the repository
+```bash
+git clone https://github.com/kywthiha/nextjs-agent-cli.git
+```
+
+2. Move into the project directory
+```bash
+cd nextjs-agent-cli
+```
+
+3. Install dependencies
+```bash
+npm install
+```
+
+4. Configure environment variables
+```bash
+cp .env.example .env
+```
+
+Add your Gemini API key to the `.env` file:
+```
+GEMINI_API_KEY=your_api_key_here
+```
+
+---
+
+## Running the CLI
+
+Start the CLI in development mode:
+
+```bash
+npm run dev
+```
+
+The agent will launch an interactive session in your terminal.
+
+---
+
+## Interactive Workflow
+
+### 1. Project Creation
+
+Choose where the Next.js project should be created.
+```
+? Where should the project be created? (./my-app)
+```
+
+---
+
+### 2. Model Selection
+
+Select the Gemini model for the agent.
+- gemini-3-flash-preview
+- gemini-3-pro-preview
+
+---
+
+### 3. Database Configuration (Optional)
+
+If your project requires a database, configure PostgreSQL:
+```
+--- PostgreSQL Configuration ---
+? Host: localhost
+? Port: 5432
+? Username: postgres
+? Password: [HIDDEN]
+```
+
+The agent will:
+- Verify the connection
+- Create the database if it does not exist
+- Handle schema setup when required
+
+---
+
+### 4. Define Your Goal
+
+Describe what you want to build using natural language.
+```
+? What do you want to build or modify?
+> Build inventory management for a mobile shop with POS and user management
+```
+
+The agent will then:
+- Generate an implementation plan (plan.md)
+- Generate a task checklist (task.md)
+- Execute tasks step by step
+- Verify builds and runtime behavior
+- Attempt fixes if errors occur
+
+---
+
+## Testing and Verification
+
+Verification is a core part of the agent’s workflow.
+
+During execution, the agent may:
+- Run dependency installs
+- Run builds
+- Detect runtime or build failures
+- Attempt automated fixes
+- Re-run verification steps
+
+If a failure requires a business or architectural decision, the agent will pause and request manual input instead of guessing.
+
+---
+
+## Manual Testing (Optional)
+
+After the agent finishes, you can manually verify the generated project:
+
+```bash
+cd my-app
+npm run dev
+```
+
+Open the browser at:
+```
+http://localhost:3000
+```
+
+---
+
+## Limitations
+
+- Some runtime issues require human decisions
+- Complex architecture changes may need guidance
+- The agent prioritizes safety and correctness over aggressive automation
+
+These constraints are intentional.
+
+---
+
+## License
+
+MIT License

package/dist/agent/agent.js

@@ -0,0 +1,340 @@
+/**
+ * Core AI Agent - Agentic loop pattern with Gemini 3 SDK
+ */
+import { GoogleGenAI, ThinkingLevel } from '@google/genai';
+import { logger } from '../utils/logger.js';
+import { AGENT_SYSTEM_PROMPT, createTaskPrompt } from './prompts/agent-prompt.js';
+import { getAllTools } from './tools/index.js';
+import { ConversationSummarizer } from './summarizer.js';
+const MAX_API_RETRIES = 5;
+const INITIAL_RETRY_DELAY_MS = 2000;
+// Token management constants
+const MAX_CONTEXT_TOKENS = 1000000; // 1M input context (Gemini 3 Pro/Flash), 64k output
+const COMPRESSION_THRESHOLD = 0.7; // Compress at 70% capacity
+const KEEP_RECENT_MESSAGES = 10; // Always keep last N messages
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+export class Agent {
+    client;
+    config;
+    tools;
+    conversation = [];
+    activeProjectPath = null;
+    isInitialized = false;
+    originalTaskPrompt = '';
+    summarizer;
+    lastTokenCount = 0; // Actual token count from last API response
+    constructor(config) {
+        this.config = config;
+        this.client = new GoogleGenAI({ apiKey: config.geminiApiKey });
+        this.tools = getAllTools();
+        this.summarizer = new ConversationSummarizer(config.geminiApiKey, config.modelName);
+    }
+    getThinkingLevel(modelName) {
+        return modelName.includes('pro') ? ThinkingLevel.HIGH : ThinkingLevel.MEDIUM;
+    }
+    async init() {
+        if (this.isInitialized)
+            return;
+        this.isInitialized = true;
+    }
+    async start(task) {
+        if (!this.isInitialized)
+            await this.init();
+        const { prompt, projectPath, databaseUrl } = task;
+        this.activeProjectPath = projectPath;
+        logger.step('Starting Full Stack Agent');
+        logger.info(`Goal: ${prompt}`);
+        logger.info(`Output: ${projectPath}`);
+        if (databaseUrl)
+            logger.info(`DB URL provided`);
+        const setupPrompt = createTaskPrompt(prompt, projectPath, databaseUrl);
+        this.originalTaskPrompt = setupPrompt;
+        // Check for previous summary to continue from
+        const previousSummary = await this.summarizer.loadSummary(projectPath);
+        if (previousSummary) {
+            logger.info('Found previous progress summary, continuing...');
+            this.conversation = [{
+                    role: 'user',
+                    parts: [{ text: `${setupPrompt}\n\n## Previous Progress:\n${previousSummary}\n\nContinue from where you left off.` }]
+                }];
+        }
+        else {
+            this.conversation = [{
+                    role: 'user',
+                    parts: [{ text: setupPrompt }]
+                }];
+        }
+        await this.executeTaskLoop('Planning-Phase');
+        logger.step('Agent session ended - Implementation Complete');
+    }
+    async chat(message) {
+        if (!this.isInitialized)
+            await this.init();
+        if (!this.activeProjectPath) {
+            throw new Error('Agent has not been started. Call start() first.');
+        }
+        logger.step('Continuing Agent Session');
+        logger.info(`Request: ${message}`);
+        this.conversation.push({
+            role: 'user',
+            parts: [{ text: message }]
+        });
+        await this.executeTaskLoop('Follow-up-Phase');
+        logger.step('Request Completed');
+    }
+    async executeTaskLoop(contextId) {
+        let iteration = 0;
+        let isComplete = false;
+        const maxIterations = this.config.maxIterations;
+        while (!isComplete && iteration < maxIterations) {
+            iteration++;
+            logger.step(`[${contextId}] Iteration ${iteration}/${maxIterations}`);
+            // Check and compress conversation if needed
+            await this.checkAndCompressConversation();
+            try {
+                const response = await this.callAIWithRetry();
+                // Track actual token usage from SDK response
+                this.updateTokenCount(response);
+                const { text, toolCalls, functionResponseParts } = this.parseResponse(response);
+                if (text) {
+                    logger.dim('AI: ' + text.substring(0, 200) + (text.length > 200 ? '...' : ''));
+                    // Check for completion signal
+                    if (text.includes('TASK COMPLETE')) {
+                        logger.success(`[${contextId}] Task Complete!`);
+                        isComplete = true;
+                        continue;
+                    }
+                }
+                if (toolCalls.length === 0) {
+                    if (!text) {
+                        logger.warn('No response from AI, retrying...');
+                        continue;
+                    }
+                    // AI just responded with text, ask it to continue
+                    this.conversation.push({
+                        role: 'user',
+                        parts: [{ text: 'Continue with the task. Use tools as needed.' }]
+                    });
+                    continue;
+                }
+                const toolResults = await this.executeTools(toolCalls);
+                this.conversation.push({
+                    role: 'model',
+                    parts: functionResponseParts.length > 0 ? functionResponseParts : [{ text: text || '' }]
+                });
+                this.conversation.push({
+                    role: 'user',
+                    parts: toolResults.map(r => ({
+                        functionResponse: {
+                            name: r.name,
+                            response: { result: r.result }
+                        }
+                    }))
+                });
+            }
+            catch (error) {
+                logger.error(`[${contextId}] Iteration ${iteration} error: ${error.message}`);
+                // Check if token limit exceeded
+                if (this.isTokenLimitError(error)) {
+                    logger.warn('Token limit exceeded, generating summary and restarting...');
+                    await this.handleTokenLimitExceeded();
+                    continue;
+                }
+                this.conversation.push({
+                    role: 'user',
+                    parts: [{ text: `Error: ${error.message}. Try a different approach.` }]
+                });
+            }
+        }
+        if (!isComplete) {
+            logger.warn(`[${contextId}] Reached max iterations (${maxIterations}) without completion signal`);
+        }
+    }
+    async callAIWithRetry() {
+        let lastError = null;
+        for (let attempt = 1; attempt <= MAX_API_RETRIES; attempt++) {
+            try {
+                return await this.callAI();
+            }
+            catch (error) {
+                lastError = error;
+                const errorMessage = error.message || '';
+                const errorString = JSON.stringify(error);
+                // Check if it's a retryable error (503, 429, overloaded, etc.)
+                const isRetryable = errorMessage.includes('503') ||
+                    errorMessage.includes('429') ||
+                    errorMessage.includes('overloaded') ||
+                    errorMessage.includes('UNAVAILABLE') ||
+                    errorMessage.includes('rate limit') ||
+                    errorMessage.includes('quota') ||
+                    errorString.includes('503') ||
+                    errorString.includes('overloaded');
+                if (isRetryable && attempt < MAX_API_RETRIES) {
+                    // Exponential backoff: 2s, 4s, 8s, 16s, 32s
+                    const delayMs = INITIAL_RETRY_DELAY_MS * Math.pow(2, attempt - 1);
+                    logger.warn(`API error (${attempt}/${MAX_API_RETRIES}), retrying in ${delayMs / 1000}s...`);
+                    await sleep(delayMs);
+                }
+                else if (!isRetryable) {
+                    // Non-retryable error, throw immediately
+                    throw error;
+                }
+            }
+        }
+        // All retries exhausted
+        throw lastError || new Error('API call failed after max retries');
+    }
+    async callAI() {
+        const functionDeclarations = this.tools.map(t => ({
+            name: t.name,
+            description: t.description,
+            parametersJsonSchema: {
+                type: 'object',
+                properties: Object.fromEntries(Object.entries(t.parameters.properties || {}).map(([key, value]) => [
+                    key,
+                    {
+                        type: value.type,
+                        description: value.description,
+                        ...(value.enum && { enum: value.enum })
+                    }
+                ])),
+                required: t.parameters.required || []
+            }
+        }));
+        const tools = [{ functionDeclarations }];
+        const modelName = this.config.modelName || 'gemini-3-flash-preview';
+        const thinkingLevel = this.getThinkingLevel(modelName);
+        const response = await this.client.models.generateContent({
+            model: modelName,
+            contents: this.conversation,
+            config: {
+                systemInstruction: AGENT_SYSTEM_PROMPT,
+                tools,
+                thinkingConfig: {
+                    thinkingLevel,
+                },
+            }
+        });
+        return response;
+    }
+    parseResponse(response) {
+        const parts = response.candidates?.[0]?.content?.parts || [];
+        let text = '';
+        const toolCalls = [];
+        const functionResponseParts = [];
+        for (const part of parts) {
+            if (part.text) {
+                text += part.text;
+            }
+            if (part.functionCall) {
+                toolCalls.push({
+                    id: `call_${Date.now()}_${toolCalls.length}`,
+                    name: part.functionCall.name || '',
+                    arguments: part.functionCall.args || {}
+                });
+                functionResponseParts.push(part);
+            }
+        }
+        return { text, toolCalls, functionResponseParts };
+    }
+    async executeTools(toolCalls) {
+        const preparedCalls = toolCalls.map(call => {
+            const tool = this.tools.find(t => t.name === call.name);
+            // Enforce project path
+            if (this.activeProjectPath) {
+                if (call.arguments.cwd !== undefined) {
+                    call.arguments.cwd = this.activeProjectPath;
+                }
+                if (call.arguments.projectPath !== undefined) {
+                    call.arguments.projectPath = this.activeProjectPath;
+                }
+            }
+            return { call, tool };
+        });
+        const promises = preparedCalls.map(async ({ call, tool }) => {
+            if (!tool) {
+                logger.warn(`Tool not found: ${call.name}`);
+                return { name: call.name, result: `Error: Tool "${call.name}" not found` };
+            }
+            if (this.config.verbose) {
+                logger.dim(`Tool: ${call.name}(${JSON.stringify(call.arguments)})`);
+            }
+            else {
+                logger.info(`  → ${call.name}`);
+            }
+            try {
+                const result = await tool.execute(call.arguments);
+                if (this.config.verbose) {
+                    const preview = result.length > 100 ? result.substring(0, 100) + '...' : result;
+                    logger.dim(`  Result: ${preview}`);
+                }
+                return { name: call.name, result };
+            }
+            catch (error) {
+                logger.error(`Tool ${call.name} failed: ${error.message}`);
+                return { name: call.name, result: `Error: ${error.message}` };
+            }
+        });
+        return await Promise.all(promises);
+    }
+    // ==================== Token Management ====================
+    isTokenLimitError(error) {
+        const msg = error.message?.toLowerCase() || '';
+        return msg.includes('token') ||
+            msg.includes('context length') ||
+            msg.includes('too long') ||
+            msg.includes('maximum context');
+    }
+    updateTokenCount(response) {
+        const usage = response.usageMetadata;
+        if (usage?.promptTokenCount) {
+            this.lastTokenCount = usage.promptTokenCount;
+            if (this.config.verbose) {
+                logger.dim(`Input tokens: ${this.lastTokenCount.toLocaleString()} / ${MAX_CONTEXT_TOKENS.toLocaleString()}`);
+            }
+        }
+    }
+    async checkAndCompressConversation() {
+        const threshold = MAX_CONTEXT_TOKENS * COMPRESSION_THRESHOLD;
+        if (this.lastTokenCount > threshold) {
+            logger.info(`Token usage ${this.lastTokenCount.toLocaleString()}/${MAX_CONTEXT_TOKENS.toLocaleString()} (${Math.round(this.lastTokenCount / MAX_CONTEXT_TOKENS * 100)}%), compressing...`);
+            this.compressConversation();
+        }
+    }
+    compressConversation() {
+        if (this.conversation.length <= KEEP_RECENT_MESSAGES + 1) {
+            return; // Nothing to compress
+        }
+        // Keep first message (original task) and last N messages
+        const firstMessage = this.conversation[0];
+        const recentMessages = this.conversation.slice(-KEEP_RECENT_MESSAGES);
+        this.conversation = [firstMessage, ...recentMessages];
+        logger.dim(`Compressed conversation to ${this.conversation.length} messages`);
+    }
+    async handleTokenLimitExceeded() {
+        if (!this.activeProjectPath) {
+            this.compressConversation();
+            return;
+        }
+        try {
+            // Generate summary using Gemini
+            logger.dim('Generating progress summary with Gemini...');
+            const summary = await this.summarizer.generateSummary(this.conversation);
+            // Save to file
+            await this.summarizer.saveSummary(this.activeProjectPath, summary);
+            // Restart with fresh conversation including summary
+            this.conversation = [{
+                    role: 'user',
+                    parts: [{ text: `${this.originalTaskPrompt}\n\n## Previous Progress:\n${summary}\n\nContinue from where you left off.` }]
+                }];
+            logger.success('Conversation reset with AI-generated progress summary');
+        }
+        catch (error) {
+            logger.error(`Failed to handle token limit: ${error.message}`);
+            // Fallback: just compress aggressively
+            this.compressConversation();
+        }
+    }
+}

package/dist/agent/index.js

@@ -0,0 +1,6 @@
+/**
+ * Agent module exports
+ */
+export { Agent } from './agent.js';
+export { AGENT_SYSTEM_PROMPT, createTaskPrompt } from './prompts/agent-prompt.js';
+export { getAllTools } from './tools/index.js';