@steipete/oracle 0.4.0

package/dist/src/cli/browserConfig.js

@@ -0,0 +1,193 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { CHATGPT_URL, DEFAULT_MODEL_TARGET, normalizeChatgptUrl, parseDuration } from '../browserMode.js';
+const DEFAULT_BROWSER_TIMEOUT_MS = 1_200_000;
+const DEFAULT_BROWSER_INPUT_TIMEOUT_MS = 30_000;
+const DEFAULT_CHROME_PROFILE = 'Default';
+const BROWSER_MODEL_LABELS = {
+    'gpt-5-pro': 'GPT-5 Pro',
+    'gpt-5.1-pro': 'GPT-5.1 Pro',
+    'gpt-5.1': 'GPT-5.1',
+    'gemini-3-pro': 'Gemini 3 Pro',
+};
+export async function buildBrowserConfig(options) {
+    const desiredModelOverride = options.browserModelLabel?.trim();
+    const normalizedOverride = desiredModelOverride?.toLowerCase() ?? '';
+    const baseModel = options.model.toLowerCase();
+    const shouldUseOverride = normalizedOverride.length > 0 && normalizedOverride !== baseModel;
+    const cookieNames = parseCookieNames(options.browserCookieNames ?? process.env.ORACLE_BROWSER_COOKIE_NAMES);
+    const inline = await resolveInlineCookies({
+        inlineArg: options.browserInlineCookies,
+        inlineFileArg: options.browserInlineCookiesFile,
+        envPayload: process.env.ORACLE_BROWSER_COOKIES_JSON,
+        envFile: process.env.ORACLE_BROWSER_COOKIES_FILE,
+        cwd: process.cwd(),
+    });
+    let remoteChrome;
+    if (options.remoteChrome) {
+        remoteChrome = parseRemoteChromeTarget(options.remoteChrome);
+    }
+    const rawUrl = options.chatgptUrl ?? options.browserUrl;
+    const url = rawUrl ? normalizeChatgptUrl(rawUrl, CHATGPT_URL) : undefined;
+    return {
+        chromeProfile: options.browserChromeProfile ?? DEFAULT_CHROME_PROFILE,
+        chromePath: options.browserChromePath ?? null,
+        chromeCookiePath: options.browserCookiePath ?? null,
+        url,
+        timeoutMs: options.browserTimeout ? parseDuration(options.browserTimeout, DEFAULT_BROWSER_TIMEOUT_MS) : undefined,
+        inputTimeoutMs: options.browserInputTimeout
+            ? parseDuration(options.browserInputTimeout, DEFAULT_BROWSER_INPUT_TIMEOUT_MS)
+            : undefined,
+        cookieSync: options.browserNoCookieSync ? false : undefined,
+        cookieNames,
+        inlineCookies: inline?.cookies,
+        inlineCookiesSource: inline?.source ?? null,
+        headless: undefined, // disable headless; Cloudflare blocks it
+        keepBrowser: options.browserKeepBrowser ? true : undefined,
+        hideWindow: options.browserHideWindow ? true : undefined,
+        desiredModel: shouldUseOverride ? desiredModelOverride : mapModelToBrowserLabel(options.model),
+        debug: options.verbose ? true : undefined,
+        // Allow cookie failures by default so runs can continue without Chrome/Keychain secrets.
+        allowCookieErrors: options.browserAllowCookieErrors ?? true,
+        remoteChrome,
+    };
+}
+export function mapModelToBrowserLabel(model) {
+    return BROWSER_MODEL_LABELS[model] ?? DEFAULT_MODEL_TARGET;
+}
+export function resolveBrowserModelLabel(input, model) {
+    const trimmed = input?.trim?.() ?? '';
+    if (!trimmed) {
+        return mapModelToBrowserLabel(model);
+    }
+    const normalizedInput = trimmed.toLowerCase();
+    if (normalizedInput === model.toLowerCase()) {
+        return mapModelToBrowserLabel(model);
+    }
+    return trimmed;
+}
+function parseRemoteChromeTarget(raw) {
+    const target = raw.trim();
+    if (!target) {
+        throw new Error('Invalid remote-chrome value: expected host:port but received an empty string.');
+    }
+    const ipv6Match = target.match(/^\[(.+)]:(\d+)$/);
+    let host;
+    let portSegment;
+    if (ipv6Match) {
+        host = ipv6Match[1]?.trim();
+        portSegment = ipv6Match[2]?.trim();
+    }
+    else {
+        const lastColon = target.lastIndexOf(':');
+        if (lastColon === -1) {
+            throw new Error(`Invalid remote-chrome format: ${target}. Expected host:port (IPv6 must use [host]:port notation).`);
+        }
+        host = target.slice(0, lastColon).trim();
+        portSegment = target.slice(lastColon + 1).trim();
+        if (host.includes(':')) {
+            throw new Error(`Invalid remote-chrome format: ${target}. Wrap IPv6 addresses in brackets, e.g. --remote-chrome "[2001:db8::1]:9222".`);
+        }
+    }
+    if (!host) {
+        throw new Error(`Invalid remote-chrome format: ${target}. Host portion is missing; expected host:port.`);
+    }
+    const port = Number.parseInt(portSegment ?? '', 10);
+    if (!Number.isFinite(port) || port <= 0 || port > 65_535) {
+        throw new Error(`Invalid remote-chrome port: "${portSegment ?? ''}". Expected a number between 1 and 65535.`);
+    }
+    return { host, port };
+}
+function parseCookieNames(raw) {
+    if (!raw)
+        return undefined;
+    const names = raw
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    return names.length ? names : undefined;
+}
+async function resolveInlineCookies({ inlineArg, inlineFileArg, envPayload, envFile, cwd, }) {
+    const tryLoad = async (source, allowPathResolution) => {
+        if (!source)
+            return undefined;
+        const trimmed = source.trim();
+        if (!trimmed)
+            return undefined;
+        if (allowPathResolution) {
+            const resolved = path.isAbsolute(trimmed) ? trimmed : path.join(cwd, trimmed);
+            try {
+                const stat = await fs.stat(resolved);
+                if (stat.isFile()) {
+                    const fileContent = await fs.readFile(resolved, 'utf8');
+                    const parsed = parseInlineCookiesPayload(fileContent);
+                    if (parsed)
+                        return parsed;
+                }
+            }
+            catch {
+                // not a file; treat as payload below
+            }
+        }
+        return parseInlineCookiesPayload(trimmed);
+    };
+    const sources = [
+        { value: inlineFileArg, allowPath: true, source: 'inline-file' },
+        { value: inlineArg, allowPath: true, source: 'inline-arg' },
+        { value: envFile, allowPath: true, source: 'env-file' },
+        { value: envPayload, allowPath: false, source: 'env-payload' },
+    ];
+    for (const { value, allowPath, source } of sources) {
+        const parsed = await tryLoad(value, allowPath);
+        if (parsed)
+            return { cookies: parsed, source };
+    }
+    // fallback: ~/.oracle/cookies.{json,base64}
+    const oracleHome = process.env.ORACLE_HOME_DIR ?? path.join(os.homedir(), '.oracle');
+    const candidates = ['cookies.json', 'cookies.base64'];
+    for (const file of candidates) {
+        const fullPath = path.join(oracleHome, file);
+        try {
+            const stat = await fs.stat(fullPath);
+            if (!stat.isFile())
+                continue;
+            const content = await fs.readFile(fullPath, 'utf8');
+            const parsed = parseInlineCookiesPayload(content);
+            if (parsed)
+                return { cookies: parsed, source: `home:${file}` };
+        }
+        catch {
+            // ignore missing/invalid
+        }
+    }
+    return undefined;
+}
+function parseInlineCookiesPayload(raw) {
+    if (!raw)
+        return undefined;
+    const text = raw.trim();
+    if (!text)
+        return undefined;
+    let jsonPayload = text;
+    // Attempt base64 decode first; fall back to raw text on failure.
+    try {
+        const decoded = Buffer.from(text, 'base64').toString('utf8');
+        if (decoded.trim().startsWith('[')) {
+            jsonPayload = decoded;
+        }
+    }
+    catch {
+        // not base64; continue with raw text
+    }
+    try {
+        const parsed = JSON.parse(jsonPayload);
+        if (Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // invalid json; skip silently to keep this hidden flag non-fatal
+    }
+    return undefined;
+}

package/dist/src/cli/bundleWarnings.js

@@ -0,0 +1,9 @@
+import chalk from 'chalk';
+export function warnIfOversizeBundle(estimatedTokens, threshold = 196_000, log = console.log) {
+    if (Number.isNaN(estimatedTokens) || estimatedTokens <= threshold) {
+        return false;
+    }
+    const msg = `Warning: bundle is ~${estimatedTokens.toLocaleString()} tokens (>${threshold.toLocaleString()}); may exceed model limits.`;
+    log(chalk.red(msg));
+    return true;
+}

package/dist/src/cli/clipboard.js

@@ -0,0 +1,10 @@
+import clipboard from 'clipboardy';
+export async function copyToClipboard(text) {
+    try {
+        await clipboard.write(text);
+        return { success: true, command: 'clipboardy' };
+    }
+    catch (error) {
+        return { success: false, error };
+    }
+}

package/dist/src/cli/detach.js

@@ -0,0 +1,11 @@
+import { PRO_MODELS } from '../oracle.js';
+export function shouldDetachSession({ 
+// Params kept for future policy tweaks; currently only model/disableDetachEnv matter.
+engine, model, waitPreference: _waitPreference, disableDetachEnv, }) {
+    if (disableDetachEnv)
+        return false;
+    // Only Pro-tier API runs should start detached by default; browser runs stay inline so failures surface.
+    if (PRO_MODELS.has(model) && engine === 'api')
+        return true;
+    return false;
+}

package/dist/src/cli/dryRun.js

@@ -0,0 +1,103 @@
+import chalk from 'chalk';
+import { MODEL_CONFIGS, TOKENIZER_OPTIONS, DEFAULT_SYSTEM_PROMPT, buildPrompt, readFiles, getFileTokenStats, printFileTokenStats, } from '../oracle.js';
+import { assembleBrowserPrompt } from '../browser/prompt.js';
+import { buildTokenEstimateSuffix, formatAttachmentLabel } from '../browser/promptSummary.js';
+import { buildCookiePlan } from '../browser/policies.js';
+export async function runDryRunSummary({ engine, runOptions, cwd, version, log, browserConfig, }, deps = {}) {
+    if (engine === 'browser') {
+        await runBrowserDryRun({ runOptions, cwd, version, log, browserConfig }, deps);
+        return;
+    }
+    await runApiDryRun({ runOptions, cwd, version, log }, deps);
+}
+async function runApiDryRun({ runOptions, cwd, version, log, }, deps) {
+    const readFilesImpl = deps.readFilesImpl ?? readFiles;
+    const files = await readFilesImpl(runOptions.file ?? [], { cwd });
+    const systemPrompt = runOptions.system?.trim() || DEFAULT_SYSTEM_PROMPT;
+    const combinedPrompt = buildPrompt(runOptions.prompt ?? '', files, cwd);
+    const tokenizer = MODEL_CONFIGS[runOptions.model].tokenizer;
+    const estimatedInputTokens = tokenizer([
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: combinedPrompt },
+    ], TOKENIZER_OPTIONS);
+    const headerLine = `[dry-run] Oracle (${version}) would call ${runOptions.model} with ~${estimatedInputTokens.toLocaleString()} tokens and ${files.length} files.`;
+    log(chalk.cyan(headerLine));
+    if (files.length === 0) {
+        log(chalk.dim('[dry-run] No files matched the provided --file patterns.'));
+        return;
+    }
+    const inputBudget = runOptions.maxInput ?? MODEL_CONFIGS[runOptions.model].inputLimit;
+    const stats = getFileTokenStats(files, {
+        cwd,
+        tokenizer,
+        tokenizerOptions: TOKENIZER_OPTIONS,
+        inputTokenBudget: inputBudget,
+    });
+    printFileTokenStats(stats, { inputTokenBudget: inputBudget, log });
+}
+async function runBrowserDryRun({ runOptions, cwd, version, log, browserConfig, }, deps) {
+    const assemblePromptImpl = deps.assembleBrowserPromptImpl ?? assembleBrowserPrompt;
+    const artifacts = await assemblePromptImpl(runOptions, { cwd });
+    const suffix = buildTokenEstimateSuffix(artifacts);
+    const headerLine = `[dry-run] Oracle (${version}) would launch browser mode (${runOptions.model}) with ~${artifacts.estimatedInputTokens.toLocaleString()} tokens${suffix}.`;
+    log(chalk.cyan(headerLine));
+    logBrowserCookieStrategy(browserConfig, log, 'dry-run');
+    logBrowserFileSummary(artifacts, log, 'dry-run');
+}
+function logBrowserCookieStrategy(browserConfig, log, label) {
+    if (!browserConfig)
+        return;
+    const plan = buildCookiePlan(browserConfig);
+    log(chalk.bold(`[${label}] ${plan.description}`));
+}
+function logBrowserFileSummary(artifacts, log, label) {
+    if (artifacts.attachments.length > 0) {
+        const prefix = artifacts.bundled ? `[${label}] Bundled upload:` : `[${label}] Attachments to upload:`;
+        log(chalk.bold(prefix));
+        artifacts.attachments.forEach((attachment) => {
+            log(`  • ${formatAttachmentLabel(attachment)}`);
+        });
+        if (artifacts.bundled) {
+            log(chalk.dim(`  (bundled ${artifacts.bundled.originalCount} files into ${artifacts.bundled.bundlePath})`));
+        }
+        return;
+    }
+    if (artifacts.inlineFileCount > 0) {
+        log(chalk.bold(`[${label}] Inline file content:`));
+        log(`  • ${artifacts.inlineFileCount} file${artifacts.inlineFileCount === 1 ? '' : 's'} pasted directly into the composer.`);
+        return;
+    }
+    log(chalk.dim(`[${label}] No files attached.`));
+}
+export async function runBrowserPreview({ runOptions, cwd, version, previewMode, log, }, deps = {}) {
+    const assemblePromptImpl = deps.assembleBrowserPromptImpl ?? assembleBrowserPrompt;
+    const artifacts = await assemblePromptImpl(runOptions, { cwd });
+    const suffix = buildTokenEstimateSuffix(artifacts);
+    const headerLine = `[preview] Oracle (${version}) browser mode (${runOptions.model}) with ~${artifacts.estimatedInputTokens.toLocaleString()} tokens${suffix}.`;
+    log(chalk.cyan(headerLine));
+    logBrowserFileSummary(artifacts, log, 'preview');
+    if (previewMode === 'json' || previewMode === 'full') {
+        const attachmentSummary = artifacts.attachments.map((attachment) => ({
+            path: attachment.path,
+            displayPath: attachment.displayPath,
+            sizeBytes: attachment.sizeBytes,
+        }));
+        const previewPayload = {
+            model: runOptions.model,
+            engine: 'browser',
+            composerText: artifacts.composerText,
+            attachments: attachmentSummary,
+            inlineFileCount: artifacts.inlineFileCount,
+            bundled: artifacts.bundled,
+            tokenEstimate: artifacts.estimatedInputTokens,
+        };
+        log('');
+        log(chalk.bold('Preview JSON'));
+        log(JSON.stringify(previewPayload, null, 2));
+    }
+    if (previewMode === 'full') {
+        log('');
+        log(chalk.bold('Composer Text'));
+        log(artifacts.composerText || chalk.dim('(empty prompt)'));
+    }
+}

