popeye-cli 1.9.4 → 1.10.0

package/cheatsheet.md

@@ -231,6 +231,32 @@ popeye-cli audit ./my-project --target frontend
 
 ---
 
+### `popeye-cli debug [projectDir]`
+
+Start an interactive debugging session for a Popeye-generated project. Indexes the project, loads anchor docs (CLAUDE.md, README, config files), then opens a debug sub-REPL where you paste errors for AI-assisted diagnosis and fixes.
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-l, --language <lang>` | Project language/type | `backend` |
+
+```bash
+popeye-cli debug ./my-project
+popeye-cli debug ./my-project --language fullstack
+```
+
+**How it works:**
+1. Scans the project directory and builds a lightweight file index (paths + metadata)
+2. Loads anchor documents: CLAUDE.md, README, package.json, docker-compose.yml, etc.
+3. Opens a `debug >` sub-REPL -- paste an error or describe a bug
+4. Extracts file paths from stack traces and detects tech context (alembic, vite, fastapi, etc.)
+5. Loads only the relevant source files on-demand (not the entire codebase)
+6. Sends targeted context to Claude for structured diagnosis
+7. Claude responds with: Diagnosis, Evidence, Proposed Fix, Commands to Verify, Ready to Apply
+
+**Permission model:** Same as Claude Code -- asks before making any file edits (no auto-write).
+
+---
+
 ## Interactive Mode Slash Commands
 
 Enter these commands during an interactive session (started via `popeye-cli interactive`).
@@ -317,6 +343,41 @@ Available upgrade paths depend on the current project type:
 | `/doctor` | Run all readiness checks inline |
 | `/review`, `/audit` | Run a post-build audit with findings and optional recovery |
 
+### Debugging
+
+| Command | Description |
+|---------|-------------|
+| `/debug`, `/dbg` | Start interactive debugging session (requires active project) |
+
+Once inside the debug session, the following sub-commands are available:
+
+| Debug Sub-Command | Description |
+|-------------------|-------------|
+| `/back`, `/done` | Return to main Popeye session |
+| `/clear` | Reset conversation history |
+| `/context` | Re-display project summary |
+| `/fix` | Apply last proposed fix via Popeye execution pipeline |
+
+**Debug session input:** Single Enter submits for commands and short messages. Multi-line paste is auto-detected and waits for the full paste to arrive before submitting.
+
+```
+# Start a debug session from the Popeye REPL
+/debug
+
+# Inside debug session, paste an error:
+debug > Traceback (most recent call last):
+  ...   File "/app/src/database/connection.py", line 15
+  ...   ConnectionRefusedError: [Errno 111] Connection refused
+  ...
+  ... (paste auto-detected, submits after 2s pause)
+
+# Apply the proposed fix
+debug > /fix
+
+# Return to main Popeye REPL (use /back, not /exit which would exit Popeye)
+debug > /back
+```
+
 ### Session Control
 
 | Command | Description |
@@ -435,6 +496,10 @@ popeye-cli resume ./taskmaster
 popeye-cli review ./taskmaster
 popeye-cli review ./taskmaster --depth 3 --strict
 
+# Debug a project (paste errors, get AI-assisted fixes)
+popeye-cli debug ./taskmaster
+popeye-cli debug ./taskmaster --language fullstack
+
 # Reset and re-plan
 popeye-cli reset ./taskmaster --phase plan
 ```

package/dist/cli/commands/debug-context.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Debug context helpers
+ * Deterministic functions for error analysis and smart file selection.
+ * Pure functions, easily testable.
+ */
+/**
+ * Entry in the lightweight file index (paths + metadata, no content).
+ */
+export interface FileIndexEntry {
+    relativePath: string;
+    size: number;
+    mtime: number;
+    isConfig: boolean;
+}
+/**
+ * Check if a file path matches a config pattern.
+ *
+ * @param filePath - Relative path to check.
+ * @returns True if the file is a known config file.
+ */
+export declare function isConfigFile(filePath: string): boolean;
+/**
+ * Extract file paths mentioned in stack traces.
+ * Supports Python tracebacks, TypeScript/JS errors, and generic path patterns.
+ *
+ * @param text - Error text or stack trace.
+ * @returns Deduplicated array of file paths found in the text.
+ */
+export declare function extractPathsFromError(text: string): string[];
+/**
+ * Detect framework/tech keywords from error text.
+ *
+ * @param text - Error text or stack trace.
+ * @returns Object with deduplicated tags array.
+ */
+export declare function detectTechFromError(text: string): {
+    tags: string[];
+};
+/**
+ * Select relevant files from the project index based on error paths and tech tags.
+ * Returns file paths sorted by relevance (direct matches first, then config, then nearby).
+ *
+ * @param fileIndex - Lightweight file index.
+ * @param errorPaths - Paths extracted from the error.
+ * @param tags - Tech tags detected from the error.
+ * @returns Array of relative paths to load.
+ */
+export declare function selectRelevantFiles(fileIndex: FileIndexEntry[], errorPaths: string[], tags: string[]): string[];
+/**
+ * Extract image/screenshot file paths from user input text.
+ * Detects both quoted and unquoted absolute/relative paths ending in image extensions.
+ *
+ * @param text - User input text.
+ * @returns Array of image file paths found in the text.
+ */
+export declare function extractImagePaths(text: string): string[];
+/**
+ * Check if a file path points to an image file.
+ *
+ * @param filePath - File path to check.
+ * @returns True if the file has an image extension.
+ */
+export declare function isImageFile(filePath: string): boolean;
+//# sourceMappingURL=debug-context.d.ts.map

