@steipete/oracle 0.11.1 → 0.12.0

package/dist/src/cli/docsCheck.js

@@ -0,0 +1,186 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const DEFAULT_DOC_PATHS = [
+    "README.md",
+    "docs/index.md",
+    "docs/agents.md",
+    "docs/sessions.md",
+    "docs/spec.md",
+    "docs/cli-reference.md",
+];
+const FLAG_RE = /(^|[\s`([{|,])(--[a-z][a-z0-9-]*)(?=$|[\s`)[\].,;:|=<>}])/g;
+const SLASH_FLAG_RE = /--[a-z][a-z0-9-]*(?:\/(?:--[a-z][a-z0-9-]*|-[a-z][a-z0-9-]*))+/g;
+const ROOT_ONLY_SECTIONS = new Set(["Core consult flags"]);
+export async function checkDocsFlags({ command, cwd = process.cwd(), paths, }) {
+    const availableFlags = collectCommanderFlags(command);
+    const rootFlags = collectCommanderFlags(command, { recursive: false });
+    const commandFlags = collectCommandFlags(command);
+    const docPaths = await resolveDocPaths(cwd, paths);
+    const issues = [];
+    const checkedFlags = new Set();
+    for (const docPath of docPaths) {
+        const body = await fs.readFile(path.resolve(cwd, docPath), "utf8");
+        for (const reference of extractMarkdownFlagReferences(body)) {
+            const { command: commandPath, flag, section } = reference;
+            checkedFlags.add(flag);
+            const scopedFlags = commandPath
+                ? (commandFlags.get(commandPath) ?? availableFlags)
+                : section && ROOT_ONLY_SECTIONS.has(section)
+                    ? rootFlags
+                    : availableFlags;
+            if (!scopedFlags.has(flag)) {
+                issues.push({ file: docPath, flag, section, command: commandPath });
+            }
+        }
+    }
+    return {
+        checkedFiles: docPaths,
+        checkedFlags: [...checkedFlags].sort(),
+        issues: issues.sort((a, b) => a.file.localeCompare(b.file) || a.flag.localeCompare(b.flag)),
+    };
+}
+export function printDocsCheckResult(result, log = console.log) {
+    if (result.issues.length === 0) {
+        log(`Docs/help check: ok (${result.checkedFlags.length} flags, ${result.checkedFiles.length} files)`);
+        return;
+    }
+    log("Docs/help drift:");
+    for (const issue of result.issues) {
+        const scopes = [issue.section, issue.command].filter(Boolean);
+        const scope = scopes.length > 0 ? ` (${scopes.join(", ")})` : "";
+        log(`- ${issue.file}${scope} mentions ${issue.flag}, but CLI help does not expose ${issue.flag}`);
+    }
+}
+export function collectCommanderFlags(command, options) {
+    const flags = new Set(["--help", "--version"]);
+    for (const option of command.options) {
+        for (const flag of extractOptionFlags(option.flags)) {
+            flags.add(flag);
+        }
+    }
+    if (options?.recursive === false) {
+        return flags;
+    }
+    for (const subcommand of command.commands) {
+        for (const flag of collectCommanderFlags(subcommand)) {
+            flags.add(flag);
+        }
+    }
+    return flags;
+}
+function collectCommandFlags(command, pathParts = ["oracle"]) {
+    const flags = new Map();
+    flags.set(pathParts.join(" "), collectCommanderFlags(command, { recursive: false }));
+    for (const subcommand of command.commands) {
+        for (const [path, subcommandFlags] of collectCommandFlags(subcommand, [
+            ...pathParts,
+            subcommand.name(),
+        ])) {
+            flags.set(path, subcommandFlags);
+        }
+    }
+    return flags;
+}
+export function extractMarkdownFlags(markdown) {
+    return [
+        ...new Set(extractMarkdownFlagReferences(markdown).map((reference) => reference.flag)),
+    ].sort();
+}
+function extractMarkdownFlagReferences(markdown) {
+    const references = [];
+    let section;
+    for (const line of markdown.split(/\r?\n/)) {
+        const heading = line.match(/^##+\s+(.+?)\s*$/);
+        if (heading) {
+            section = heading[1];
+        }
+        const commandPath = extractOracleCommandPath(line);
+        const lineFlags = new Set();
+        for (const match of line.matchAll(FLAG_RE)) {
+            const flag = match[2];
+            if (!flag || flag.endsWith("-")) {
+                continue;
+            }
+            lineFlags.add(flag);
+        }
+        for (const flag of expandSlashFlagReferences(line)) {
+            lineFlags.add(flag);
+        }
+        for (const flag of lineFlags) {
+            references.push({ flag, section, command: commandPath });
+        }
+    }
+    return references.sort((a, b) => a.flag.localeCompare(b.flag) || (a.section ?? "").localeCompare(b.section ?? ""));
+}
+function extractOracleCommandPath(line) {
+    const trimmed = line.trim().replace(/^[$>]\s+/, "");
+    if (!trimmed.startsWith("oracle ") && !trimmed.startsWith("npx ")) {
+        return undefined;
+    }
+    const tokens = trimmed.split(/\s+/);
+    let oracleIndex = tokens[0] === "oracle" ? 0 : -1;
+    if (oracleIndex === -1) {
+        oracleIndex = tokens.findIndex((token) => token === "@steipete/oracle");
+    }
+    if (oracleIndex === -1) {
+        return undefined;
+    }
+    const pathParts = ["oracle"];
+    for (const token of tokens.slice(oracleIndex + 1)) {
+        if (token.startsWith("-") || !/^[a-z][a-z0-9-]*$/.test(token)) {
+            break;
+        }
+        pathParts.push(token);
+    }
+    return pathParts.join(" ");
+}
+function extractOptionFlags(flagsText) {
+    const flags = new Set();
+    for (const match of flagsText.matchAll(/--\[no-\]([a-z][a-z0-9-]*)/g)) {
+        flags.add(`--${match[1]}`);
+        flags.add(`--no-${match[1]}`);
+    }
+    for (const match of flagsText.matchAll(/--[a-z][a-z0-9-]*/g)) {
+        flags.add(match[0]);
+    }
+    return [...flags];
+}
+function expandSlashFlagReferences(line) {
+    const flags = [];
+    for (const match of line.matchAll(SLASH_FLAG_RE)) {
+        const parts = match[0].split("/");
+        const base = parts[0];
+        const basePrefix = base.slice(0, base.lastIndexOf("-") + 1);
+        flags.push(base);
+        for (const part of parts.slice(1)) {
+            if (part.startsWith("--")) {
+                flags.push(part);
+            }
+            else if (part.startsWith("-") && basePrefix) {
+                flags.push(`${basePrefix}${part.slice(1)}`);
+            }
+        }
+    }
+    return flags;
+}
+async function resolveDocPaths(cwd, paths) {
+    const candidates = paths && paths.length > 0 ? paths : DEFAULT_DOC_PATHS;
+    const existing = [];
+    for (const candidate of candidates) {
+        try {
+            const stat = await fs.stat(path.resolve(cwd, candidate));
+            if (stat.isFile()) {
+                existing.push(candidate);
+            }
+        }
+        catch {
+            if (paths && paths.length > 0) {
+                throw new Error(`Docs check path not found: ${candidate}`);
+            }
+        }
+    }
+    if (existing.length === 0) {
+        throw new Error("No docs found to check. Run from the repo root or pass --docs-path <file>.");
+    }
+    return existing;
+}

package/dist/src/cli/engine.js

@@ -12,21 +12,28 @@ export function defaultWaitPreference(model, engine) {
  * Precedence:
  * 1) Legacy --browser flag forces browser.
  * 2) Explicit --engine value.