package/dist/src/cli/duplicatePromptGuard.js

@@ -0,0 +1,14 @@
+import chalk from 'chalk';
+export async function shouldBlockDuplicatePrompt({ prompt, force, sessionStore, log = console.log, }) {
+    if (force)
+        return false;
+    const normalized = prompt?.trim();
+    if (!normalized)
+        return false;
+    const running = (await sessionStore.listSessions()).filter((entry) => entry.status === 'running');
+    const duplicate = running.find((entry) => (entry.options?.prompt?.trim?.() ?? '') === normalized);
+    if (!duplicate)
+        return false;
+    log(chalk.yellow(`A session with the same prompt is already running (${duplicate.id}). Reattach with "oracle session ${duplicate.id}" or rerun with --force to start another run.`));
+    return true;
+}

package/dist/src/cli/engine.js

@@ -0,0 +1,25 @@
+import { PRO_MODELS } from '../oracle.js';
+export function defaultWaitPreference(model, engine) {
+    // Pro-class API runs can take a long time; prefer non-blocking unless explicitly overridden.
+    if (engine === 'api' && PRO_MODELS.has(model)) {
+        return false;
+    }
+    return true; // browser or non-pro models are fast enough to block by default
+}
+/**
+ * Determine which engine to use based on CLI flags and the environment.
+ *
+ * Precedence:
+ * 1) Legacy --browser flag forces browser.
+ * 2) Explicit --engine value.
+ * 3) OPENAI_API_KEY decides: api when set, otherwise browser.
+ */
+export function resolveEngine({ engine, browserFlag, env, }) {
+    if (browserFlag) {
+        return 'browser';
+    }
+    if (engine) {
+        return engine;
+    }
+    return env.OPENAI_API_KEY ? 'api' : 'browser';
+}

