@involvex/prompt-enhancer 0.0.3 → 0.0.4

package/dist/cli.js

@@ -4,50 +4,110 @@ import { render } from 'ink';
 import meow from 'meow';
 import App from './app.js';
 import Help from './commands/help.js';
-import hasFlag from 'has-flag';
 import About from './commands/about.js';
 import DirectEnhance from './commands/direct-enhance.js';
+import DisplayVersion from './commands/version.js';
+import { configureRuntimeLogging, normalizeVerboseLevel, writeRuntimeBanner, } from './lib/utils/runtime-logging.js';
 // Handle Ctrl+C globally to exit from any screen
 process.on('SIGINT', () => {
     process.exit(0);
 });
 const cli = meow(`
-	Usage
-	  $ prompt-enhancer
-
-	Options
-		--prompt,-p  Your prompt to enhance
-
-	Examples
-	  $ prompt-enhancer
-	  $ prompt-enhancer --prompt="Your prompt here"
-	  $ prompt-enhancer -p "Your prompt here"
+Run "prompt-enhancer --help" for comprehensive usage.
 `, {
     importMeta: import.meta,
+    autoHelp: false,
+    autoVersion: false,
     flags: {
         prompt: {
             type: 'string',
             shortFlag: 'p',
         },
+        help: {
+            type: 'boolean',
+            default: false,
+            shortFlag: 'h',
+        },
+        version: {
+            type: 'boolean',
+            default: false,
+            shortFlag: 'v',
+        },
+        about: {
+            type: 'boolean',
+            default: false,
+        },
+        debug: {
+            type: 'boolean',
+            default: false,
+        },
+        trace: {
+            type: 'boolean',
+            default: false,
+        },
+        verbose: {
+            type: 'number',
+            default: 1,
+        },
+        output: {
+            type: 'string',
+            shortFlag: 'o',
+        },
+        outputFormat: {
+            type: 'string',
+            default: 'auto',
+        },
     },
 });