package/dist/cli/commands/debug-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-context.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/debug-context.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;CACnB;AAYD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGtD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAsC5D;AA2BD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAapE;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,cAAc,EAAE,EAC3B,UAAU,EAAE,MAAM,EAAE,EACpB,IAAI,EAAE,MAAM,EAAE,GACb,MAAM,EAAE,CAkEV;AAKD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAgBxD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGrD"}

package/dist/cli/commands/debug-context.js

@@ -0,0 +1,221 @@
+/**
+ * Debug context helpers
+ * Deterministic functions for error analysis and smart file selection.
+ * Pure functions, easily testable.
+ */
+import path from 'node:path';
+/** Config file patterns that are always considered relevant */
+const CONFIG_PATTERNS = [
+    'package.json', 'package-lock.json', 'tsconfig.json', 'vite.config',
+    'pyproject.toml', 'requirements.txt', 'Pipfile',
+    'docker-compose.yml', 'docker-compose.yaml', 'Dockerfile',
+    '.env.example', '.env.local', 'alembic.ini',
+    'next.config', 'tailwind.config', 'postcss.config',
+    'jest.config', 'vitest.config', 'pytest.ini', 'setup.cfg',
+];
+/**
+ * Check if a file path matches a config pattern.
+ *
+ * @param filePath - Relative path to check.
+ * @returns True if the file is a known config file.
+ */
+export function isConfigFile(filePath) {
+    const basename = path.basename(filePath);
+    return CONFIG_PATTERNS.some((p) => basename.startsWith(p));
+}
+/**
+ * Extract file paths mentioned in stack traces.
+ * Supports Python tracebacks, TypeScript/JS errors, and generic path patterns.
+ *
+ * @param text - Error text or stack trace.
+ * @returns Deduplicated array of file paths found in the text.
+ */
+export function extractPathsFromError(text) {
+    const paths = new Set();
+    // Python traceback: File "/app/src/module/file.py", line 42
+    const pyPattern = /File "([^"]+\.py[cw]?)", line \d+/g;
+    for (const match of text.matchAll(pyPattern)) {
+        paths.add(normalizePath(match[1]));
+    }
+    // TS/JS errors: src/components/App.tsx(15,3) or src/components/App.tsx:15:3
+    const tsPattern = /([a-zA-Z0-9_./\\-]+\.(?:ts|tsx|js|jsx|mjs|cjs))[\s:(]/g;
+    for (const match of text.matchAll(tsPattern)) {
+        paths.add(normalizePath(match[1]));
+    }
+    // Docker / generic paths: /app/src/..., ./src/...
+    const genericPattern = /(?:\/app\/|\.\/)((?:src|app|lib|tests?|config)\/[a-zA-Z0-9_./-]+\.\w+)/g;
+    for (const match of text.matchAll(genericPattern)) {
+        paths.add(normalizePath(match[1]));
+    }
+    // Module not found patterns: Cannot find module './foo/bar'
+    const modulePattern = /Cannot find module ['"]([^'"]+)['"]/g;
+    for (const match of text.matchAll(modulePattern)) {
+        const mod = match[1];
+        if (mod.startsWith('.') || mod.startsWith('/')) {
+            paths.add(normalizePath(mod));
+        }
+    }
+    // ModuleNotFoundError: No module named 'src.foo.bar'
+    const pyModulePattern = /No module named ['"]([^'"]+)['"]/g;
+    for (const match of text.matchAll(pyModulePattern)) {
+        const dotPath = match[1].replace(/\./g, '/');
+        paths.add(dotPath);
+    }
+    return Array.from(paths);
+}
+/** Tech keyword map: keyword -> tags */
+const TECH_KEYWORDS = {
+    'alembic': ['alembic', 'database', 'migration'],
+    'sqlalchemy': ['sqlalchemy', 'database', 'orm'],
+    'prisma': ['prisma', 'database', 'orm'],
+    'docker': ['docker', 'container'],
+    'docker-compose': ['docker', 'container', 'compose'],
+    'vite': ['vite', 'bundler', 'frontend'],
+    'webpack': ['webpack', 'bundler', 'frontend'],
+    'next': ['nextjs', 'react', 'frontend'],
+    'fastapi': ['fastapi', 'backend', 'python'],
+    'flask': ['flask', 'backend', 'python'],
+    'express': ['express', 'backend', 'node'],
+    'postgres': ['postgres', 'database'],
+    'redis': ['redis', 'cache'],
+    'tailwind': ['tailwind', 'css', 'frontend'],
+    'pytest': ['pytest', 'testing', 'python'],
+    'jest': ['jest', 'testing', 'node'],
+    'vitest': ['vitest', 'testing', 'node'],
+    'nginx': ['nginx', 'proxy'],
+    'cors': ['cors', 'api'],
+    'migration': ['migration', 'database'],
+    'celery': ['celery', 'queue', 'python'],
+};
+/**
+ * Detect framework/tech keywords from error text.
+ *
+ * @param text - Error text or stack trace.
+ * @returns Object with deduplicated tags array.
+ */
+export function detectTechFromError(text) {
+    const tags = new Set();
+    const lower = text.toLowerCase();
+    for (const [keyword, keywordTags] of Object.entries(TECH_KEYWORDS)) {
+        if (lower.includes(keyword)) {
+            for (const tag of keywordTags) {
+                tags.add(tag);
+            }
+        }
+    }
+    return { tags: Array.from(tags) };
+}
+/**
+ * Select relevant files from the project index based on error paths and tech tags.
+ * Returns file paths sorted by relevance (direct matches first, then config, then nearby).
+ *
+ * @param fileIndex - Lightweight file index.
+ * @param errorPaths - Paths extracted from the error.
+ * @param tags - Tech tags detected from the error.
+ * @returns Array of relative paths to load.
+ */
+export function selectRelevantFiles(fileIndex, errorPaths, tags) {
+    if (fileIndex.length === 0)
+        return [];
+    const selected = new Set();
+    const MAX_FILES = 15;
+    // 1. Direct matches: files mentioned in the error
+    for (const errorPath of errorPaths) {
+        for (const entry of fileIndex) {
+            if (entry.relativePath.endsWith(errorPath) ||
+                entry.relativePath === errorPath ||
+                entry.relativePath.includes(errorPath)) {
+                selected.add(entry.relativePath);
+            }
+        }
+    }
+    // 2. Sibling files: files in the same directory as matches
+    const matchedDirs = new Set();
+    for (const sel of selected) {
+        matchedDirs.add(path.dirname(sel));
+    }
+    for (const dir of matchedDirs) {
+        for (const entry of fileIndex) {
+            if (path.dirname(entry.relativePath) === dir && selected.size < MAX_FILES) {
+                selected.add(entry.relativePath);
+            }
+        }
+    }
+    // 3. Tag-based: config files related to detected tech
+    if (tags.includes('database') || tags.includes('migration')) {
+        for (const entry of fileIndex) {
+            if (entry.relativePath.includes('alembic') ||
+                entry.relativePath.includes('migration') ||
+                entry.relativePath.includes('prisma') ||
+                entry.relativePath.includes('schema.sql')) {
+                if (selected.size < MAX_FILES)
+                    selected.add(entry.relativePath);
+            }
+        }
+    }
+    if (tags.includes('docker') || tags.includes('compose')) {
+        for (const entry of fileIndex) {
+            if (entry.relativePath.includes('docker') ||
+                entry.relativePath.includes('Dockerfile')) {
+                if (selected.size < MAX_FILES)
+                    selected.add(entry.relativePath);
+            }
+        }
+    }
+    // 4. Fallback: always include config files if we have few matches
+    if (selected.size < 5) {
+        for (const entry of fileIndex) {
+            if (entry.isConfig && selected.size < MAX_FILES) {
+                selected.add(entry.relativePath);
+            }
+        }
+    }
+    return Array.from(selected).slice(0, MAX_FILES);
+}
+/** Image file extensions that Claude can read via the Read tool */
+const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.svg']);
+/**
+ * Extract image/screenshot file paths from user input text.
+ * Detects both quoted and unquoted absolute/relative paths ending in image extensions.
+ *
+ * @param text - User input text.
+ * @returns Array of image file paths found in the text.
+ */
+export function extractImagePaths(text) {
+    const paths = new Set();
+    // Quoted paths: '/path/to/image.png' or "/path/to/image.png"
+    const quotedPattern = /['"]([^'"]+\.(?:png|jpg|jpeg|gif|webp|bmp|svg))['"]/gi;
+    for (const match of text.matchAll(quotedPattern)) {
+        paths.add(match[1]);
+    }
+    // Unquoted absolute paths: /path/to/image.png (no spaces allowed in unquoted)
+    const absolutePattern = /(\/[^\s'"]+\.(?:png|jpg|jpeg|gif|webp|bmp|svg))/gi;
+    for (const match of text.matchAll(absolutePattern)) {
+        paths.add(match[1]);
+    }
+    return Array.from(paths);
+}
+/**
+ * Check if a file path points to an image file.
+ *
+ * @param filePath - File path to check.
+ * @returns True if the file has an image extension.
+ */
+export function isImageFile(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return IMAGE_EXTENSIONS.has(ext);
+}
+/**
+ * Normalize a file path by stripping common prefixes (/app/, ./, etc.).
+ *
+ * @param p - Raw file path from error text.
+ * @returns Normalized relative path.
+ */
+function normalizePath(p) {
+    let normalized = p.replace(/\\/g, '/');
+    // Strip common container prefixes
+    normalized = normalized.replace(/^\/app\//, '');
+    normalized = normalized.replace(/^\.\//, '');
+    return normalized;
+}
+//# sourceMappingURL=debug-context.js.map

package/dist/cli/commands/debug-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-context.js","sourceRoot":"","sources":["../../../src/cli/commands/debug-context.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/debug-prompts.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Debug session prompts
+ * System prompt with strict output contract and conversation history formatting.
+ */
+/**
+ * Message in the debug conversation history.
+ */
+export interface DebugMessage {
+    role: 'user' | 'assistant';
+    content: string;
+}
+/**
+ * Build the system prompt for the debug session.
+ *
+ * @returns The system prompt instructing Claude on debug response format.
+ */
+export declare function getDebugSystemPrompt(): string;
+/**
+ * Format conversation history for inclusion in the prompt.
+ *
+ * @param history - Array of debug messages.
+ * @returns Formatted string of conversation history.
+ */
+export declare function formatConversationHistory(history: DebugMessage[]): string;
+//# sourceMappingURL=debug-prompts.d.ts.map

package/dist/cli/commands/debug-prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-prompts.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/debug-prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAqD7C;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CAWzE"}

package/dist/cli/commands/debug-prompts.js

@@ -0,0 +1,80 @@
+/**
+ * Debug session prompts
+ * System prompt with strict output contract and conversation history formatting.
+ */
+/**
+ * Build the system prompt for the debug session.
+ *
+ * @returns The system prompt instructing Claude on debug response format.
+ */
+export function getDebugSystemPrompt() {
+    return `You are an expert debugger embedded in the Popeye CLI. Your role is to diagnose
+errors in projects generated by Popeye (full-stack apps, backends, frontends, websites).
+
+You have access to the project's file system through your tools. When the user pastes an error,
+diagnose it using the project context provided and the files you can read.
+
+## Response Format
+
+You MUST structure every response with these sections:
+
+### Diagnosis
+Explain what is wrong and why it is happening. Be specific -- reference exact module names,
+configuration keys, or missing dependencies.
+
+### Evidence
+List the specific files and lines that confirm your diagnosis. Use the format:
+- \`path/to/file.ts:42\` -- description of what you found
+
+### Proposed Fix
+Provide the exact changes needed. Show file paths and the code to add, modify, or remove.
+Use diff-style formatting when helpful:
+\`\`\`diff
+- old line
++ new line
+\`\`\`
+
+### Commands to Verify
+List shell commands the user should run to confirm the fix works. For example:
+\`\`\`bash
+docker-compose up --build
+npm run dev
+pytest tests/ -v
+\`\`\`
+
+### Ready to Apply?
+End with a short note reminding the user they can type \`/fix\` in the debug session
+to have Popeye apply the proposed changes automatically.
+
+## Screenshots and Images
+- Users may paste file paths to screenshots or images (e.g., \`/path/to/Screenshot.png\`).
+- When you see an image path in the user's message, use the **Read** tool to view it.
+  The Read tool supports PNG, JPG, GIF, WebP, and other image formats.
+- After viewing the screenshot, analyze what it shows (UI bugs, missing elements, error dialogs,
+  browser console errors, terminal output, etc.) and include your visual findings in the Diagnosis.
+- If the image path is invalid or unreadable, tell the user and ask them to verify the path.
+
+## Rules
+- Never guess. If you need more context, ask the user or read additional files.
+- Reference actual file paths from the project, not hypothetical ones.
+- When multiple issues exist, address the root cause first.
+- Keep explanations concise -- developers are your audience.
+- If the error is outside the project (e.g., a system-level issue), say so clearly.`;
+}
+/**
+ * Format conversation history for inclusion in the prompt.
+ *
+ * @param history - Array of debug messages.
+ * @returns Formatted string of conversation history.
+ */
+export function formatConversationHistory(history) {
+    if (history.length === 0)
+        return '';
+    const lines = ['## Previous Conversation'];
+    for (const msg of history) {
+        const role = msg.role === 'user' ? 'User' : 'Assistant';
+        lines.push(`\n**${role}:**\n${msg.content}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=debug-prompts.js.map

package/dist/cli/commands/debug-prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-prompts.js","sourceRoot":"","sources":["../../../src/cli/commands/debug-prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH;;;;GAIG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oFAmD2E,CAAC;AACrF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAuB;IAC/D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEpC,MAAM,KAAK,GAAa,CAAC,0BAA0B,CAAC,CAAC;IAErD,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC;QACxD,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,QAAQ,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/cli/commands/debug.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Debug command
+ * Interactive debugging session that primes Claude with project context
+ * and lets users paste errors for AI-assisted diagnosis and fixes.
+ */
+import { Command } from 'commander';
+import type { FileIndexEntry } from './debug-context.js';
+import type { DebugMessage } from './debug-prompts.js';
+/**
+ * Context gathered about the project for debug sessions.
+ */
+export interface DebugContext {
+    projectDir: string;
+    structureSummary: string;
+    purpose: string;
+    claudeMd?: string;
+    readme?: string;
+    anchorFiles: Record<string, string>;
+    fileIndex: FileIndexEntry[];
+    language: string;
+}
+/**
+ * Options for starting a debug session.
+ */
+export interface DebugSessionOptions {
+    projectDir: string;
+    language: string;
+}
+/**
+ * Gather debug context for the project. Builds a lightweight index and
+ * reads anchor documents (CLAUDE.md, README, config files).
+ *
+ * @param projectDir - Project root directory.
+ * @param language - Project language/type.
+ * @returns DebugContext with project metadata and file index.
+ */
+export declare function gatherDebugContext(projectDir: string, language: string): Promise<DebugContext>;
+/**
+ * Display project summary to the user at the start of a debug session.
+ *
+ * @param context - The gathered debug context.
+ */
+export declare function displayProjectSummary(context: DebugContext): void;
+/**
+ * Build the full debug prompt for Claude, combining project context,
+ * relevant file contents, conversation history, and the current message.
+ *
+ * @param context - Debug context with project metadata.
+ * @param history - Conversation history.
+ * @param userMessage - Current user message/error.
+ * @param relevantFileContents - Map of file path -> content for relevant files.
+ * @param imagePaths - Optional array of image/screenshot paths to read.
+ * @returns Assembled prompt string.
+ */
+export declare function buildDebugPrompt(context: DebugContext, history: DebugMessage[], userMessage: string, relevantFileContents: Record<string, string>, imagePaths?: string[]): string;
+/**
+ * Run the interactive debug session sub-REPL.
+ *
+ * @param options - Debug session options (projectDir, language).
+ */
+export declare function runDebugSession(options: DebugSessionOptions): Promise<void>;
+/**
+ * Create the Commander.js debug command for CLI usage.
+ *
+ * @returns Commander Command instance.
+ */
+export declare function createDebugCommand(): Command;
+//# sourceMappingURL=debug.d.ts.map

package/dist/cli/commands/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/debug.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAoBpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAYzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAiBvD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAmED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,YAAY,CAAC,CA2DvB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAiCjE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,YAAY,EAAE,EACvB,WAAW,EAAE,MAAM,EACnB,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5C,UAAU,GAAE,MAAM,EAAO,GACxB,MAAM,CAmDR;AAuHD;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoIjF;AAqDD;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAyB5C"}