package/dist/src/cli/errorUtils.js

@@ -0,0 +1,9 @@
+const LOGGED_SYMBOL = Symbol('oracle.alreadyLogged');
+export function markErrorLogged(error) {
+    if (error instanceof Error) {
+        error[LOGGED_SYMBOL] = true;
+    }
+}
+export function isErrorLogged(error) {
+    return Boolean(error instanceof Error && error[LOGGED_SYMBOL]);
+}

package/dist/src/cli/format.js

@@ -0,0 +1,13 @@
+export function formatCompactNumber(value) {
+    if (Number.isNaN(value) || !Number.isFinite(value))
+        return '0';
+    const abs = Math.abs(value);
+    const stripTrailingZero = (text) => text.replace(/\.0$/, '');
+    if (abs >= 1_000_000) {
+        return `${stripTrailingZero((value / 1_000_000).toFixed(1))}m`;
+    }
+    if (abs >= 1_000) {
+        return `${stripTrailingZero((value / 1_000).toFixed(1))}k`;
+    }
+    return value.toLocaleString();
+}

package/dist/src/cli/help.js

@@ -0,0 +1,77 @@
+import kleur from 'kleur';
+const createColorWrapper = (isTty) => (styler) => (text) => isTty ? styler(text) : text;
+export function applyHelpStyling(program, version, isTty) {
+    const wrap = createColorWrapper(isTty);
+    const colors = {
+        banner: wrap((text) => kleur.bold().blue(text)),
+        subtitle: wrap((text) => kleur.dim(text)),
+        section: wrap((text) => kleur.bold().white(text)),
+        bullet: wrap((text) => kleur.blue(text)),
+        command: wrap((text) => kleur.bold().blue(text)),
+        option: wrap((text) => kleur.cyan(text)),
+        argument: wrap((text) => kleur.magenta(text)),
+        description: wrap((text) => kleur.white(text)),
+        muted: wrap((text) => kleur.gray(text)),
+        accent: wrap((text) => kleur.cyan(text)),
+    };
+    program.configureHelp({
+        styleTitle(title) {
+            return colors.section(title);
+        },
+        styleDescriptionText(text) {
+            return colors.description(text);
+        },
+        styleCommandText(text) {
+            return colors.command(text);
+        },
+        styleSubcommandText(text) {
+            return colors.command(text);
+        },
+        styleOptionText(text) {
+            return colors.option(text);
+        },
+        styleArgumentText(text) {
+            return colors.argument(text);
+        },
+    });
+    program.addHelpText('beforeAll', () => renderHelpBanner(version, colors));
+    program.addHelpText('after', () => renderHelpFooter(program, colors));
+}
+function renderHelpBanner(version, colors) {
+    const subtitle = 'GPT-5.1 Pro/GPT-5.1 for tough questions with code/file context.';
+    return `${colors.banner(`Oracle CLI v${version}`)} ${colors.subtitle(`— ${subtitle}`)}\n`;
+}
+function renderHelpFooter(program, colors) {
+    const tips = [
+        `${colors.bullet('•')} Oracle cannot see your project unless you pass ${colors.accent('--file …')} — attach the files/dirs you want it to read.`,
+        `${colors.bullet('•')} Attach lots of source (whole directories beat single files) and keep total input under ~196k tokens.`,
+        `${colors.bullet('•')} Oracle starts empty—open with a short project briefing (stack, services, build steps), spell out the question and prior attempts, and why it matters; the more explanation and context you provide, the better the response will be.`,
+        `${colors.bullet('•')} Spell out the project + platform + version requirements (repo name, target OS/toolchain versions, API dependencies) so Oracle doesn’t guess defaults.`,
+        `${colors.bullet('•')} When comparing multiple repos/files, spell out each repo + path + role (e.g., “Project A SettingsView → apps/project-a/Sources/SettingsView.swift; Project B SettingsView → ../project-b/mac/...”) so the model knows exactly which file is which.`,
+        `${colors.bullet('•')} Best results: 6–30 sentences plus key source files; very short prompts often yield generic answers.`,
+        `${colors.bullet('•')} Oracle is one-shot: it does not remember prior runs, so start fresh each time with full context.`,
+        `${colors.bullet('•')} Run ${colors.accent('--files-report')} to inspect token spend before hitting the API.`,
+        `${colors.bullet('•')} Non-preview runs spawn detached sessions (especially gpt-5.1-pro API). If the CLI times out, do not re-run — reattach with ${colors.accent('oracle session <slug>')} to resume/inspect the existing run.`,
+        `${colors.bullet('•')} Set a memorable 3–5 word slug via ${colors.accent('--slug "<words>"')} to keep session IDs tidy.`,
+        `${colors.bullet('•')} Finished sessions auto-hide preamble logs when reattached; raw timestamps remain in the saved log file.`,
+        `${colors.bullet('•')} Need hidden flags? Run ${colors.accent(`${program.name()} --help --verbose`)} to list search/token/browser overrides.`,
+        `${colors.bullet('•')} If any Oracle session is already running, do not start new API runs. Attach to the existing browser session instead; only trigger API calls when you explicitly mean to.`,
+        `${colors.bullet('•')} Duplicate prompt guard: if the same prompt is already running, new runs are blocked unless you pass ${colors.accent('--force')}—prefer reattaching instead of spawning duplicates.`,
+    ].join('\n');
+    const formatExample = (command, description) => `${colors.command(`  ${command}`)}\n${colors.muted(`    ${description}`)}`;
+    const examples = [
+        formatExample(`${program.name()} --render --copy --prompt "Review the TS data layer for schema drift" --file "src/**/*.ts,*/*.test.ts"`, 'Build the bundle, print it, and copy it for manual paste into ChatGPT.'),
+        formatExample(`${program.name()} --prompt "Cross-check the data layer assumptions" --models gpt-5.1-pro,gemini-3-pro --file "src/**/*.ts"`, 'Run multiple API models in one go and aggregate cost/usage.'),
+        formatExample(`${program.name()} status --hours 72 --limit 50`, 'Show sessions from the last 72h (capped at 50 entries).'),
+        formatExample(`${program.name()} session <sessionId>`, 'Attach to a running/completed session and stream the saved transcript.'),
+        formatExample(`${program.name()} --prompt "Ship review" --slug "release-readiness-audit"`, 'Encourage the model to hand you a 3–5 word slug and pass it along with --slug.'),
+        formatExample(`${program.name()} --prompt "Tabs frozen: compare Project A SettingsView (apps/project-a/Sources/SettingsView.swift) vs Project B SettingsView (../project-b/mac/App/Presentation/Views/SettingsView.swift)" --file apps/project-a/Sources/SettingsView.swift --file ../project-b/mac/App/Presentation/Views/SettingsView.swift`, 'Spell out what each attached file is (repo + path + role) before asking for comparisons so the model knows exactly what it is reading.'),
+    ].join('\n\n');
+    return `
+${colors.section('Tips')}
+${tips}
+
+${colors.section('Examples')}
+${examples}
+`;
+}

