scoutline 0.1.0 → 0.6.0

package/dist/index.js

@@ -6,34 +6,60 @@ 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 { cacheStatsCommand, cacheClearCommand, formatDoctorCacheSummary, CACHE_HELP, } from "./commands/cache.js";
+import { cacheStats, clearAllCaches } from "./lib/cache.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 (Provider Capability; Z.AI supports it,
+           MiniMax returns UNSUPPORTED_CAPABILITY)
+  repo     GitHub repository exploration (Provider Capability; Z.AI supports it,
+           MiniMax returns UNSUPPORTED_CAPABILITY)
+  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
+  cache    Inspect or clear the local cache (stats / clear)
+  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. The 'repo' and 'read' commands
+participate in Provider selection: Z.AI advertises and supplies the
+repository-exploration and reader Capabilities; MiniMax advertises and
+supplies neither, so selecting MiniMax (explicitly or via
+SCOUTLINE_PROVIDER) returns UNSUPPORTED_CAPABILITY with no fallback.
+Z.AI-only commands (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
@@ -44,6 +70,7 @@ Help:
   scoutline tools --help
   scoutline call --help
   scoutline code --help
+  scoutline cache --help
 `.trim();
 function parseArgs(args) {
     const flags = {};
@@ -93,6 +120,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 +136,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 +347,87 @@ 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, {
+    // Parse-level validation BEFORE Provider resolution. URL scheme and
+    // --extract mode are validated at parse time so an invalid value
+    // surfaces VALIDATION_ERROR regardless of which Provider would have
+    // been selected, because parse-level validation fires before the
+    // support/configuration gates. The handler re-runs an identical
+    // check as defensive backstop. The pre-dispatch
+    // configuredSecrets(env) redaction read in `main` is the only
+    // permitted credential-related read before this point.
+    if (typeof url !== "string" || (!url.startsWith("http://") && !url.startsWith("https://"))) {
+        throw new ValidationError("URL must start with http:// or https://");
+    }
+    const extractFlag = flags.extract;
+    if (extractFlag !== undefined && !isExtractMode(extractFlag)) {
+        throw new ValidationError(`Invalid --extract mode: ${extractFlag}. Use one of: code, links, tables, headings`);
+    }
+    const extract = extractFlag !== undefined ? extractFlag : undefined;
+    // Resolve the effective Provider (DESIGN.md §6, FR-001–FR-005):
+    // explicit --provider > SCOUTLINE_PROVIDER > default zai. Selection
+    // never consults credentials (FR-003) and never branches on Provider
+    // ID; an unknown explicit/env value throws VALIDATION_ERROR here.
+    const providerId = resolveProviderId(deps.provider, deps.env);
+    const descriptor = getProviderDescriptor(providerId, deps.providerDescriptors);
+    // Capability support check BEFORE `descriptor.isConfigured`,
+    // `descriptor.create`, Adapter access, operation validation/
+    // cacheIdentity, credential use, cache, or transport. Unsupported
+    // MiniMax (explicit or environment) returns UNSUPPORTED_CAPABILITY
+    // with no fallback to Z.AI; zero selected-Provider work occurs.
+    if (!descriptor.capabilities().has("reader")) {
+        throw new UnsupportedCapabilityError(providerId, "reader");
+    }
+    // FR-003: selection returns the default zai even when unconfigured.
+    // Supported-but-unconfigured Z.AI surfaces a missing credential as
+    // ConfigurationError (exit 3) AFTER the support metadata check and
+    // BEFORE `descriptor.create`.
+    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.reader;
+    // Defensive fail-closed: the descriptor advertised support but the
+    // Adapter omitted the handle. Treat as unsupported so a registry
+    // mismatch can never reach transport.
+    if (!capability) {
+        throw new UnsupportedCapabilityError(providerId, "reader");
+    }
+    // Shared Reader execution dependencies. The cache/sleep/random
+    // default to the same production values as Search and Repository
+    // but are kept as separate optional MainDependencies so reader
+    // tests can inject isolated in-memory doubles.
+    const executionDeps = {
+        cache: deps.readerCache,
+        sleep: deps.readerSleep,
+        random: deps.readerRandom,
+    };
+    return invokeCommand(deps.invocation, (context) => read(url, {
         format: flags.format,
         noImages: flags["no-images"] === true,
         noCache: flags["no-cache"] === true,
@@ -231,112 +438,231 @@ 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,
+    }, { capability, execution: executionDeps }, 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];
+    // Parse-level validation. Subcommand grammar and required positionals
+    // are validated BEFORE Provider resolution, capability support check,
+    // configuration check, Adapter construction, or any
+    // operation/cacheIdentity/credential/cache/transport work. The
+    // pre-dispatch `configuredSecrets(env)` redaction read in `main` is
+    // the only permitted credential-related read before this point; it is
+    // not selected-Provider resolution and is covered separately by the
+    // ordering tests.
+    let searchQuery;
+    let readPath;
+    if (command === "search") {
+        searchQuery = positional.slice(2).join(" ");
+        if (!repo || !searchQuery) {
+            throw new ValidationError("Missing repo or query", "Usage: scoutline repo search <owner/repo> <query>");
+        }
+    }
+    else if (command === "tree") {
+        if (!repo) {
+            throw new ValidationError("Missing repo", "Usage: scoutline repo tree <owner/repo>");
+        }
+    }
+    else if (command === "read") {
+        readPath = positional[2];
+        if (!repo || !readPath) {
+            throw new ValidationError("Missing repo or path", "Usage: scoutline repo read <owner/repo> <path>");
+        }
+    }
+    else {
+        throw new ValidationError(`Unknown repo command: ${command}`, 'Run "scoutline repo --help" for available commands');
+    }
+    // Resolve the effective Provider (DESIGN.md §6, FR-001–FR-005):
+    // explicit --provider > SCOUTLINE_PROVIDER > default zai. Selection
+    // never consults credentials (FR-003) and never branches on Provider
+    // ID; an unknown explicit/env value throws VALIDATION_ERROR here.
+    const providerId = resolveProviderId(deps.provider, deps.env);
+    const descriptor = getProviderDescriptor(providerId, deps.providerDescriptors);
+    // Capability support check BEFORE `descriptor.isConfigured`,
+    // `descriptor.create`, Adapter access, operation validation/
+    // cacheIdentity, credential use, cache, or transport. Unsupported
+    // MiniMax (explicit or environment) returns UNSUPPORTED_CAPABILITY
+    // with no fallback to Z.AI; zero selected-Provider work occurs.
+    if (!descriptor.capabilities().has("repository-exploration")) {
+        throw new UnsupportedCapabilityError(providerId, "repository-exploration");
+    }
+    // FR-003: selection returns the default zai even when unconfigured.
+    // Supported-but-unconfigured Z.AI surfaces a missing credential as
+    // ConfigurationError (exit 3) AFTER the support metadata check and
+    // BEFORE `descriptor.create`.
+    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.repository;
+    // Defensive fail-closed: the descriptor advertised support but the
+    // Adapter omitted the handle. Treat as unsupported so a registry
+    // mismatch can never reach transport.
+    if (!capability) {
+        throw new UnsupportedCapabilityError(providerId, "repository-exploration");
+    }
+    // Shared Repository execution dependencies. The cache/sleep/random
+    // default to the same production values as Search but are kept as
+    // separate optional MainDependencies so repository tests can inject
+    // isolated in-memory doubles.
+    const executionDeps = {
+        cache: deps.repositoryCache,
+        sleep: deps.repositorySleep,
+        random: deps.repositoryRandom,
+    };
     switch (command) {
-        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>");
-            }
-            await repoSearch(repo, query, {
-                language: flags.language,
-                maxChars: flags["max-chars"] ? parseInt(flags["max-chars"], 10) : undefined,
-                noCache: flags["no-cache"] === true,
-            });
-            break;
-        case "tree":
-            if (!repo) {
-                outputError("Missing repo", "INVALID_ARGS", "Usage: scoutline repo tree <owner/repo>");
-            }
-            await repoTree(repo, {
-                path: flags.path,
-                depth: flags.depth ? parseInt(flags.depth, 10) : undefined,
-                noCache: flags["no-cache"] === true,
-            });
-            break;
-        case "read":
-            const path = positional[2];
-            if (!repo || !path) {
-                outputError("Missing repo or path", "INVALID_ARGS", "Usage: scoutline repo read <owner/repo> <path>");
-            }
-            await repoRead(repo, path, {
-                maxChars: flags["max-chars"] ? parseInt(flags["max-chars"], 10) : undefined,
-                noCache: flags["no-cache"] === true,
-            });
-            break;
+        case "search": {
+            const language = flags.language;
+            const maxChars = flags["max-chars"] ? parseInt(flags["max-chars"], 10) : undefined;
+            const noCache = flags["no-cache"] === true;
+            return invokeCommand(deps.invocation, () => repoSearch(repo, searchQuery, { language, maxChars, noCache }, { capability, execution: executionDeps }), outputMode, deps.now, deps.secrets);
+        }
+        case "tree": {
+            const treePath = flags.path;
+            const depth = flags.depth ? parseInt(flags.depth, 10) : undefined;
+            const noCache = flags["no-cache"] === true;
+            return invokeCommand(deps.invocation, () => repoTree(repo, { path: treePath, depth, noCache }, { capability, execution: executionDeps }), outputMode, deps.now, deps.secrets);
+        }
+        case "read": {
+            const maxChars = flags["max-chars"] ? parseInt(flags["max-chars"], 10) : undefined;
+            const noCache = flags["no-cache"] === true;
+            return invokeCommand(deps.invocation, () => repoRead(repo, readPath, { maxChars, noCache }, { capability, execution: executionDeps }), outputMode, deps.now, deps.secrets);
+        }
         default:
-            outputError(`Unknown repo command: ${command}`, "INVALID_ARGS", 'Run "scoutline repo --help" for available commands');
+            // Unreachable: the parse-level validation above already rejected
+            // unknown subcommands. Keep a defensive throw so the dispatch
+            // table stays total.
+            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;
+    }
+    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);
+    // Cache Module Unification Ticket 03 — Doctor's one-line cache summary.
+    // The dispatcher formats the summary here (L1 fix) from `cacheStats()`
+    // output; the report builder only embeds the pre-formatted string.
+    // `cacheStats()` never throws (it catches all I/O internally); on a
+    // missing directory it returns zeros, which still format correctly.
+    const cacheSummary = formatDoctorCacheSummary(await cacheStats());
+    return invokeCommand(deps.invocation, () => doctor({
+        buildReport: () => buildDiagnosticsReport({
+            noTools,
+            effectiveProvider,
+            descriptors: deps.providerDescriptors,
+            env: deps.env,
+            sleep: deps.searchSleep,
+            random: deps.searchRandom,
+            cacheSummary,
+        }),
+    }), outputMode, deps.now, deps.secrets);
+}
+/**
+ * `scoutline cache <stats|clear>` — local cache utility. Like Doctor,
+ * it bypasses Provider resolution entirely (no descriptor lookup, no
+ * Adapter, no transport). The command surfaces the inventory and clear
+ * helpers owned by `src/lib/cache.ts` (Ticket 01) through the
+ * presentation-only handlers in `src/commands/cache.ts`.
+ */
+async function handleCache(args, outputMode, deps) {
+    const { flags, positional } = parseArgs(args);
+    if (flags.help || flags.h || positional.length === 0) {
+        deps.invocation.writeStdout(CACHE_HELP);
+        return 0;
+    }
+    const subcommand = positional[0];
+    switch (subcommand) {
+        case "stats":
+            return invokeCommand(deps.invocation, () => cacheStatsCommand({
+                getStats: () => cacheStats(),
+            }), outputMode, deps.now, deps.secrets);
+        case "clear":
+            return invokeCommand(deps.invocation, () => cacheClearCommand({
+                clear: () => clearAllCaches(),
+            }), outputMode, deps.now, deps.secrets);
+        default:
+            throw new ValidationError(`Unknown cache command: ${subcommand}`, 'Run "scoutline cache --help" for available commands');
     }
-    await doctor({
-        noTools: flags["no-tools"] === true,
-        enableVision: flags.vision !== false,
-    });
 }
-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 +671,130 @@ 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;
+    // P6-07: Repository execution defaults to the same production values
+    // as Search but stays as separate optional MainDependencies so
+    // repository tests can inject isolated in-memory doubles.
+    const repositoryCache = dependencies.repositoryCache ?? defaultResponseCache;
+    const repositorySleep = dependencies.repositorySleep ?? realSleep;
+    const repositoryRandom = dependencies.repositoryRandom ?? Math.random;
+    // Reader Migration Ticket 04: Reader execution defaults to the same
+    // production values as Search/Repository but stays as separate
+    // optional MainDependencies so reader tests can inject isolated
+    // in-memory doubles.
+    const readerCache = dependencies.readerCache ?? defaultResponseCache;
+    const readerSleep = dependencies.readerSleep ?? realSleep;
+    const readerRandom = dependencies.readerRandom ?? 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,
+        repositoryCache,
+        repositorySleep,
+        repositoryRandom,
+        readerCache,
+        readerSleep,
+        readerRandom,
+    };
+    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 "cache":
+                return await handleCache(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