scoutline 0.1.0 → 0.2.0

package/dist/index.js

@@ -6,34 +6,50 @@ import { search, SEARCH_HELP } from "./commands/search.js";
 import { read, READ_HELP } from "./commands/read.js";
 import { repoSearch, repoTree, repoRead, REPO_HELP } from "./commands/repo.js";
 import { listTools, showTool, callTool, TOOLS_HELP, CALL_HELP } from "./commands/tools.js";
-import { doctor, DOCTOR_HELP } from "./commands/doctor.js";
-import { quota, QUOTA_HELP } from "./commands/quota.js";
+import { doctor, buildDiagnosticsReport, DOCTOR_HELP } from "./commands/doctor.js";
+import { quota, buildQuotaDashboard, QUOTA_HELP } from "./commands/quota.js";
 import { isExtractMode } from "./lib/extract.js";
 import { runCodeFile, evalCode, printInterfaces, printPromptTemplate, CODE_HELP, } from "./commands/code.js";
-import { outputError, setOutputMode } from "./lib/output.js";
+import { isOutputMode, OUTPUT_MODES } from "./lib/output.js";
+import { formatErrorOutput } from "./lib/output.js";
+import { ConfigurationError, ValidationError, UnsupportedCapabilityError, getErrorExitCode, } from "./lib/errors.js";
+import { invokeCommand } from "./command-invocation.js";
+import { defaultResponseCache } from "./lib/cache.js";
+import { configuredSecrets } from "./lib/redact.js";
+import { resolveProviderId } from "./providers/selection.js";
+import { BUILT_IN_PROVIDER_DESCRIPTORS, getProviderDescriptor } from "./providers/registry.js";
+import { visionOperationToCapability } from "./capabilities/vision.js";
 import { createRequire } from "node:module";
 const require = createRequire(import.meta.url);
 const { version: VERSION } = require("../package.json");
 const MAIN_HELP = `
-scoutline v${VERSION} - CLI for Z.AI MCP services
+scoutline v${VERSION} - Multimodal source investigation CLI
 
 Usage: scoutline <command> [args] [options]
 
 Commands:
-  vision   Image and video analysis (MCP)
-  search   Real-time web search
-  read     Fetch and parse web pages
-  repo     GitHub repository exploration
-  quota    Authoritative Z.AI plan usage (calls remaining, reset time)
-  tools    List available MCP tools
-  tool     Show a tool schema
-  call     Call a tool directly
-  doctor   Environment + connectivity checks
-  code     Execute TypeScript tool chains (Code Mode)
+  vision   Image and video analysis (Z.AI; MiniMax for interpret-image)
+  search   Real-time web search (shared: Z.AI + MiniMax)
+  read     Fetch and parse web pages (Z.AI only)
+  repo     GitHub repository exploration (Z.AI only)
+  quota    Provider-aware plan usage (calls remaining, reset time)
+  tools    List available MCP tools (Z.AI)
+  tool     Show a tool schema (Z.AI)
+  call     Call a tool directly (Z.AI)
+  doctor   Provider-aware environment + connectivity checks
+  code     Execute TypeScript tool chains (Code Mode, Z.AI)
+
+Provider selection (precedence: --provider, then SCOUTLINE_PROVIDER, then zai):
+  --provider <zai|minimax>   Select the active Provider for shared capabilities
+  SCOUTLINE_PROVIDER=<id>    Fallback when --provider is not passed
+
+Shared capabilities accept --provider. Z.AI-only commands (read, repo,
+tools, tool, call, code) carry the flag but ignore it. Quota and doctor
+report per-Provider; --provider picks the effective Provider for metadata.
 
 Global Options:
-  --output-format <data|json|pretty|compact|markdown|refs>  Output mode (default: data)
-  -O <mode>                                                  Alias for --output-format
+  --output-format <data|json|pretty|compact|markdown|refs|tty>  Output mode (default: data)
+  -O <mode>                                                     Alias for --output-format
 
 Help:
   scoutline --help
@@ -93,6 +109,7 @@ function extractGlobalOptions(args) {
     let outputFormat;
     let forcePretty = false;
     let forceRaw = false;
+    let provider;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === "--output-format" || arg === "-O") {
@@ -108,90 +125,208 @@ function extractGlobalOptions(args) {
             forceRaw = true;
             continue;
         }
+        if (arg === "--provider") {
+            // Global option: accepted before OR after the command token. It is
+            // removed from the rest stream so command-local positional parsing
+            // never observes it. Only shared Search resolves/validates it; the
+            // Z.AI-only command families carry it but never consult it.
+            provider = args[i + 1];
+            i += 1;
+            continue;
+        }
         rest.push(arg);
     }
-    return { outputFormat, forcePretty, forceRaw, rest };
+    return { outputFormat, forcePretty, forceRaw, provider, rest };
 }
-function applyOutputMode(mode) {
-    const valid = ["data", "json", "pretty", "compact", "markdown", "refs", "tty"];
-    if (!mode)
-        return;
-    if (valid.includes(mode)) {
-        setOutputMode(mode);
-        return;
-    }
-    outputError(`Invalid output format: ${mode}`, "INVALID_ARGS", `Use one of: ${valid.join(", ")}`);
+function resolveOutputMode(explicit, forcePretty, forceRaw, adapter) {
+    if (explicit !== undefined) {
+        if (!isOutputMode(explicit)) {
+            throw new ValidationError(`Invalid output format: ${explicit}`, `Use one of: ${OUTPUT_MODES.join(", ")}`);
+        }
+        return explicit;
+    }
+    if (forcePretty)
+        return "tty";
+    if (forceRaw)
+        return "data";
+    const envMode = adapter.environmentOutputMode;
+    if (typeof envMode === "string" && isOutputMode(envMode)) {
+        return envMode;
+    }
+    if (adapter.stdoutIsTTY)
+        return "tty";
+    return "data";
 }
-async function handleVision(args) {
+async function handleVision(args, outputMode, deps) {
     const { flags, positional } = parseArgs(args);
     if (flags.help || flags.h || positional.length === 0) {
-        console.log(vision.VISION_HELP);
-        return;
+        deps.invocation.writeStdout(vision.VISION_HELP);
+        return 0;
     }
     const command = positional[0];
     const source = positional[1];
     const prompt = positional[2];
+    // Map the subcommand to its Vision operation. Unknown subcommands are
+    // a parse-time VALIDATION_ERROR and are rejected before any Provider
+    // resolution, support check, or media access.
+    const operation = visionOperationForCommand(command);
+    // Resolve the effective Provider for Vision (DESIGN.md §6). Invalid
+    // explicit/env input fails here with VALIDATION_ERROR before any Vision
+    // support check or media access. Selection never consults credentials
+    // (FR-003); the configured check below is the caller's responsibility.
+    const providerId = resolveProviderId(deps.provider, deps.env);
+    const descriptor = getProviderDescriptor(providerId, deps.providerDescriptors);
+    // Gate the operation on descriptor metadata BEFORE Adapter construction.
+    // An unsupported operation (e.g. MiniMax for any specialized op, diff, or
+    // video) fails with UNSUPPORTED_CAPABILITY before credentials, media,
+    // transport, cache, or any Z.AI fallback (FR-023, FR-024). No command
+    // branches on a Provider ID: the support check alone decides availability.
+    const capabilityId = visionOperationToCapability(operation);
+    if (!descriptor.capabilities().has(capabilityId)) {
+        throw new UnsupportedCapabilityError(providerId, capabilityId);
+    }
+    // FR-003: selection returns the default zai even when unconfigured. The
+    // dispatch layer surfaces a missing credential as ConfigurationError
+    // (exit 3), AFTER the capability support check (FR-023) but before any
+    // Adapter construction or media access (Fixup A — B5).
+    if (!descriptor.isConfigured(deps.env)) {
+        throw new ConfigurationError(`Provider "${providerId}" is not configured. Set the required API key.`);
+    }
+    const adapter = descriptor.create({ env: deps.env });
+    const visionCapability = adapter.vision;
+    if (!visionCapability || !visionCapability.supports(operation)) {
+        throw new UnsupportedCapabilityError(providerId, capabilityId);
+    }
+    // Vision bypasses the response cache (FR-022). The shared execution
+    // primitives (sleep/random) are the same ones Search consumes; they
+    // drive retry backoff deterministically under test.
+    const visionDeps = {
+        capability: visionCapability,
+        sleep: deps.searchSleep,
+        random: deps.searchRandom,
+    };
     switch (command) {
         case "analyze":
-            if (!source) {
-                outputError("Missing image source", "INVALID_ARGS", "Usage: scoutline vision analyze <image> [prompt]");
-            }
-            await vision.analyze(source, prompt);
-            break;
-        case "ui-to-code":
-            if (!source) {
-                outputError("Missing image source", "INVALID_ARGS", "Usage: scoutline vision ui-to-code <image> [prompt]");
-            }
+            return invokeCommand(deps.invocation, (context) => vision.analyze(source, prompt, visionDeps, context), outputMode, deps.now, deps.secrets);
+        case "ui-to-code": {
             const outputType = flags.output || "code";
-            await vision.uiToCode(source, prompt, outputType);
-            break;
+            return invokeCommand(deps.invocation, (context) => vision.uiToCode(source, prompt, outputType, visionDeps, context), outputMode, deps.now, deps.secrets);
+        }
         case "extract-text":
-            if (!source) {
-                outputError("Missing image source", "INVALID_ARGS", "Usage: scoutline vision extract-text <image> [prompt] [--language <lang>]");
-            }
-            await vision.extractText(source, prompt, flags.language);
-            break;
+            return invokeCommand(deps.invocation, (context) => vision.extractText(source, prompt, flags.language, visionDeps, context), outputMode, deps.now, deps.secrets);
         case "diagnose-error":
-            if (!source) {
-                outputError("Missing image source", "INVALID_ARGS", "Usage: scoutline vision diagnose-error <image> [prompt] [--context <ctx>]");
-            }
-            await vision.diagnoseError(source, prompt, flags.context);
-            break;
+            return invokeCommand(deps.invocation, (context) => vision.diagnoseError(source, prompt, flags.context, visionDeps, context), outputMode, deps.now, deps.secrets);
         case "diagram":
-            if (!source) {
-                outputError("Missing image source", "INVALID_ARGS", "Usage: scoutline vision diagram <image> [prompt] [--type <type>]");
-            }
-            await vision.diagram(source, prompt, flags.type);
-            break;
+            return invokeCommand(deps.invocation, (context) => vision.diagram(source, prompt, flags.type, visionDeps, context), outputMode, deps.now, deps.secrets);
         case "chart":
-            if (!source) {
-                outputError("Missing image source", "INVALID_ARGS", "Usage: scoutline vision chart <image> [prompt] [--focus <focus>]");
-            }
-            await vision.chart(source, prompt, flags.focus);
-            break;
-        case "diff":
+            return invokeCommand(deps.invocation, (context) => vision.chart(source, prompt, flags.focus, visionDeps, context), outputMode, deps.now, deps.secrets);
+        case "diff": {
             const actual = positional[2];
             const diffPrompt = positional[3];
-            if (!source || !actual) {
-                outputError("Missing image sources", "INVALID_ARGS", "Usage: scoutline vision diff <expected> <actual> [prompt]");
-            }
-            await vision.diff(source, actual, diffPrompt);
-            break;
+            return invokeCommand(deps.invocation, (context) => vision.diff(source, actual, diffPrompt, visionDeps, context), outputMode, deps.now, deps.secrets);
+        }
         case "video":
-            if (!source) {
-                outputError("Missing video source", "INVALID_ARGS", "Usage: scoutline vision video <video> [prompt]");
-            }
-            await vision.video(source, prompt);
-            break;
+            return invokeCommand(deps.invocation, (context) => vision.video(source, prompt, visionDeps, context), outputMode, deps.now, deps.secrets);
+        default:
+            throw new ValidationError(`Unknown vision command: ${command}`, 'Run "scoutline vision --help" for available commands');
+    }
+}
+/**
+ * Map a Vision subcommand to its discriminated operation id. Used by
+ * `handleVision` to gate the operation against descriptor metadata before
+ * Adapter construction. Unknown subcommands throw `ValidationError`.
+ */
+function visionOperationForCommand(command) {
+    switch (command) {
+        case "analyze":
+            return "interpret-image";
+        case "ui-to-code":
+            return "ui-artifact";
+        case "extract-text":
+            return "extract-text";
+        case "diagnose-error":
+            return "diagnose-error";
+        case "diagram":
+            return "diagram";
+        case "chart":
+            return "chart";
+        case "diff":
+            return "diff";
+        case "video":
+            return "video";
         default:
-            outputError(`Unknown vision command: ${command}`, "INVALID_ARGS", 'Run "scoutline vision --help" for available commands');
+            throw new ValidationError(`Unknown vision command: ${command}`, 'Run "scoutline vision --help" for available commands');
+    }
+}
+/**
+ * Parse and validate the `--count` flag value (Fixup C — B11, Fixup D). Per
+ * DESIGN.md §7, count must be a safe integer >= 0. Invalid values (NaN,
+ * negative, non-integer, Infinity, values above Number.MAX_SAFE_INTEGER)
+ * throw `ValidationError` BEFORE any Provider resolution or invocation.
+ *
+ * Fixup D hardens two gaps:
+ *   - `--count` without a value parses to `true`; that is a user error,
+ *     not an absent flag, and now throws VALIDATION_ERROR instead of being
+ *     silently treated as absent.
+ *   - Uses `Number.isSafeInteger` instead of `Number.isFinite` +
+ *     `Number.isInteger` so values above 2^53-1 are rejected rather than
+ *     silently rounded.
+ *
+ * Exported for testing so the validation can be exercised without going
+ * through the CLI parser (which does not deliver negative numbers as flag
+ * values today).
+ */
+export function parseAndValidateCount(raw) {
+    if (raw === undefined || raw === "")
+        return undefined;
+    if (raw === true) {
+        throw new ValidationError("Count requires a numeric value.", "Use a non-negative integer (e.g. --count 5).");
+    }
+    const str = typeof raw === "string" ? raw : String(raw);
+    if (!/^\d+$/.test(str)) {
+        throw new ValidationError(`Invalid --count value "${str}": must be a non-negative integer`, "Use a non-negative integer (e.g. --count 5).");
     }
+    const parsed = Number(str);
+    if (!Number.isSafeInteger(parsed) || parsed < 0) {
+        throw new ValidationError(`Invalid --count value "${str}": must be a non-negative safe integer`, "Use a non-negative integer (e.g. --count 5).");
+    }
+    return parsed;
 }
-async function handleSearch(args) {
+async function handleSearch(args, outputMode, deps) {
     const { flags, positional } = parseArgs(args);
     if (flags.help || flags.h || positional.length === 0) {
-        console.log(SEARCH_HELP);
-        return;
+        deps.invocation.writeStdout(SEARCH_HELP);
+        return 0;
+    }
+    // Fixup D — B11: validate --count BEFORE Provider resolution and the
+    // configured/credential check. A syntax error in a CLI argument must
+    // not depend on whether credentials are present: `search q --count nope`
+    // with NO credentials must surface VALIDATION_ERROR (exit 1), not
+    // CONFIGURATION_ERROR (exit 3). Order: parse global options -> validate
+    // count -> resolve provider -> check configured -> dispatch.
+    const count = parseAndValidateCount(flags.count);
+    // Resolve the Provider ONLY inside shared Search (DESIGN.md §6). Other
+    // command families carry the parsed flag but never resolve or validate
+    // it. An invalid explicit/env value throws VALIDATION_ERROR here, before
+    // any Adapter construction or invocation. Selection never consults
+    // credentials (FR-003); the configured check below is the caller's
+    // responsibility (Fixup A — B5).
+    const providerId = resolveProviderId(deps.provider, deps.env);
+    const descriptor = getProviderDescriptor(providerId, deps.providerDescriptors);
+    if (!descriptor.capabilities().has("search")) {
+        throw new UnsupportedCapabilityError(providerId, "search");
+    }
+    // FR-003: selection returns the default zai even when unconfigured. The
+    // dispatch layer surfaces a missing credential as ConfigurationError
+    // (exit 3), AFTER the capability support check (FR-023) but before any
+    // Adapter construction (Fixup A — B5).
+    if (!descriptor.isConfigured(deps.env)) {
+        throw new ConfigurationError(`Provider "${providerId}" is not configured. Set the required API key.`);
+    }
+    const adapter = descriptor.create({ env: deps.env });
+    const capability = adapter.search;
+    if (!capability) {
+        throw new UnsupportedCapabilityError(providerId, "search");
     }
     const query = positional.join(" ");
     const fieldsRaw = flags.fields;
@@ -201,26 +336,33 @@ async function handleSearch(args) {
             .map((f) => f.trim())
             .filter(Boolean)
         : undefined;
-    await search(query, {
-        count: flags.count ? parseInt(flags.count, 10) : undefined,
+    return invokeCommand(deps.invocation, (context) => search(query, {
+        count,
         domain: flags.domain,
         recency: flags.recency,
         contentSize: flags["content-size"],
         location: flags.location,
-        maxSummary: flags["max-summary"] ? parseInt(flags["max-summary"], 10) : undefined,
+        maxSummary: flags["max-summary"]
+            ? parseInt(flags["max-summary"], 10)
+            : undefined,
         fields: fields && fields.length > 0 ? fields : undefined,
         noCache: flags["no-cache"] === true,
         merge: flags.merge === true,
-    });
+    }, {
+        capability,
+        cache: deps.searchCache,
+        sleep: deps.searchSleep,
+        random: deps.searchRandom,
+    }, context), outputMode, deps.now, deps.secrets);
 }
-async function handleRead(args) {
+async function handleRead(args, outputMode, deps) {
     const { flags, positional } = parseArgs(args);
     if (flags.help || flags.h || positional.length === 0) {
-        console.log(READ_HELP);
-        return;
+        deps.invocation.writeStdout(READ_HELP);
+        return 0;
     }
     const url = positional[0];
-    await read(url, {
+    return invokeCommand(deps.invocation, (context) => read(url, {
         format: flags.format,
         noImages: flags["no-images"] === true,
         noCache: flags["no-cache"] === true,
@@ -231,112 +373,142 @@ async function handleRead(args) {
         withImagesSummary: flags["with-images-summary"] === true,
         maxChars: flags["max-chars"] ? parseInt(flags["max-chars"], 10) : undefined,
         fullEnvelope: flags["full-envelope"] === true,
-        extract: isExtractMode(flags.extract) ? flags.extract : undefined,
-    });
+        extract: isExtractMode(flags.extract)
+            ? flags.extract
+            : undefined,
+    }, outputMode, context), outputMode, deps.now, deps.secrets);
 }
-async function handleRepo(args) {
+async function handleRepo(args, outputMode, deps) {
     const { flags, positional } = parseArgs(args);
     if (flags.help || flags.h || positional.length === 0) {
-        console.log(REPO_HELP);
-        return;
+        deps.invocation.writeStdout(REPO_HELP);
+        return 0;
     }
     const command = positional[0];
     const repo = positional[1];
     switch (command) {
-        case "search":
+        case "search": {
             const query = positional.slice(2).join(" ");
             if (!repo || !query) {
-                outputError("Missing repo or query", "INVALID_ARGS", "Usage: scoutline repo search <owner/repo> <query>");
+                throw new ValidationError("Missing repo or query", "Usage: scoutline repo search <owner/repo> <query>");
             }
-            await repoSearch(repo, query, {
+            return invokeCommand(deps.invocation, (context) => repoSearch(repo, query, {
                 language: flags.language,
                 maxChars: flags["max-chars"] ? parseInt(flags["max-chars"], 10) : undefined,
                 noCache: flags["no-cache"] === true,
-            });
-            break;
-        case "tree":
+            }, context), outputMode, deps.now, deps.secrets);
+        }
+        case "tree": {
             if (!repo) {
-                outputError("Missing repo", "INVALID_ARGS", "Usage: scoutline repo tree <owner/repo>");
+                throw new ValidationError("Missing repo", "Usage: scoutline repo tree <owner/repo>");
             }
-            await repoTree(repo, {
+            return invokeCommand(deps.invocation, (context) => repoTree(repo, {
                 path: flags.path,
                 depth: flags.depth ? parseInt(flags.depth, 10) : undefined,
                 noCache: flags["no-cache"] === true,
-            });
-            break;
-        case "read":
+            }, context), outputMode, deps.now, deps.secrets);
+        }
+        case "read": {
             const path = positional[2];
             if (!repo || !path) {
-                outputError("Missing repo or path", "INVALID_ARGS", "Usage: scoutline repo read <owner/repo> <path>");
+                throw new ValidationError("Missing repo or path", "Usage: scoutline repo read <owner/repo> <path>");
             }
-            await repoRead(repo, path, {
+            return invokeCommand(deps.invocation, (context) => repoRead(repo, path, {
                 maxChars: flags["max-chars"] ? parseInt(flags["max-chars"], 10) : undefined,
                 noCache: flags["no-cache"] === true,
-            });
-            break;
+            }, context), outputMode, deps.now, deps.secrets);
+        }
         default:
-            outputError(`Unknown repo command: ${command}`, "INVALID_ARGS", 'Run "scoutline repo --help" for available commands');
+            throw new ValidationError(`Unknown repo command: ${command}`, 'Run "scoutline repo --help" for available commands');
     }
 }
-async function handleTools(args) {
+async function handleTools(args, outputMode, deps) {
     const { flags } = parseArgs(args);
     if (flags.help || flags.h) {
-        console.log(TOOLS_HELP);
-        return;
+        deps.invocation.writeStdout(TOOLS_HELP);
+        return 0;
     }
-    await listTools({
+    return invokeCommand(deps.invocation, (context) => listTools({
         filter: flags.filter,
         full: flags.full === true,
         typescript: flags.typescript === true || flags.ts === true,
         enableVision: flags.vision !== false,
-    });
+    }, context), outputMode, deps.now, deps.secrets);
 }
-async function handleTool(args) {
+async function handleTool(args, outputMode, deps) {
     const { flags, positional } = parseArgs(args);
     if (flags.help || flags.h || positional.length === 0) {
-        console.log(TOOLS_HELP);
-        return;
+        deps.invocation.writeStdout(TOOLS_HELP);
+        return 0;
     }
-    await showTool(positional[0], { enableVision: flags.vision !== false });
+    return invokeCommand(deps.invocation, (context) => showTool(positional[0], { enableVision: flags.vision !== false }, context), outputMode, deps.now, deps.secrets);
 }
-async function handleCall(args) {
+async function handleCall(args, outputMode, deps) {
     const { flags, positional } = parseArgs(args);
     if (flags.help || flags.h || positional.length === 0) {
-        console.log(CALL_HELP);
-        return;
+        deps.invocation.writeStdout(CALL_HELP);
+        return 0;
     }
-    await callTool(positional[0], {
+    return invokeCommand(deps.invocation, (context) => callTool(positional[0], {
         json: flags.json,
         file: flags.file,
         stdin: flags.stdin === true,
         dryRun: flags["dry-run"] === true,
         enableVision: flags.vision !== false,
-    });
+    }, context), outputMode, deps.now, deps.secrets);
 }
-async function handleDoctor(args) {
+async function handleDoctor(args, outputMode, deps) {
     const { flags } = parseArgs(args);
     if (flags.help || flags.h) {
-        console.log(DOCTOR_HELP);
-        return;
+        deps.invocation.writeStdout(DOCTOR_HELP);
+        return 0;
     }
-    await doctor({
-        noTools: flags["no-tools"] === true,
-        enableVision: flags.vision !== false,
-    });
+    const noTools = flags["no-tools"] === true;
+    // Resolve the effective Provider ID for report metadata, mirroring
+    // Search/Vision/quota. Descriptors are intentionally NOT passed here so
+    // the report always lists every built-in Provider even when the
+    // effective Provider is unconfigured.
+    const effectiveProvider = resolveProviderId(deps.provider, deps.env);
+    return invokeCommand(deps.invocation, () => doctor({
+        buildReport: () => buildDiagnosticsReport({
+            noTools,
+            effectiveProvider,
+            descriptors: deps.providerDescriptors,
+            env: deps.env,
+            sleep: deps.searchSleep,
+            random: deps.searchRandom,
+        }),
+    }), outputMode, deps.now, deps.secrets);
 }
-async function handleQuota(args) {
+async function handleQuota(args, outputMode, deps) {
     const { flags } = parseArgs(args);
     if (flags.help || flags.h) {
-        console.log(QUOTA_HELP);
-        return;
+        deps.invocation.writeStdout(QUOTA_HELP);
+        return 0;
     }
-    await quota({});
+    const allProviders = flags["all-providers"] === true;
+    // Resolve the effective Provider ID for dashboard metadata. Config
+    // validation is owned by the dashboard builder (ConfigurationError,
+    // exit 3) so an unconfigured default is reported as configuration, not
+    // a registry error. Descriptors are intentionally NOT passed here so
+    // all-provider mode is not blocked by an unconfigured effective.
+    const effectiveProvider = resolveProviderId(deps.provider, deps.env);
+    return invokeCommand(deps.invocation, () => quota({
+        buildDashboard: () => buildQuotaDashboard({
+            allProviders,
+            effectiveProvider,
+            descriptors: deps.providerDescriptors,
+            env: deps.env,
+            sleep: deps.searchSleep,
+            random: deps.searchRandom,
+        }),
+    }), outputMode, deps.now, deps.secrets);
 }
-async function handleCode(args) {
+async function handleCode(args, outputMode, deps) {
     const { flags, positional } = parseArgs(args);
     if (flags.help || flags.h || positional.length === 0) {
-        console.log(CODE_HELP);
-        return;
+        deps.invocation.writeStdout(CODE_HELP);
+        return 0;
     }
     const command = positional[0];
     const timeout = flags.timeout ? parseInt(flags.timeout, 10) : undefined;
@@ -345,99 +517,109 @@ async function handleCode(args) {
         case "run": {
             const filePath = positional[1];
             if (!filePath) {
-                outputError("Missing code file", "INVALID_ARGS", "Usage: scoutline code run <file>");
+                throw new ValidationError("Missing code file", "Usage: scoutline code run <file>");
             }
-            await runCodeFile(filePath, { timeout, includeLogs });
-            break;
+            return invokeCommand(deps.invocation, (context) => runCodeFile(filePath, { timeout, includeLogs }, context), outputMode, deps.now, deps.secrets);
         }
         case "eval": {
             const code = positional.slice(1).join(" ");
             if (!code) {
-                outputError("Missing code string", "INVALID_ARGS", "Usage: scoutline code eval <code>");
+                throw new ValidationError("Missing code string", "Usage: scoutline code eval <code>");
             }
-            await evalCode(code, { timeout, includeLogs });
-            break;
+            return invokeCommand(deps.invocation, (context) => evalCode(code, { timeout, includeLogs }, context), outputMode, deps.now, deps.secrets);
         }
         case "interfaces":
-            await printInterfaces();
-            break;
+            return invokeCommand(deps.invocation, (context) => printInterfaces(context), outputMode, deps.now, deps.secrets);
         case "prompt":
-            printPromptTemplate();
-            break;
+            return invokeCommand(deps.invocation, async (context) => printPromptTemplate(context), outputMode, deps.now, deps.secrets);
         default:
-            outputError(`Unknown code command: ${command}`, "INVALID_ARGS", 'Run "scoutline code --help" for available commands');
+            throw new ValidationError(`Unknown code command: ${command}`, 'Run "scoutline code --help" for available commands');
     }
 }
-export async function main(args) {
-    const cleanArgs = args[0]?.includes("node") || args[0]?.includes("scoutline") ? args.slice(2) : args;
-    const { outputFormat, forcePretty, forceRaw, rest } = extractGlobalOptions(cleanArgs);
-    // Resolve effective mode: explicit -O wins; else --pretty-output / --raw;
-    // else auto: "tty" when stdout is a TTY, "data" when piped.
-    if (outputFormat) {
-        applyOutputMode(outputFormat);
-    }
-    else if (forcePretty) {
-        setOutputMode("tty");
-    }
-    else if (forceRaw) {
-        setOutputMode("data");
-    }
-    else if (process.stdout.isTTY) {
-        setOutputMode("tty");
-    } // else: default "data" mode (set at module load in output.ts)
+const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export async function main(args, dependencies) {
+    const { invocation, env, now } = dependencies;
+    const providerDescriptors = dependencies.providerDescriptors ?? BUILT_IN_PROVIDER_DESCRIPTORS;
+    const searchCache = dependencies.searchCache ?? defaultResponseCache;
+    const searchSleep = dependencies.searchSleep ?? realSleep;
+    const searchRandom = dependencies.searchRandom ?? Math.random;
+    // Resolve configured Provider credentials from the INJECTED env (B3) so
+    // redaction follows the same environment the handlers see — a secret
+    // that exists only in MainDependencies.env is still redacted from output.
+    const secrets = configuredSecrets(env);
+    const { outputFormat, forcePretty, forceRaw, provider, rest } = extractGlobalOptions([...args]);
+    // Fixup C — B10: resolve the output mode BEFORE the dispatch try/catch.
+    // An invalid explicit mode still surfaces as a typed ValidationError,
+    // but the surface formatter uses the user's REQUESTED mode (or the
+    // best deterministic fallback) so the envelope matches what the user
+    // asked for. Pre-invocation validation errors (provider resolution,
+    // missing credentials, count parsing, etc.) MUST honour the requested
+    // output mode the same way handler errors do.
+    let outputMode;
+    try {
+        outputMode = resolveOutputMode(outputFormat, forcePretty ?? false, forceRaw ?? false, invocation);
+    }
+    catch (error) {
+        // The explicit mode is invalid — fall back to a deterministic
+        // compact form so we can still surface a structured error envelope.
+        invocation.writeStderr(formatErrorOutput(error, "data", secrets));
+        return getErrorExitCode(error);
+    }
     if (rest.length === 0 || rest[0] === "--help" || rest[0] === "-h") {
-        console.log(MAIN_HELP);
-        return;
+        invocation.writeStdout(MAIN_HELP);
+        return 0;
     }
     if (rest[0] === "--version" || rest[0] === "-v") {
-        console.log(VERSION);
-        return;
+        invocation.writeStdout(VERSION);
+        return 0;
     }
     const command = rest[0];
     const commandArgs = rest.slice(1);
-    switch (command) {
-        case "vision":
-            await handleVision(commandArgs);
-            break;
-        case "search":
-            await handleSearch(commandArgs);
-            break;
-        case "read":
-            await handleRead(commandArgs);
-            break;
-        case "repo":
-            await handleRepo(commandArgs);
-            break;
-        case "tools":
-            await handleTools(commandArgs);
-            break;
-        case "tool":
-            await handleTool(commandArgs);
-            break;
-        case "call":
-            await handleCall(commandArgs);
-            break;
-        case "doctor":
-            await handleDoctor(commandArgs);
-            break;
-        case "quota":
-            await handleQuota(commandArgs);
-            break;
-        case "code":
-            await handleCode(commandArgs);
-            break;
-        default:
-            outputError(`Unknown command: ${command}`, "INVALID_ARGS", 'Run "scoutline --help" for available commands');
+    const handlerDeps = {
+        invocation,
+        env,
+        secrets,
+        now,
+        provider,
+        providerDescriptors,
+        searchCache,
+        searchSleep,
+        searchRandom,
+    };
+    try {
+        switch (command) {
+            case "vision":
+                return await handleVision(commandArgs, outputMode, handlerDeps);
+            case "search":
+                return await handleSearch(commandArgs, outputMode, handlerDeps);
+            case "read":
+                return await handleRead(commandArgs, outputMode, handlerDeps);
+            case "repo":
+                return await handleRepo(commandArgs, outputMode, handlerDeps);
+            case "tools":
+                return await handleTools(commandArgs, outputMode, handlerDeps);
+            case "tool":
+                return await handleTool(commandArgs, outputMode, handlerDeps);
+            case "call":
+                return await handleCall(commandArgs, outputMode, handlerDeps);
+            case "doctor":
+                return await handleDoctor(commandArgs, outputMode, handlerDeps);
+            case "quota":
+                return await handleQuota(commandArgs, outputMode, handlerDeps);
+            case "code":
+                return await handleCode(commandArgs, outputMode, handlerDeps);
+            default:
+                invocation.writeStderr(formatErrorOutput(new ValidationError(`Unknown command: ${command}`, 'Run "scoutline --help" for available commands'), outputMode, secrets));
+                return 1;
+        }
+    }
+    catch (error) {
+        // Fixup C — B10: pre-invocation validation errors (provider
+        // resolution, missing credential, count parsing, etc.) MUST be
+        // formatted in the resolved output mode — they used to be hardcoded
+        // to "data" regardless of what the user asked for.
+        invocation.writeStderr(formatErrorOutput(error, outputMode, secrets));
+        return getErrorExitCode(error);
     }
 }
-main(process.argv)
-    .then(() => process.exit(0))
-    .catch((error) => {
-    console.error(JSON.stringify({
-        success: false,
-        error: error.message,
-        code: "FATAL_ERROR",
-    }, null, 2));
-    process.exit(1);
-});
 //# sourceMappingURL=index.js.map