package/dist/src/cli/hiddenAliases.js

@@ -0,0 +1,22 @@
+/**
+ * Normalize hidden alias flags so they behave like their primary counterparts.
+ *
+ * - `--message` maps to `--prompt` when no prompt is provided.
+ * - `--include` extends the `--file` list.
+ * - `--mode` maps to `--engine` for backward compatibility with older docs/UX.
+ */
+export function applyHiddenAliases(options, setOptionValue) {
+    if (options.include && options.include.length > 0) {
+        const mergedFiles = [...(options.file ?? []), ...options.include];
+        options.file = mergedFiles;
+        setOptionValue?.('file', mergedFiles);
+    }
+    if (!options.prompt && options.message) {
+        options.prompt = options.message;
+        setOptionValue?.('prompt', options.message);
+    }
+    if (!options.engine && options.mode) {
+        options.engine = options.mode;
+        setOptionValue?.('engine', options.mode);
+    }
+}

package/dist/src/cli/markdownBundle.js

@@ -0,0 +1,17 @@
+import fs from 'node:fs/promises';
+import { DEFAULT_SYSTEM_PROMPT } from '../oracle/config.js';
+import { buildPrompt } from '../oracle/request.js';
+import { createFileSections, readFiles } from '../oracle/files.js';
+import { createFsAdapter } from '../oracle/fsAdapter.js';
+import { buildPromptMarkdown } from '../oracle/promptAssembly.js';
+export async function buildMarkdownBundle(options, deps = {}) {
+    const cwd = deps.cwd ?? process.cwd();
+    const fsModule = deps.fs ?? createFsAdapter(fs);
+    const files = await readFiles(options.file ?? [], { cwd, fsModule });
+    const sections = createFileSections(files, cwd);
+    const systemPrompt = options.system?.trim() || DEFAULT_SYSTEM_PROMPT;
+    const userPrompt = (options.prompt ?? '').trim();
+    const markdown = buildPromptMarkdown(systemPrompt, userPrompt, sections);
+    const promptWithFiles = buildPrompt(userPrompt, files, cwd);
+    return { markdown, promptWithFiles, systemPrompt, files };
+}