-if (cli.input[0] === 'help' || hasFlag('--help')) {
+if (!Number.isInteger(cli.flags.verbose) ||
+    cli.flags.verbose < 1 ||
+    cli.flags.verbose > 3) {
+    console.error(`Invalid --verbose value "${cli.flags.verbose}". Use integer values: 1, 2, or 3.`);
+    process.exit(1);
+}
+if (!['auto', 'txt', 'json', 'md'].includes(cli.flags.outputFormat.toLowerCase())) {
+    console.error(`Invalid --output-format "${cli.flags.outputFormat}". Supported formats: auto, txt, json, md.`);
+    process.exit(1);
+}
+const subcommand = cli.input[0]?.toLowerCase();
+const normalizedVerbose = normalizeVerboseLevel(cli.flags.verbose);
+const effectiveVerbose = cli.flags.trace
+    ? 3
+    : cli.flags.debug
+        ? Math.max(2, normalizedVerbose)
+        : normalizedVerbose;
+configureRuntimeLogging({
+    debug: cli.flags.debug,
+    trace: cli.flags.trace,
+    verbose: effectiveVerbose,
+});
+if (cli.flags.debug || cli.flags.trace || effectiveVerbose > 1) {
+    writeRuntimeBanner('prompt-enhancer');
+}
+if (subcommand === 'help' || cli.flags.help) {
     render(_jsx(Help, {}));
 }
-else if (cli.flags.prompt) {
+else if (subcommand === 'version' || cli.flags.version) {
+    render(_jsx(DisplayVersion, {}));
+}
+else if (subcommand === 'about' || cli.flags.about) {
+    render(_jsx(About, {}));
+}
+else if (cli.flags.prompt ||
+    subcommand === 'enhance' ||
+    (subcommand === 'headless' && cli.input.length > 1)) {
+    const promptFromSubcommand = subcommand === 'enhance' || subcommand === 'headless'
+        ? cli.input.slice(1).join(' ').trim()
+        : '';
+    const prompt = cli.flags.prompt || promptFromSubcommand;
+    if (!prompt) {
+        console.error('Headless mode requires a prompt. Use --prompt "..." or `prompt-enhancer enhance "..."`.');
+        process.exit(1);
+    }
     // Direct enhancement mode when --prompt/-p flag is provided
-    render(_jsx(DirectEnhance, { prompt: cli.flags.prompt }));
+    render(_jsx(DirectEnhance, { prompt: prompt, debug: cli.flags.debug, trace: cli.flags.trace, verbose: effectiveVerbose, outputPath: cli.flags.output, outputFormat: cli.flags.outputFormat.toLowerCase() }));
 }
 else {
     // Interactive TUI mode (default)
     render(_jsx(App, { prompt: "" }));
 }
-if (hasFlag('--debug')) {
-    console.log('Debug flags:', cli.flags);
-}
-if (hasFlag('--version')) {
-    await import('./commands/version.js');
-}
-if (hasFlag('--about')) {
-    render(_jsx(About, {}));
-}

package/dist/commands/direct-enhance.d.ts

@@ -1,5 +1,11 @@
+import { type OutputFormat } from '../lib/utils/output-writer.js';
 interface DirectEnhanceProps {
     prompt: string;
+    debug?: boolean;
+    trace?: boolean;
+    verbose?: 1 | 2 | 3;
+    outputPath?: string;
+    outputFormat?: OutputFormat | 'auto';
 }
-export default function DirectEnhance({ prompt }: DirectEnhanceProps): import("react/jsx-runtime").JSX.Element;
+export default function DirectEnhance({ prompt, debug, trace, verbose, outputPath, outputFormat, }: DirectEnhanceProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/commands/direct-enhance.js

@@ -4,41 +4,103 @@ import { Text, Box } from 'ink';
 import { ConfigManager } from '../lib/config/manager.js';
 import { HistoryManager } from '../lib/history/manager.js';
 import { EnhancementEngine } from '../lib/enhancement/engine.js';
-export default function DirectEnhance({ prompt }) {
+import { debugLog, formatErrorDetails, logWithLevel, traceLog, } from '../lib/utils/runtime-logging.js';
+import { writeEnhancementOutputFile, } from '../lib/utils/output-writer.js';
+export default function DirectEnhance({ prompt, debug = false, trace = false, verbose = 1, outputPath, outputFormat = 'auto', }) {
     const [status, setStatus] = useState('initializing');
     const [output, setOutput] = useState('');
     const [error, setError] = useState('');
+    const [outputFileMessage, setOutputFileMessage] = useState('');
     useEffect(() => {
         (async () => {
+            const startedAt = Date.now();
+            let providerName = 'unknown';
+            let modelName = 'default';
             try {
+                traceLog('Starting headless enhancement run', {
+                    trace,
+                    debug,
+                    verbose,
+                    outputPath: outputPath ?? null,
+                    outputFormat,
+                });
                 // Initialize managers
+                traceLog('Initializing configuration manager');
                 const configManager = new ConfigManager();
                 await configManager.load(); // Load config from file
+                const config = configManager.getConfig();
+                providerName = config.defaultProvider;
+                modelName = config.defaultModel ?? 'default';
+                logWithLevel(2, 'Loaded configuration for headless mode', {
+                    defaultProvider: providerName,
+                    defaultModel: modelName,
+                    saveHistory: config.saveHistory,
+                });
+                traceLog('Initializing history manager');
                 const historyManager = new HistoryManager();
                 await historyManager.load(); // Load history from file
+                traceLog('Initializing enhancement engine');
                 const engine = new EnhancementEngine(configManager, historyManager);
                 setStatus('enhancing');
+                logWithLevel(1, 'Enhancement request started.');
                 // Stream enhancement
                 let result = '';
+                let chunkCount = 0;
                 const generator = engine.enhanceStream({
                     prompt,
                     saveToHistory: true,
                 });
                 for await (const chunk of generator) {
+                    chunkCount++;
                     result += chunk;
                     setOutput(result);
+                    if (verbose >= 3) {
+                        logWithLevel(3, `Received stream chunk #${chunkCount}`, {
+                            chunkLength: chunk.length,
+                            totalLength: result.length,
+                        });
+                    }
                 }
                 if (!result.trim()) {
                     throw new Error('Enhancement returned an empty result — the model may be rate-limited or temporarily unavailable.');
                 }
+                logWithLevel(1, 'Enhancement request completed.', {
+                    durationMs: Date.now() - startedAt,
+                    outputLength: result.length,
+                    chunkCount,
+                });
+                if (outputPath) {
+                    traceLog('Writing enhancement output to file', {
+                        outputPath,
+                        outputFormat,
+                    });
+                    const outputFile = await writeEnhancementOutputFile(outputPath, {
+                        originalPrompt: prompt,
+                        enhancedPrompt: result,
+                        provider: providerName,
+                        model: modelName,
+                        timestamp: new Date().toISOString(),
+                        durationMs: Date.now() - startedAt,
+                    }, outputFormat);
+                    setOutputFileMessage(`Output written to ${outputFile.path} (${outputFile.format})`);
+                    logWithLevel(2, 'Output file written successfully.', outputFile);
+                }
                 setStatus('complete');
             }
             catch (err) {
                 setStatus('error');
-                setError(err instanceof Error ? err.message : String(err));
+                const errorText = formatErrorDetails(err);
+                setError(errorText);
+                if (debug) {
+                    debugLog('Headless enhancement failed with detailed error', {
+                        error: errorText,
+                        promptLength: prompt.length,
+                        outputPath: outputPath ?? null,
+                    });
+                }
             }
         })();
-    }, [prompt]);
+    }, [debug, outputFormat, outputPath, prompt, trace, verbose]);
     if (status === 'error') {
         return (_jsx(Box, { flexDirection: "column", marginY: 1, children: _jsxs(Text, { color: "red", children: ["Error: ", error] }) }));
     }
@@ -48,5 +110,5 @@ export default function DirectEnhance({ prompt }) {
     if (status === 'enhancing') {
         return (_jsxs(Box, { flexDirection: "column", marginY: 1, children: [_jsx(Text, { bold: true, color: "cyan", children: "Enhancing prompt..." }), _jsx(Text, { children: output })] }));
     }
-    return (_jsxs(Box, { flexDirection: "column", marginY: 1, children: [_jsx(Text, { bold: true, color: "green", children: "Enhanced prompt:" }), _jsx(Text, { children: output })] }));
+    return (_jsxs(Box, { flexDirection: "column", marginY: 1, children: [_jsx(Text, { bold: true, color: "green", children: "Enhanced prompt:" }), _jsx(Text, { children: output }), outputFileMessage && _jsx(Text, { color: "cyan", children: outputFileMessage })] }));
 }

package/dist/commands/help.js

@@ -1,6 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-// import React from 'react';
 import { Text, Box } from 'ink';
 export default function Help() {
-    return (_jsxs(Box, { flexDirection: "column", padding: 1, children: [_jsx(Text, { bold: true, children: "Usage" }), _jsx(Text, { children: " $ %NAME%" }), _jsx(Text, {}), _jsx(Text, { bold: true, children: "Options" }), _jsx(Text, { children: " --name Your name" }), _jsx(Text, {}), _jsx(Text, { bold: true, children: "Examples" }), _jsx(Text, { children: " $ %NAME% --name=Jane" }), _jsx(Text, { children: " Hello, Jane" })] }));
+    return (_jsxs(Box, { flexDirection: "column", padding: 1, children: [_jsx(Text, { bold: true, color: "cyan", children: "Prompt Enhancer \u2014 Comprehensive Help" }), _jsx(Text, { children: "Enhance prompts in interactive TUI mode or headless CLI mode." }), _jsx(Text, {}), _jsx(Text, { bold: true, children: "Usage" }), _jsx(Text, { children: " prompt-enhancer" }), _jsx(Text, { children: " prompt-enhancer --prompt \"Your prompt text\"" }), _jsx(Text, { children: " prompt-enhancer enhance \"Your prompt text\"" }), _jsx(Text, {}), _jsx(Text, { bold: true, children: "Subcommands" }), _jsx(Text, { children: " help Show this help output" }), _jsx(Text, { children: " about Show package and repository information" }), _jsx(Text, { children: " version Show CLI name, description, and version" }), _jsx(Text, { children: " enhance Run headless enhancement from positional text" }), _jsx(Text, {}), _jsx(Text, { bold: true, children: "Options (headless and global)" }), _jsxs(Text, { children: [' ', "-p, --prompt <text> Prompt to enhance (headless mode) [default: undefined]"] }), _jsxs(Text, { children: [' ', "-o, --output <path> Write enhancement output to file [default: undefined]"] }), _jsxs(Text, { children: [' ', "--output-format <fmt> Output file format: auto|txt|json|md [default: auto]"] }), _jsxs(Text, { children: [' ', "--verbose <level> Output verbosity level 1-3 [default: 1]"] }), _jsxs(Text, { children: [' ', "--debug Enable debug diagnostics, API payload logs, and detailed error details [default: false]"] }), _jsx(Text, { children: " --trace Enable step-by-step execution trace [default: false]" }), _jsx(Text, { children: " --about Show package metadata [default: false]" }), _jsx(Text, { children: " -v, --version Show version info [default: false]" }), _jsx(Text, { children: " --help Show this help output [default: false]" }), _jsx(Text, {}), _jsx(Text, { bold: true, children: "Verbose Levels" }), _jsx(Text, { children: " 1 Minimal runtime information (default)" }), _jsx(Text, { children: " 2 Lifecycle progress and major checkpoints" }), _jsx(Text, { children: " 3 Chunk-level streaming diagnostics and deep detail" }), _jsx(Text, {}), _jsx(Text, { bold: true, children: "Debug and Trace Behavior" }), _jsxs(Text, { children: [' ', "--debug automatically enables debug diagnostics and raw provider request/response payload logging."] }), _jsxs(Text, { children: [' ', "--trace enables step-by-step execution logs and implies highest runtime detail during execution."] }), _jsx(Text, {}), _jsx(Text, { bold: true, children: "Common Workflows" }), _jsx(Text, { children: " Interactive mode (menu):" }), _jsx(Text, { children: " prompt-enhancer" }), _jsx(Text, { children: " Basic headless run:" }), _jsx(Text, { children: " prompt-enhancer --prompt \"Write a better API README\"" }), _jsx(Text, { children: " Save output as JSON:" }), _jsxs(Text, { children: [' ', "prompt-enhancer -p \"Improve this prompt\" -o .\\output\\result.json --output-format json"] }), _jsx(Text, { children: " Full diagnostics with tracing:" }), _jsxs(Text, { children: [' ', "prompt-enhancer enhance \"Create a test plan\" --debug --trace --verbose 3"] }), _jsx(Text, { children: " Markdown output (format inferred from extension):" }), _jsxs(Text, { children: [' ', "prompt-enhancer -p \"Draft a deployment checklist\" -o .\\out\\checklist.md"] }), _jsx(Text, {}), _jsx(Text, { bold: true, children: "Troubleshooting" }), _jsxs(Text, { children: [' ', "- Empty enhancement output: try a different model/provider or rerun with --debug."] }), _jsxs(Text, { children: [' ', "- API/auth failures: verify provider keys in Settings (interactive mode) or config file."] }), _jsxs(Text, { children: [' ', "- Output write failures: ensure target directory is writable and format is valid."] }), _jsxs(Text, { children: [' ', "- Verbose level errors: use only --verbose 1, --verbose 2, or --verbose 3."] }), _jsx(Text, {}), _jsx(Text, { color: "gray", children: "Tip: use interactive mode for iterative prompt refinement and provider configuration." })] }));
 }

package/dist/lib/providers/copilot.js

@@ -7,6 +7,7 @@
 import { OpenAI } from 'openai';
 import { Provider } from './base.js';
 import { getCopilotToken } from '../utils/copilot-auth.js';
+import { debugLog, logWithLevel } from '../utils/runtime-logging.js';
 export class CopilotProvider extends Provider {
     client;
     initialized = false;
@@ -39,6 +40,21 @@ export class CopilotProvider extends Provider {
         await this.ensureInitialized();
         const systemPrompt = options?.systemPrompt ||
             'You are an expert at enhancing and improving user prompts for LLMs. Analyze the given prompt and return an improved version that is clearer, more specific, and more likely to produce better results. Return ONLY the enhanced prompt, no explanations.';
+        debugLog('Copilot API request payload', {
+            model: options?.model || this.defaultModel,
+            temperature: options?.temperature || 0.7,
+            max_tokens: options?.maxTokens || 1000,
+            messages: [
+                {
+                    role: 'system',
+                    content: systemPrompt,
+                },
+                {
+                    role: 'user',
+                    content: `Original prompt:\n${prompt}`,
+                },
+            ],
+        });
         const response = await this.client.chat.completions.create({
             messages: [
                 {
@@ -54,6 +70,7 @@ export class CopilotProvider extends Provider {
             temperature: options?.temperature || 0.7,
             max_tokens: options?.maxTokens || 1000,
         });
+        debugLog('Copilot API response payload', response);
         const content = response.choices[0]?.message?.content;
         if (!content) {
             throw new Error('No response received from Copilot');
@@ -64,6 +81,22 @@ export class CopilotProvider extends Provider {
         await this.ensureInitialized();
         const systemPrompt = options?.systemPrompt ||
             'You are an expert at enhancing and improving user prompts for LLMs. Analyze the given prompt and return an improved version that is clearer, more specific, and more likely to produce better results. Return ONLY the enhanced prompt, no explanations.';
+        debugLog('Copilot stream API request payload', {
+            messages: [
+                {
+                    role: 'system',
+                    content: systemPrompt,
+                },
+                {
+                    role: 'user',
+                    content: `Original prompt:\n${prompt}`,
+                },
+            ],
+            model: options?.model || this.defaultModel,
+            temperature: options?.temperature || 0.7,
+            max_tokens: options?.maxTokens || 1000,
+            stream: true,
+        });
         const stream = await this.client.chat.completions.create({
             messages: [
                 {
@@ -80,7 +113,12 @@ export class CopilotProvider extends Provider {
             max_tokens: options?.maxTokens || 1000,
             stream: true,
         });
+        let chunkCount = 0;
         for await (const event of stream) {
+            chunkCount++;
+            logWithLevel(3, `Copilot stream event #${chunkCount}`, {
+                hasChoices: Boolean(event.choices?.length),
+            });
             const content = event.choices[0]?.delta?.content;
             if (content) {
                 yield content;

package/dist/lib/providers/gemini.js

@@ -3,6 +3,7 @@
  */
 import { GoogleGenerativeAI } from '@google/generative-ai';
 import { Provider } from './base.js';
+import { debugLog, logWithLevel } from '../utils/runtime-logging.js';
 export class GeminiProvider extends Provider {
     client;
     constructor(credentials) {
@@ -18,7 +19,7 @@ export class GeminiProvider extends Provider {
         });
         const systemPrompt = options?.systemPrompt ||
             'You are an expert at enhancing and improving user prompts for LLMs. Analyze the given prompt and return an improved version that is clearer, more specific, and more likely to produce better results. Return ONLY the enhanced prompt, no explanations.';
-        const result = await model.generateContent({
+        const payload = {
             contents: [
                 {
                     role: 'user',
@@ -29,8 +30,19 @@ export class GeminiProvider extends Provider {
                     ],
                 },
             ],
+        };
+        debugLog('Gemini API request payload', {
+            model: options?.model || this.defaultModel,
+            temperature: options?.temperature,
+            maxTokens: options?.maxTokens,
+            payload,
         });
+        const result = await model.generateContent(payload);
         const response = result.response;
+        debugLog('Gemini API response metadata', {
+            candidates: response.candidates?.length ?? 0,
+            usageMetadata: response.usageMetadata ?? null,
+        });
         const text = response.text();
         if (!text) {
             throw new Error('No response received from Gemini');
@@ -43,7 +55,7 @@ export class GeminiProvider extends Provider {
         });
         const systemPrompt = options?.systemPrompt ||
             'You are an expert at enhancing and improving user prompts for LLMs. Analyze the given prompt and return an improved version that is clearer, more specific, and more likely to produce better results. Return ONLY the enhanced prompt, no explanations.';
-        const result = await model.generateContentStream({
+        const streamPayload = {
             contents: [
                 {
                     role: 'user',
@@ -54,10 +66,20 @@ export class GeminiProvider extends Provider {
                     ],
                 },
             ],
+        };
+        debugLog('Gemini stream request payload', {
+            model: options?.model || this.defaultModel,
+            streamPayload,
         });
+        const result = await model.generateContentStream(streamPayload);
+        let chunkCount = 0;
         for await (const chunk of result.stream) {
+            chunkCount++;
             const text = chunk.text();
             if (text) {
+                logWithLevel(3, `Gemini stream chunk #${chunkCount}`, {
+                    length: text.length,
+                });
                 yield text;
             }
         }

package/dist/lib/providers/kilo.js

@@ -4,6 +4,7 @@
  * API: https://kilo.ai/  — free models still require an API key from https://app.kilo.ai
  */
 import { Provider } from './base.js';
+import { debugLog, logWithLevel, redactAuthorizationHeaders, } from '../utils/runtime-logging.js';
 export const KILO_MODELS = [
     {
         id: 'openrouter/free',
@@ -75,11 +76,25 @@ export class KiloProvider extends Provider {
             max_tokens: options?.maxTokens ?? 1000,
             stream: false,
         };
+        const headers = this.buildHeaders();
+        debugLog('Kilo API request payload', {
+            endpoint: this.endpoint,
+            headers: redactAuthorizationHeaders(headers),
+            body,
+        });
         const response = await fetch(this.endpoint, {
             method: 'POST',
-            headers: this.buildHeaders(),
+            headers,
             body: JSON.stringify(body),
         });
+        debugLog('Kilo API response status', {
+            status: response.status,
+            statusText: response.statusText,
+        });
+        if (response.ok) {
+            const rawResponse = await response.clone().text();
+            debugLog('Kilo API raw response body', rawResponse);
+        }
         if (!response.ok) {
             await throwOnError(response);
         }
@@ -100,11 +115,21 @@ export class KiloProvider extends Provider {
             max_tokens: options?.maxTokens ?? 1000,
             stream: true,
         };
+        const headers = this.buildHeaders();
+        debugLog('Kilo stream request payload', {
+            endpoint: this.endpoint,
+            headers: redactAuthorizationHeaders(headers),
+            body,
+        });
         const response = await fetch(this.endpoint, {
             method: 'POST',
-            headers: this.buildHeaders(),
+            headers,
             body: JSON.stringify(body),
         });
+        debugLog('Kilo stream response status', {
+            status: response.status,
+            statusText: response.statusText,
+        });
         if (!response.ok) {
             await throwOnError(response);
         }
@@ -113,6 +138,7 @@ export class KiloProvider extends Provider {
         const reader = response.body.getReader();
         const decoder = new TextDecoder();
         let buffer = '';
+        let eventCount = 0;
         try {
             while (true) {
                 const { done, value } = await reader.read();
@@ -127,6 +153,8 @@ export class KiloProvider extends Provider {
                         if (data === '[DONE]')
                             return;
                         try {
+                            eventCount++;
+                            logWithLevel(3, `Kilo stream event #${eventCount}`, data);
                             const parsed = JSON.parse(data);
                             if (parsed.error) {
                                 const msg = parsed.error.message ?? JSON.stringify(parsed.error);

package/dist/lib/providers/opencode.js

@@ -5,6 +5,7 @@
  * Chat completions: https://opencode.ai/zen/v1/chat/completions
  */
 import { Provider } from './base.js';
+import { debugLog, logWithLevel, redactAuthorizationHeaders, } from '../utils/runtime-logging.js';
 export const OPENCODE_BASE_URL = 'https://opencode.ai/zen/v1';
 export const OPENCODE_MODELS_ENDPOINT = `${OPENCODE_BASE_URL}/models`;
 export const OPENCODE_CHAT_ENDPOINT = `${OPENCODE_BASE_URL}/chat/completions`;
@@ -71,11 +72,25 @@ export class OpenCodeProvider extends Provider {
             max_tokens: options?.maxTokens ?? 1000,
             stream: false,
         };
+        const headers = this.buildHeaders();
+        debugLog('OpenCode API request payload', {
+            endpoint: this.chatEndpoint,
+            headers: redactAuthorizationHeaders(headers),
+            body,
+        });
         const response = await fetch(this.chatEndpoint, {
             method: 'POST',
-            headers: this.buildHeaders(),
+            headers,
             body: JSON.stringify(body),
         });
+        debugLog('OpenCode API response status', {
+            status: response.status,
+            statusText: response.statusText,
+        });
+        if (response.ok) {
+            const rawResponse = await response.clone().text();
+            debugLog('OpenCode raw response body', rawResponse);
+        }
         if (!response.ok) {
             await throwOnError(response);
         }
@@ -96,11 +111,21 @@ export class OpenCodeProvider extends Provider {
             max_tokens: options?.maxTokens ?? 1000,
             stream: true,
         };
+        const headers = this.buildHeaders();
+        debugLog('OpenCode stream request payload', {
+            endpoint: this.chatEndpoint,
+            headers: redactAuthorizationHeaders(headers),
+            body,
+        });
         const response = await fetch(this.chatEndpoint, {
             method: 'POST',
-            headers: this.buildHeaders(),
+            headers,
             body: JSON.stringify(body),
         });
+        debugLog('OpenCode stream response status', {
+            status: response.status,
+            statusText: response.statusText,
+        });
         if (!response.ok) {
             await throwOnError(response);
         }
@@ -109,6 +134,7 @@ export class OpenCodeProvider extends Provider {
         const reader = response.body.getReader();
         const decoder = new TextDecoder();
         let buffer = '';
+        let eventCount = 0;
         try {
             while (true) {
                 const { done, value } = await reader.read();
@@ -123,6 +149,8 @@ export class OpenCodeProvider extends Provider {
                         if (data === '[DONE]')
                             return;
                         try {
+                            eventCount++;
+                            logWithLevel(3, `OpenCode stream event #${eventCount}`, data);
                             const parsed = JSON.parse(data);
                             if (parsed.error) {
                                 const msg = parsed.error.message ?? JSON.stringify(parsed.error);

package/dist/lib/utils/output-writer.d.ts

@@ -0,0 +1,13 @@
+export type OutputFormat = 'txt' | 'json' | 'md';
+export interface EnhancementOutputPayload {
+    originalPrompt: string;
+    enhancedPrompt: string;
+    provider: string;
+    model: string;
+    timestamp: string;
+    durationMs: number;
+}
+export declare function writeEnhancementOutputFile(path: string, payload: EnhancementOutputPayload, format?: string): Promise<{
+    path: string;
+    format: OutputFormat;
+}>;

package/dist/lib/utils/output-writer.js

@@ -0,0 +1,70 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, extname } from 'node:path';
+function inferOutputFormat(path) {
+    const extension = extname(path).toLowerCase();
+    if (extension === '.json')
+        return 'json';
+    if (extension === '.md' || extension === '.markdown')
+        return 'md';
+    return 'txt';
+}
+function resolveOutputFormat(path, format) {
+    if (!format || format === 'auto') {
+        return inferOutputFormat(path);
+    }
+    if (format === 'txt' || format === 'json' || format === 'md') {
+        return format;
+    }
+    throw new Error(`Unsupported output format "${format}". Supported formats: txt, json, md, auto.`);
+}
+function toText(payload) {
+    return `Prompt Enhancer Output
+Timestamp: ${payload.timestamp}
+Provider: ${payload.provider}
+Model: ${payload.model}
+Duration: ${payload.durationMs} ms
+
+Original Prompt:
+${payload.originalPrompt}
+
+Enhanced Prompt:
+${payload.enhancedPrompt}
+`;
+}
+function toMarkdown(payload) {
+    return `## Prompt Enhancer Output
+
+- **Timestamp:** ${payload.timestamp}
+- **Provider:** ${payload.provider}
+- **Model:** ${payload.model}
+- **Duration:** ${payload.durationMs} ms
+
+### Original Prompt
+
+\`\`\`text
+${payload.originalPrompt}
+\`\`\`
+
+### Enhanced Prompt
+
+\`\`\`text
+${payload.enhancedPrompt}
+\`\`\`
+`;
+}
+export async function writeEnhancementOutputFile(path, payload, format) {
+    const outputFormat = resolveOutputFormat(path, format);
+    await mkdir(dirname(path), { recursive: true });
+    let content = '';
+    if (outputFormat === 'json') {
+        content = JSON.stringify(payload, null, 2);
+    }
+    else if (outputFormat === 'md') {
+        content = toMarkdown(payload);
+    }
+    else {
+        content = toText(payload);
+    }
+    await writeFile(path, content, 'utf8');
+    return { path, format: outputFormat };
+}

package/dist/lib/utils/runtime-logging.d.ts

@@ -0,0 +1,16 @@
+export type VerboseLevel = 1 | 2 | 3;
+export interface RuntimeLoggingOptions {
+    debug: boolean;
+    trace: boolean;
+    verbose: VerboseLevel;
+}
+export declare function normalizeVerboseLevel(value: number | undefined): VerboseLevel;
+export declare function configureRuntimeLogging(options: Partial<RuntimeLoggingOptions>): RuntimeLoggingOptions;
+export declare function getRuntimeLoggingOptions(): RuntimeLoggingOptions;
+export declare function logWithLevel(level: number, message: string, details?: unknown): void;
+export declare function debugLog(message: string, details?: unknown): void;
+export declare function traceLog(step: string, details?: unknown): void;
+export declare function formatErrorDetails(error: unknown): string;
+export declare function safeSerialize(value: unknown): string;
+export declare function redactAuthorizationHeaders(headers: Record<string, string>): Record<string, string>;
+export declare function writeRuntimeBanner(command: string): void;

package/dist/lib/utils/runtime-logging.js

@@ -0,0 +1,94 @@
+import process from 'node:process';
+const runtimeLoggingOptions = {
+    debug: false,
+    trace: false,
+    verbose: 1,
+};
+function clampVerboseLevel(value) {
+    if (value <= 1)
+        return 1;
+    if (value >= 3)
+        return 3;
+    return 2;
+}
+export function normalizeVerboseLevel(value) {
+    if (typeof value !== 'number' || Number.isNaN(value)) {
+        return 1;
+    }
+    return clampVerboseLevel(Math.floor(value));
+}
+export function configureRuntimeLogging(options) {
+    if (typeof options.debug === 'boolean') {
+        runtimeLoggingOptions.debug = options.debug;
+    }
+    if (typeof options.trace === 'boolean') {
+        runtimeLoggingOptions.trace = options.trace;
+    }
+    if (typeof options.verbose === 'number') {
+        runtimeLoggingOptions.verbose = normalizeVerboseLevel(options.verbose);
+    }
+    return { ...runtimeLoggingOptions };
+}
+export function getRuntimeLoggingOptions() {
+    return { ...runtimeLoggingOptions };
+}
+export function logWithLevel(level, message, details) {
+    if (runtimeLoggingOptions.verbose < level)
+        return;
+    if (details === undefined) {
+        console.error(`[verbose:${level}] ${message}`);
+        return;
+    }
+    console.error(`[verbose:${level}] ${message}`);
+    console.error(safeSerialize(details));
+}
+export function debugLog(message, details) {
+    if (!runtimeLoggingOptions.debug)
+        return;
+    if (details === undefined) {
+        console.error(`[debug] ${message}`);
+        return;
+    }
+    console.error(`[debug] ${message}`);
+    console.error(safeSerialize(details));
+}
+export function traceLog(step, details) {
+    if (!runtimeLoggingOptions.trace)
+        return;
+    if (details === undefined) {
+        console.error(`[trace] ${step}`);
+        return;
+    }
+    console.error(`[trace] ${step}`);
+    console.error(safeSerialize(details));
+}
+export function formatErrorDetails(error) {
+    if (error instanceof Error) {
+        if (runtimeLoggingOptions.debug && error.stack) {
+            return error.stack;
+        }
+        return error.message;
+    }
+    return String(error);
+}
+export function safeSerialize(value) {
+    try {
+        return JSON.stringify(value, null, 2);
+    }
+    catch {
+        return String(value);
+    }
+}
+export function redactAuthorizationHeaders(headers) {
+    const redacted = { ...headers };
+    for (const key of Object.keys(redacted)) {
+        if (key.toLowerCase() === 'authorization') {
+            redacted[key] = 'Bearer ***redacted***';
+        }
+    }
+    return redacted;
+}
+export function writeRuntimeBanner(command) {
+    const options = getRuntimeLoggingOptions();
+    console.error(`[runtime] ${command} | debug=${options.debug} trace=${options.trace} verbose=${options.verbose} node=${process.version}`);
+}

package/package.json

@@ -2,7 +2,7 @@
 	"name": "@involvex/prompt-enhancer",
 	"description": "A Cli to enhance your prompts",
 	"author": "involvex",
-	"version": "0.0.3",
+	"version": "0.0.4",
 	"license": "MIT",
 	"bin": {
 		"prompt-enhancer": "dist/cli.js"

package/readme.md

@@ -180,15 +180,31 @@ $ prompt-enhancer --help
 
   Usage
     $ prompt-enhancer
+    $ prompt-enhancer --prompt "your prompt"
+    $ prompt-enhancer enhance "your prompt"
 
   Options
-    --prompt, -p    Your prompt to enhance (optional)
-    --help, -h      Show help
-    --version, -v   Show version
+    --prompt, -p              Prompt text for headless mode
+    --output, -o              Write output to a file
+    --output-format           Output format: auto | txt | json | md (default: auto)
+    --verbose                 Verbosity level: 1 | 2 | 3 (default: 1)
+    --debug                   Enable debug diagnostics + API request/response logs
+    --trace                   Enable step-by-step execution trace
+    --about                   Show package metadata
+    --version, -v             Show version
+    --help, -h                Show help
+
+  Subcommands
+    help                      Show comprehensive help
+    about                     Show package metadata
+    version                   Show version details
+    enhance                   Run headless enhancement using positional prompt text
 
   Examples
     $ prompt-enhancer
     $ prompt-enhancer -p "build a cli to enhance prompts"
+    $ prompt-enhancer -p "summarize this architecture" -o .\out\result.json --output-format json
+    $ prompt-enhancer enhance "design API retries" --debug --trace --verbose 3
     $ prompt-enhancer --help
 ```