@andrewting19/oracle 0.9.1

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 = "Prompt + files required — GPT-5.4 Pro/GPT-5.4 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("•")} Required: always pass a prompt AND ${colors.accent("--file …")} (directories/globs are fine); Oracle cannot see your project otherwise.`,
+        `${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 by default. For OpenAI/Azure API runs, you can chain follow-ups by passing ${colors.accent("--followup <sessionId|responseId>")} (continues via Responses API previous_response_id).`,
+        `${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.4-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.2-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,21 @@
+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,
+        maxFileSizeBytes: options.maxFileSizeBytes,
+    });
+    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;
+    }
+}

package/dist/src/cli/notifier.js

@@ -0,0 +1,316 @@
+import notifier from "toasted-notifier";
+import { spawn } from "node:child_process";
+import { formatUSD, formatNumber } from "../oracle/format.js";
+import { MODEL_CONFIGS } from "../oracle/config.js";
+import { estimateUsdCost } from "tokentally";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+const ORACLE_EMOJI = "🧿";
+export function resolveNotificationSettings({ cliNotify, cliNotifySound, env, config, }) {
+    const defaultEnabled = !(bool(env.CI) || bool(env.SSH_CONNECTION) || muteByConfig(env, config));
+    const envNotify = parseToggle(env.ORACLE_NOTIFY);
+    const envSound = parseToggle(env.ORACLE_NOTIFY_SOUND);
+    const enabled = cliNotify ?? envNotify ?? config?.enabled ?? defaultEnabled;
+    const sound = cliNotifySound ?? envSound ?? config?.sound ?? false;
+    return { enabled, sound };
+}
+export function deriveNotificationSettingsFromMetadata(metadata, env, config) {
+    if (metadata?.notifications) {
+        return metadata.notifications;
+    }
+    return resolveNotificationSettings({
+        cliNotify: undefined,
+        cliNotifySound: undefined,
+        env,
+        config,
+    });
+}
+export async function sendSessionNotification(payload, settings, log, answerPreview) {
+    if (!settings.enabled || isTestEnv(process.env)) {
+        return;
+    }
+    const title = `Oracle${ORACLE_EMOJI} finished`;
+    const message = buildMessage(payload, sanitizePreview(answerPreview));
+    try {
+        if (await tryMacNativeNotifier(title, message, settings)) {
+            return;
+        }
+        if (!(await shouldSkipToastedNotifier())) {
+            // Fallback to toasted-notifier (cross-platform). macAppIconOption() is only honored on macOS.
+            await notifier.notify({
+                title,
+                message,
+                sound: settings.sound,
+            });
+            return;
+        }
+    }
+    catch (error) {
+        if (isMacExecError(error)) {
+            const repaired = await repairMacNotifier(log);
+            if (repaired) {
+                try {
+                    await notifier.notify({ title, message, sound: settings.sound, ...macAppIconOption() });
+                    return;
+                }
+                catch (retryError) {
+                    const reason = describeNotifierError(retryError);
+                    log(`(notify skipped after retry: ${reason})`);
+                    return;
+                }
+            }
+        }
+        if (isMacBadCpuError(error)) {
+            const reason = describeNotifierError(error);
+            log(`(notify skipped: ${reason})`);
+            return;
+        }
+        const reason = describeNotifierError(error);
+        log(`(notify skipped: ${reason})`);
+    }
+    // Last-resort macOS fallback: AppleScript alert (simple, noisy, but works when helpers are blocked).
+    if (process.platform === "darwin") {
+        try {
+            await sendOsascriptAlert(title, message, log);
+            return;
+        }
+        catch (scriptError) {
+            const reason = describeNotifierError(scriptError);
+            log(`(notify skipped: osascript fallback failed: ${reason})`);
+        }
+    }
+}
+function buildMessage(payload, answerPreview) {
+    const parts = [];
+    const sessionLabel = payload.sessionName || payload.sessionId;
+    parts.push(sessionLabel);
+    // Show cost only for API runs.
+    if (payload.mode === "api") {
+        const cost = payload.costUsd ?? inferCost(payload);
+        if (cost !== undefined) {
+            // Round to $0.00 for a concise toast.
+            parts.push(formatUSD(Number(cost.toFixed(2))));
+        }
+    }
+    if (payload.characters != null) {
+        parts.push(`${formatNumber(payload.characters)} chars`);
+    }
+    if (answerPreview) {
+        parts.push(answerPreview);
+    }
+    return parts.join(" · ");
+}
+function sanitizePreview(preview) {
+    if (!preview)
+        return undefined;
+    let text = preview;
+    // Strip code fences and inline code markers.
+    text = text.replace(/```[\s\S]*?```/g, " ");
+    text = text.replace(/`([^`]+)`/g, "$1");
+    // Convert markdown links and images to their visible text.
+    text = text.replace(/!\[([^\]]*)\]\([^)]+\)/g, "$1");
+    text = text.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1");
+    // Drop bold/italic markers.
+    text = text.replace(/(\*\*|__|\*|_)/g, "");
+    // Remove headings / list markers / blockquotes.
+    text = text.replace(/^\s*#+\s*/gm, "");
+    text = text.replace(/^\s*[-*+]\s+/gm, "");
+    text = text.replace(/^\s*>\s+/gm, "");
+    // Collapse whitespace and trim.
+    text = text.replace(/\s+/g, " ").trim();
+    // Limit length to keep notifications short.
+    const max = 200;
+    if (text.length > max) {
+        text = `${text.slice(0, max - 1)}…`;
+    }
+    return text;
+}
+// Exposed for unit tests only.
+export const testHelpers = { sanitizePreview };
+function inferCost(payload) {
+    const model = payload.model;
+    const usage = payload.usage;
+    if (!model || !usage)
+        return undefined;
+    const config = MODEL_CONFIGS[model];
+    if (!config?.pricing)
+        return undefined;
+    return (estimateUsdCost({
+        usage: { inputTokens: usage.inputTokens, outputTokens: usage.outputTokens },
+        pricing: {
+            inputUsdPerToken: config.pricing.inputPerToken,
+            outputUsdPerToken: config.pricing.outputPerToken,
+        },
+    })?.totalUsd ?? undefined);
+}
+function parseToggle(value) {
+    if (value == null)
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(normalized))
+        return true;
+    if (["0", "false", "no", "off"].includes(normalized))
+        return false;
+    return undefined;
+}
+function bool(value) {
+    return Boolean(value && String(value).length > 0);
+}
+function isMacExecError(error) {
+    return Boolean(process.platform === "darwin" &&
+        error &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === "EACCES");
+}
+function isMacBadCpuError(error) {
+    return Boolean(process.platform === "darwin" &&
+        error &&
+        typeof error === "object" &&
+        "errno" in error &&
+        error.errno === -86);
+}
+async function repairMacNotifier(log) {
+    const binPath = macNotifierPath();
+    if (!binPath)
+        return false;
+    try {
+        await fs.chmod(binPath, 0o755);
+        return true;
+    }
+    catch (chmodError) {
+        const reason = chmodError instanceof Error ? chmodError.message : String(chmodError);
+        log(`(notify repair failed: ${reason} — try: xattr -dr com.apple.quarantine "${path.dirname(binPath)}")`);
+        return false;
+    }
+}
+function macNotifierPath() {
+    if (process.platform !== "darwin")
+        return null;
+    try {
+        const req = createRequire(import.meta.url);
+        const modPath = req.resolve("toasted-notifier");
+        const base = path.dirname(modPath);
+        return path.join(base, "vendor", "mac.noindex", "terminal-notifier.app", "Contents", "MacOS", "terminal-notifier");
+    }
+    catch {
+        return null;
+    }
+}
+async function shouldSkipToastedNotifier() {
+    if (process.platform !== "darwin")
+        return false;
+    // On Apple Silicon without Rosetta, prefer the native helper and skip x86-only fallback.
+    const arch = process.arch;
+    if (arch !== "arm64")
+        return false;
+    return !(await hasRosetta());
+}
+async function hasRosetta() {
+    return new Promise((resolve) => {
+        const child = spawn("pkgutil", ["--files", "com.apple.pkg.RosettaUpdateAuto"], {
+            stdio: "ignore",
+        });
+        child.on("exit", (code) => resolve(code === 0));
+        child.on("error", () => resolve(false));
+    });
+}
+async function sendOsascriptAlert(title, message, _log) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("osascript", [
+            "-e",
+            `display notification "${escapeAppleScript(message)}" with title "${escapeAppleScript(title)}"`,
+        ], {
+            stdio: "ignore",
+        });
+        child.on("exit", (code) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new Error(`osascript exited with code ${code ?? -1}`));
+            }
+        });
+        child.on("error", reject);
+    });
+}
+function escapeAppleScript(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function macAppIconOption() {
+    if (process.platform !== "darwin")
+        return {};
+    const iconPaths = [
+        path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../assets-oracle-icon.png"),
+        path.resolve(process.cwd(), "assets-oracle-icon.png"),
+    ];
+    for (const candidate of iconPaths) {
+        if (candidate && fsExistsSync(candidate)) {
+            return { appIcon: candidate };
+        }
+    }
+    return {};
+}
+function fsExistsSync(target) {
+    try {
+        return Boolean(require("node:fs").statSync(target));
+    }
+    catch {
+        return false;
+    }
+}
+async function tryMacNativeNotifier(title, message, settings) {
+    const binary = macNativeNotifierPath();
+    if (!binary)
+        return false;
+    return new Promise((resolve) => {
+        const child = spawn(binary, [title, message, settings.sound ? "Glass" : ""], {
+            stdio: "ignore",
+        });
+        child.on("error", () => resolve(false));
+        child.on("exit", (code) => resolve(code === 0));
+    });
+}
+function macNativeNotifierPath() {
+    if (process.platform !== "darwin")
+        return null;
+    const candidates = [
+        path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../vendor/oracle-notifier/OracleNotifier.app/Contents/MacOS/OracleNotifier"),
+        path.resolve(process.cwd(), "vendor/oracle-notifier/OracleNotifier.app/Contents/MacOS/OracleNotifier"),
+    ];
+    for (const candidate of candidates) {
+        if (fsExistsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function muteByConfig(env, config) {
+    if (!config?.muteIn)
+        return false;
+    return ((config.muteIn.includes("CI") && bool(env.CI)) ||
+        (config.muteIn.includes("SSH") && bool(env.SSH_CONNECTION)));
+}
+function isTestEnv(env) {
+    return (env.ORACLE_DISABLE_NOTIFICATIONS === "1" ||
+        env.NODE_ENV === "test" ||
+        Boolean(env.VITEST || env.VITEST_WORKER_ID || env.JEST_WORKER_ID));
+}
+function describeNotifierError(error) {
+    if (error && typeof error === "object") {
+        const err = error;
+        if (typeof err.errno === "number" || typeof err.code === "string") {
+            const errno = typeof err.errno === "number" ? err.errno : undefined;
+            // macOS returns errno -86 for “Bad CPU type in executable” (e.g., wrong arch or quarantined binary).
+            if (errno === -86) {
+                return "notifier binary failed to launch (Bad CPU type/quarantine); try xattr -dr com.apple.quarantine vendor/oracle-notifier && ./vendor/oracle-notifier/build-notifier.sh";
+            }
+        }
+        if (typeof err.message === "string") {
+            return err.message;
+        }
+    }
+    return typeof error === "string" ? error : String(error);
+}