- * 3) ORACLE_ENGINE environment override (api|browser).
- * 4) OPENAI_API_KEY decides: api when set, otherwise browser.
+ * 3) Explicit API provider routing flags force API.
+ * 4) ORACLE_ENGINE environment override (api|browser).
+ * 5) API environment decides: api when set, otherwise browser.
  */
-export function resolveEngine({ engine, browserFlag, env, }) {
+export function resolveEngine({ engine, browserFlag, apiProviderRequested, env, }) {
     if (browserFlag) {
         return "browser";
     }
     if (engine) {
         return engine;
     }
+    if (apiProviderRequested) {
+        return "api";
+    }
     const envEngine = normalizeEngineMode(env.ORACLE_ENGINE);
     if (envEngine) {
         return envEngine;
     }
-    return env.OPENAI_API_KEY ? "api" : "browser";
+    return hasApiEnvironment(env) ? "api" : "browser";
+}
+function hasApiEnvironment(env) {
+    return Boolean(env.OPENAI_API_KEY || env.OPENROUTER_API_KEY);
 }
 function normalizeEngineMode(raw) {
     if (typeof raw !== "string") {

package/dist/src/cli/options.js

@@ -1,8 +1,8 @@
 import { InvalidArgumentError } from "commander";
-import { parseDuration } from "../browserMode.js";
+import { parseDuration } from "../duration.js";
 import path from "node:path";
 import fg from "fast-glob";
-import { DEFAULT_MODEL, MODEL_CONFIGS } from "../oracle.js";
+import { DEFAULT_MODEL, MODEL_CONFIGS } from "../oracle/config.js";
 export function collectPaths(value, previous = []) {
     if (!value) {
         return previous;
@@ -140,11 +140,17 @@ export function parseTimeoutOption(value) {
     const normalized = value.trim().toLowerCase();
     if (normalized === "auto")
         return "auto";
-    const parsed = Number.parseFloat(normalized);
-    if (Number.isNaN(parsed) || parsed <= 0) {
-        throw new InvalidArgumentError('Timeout must be a positive number of seconds or "auto".');
+    if (/^[0-9]+(?:\.[0-9]+)?$/.test(normalized)) {
+        const parsed = Number.parseFloat(normalized);
+        if (parsed > 0) {
+            return parsed;
+        }
     }
-    return parsed;
+    const parsedMs = parseDuration(normalized, Number.NaN);
+    if (!Number.isFinite(parsedMs) || parsedMs <= 0) {
+        throw new InvalidArgumentError('Timeout must be a positive number of seconds, a duration like "10m", or "auto".');
+    }
+    return parsedMs / 1000;
 }
 export function parseDurationOption(value, label) {
     if (value == null)

package/dist/src/cli/perfTrace.js

@@ -0,0 +1,242 @@
+import { writeFileSync } from "node:fs";
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+const SECRET_VALUE_FLAGS = new Set([
+    "--api-key",
+    "--browser-follow-up",
+    "--browser-inline-cookies",
+    "--browser-inline-cookies-file",
+    "--message",
+    "--prompt",
+    "--remote-token",
+    "--token",
+    "-p",
+]);
+const VALUE_FLAGS = new Set([
+    "--aspect",
+    "--azure-api-version",
+    "--azure-deployment",
+    "--azure-endpoint",
+    "--base-url",
+    "--browser-archive",
+    "--browser-attachments",
+    "--browser-auto-reattach-delay",
+    "--browser-auto-reattach-interval",
+    "--browser-auto-reattach-timeout",
+    "--browser-bundle-format",
+    "--browser-cookie-names",
+    "--browser-cookie-path",
+    "--browser-cookie-wait",
+    "--browser-input-timeout",
+    "--browser-max-concurrent-tabs",
+    "--browser-model-strategy",
+    "--browser-port",
+    "--browser-profile-lock-timeout",
+    "--browser-recheck-delay",
+    "--browser-recheck-timeout",
+    "--browser-research",
+    "--browser-reuse-wait",
+    "--browser-tab",
+    "--browser-timeout",
+    "--browser-url",
+    "--chatgpt-url",
+    "--engine",
+    "--followup",
+    "--followup-model",
+    "--heartbeat",
+    "--http-timeout",
+    "--max-file-size-bytes",
+    "--model",
+    "--models",
+    "--output",
+    "--partial",
+    "--perf-trace-path",
+    "--provider",
+    "--remote-chrome",
+    "--remote-host",
+    "--slug",
+    "--timeout",
+    "--write-output",
+    "--youtube",
+    "--zombie-timeout",
+    "-e",
+    "-m",
+    "-s",
+]);
+export function isTraceValueFlag(flag) {
+    return SECRET_VALUE_FLAGS.has(flag) || VALUE_FLAGS.has(flag);
+}
+class DisabledPerfTrace {
+    mark() { }
+    wrapFirstOutput() { }
+    flush() { }
+}
+class FilePerfTrace {
+    outputPath;
+    options;
+    events = [];
+    wrapped = false;
+    firstOutput = false;
+    flushed = false;
+    constructor(outputPath, options) {
+        this.outputPath = outputPath;
+        this.options = options;
+    }
+    mark(name, data) {
+        this.events.push({
+            name,
+            ms: Number(performance.now().toFixed(3)),
+            data,
+        });
+    }
+    wrapFirstOutput() {
+        if (this.wrapped)
+            return;
+        this.wrapped = true;
+        const wrap = (stream) => {
+            const original = stream.write.bind(stream);
+            stream.write = ((...args) => {
+                if (!this.firstOutput) {
+                    this.firstOutput = true;
+                    this.mark("first-output", {
+                        stream: stream === process.stderr ? "stderr" : "stdout",
+                    });
+                }
+                return original(...args);
+            });
+        };
+        wrap(process.stdout);
+        wrap(process.stderr);
+    }
+    flush(exitCode) {
+        if (this.flushed)
+            return;
+        this.flushed = true;
+        this.mark("exit", { exitCode: exitCode ?? 0 });
+        const payload = {
+            version: this.options.version,
+            argv: sanitizeTraceArgv(this.options.argv),
+            cwd: this.options.cwd ?? process.cwd(),
+            pid: process.pid,
+            node: process.version,
+            timeOrigin: performance.timeOrigin,
+            totalMs: Number(performance.now().toFixed(3)),
+            events: this.events,
+        };
+        writeFileSync(this.outputPath, `${JSON.stringify(payload, null, 2)}\n`);
+    }
+}
+export function createPerfTrace(options) {
+    const envValue = process.env.ORACLE_PERF_TRACE;
+    const optionValue = options.value;
+    if (!optionValue && !envValue) {
+        return new DisabledPerfTrace();
+    }
+    const rawValue = typeof optionValue === "string" ? optionValue : envValue;
+    const outputPath = rawValue && rawValue !== "1" && rawValue !== "true"
+        ? path.resolve(options.cwd ?? process.cwd(), rawValue)
+        : path.join(options.cwd ?? process.cwd(), `.oracle-perf-${new Date().toISOString().replace(/[:.]/g, "-")}-${process.pid}.json`);
+    const trace = new FilePerfTrace(outputPath, options);
+    trace.wrapFirstOutput();
+    trace.mark("cli-module-ready");
+    return trace;
+}
+export function deriveDetachedPerfTraceEnv(value, sessionId) {
+    const trimmed = value?.trim();
+    if (!trimmed || trimmed === "1" || trimmed.toLowerCase() === "true")
+        return value;
+    const safeSessionId = sessionId.replace(/[^A-Za-z0-9._-]/g, "_");
+    const lastSlash = Math.max(trimmed.lastIndexOf("/"), trimmed.lastIndexOf("\\"));
+    const lastDot = trimmed.lastIndexOf(".");
+    if (lastDot > lastSlash) {
+        return `${trimmed.slice(0, lastDot)}.${safeSessionId}${trimmed.slice(lastDot)}`;
+    }
+    return `${trimmed}.${safeSessionId}.json`;
+}
+export function resolveDetachedPerfTraceEnv(cliValue, envValue, sessionId) {
+    if (typeof cliValue === "string") {
+        return deriveDetachedPerfTraceEnv(cliValue, sessionId);
+    }
+    if (cliValue === true) {
+        return "1";
+    }
+    return deriveDetachedPerfTraceEnv(envValue, sessionId);
+}
+export function buildDetachedPerfTraceEnv(env, cliValue, sessionId) {
+    const nextEnv = { ...env };
+    const traceValue = resolveDetachedPerfTraceEnv(cliValue, env.ORACLE_PERF_TRACE, sessionId);
+    if (traceValue) {
+        nextEnv.ORACLE_PERF_TRACE = traceValue;
+    }
+    else {
+        delete nextEnv.ORACLE_PERF_TRACE;
+    }
+    return nextEnv;
+}
+export function sanitizeTraceArgv(argv) {
+    const sanitized = [];
+    let redactNext = false;
+    let valueNext = false;
+    let afterDoubleDash = false;
+    for (const arg of argv) {
+        if (afterDoubleDash) {
+            sanitized.push("[redacted-positional]");
+            continue;
+        }
+        if (arg === "--") {
+            sanitized.push(arg);
+            afterDoubleDash = true;
+            continue;
+        }
+        if (redactNext) {
+            sanitized.push("[redacted]");
+            redactNext = false;
+            continue;
+        }
+        if (valueNext) {
+            sanitized.push(redactPotentialSecret(arg));
+            valueNext = false;
+            continue;
+        }
+        const equalsIndex = arg.indexOf("=");
+        const flag = equalsIndex >= 0 ? arg.slice(0, equalsIndex) : arg;
+        if (equalsIndex >= 0 && SECRET_VALUE_FLAGS.has(flag)) {
+            sanitized.push(`${flag}=[redacted]`);
+            continue;
+        }
+        if (arg.startsWith("-p") && arg.length > 2) {
+            sanitized.push("-p[redacted]");
+            continue;
+        }
+        if (equalsIndex >= 0) {
+            sanitized.push(`${flag}=${redactPotentialSecret(arg.slice(equalsIndex + 1))}`);
+            continue;
+        }
+        if (SECRET_VALUE_FLAGS.has(arg)) {
+            sanitized.push(arg);
+            redactNext = true;
+            continue;
+        }
+        if (VALUE_FLAGS.has(arg)) {
+            sanitized.push(arg);
+            valueNext = true;
+            continue;
+        }
+        if (!arg.startsWith("-")) {
+            sanitized.push("[redacted-positional]");
+            continue;
+        }
+        sanitized.push(arg);
+    }
+    return sanitized;
+}
+function redactPotentialSecret(value) {
+    return value
+        .replace(/\bBearer\s+[A-Za-z0-9._\-+/=]+/gi, "Bearer [redacted]")
+        .replace(/:\/\/([^:/?#\s]+):([^@/?#\s]+)@/g, "://$1:[redacted]@")
+        .replace(/([?&](?:access_)?token=)[^&#\s]+/gi, "$1[redacted]")
+        .replace(/([?&](?:api[-_]?key|auth|authorization|password|secret)=)[^&#\s]+/gi, "$1[redacted]")
+        .replace(/\bsk-(?:ant-|or-)?[A-Za-z0-9_-]{8,}\b/g, "sk-...[redacted]")
+        .replace(/\bxai-[A-Za-z0-9_-]{8,}\b/g, "xai-...[redacted]")
+        .replace(/\bAIza[0-9A-Za-z_-]{8,}\b/g, "AIza...[redacted]");
+}

package/dist/src/cli/promptRequirement.js

@@ -10,6 +10,8 @@ export function shouldRequirePrompt(rawArgs, options) {
         options.execSession ||
         options.status ||
         options.debugHelp ||
+        options.route ||
+        options.preflight ||
         firstArg === "status" ||
         firstArg === "session");
     const requiresPrompt = options.renderMarkdown || Boolean(options.preview) || Boolean(options.dryRun) || !bypassPrompt;

package/dist/src/cli/providerDoctor.js

@@ -0,0 +1,85 @@
+import chalk from "chalk";
+import { DEFAULT_MODEL } from "../oracle/config.js";
+import { resolveApiModel } from "./options.js";
+import { loadUserConfig } from "../config.js";
+import { buildProviderRoutePlan } from "../oracle/providerRoutePlan.js";
+export async function runProviderDoctor(options) {
+    if (!options.providers) {
+        console.log("Run `oracle doctor --providers` to inspect API provider readiness.");
+        return;
+    }
+    const { config: userConfig } = await loadUserConfig();
+    const providerMode = resolveProviderMode(options);
+    const azure = resolveAzureOptions(options, userConfig);
+    const models = resolveModels(options, userConfig);
+    const plans = models.map((model) => buildProviderRoutePlan({
+        model,
+        providerMode,
+        azure,
+        baseUrl: options.baseUrl ?? userConfig.apiBaseUrl,
+        env: process.env,
+    }));
+    if (options.json) {
+        console.log(JSON.stringify({ providers: plans }, null, 2));
+        process.exitCode = plans.some((plan) => !plan.ok) ? 1 : 0;
+        return;
+    }
+    printProviderPlans(plans);
+    process.exitCode = plans.some((plan) => !plan.ok) ? 1 : 0;
+}
+export function printProviderPlans(plans, { title = "Provider readiness" } = {}) {
+    console.log(chalk.bold(title));
+    console.log("");
+    for (const plan of plans) {
+        const status = plan.ok ? chalk.green("ok") : chalk.red("not ready");
+        console.log(`${plan.model}: ${status}`);
+        console.log(chalk.dim(`  provider: ${plan.providerLabel}`));
+        console.log(chalk.dim(`  base: ${plan.base || "(none)"}`));
+        console.log(chalk.dim(`  key: ${plan.keyPreview}`));
+        if (plan.isAzureOpenAI || plan.azureDeploymentName) {
+            console.log(chalk.dim(`  azure deployment: ${plan.azureDeploymentName ?? "none"}`));
+        }
+        if (plan.azureNote) {
+            console.log(chalk.dim(`  azure: ${plan.azureNote}`));
+        }
+        if (plan.error) {
+            console.log(chalk.dim(`  error: ${plan.error}`));
+        }
+        console.log("");
+    }
+}
+function resolveModels(options, userConfig) {
+    const entries = Array.isArray(options.models) && options.models.length > 0
+        ? options.models
+        : typeof options.models === "string" && options.models.trim().length > 0
+            ? options.models
+                .split(",")
+                .map((entry) => entry.trim())
+                .filter(Boolean)
+            : [options.model ?? userConfig.model ?? DEFAULT_MODEL];
+    return Array.from(new Set(entries.map((entry) => resolveApiModel(entry))));
+}
+function resolveProviderMode(options) {
+    const provider = options.provider ?? "auto";
+    if (provider === "azure" && options.azure === false) {
+        throw new Error("--provider azure cannot be combined with --no-azure.");
+    }
+    if (options.azure === false) {
+        return "openai";
+    }
+    return provider;
+}
+function resolveAzureOptions(options, userConfig) {
+    const endpoint = firstNonEmpty(options.azureEndpoint, process.env.AZURE_OPENAI_ENDPOINT, userConfig.azure?.endpoint);
+    if (!endpoint) {
+        return undefined;
+    }
+    return {
+        endpoint,
+        deployment: firstNonEmpty(options.azureDeployment, process.env.AZURE_OPENAI_DEPLOYMENT, userConfig.azure?.deployment),
+        apiVersion: firstNonEmpty(options.azureApiVersion, process.env.AZURE_OPENAI_API_VERSION, userConfig.azure?.apiVersion),
+    };
+}
+function firstNonEmpty(...values) {
+    return values.find((value) => value?.trim());
+}