package/dist/src/cli/markdownRenderer.js

@@ -0,0 +1,97 @@
+import chalk from 'chalk';
+import { render as renderMarkdown } from 'markdansi';
+import { bundledLanguages, bundledThemes, createHighlighter, } from 'shiki';
+const DEFAULT_THEME = 'github-dark';
+const HIGHLIGHT_LANGS = ['ts', 'tsx', 'js', 'jsx', 'json', 'swift'];
+const SUPPORTED_LANG_ALIASES = {
+    ts: 'ts',
+    typescript: 'ts',
+    tsx: 'tsx',
+    js: 'js',
+    javascript: 'js',
+    jsx: 'jsx',
+    json: 'json',
+    swift: 'swift',
+};
+const shikiPromise = createHighlighter({
+    themes: [bundledThemes[DEFAULT_THEME]],
+    langs: HIGHLIGHT_LANGS.map((lang) => bundledLanguages[lang]),
+});
+let shiki = null;
+void shikiPromise
+    .then((instance) => {
+    shiki = instance;
+})
+    .catch(() => {
+    shiki = null;
+});
+export async function ensureShikiReady() {
+    if (shiki)
+        return;
+    try {
+        shiki = await shikiPromise;
+    }
+    catch {
+        shiki = null;
+    }
+}
+function normalizeLanguage(lang) {
+    if (!lang)
+        return null;
+    const key = lang.toLowerCase();
+    return SUPPORTED_LANG_ALIASES[key] ?? null;
+}
+function styleToken(text, fontStyle = 0) {
+    let styled = text;
+    if (fontStyle & 1)
+        styled = chalk.italic(styled);
+    if (fontStyle & 2)
+        styled = chalk.bold(styled);
+    if (fontStyle & 4)
+        styled = chalk.underline(styled);
+    if (fontStyle & 8)
+        styled = chalk.strikethrough(styled);
+    return styled;
+}
+function shikiHighlighter(code, lang) {
+    if (!process.stdout.isTTY || !shiki)
+        return code;
+    const normalizedLang = normalizeLanguage(lang);
+    if (!normalizedLang)
+        return code;
+    try {
+        if (!shiki.getLoadedLanguages().includes(normalizedLang)) {
+            return code;
+        }
+        const { tokens } = shiki.codeToTokens(code, { lang: normalizedLang, theme: DEFAULT_THEME });
+        return tokens
+            .map((line) => line
+            .map((token) => {
+            const colored = token.color ? chalk.hex(token.color)(token.content) : token.content;
+            return styleToken(colored, token.fontStyle);
+        })
+            .join(''))
+            .join('\n');
+    }
+    catch {
+        return code;
+    }
+}
+export function renderMarkdownAnsi(markdown) {
+    try {
+        const color = Boolean(process.stdout.isTTY);
+        const width = process.stdout.columns;
+        const hyperlinks = color; // enable OSC 8 only when we have color/TTY
+        return renderMarkdown(markdown, {
+            color,
+            width,
+            wrap: true,
+            hyperlinks,
+            highlighter: color ? shikiHighlighter : undefined,
+        });
+    }
+    catch {
+        // Last-resort fallback: return the raw markdown so we never crash.
+        return markdown;
+    }
+}