scoutline 0.1.0 → 0.6.0

package/dist/commands/doctor.js

@@ -1,70 +1,197 @@
 /**
- * Doctor command for environment and MCP diagnostics
+ * Doctor command — Provider-aware diagnostics (P4-04, DESIGN.md §14).
+ *
+ * The command is presentation-only: it receives a report builder through
+ * injected dependencies and wraps the resulting {@link DiagnosticsReport}
+ * as base data with a computed exit code. Provider resolution, capability
+ * probing, settled collection, and failure redaction live in
+ * {@link buildDiagnosticsReport} so the command never imports a Provider
+ * transport (ZaiMcpClient, monitor client, or environment credential
+ * reads) directly.
+ *
+ * Exit semantics (DESIGN.md §14):
+ *   - Missing effective Provider credentials -> exit 1.
+ *   - Any configured probe error -> exit 1 (successful entries preserved).
+ *   - All configured probes succeed, or only tools-disabled skips -> exit 0.
+ *
+ * Under `--no-tools` the command returns after metadata + configured-state
+ * evaluation and constructs no Adapter and no transport (FR-034).
  */
-import { ZaiMcpClient } from "../lib/mcp-client.js";
-import { outputSuccess } from "../lib/output.js";
-import { formatErrorOutput } from "../lib/errors.js";
-import { silenceConsole, restoreConsole } from "../lib/silence.js";
-function getNodeMajor() {
+import { deriveSharedCapabilities, deriveZaiOnlyCapabilities, diagnosticErrorFromError, } from "../capabilities/diagnostics.js";
+import { executeProviderOperation } from "../lib/execution.js";
+import { UnsupportedCapabilityError } from "../lib/errors.js";
+import { redactSecrets, configuredSecrets } from "../lib/redact.js";
+function nodeMajor() {
     const [major] = process.versions.node.split(".");
     return parseInt(major, 10);
 }
-export async function doctor(options = {}) {
-    const apiKey = process.env.Z_AI_API_KEY || process.env.ZAI_API_KEY;
-    const mode = (process.env.Z_AI_MODE || process.env.PLATFORM_MODE || "ZAI").toUpperCase();
-    const nodeMajor = getNodeMajor();
-    const report = {
-        env: {
-            apiKeyPresent: Boolean(apiKey),
-            mode,
-            baseUrl: process.env.Z_AI_BASE_URL || undefined,
-        },
+/**
+ * Probe one Provider's connectivity through shared execution. The Adapter
+ * transport performs a single attempt (Z.AI tool discovery or MiniMax raw
+ * quota probe); the retry policy lives in
+ * `executeProviderOperation("diagnostics", ...)`.
+ */
+async function probeProvider(descriptor, env, sleep, random) {
+    const adapter = descriptor.create({ env });
+    const capability = adapter.diagnostics;
+    if (!capability) {
+        throw new UnsupportedCapabilityError(descriptor.id, "diagnostics");
+    }
+    return executeProviderOperation("diagnostics", () => capability.invoke({ probe: true }), {
+        sleep,
+        random,
+    });
+}
+/**
+ * Build a schema-version-1 {@link DiagnosticsReport}. Inventory
+ * (`sharedCapabilities`, `zaiOnlyCapabilities`) is derived purely from
+ * `deps.descriptors` — no descriptor.create(), no transport, no
+ * production registry import. Under `--no-tools` the command returns
+ * after metadata + configured-state evaluation. Otherwise each
+ * configured Provider is probed through shared execution with settled
+ * collection, preserving registry order and normalized redacted
+ * failures.
+ */
+export async function buildDiagnosticsReport(deps) {
+    const secrets = configuredSecrets(deps.env);
+    const baseEntries = deps.descriptors.map((descriptor) => ({
+        provider: descriptor.id,
+        configured: descriptor.isConfigured(deps.env),
+        capabilities: [...descriptor.capabilities()],
+    }));
+    const providers = deps.noTools
+        ? baseEntries.map((entry) => ({
+            ...entry,
+            status: "skipped",
+            reason: entry.configured ? "tools-disabled" : "not-configured",
+        }))
+        : await probeEntries(baseEntries, deps, secrets);
+    // L1 fix: the cache summary is formatted by the CLI handler and
+    // threaded through deps.cacheSummary. The report builder only embeds
+    // it; it never reads `cacheStats()` itself.
+    const cache = deps.cacheSummary === undefined ? undefined : { summary: deps.cacheSummary };
+    return {
+        schemaVersion: 1,
+        effectiveProvider: deps.effectiveProvider,
+        sharedCapabilities: deriveSharedCapabilities(deps.descriptors),
+        zaiOnlyCapabilities: deriveZaiOnlyCapabilities(deps.descriptors),
         node: {
-            version: process.versions.node,
-            visionMcpCompatible: nodeMajor >= 22,
+            version: process.version,
+            visionMcpCompatible: nodeMajor() >= 22,
         },
+        providers,
+        ...(cache !== undefined ? { cache } : {}),
+    };
+}
+/**
+ * Probe every configured Provider in registry order using settled
+ * collection. Unconfigured entries are skipped (not-configured) and do
+ * NOT fail the report. A configured probe failure is normalized and
+ * recursively redacted before joining the report; successful entries
+ * are preserved alongside it.
+ */
+async function probeEntries(baseEntries, deps, secrets) {
+    const configuredIndexes = baseEntries
+        .map((entry, index) => (entry.configured ? index : -1))
+        .filter((index) => index >= 0);
+    const settled = await Promise.allSettled(configuredIndexes.map((index) => probeProvider(deps.descriptors[index], deps.env, deps.sleep, deps.random)));
+    let settledCursor = 0;
+    return baseEntries.map((entry) => {
+        if (!entry.configured) {
+            return { ...entry, status: "skipped", reason: "not-configured" };
+        }
+        const result = settled[settledCursor++];
+        if (result.status === "fulfilled") {
+            return { ...entry, status: "ok" };
+        }
+        const redacted = redactSecrets(diagnosticErrorFromError(result.reason), secrets);
+        return { ...entry, status: "error", error: redacted };
+    });
+}
+// ---------------------------------------------------------------------------
+// Exit code
+// ---------------------------------------------------------------------------
+/**
+ * Compute the doctor exit code from a finalized report. Exit 1 when the
+ * effective Provider is unconfigured or any configured probe errored;
+ * otherwise exit 0. A tools-disabled or not-configured skip on a
+ * non-effective Provider never fails the report.
+ */
+export function doctorExitCode(report) {
+    const effective = report.providers.find((p) => p.provider === report.effectiveProvider);
+    if (!effective || !effective.configured)
+        return 1;
+    if (report.providers.some((p) => p.status === "error"))
+        return 1;
+    return 0;
+}
+/**
+ * Run the doctor command. Returns the diagnostics report as base data
+ * with a computed exit code (1 when the effective Provider is
+ * unconfigured or any configured probe failed; otherwise 0).
+ */
+export async function doctor(deps) {
+    const report = await deps.buildReport();
+    return {
+        kind: "data",
+        data: report,
+        exitCode: doctorExitCode(report),
     };
-    if (options.noTools || !apiKey) {
-        outputSuccess(report);
-        return;
-    }
-    silenceConsole();
-    const client = new ZaiMcpClient({ enableVision: options.enableVision });
-    try {
-        const tools = await client.listTools();
-        const byServer = tools.reduce((acc, tool) => {
-            const parts = tool.name.split(".");
-            const server = parts.length >= 2 ? parts[1] : "unknown";
-            acc[server] = (acc[server] || 0) + 1;
-            return acc;
-        }, {});
-        report.mcp = {
-            toolCount: tools.length,
-            servers: byServer,
-        };
-        outputSuccess(report);
-    }
-    catch (error) {
-        restoreConsole();
-        console.error(formatErrorOutput(error));
-        process.exit(1);
-    }
-    finally {
-        await client.close().catch(() => { });
-        restoreConsole();
-    }
 }
 export const DOCTOR_HELP = `
-Doctor - Check environment and MCP connectivity
+Doctor - Provider-aware environment and connectivity diagnostics
 
 Usage: scoutline doctor [options]
 
+Reports a schema-version-1 diagnostics report listing every built-in
+Provider (zai, minimax) with its configured state, declared
+Capabilities, and connectivity status. The effective Provider (resolved
+from --provider, SCOUTLINE_PROVIDER, or the default zai) is the
+Provider that serves the shared Capabilities shared across every
+built-in descriptor. The sharedCapabilities and zaiOnlyCapabilities
+fields are derived from descriptor metadata, so they always reflect
+the descriptors passed to this command.
+
+Z.AI connectivity is probed through MCP tool discovery; MiniMax
+connectivity through a single raw quota probe that authenticates
+without a generative request.
+
+Repository exploration is a Provider Capability. Z.AI descriptor
+metadata advertises repository-exploration and the Z.AI Adapter
+supplies it; MiniMax advertises and supplies neither. The
+sharedCapabilities and zaiOnlyCapabilities fields above reflect that
+descriptor state (repository-exploration currently appears in
+zaiOnlyCapabilities).
+
+Reader is a Provider Capability. Z.AI descriptor metadata advertises
+reader and the Z.AI Adapter supplies it; MiniMax advertises and
+supplies neither. reader currently appears in zaiOnlyCapabilities
+alongside repository-exploration.
+
+Public 'repo' and 'read' commands participate in Provider selection.
+They honour --provider / SCOUTLINE_PROVIDER / the default zai, route
+through the Z.AI Adapter's Repository and Reader Capabilities
+respectively, and return UNSUPPORTED_CAPABILITY when the selected
+Provider does not advertise the requested capability (e.g.
+'repo --provider minimax' or 'read --provider minimax' fail without
+falling back to Z.AI). A supported-but-unconfigured Z.AI returns
+ConfigurationError; supported-and-configured Z.AI dispatches through
+the Repository Explorer / Reader Adapter.
+
 Options:
-  --no-tools   Skip tool discovery (env-only check)
-  --no-vision  Skip vision MCP server (faster startup)
+  --no-tools   Skip every connectivity probe (metadata-only). Under
+               --no-tools no Provider transport is constructed: a
+               configured Provider is reported as skipped
+               (tools-disabled) and does not fail the report.
+
+Exit codes:
+  0  All configured probes succeeded (or only tools-disabled skips).
+  1  The effective Provider is unconfigured or any configured probe
+       failed; successful entries are still reported.
 
 Examples:
-  scoutline doctor
-  scoutline doctor --no-tools
+  scoutline doctor                 # full diagnostics
+  scoutline doctor --provider minimax
+  scoutline doctor --no-tools      # metadata only, no transport
 `.trim();
 //# sourceMappingURL=doctor.js.map

package/dist/commands/doctor.js.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"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"}

package/dist/commands/quota.d.ts

@@ -1,9 +1,51 @@
 /**
- * Quota command — authoritative Z.AI Coding Plan usage from the monitor API.
+ * Quota command — Provider-neutral quota dashboard (P4-03, ADR-0001).
+ *
+ * The command is presentation-only: it receives a dashboard builder
+ * through injected dependencies and wraps the resulting
+ * {@link QuotaDashboard} as base data with a TTY presentation override.
+ * Provider resolution, capability invocation, settled collection, and
+ * failure redaction live in {@link buildQuotaDashboard} so the command
+ * never imports a Provider monitor client or maps a Provider response.
+ *
+ * Default mode (effective Provider) propagates quota failures through
+ * the ordinary error path (thrown → invokeCommand). All-provider mode
+ * (`--all-providers`) uses settled collection, emits successful and
+ * failed entries, and yields exit 1 when any configured Provider fails.
  */
+import type { CommandResult } from "../command-invocation.js";
+import type { QuotaDashboard } from "../capabilities/quota.js";
+import type { ProviderDescriptor, ProviderId } from "../providers/types.js";
+export interface QuotaDashboardDependencies {
+    readonly allProviders: boolean;
+    readonly effectiveProvider: ProviderId;
+    readonly descriptors: readonly ProviderDescriptor[];
+    readonly env: NodeJS.ProcessEnv;
+    readonly sleep: (ms: number) => Promise<void>;
+    readonly random: () => number;
+}
+/**
+ * Build a {@link QuotaDashboard} for the selected mode. The effective
+ * Provider is resolved by the dispatcher (`index.ts`) and passed in as
+ * metadata; config validation happens here.
+ */
+export declare function buildQuotaDashboard(deps: QuotaDashboardDependencies): Promise<QuotaDashboard>;
 export interface QuotaOptions {
-    window?: "current";
+    allProviders?: boolean;
+}
+/**
+ * Injectable dependencies for the quota command. `buildDashboard`
+ * resolves the effective/all-provider dashboard; the command only wraps
+ * it for presentation and exit-code selection.
+ */
+export interface QuotaCommandDependencies {
+    readonly buildDashboard: () => Promise<QuotaDashboard>;
 }
-export declare function quota(_options?: QuotaOptions): Promise<void>;
+/**
+ * Run the quota command. Returns the dashboard as base data with a TTY
+ * presentation override. Exit code is 1 when any dashboard entry failed
+ * (all-provider mode); otherwise 0.
+ */
+export declare function quota(deps: QuotaCommandDependencies): Promise<CommandResult<QuotaDashboard>>;
 export declare const QUOTA_HELP: string;
 //# sourceMappingURL=quota.d.ts.map

package/dist/commands/quota.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"quota.d.ts","sourceRoot":"","sources":["../../src/commands/quota.ts"],"names":[],"mappings":"AAAA;;GAEG;AAYH,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAED,wBAAsB,KAAK,CAAC,QAAQ,GAAE,YAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2CtE;AAED,eAAO,MAAM,UAAU,QAwBf,CAAC"}
+{"version":3,"file":"quota.d.ts","sourceRoot":"","sources":["../../src/commands/quota.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAIV,cAAc,EACf,MAAM,0BAA0B,CAAC;AAIlC,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAS5E,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,UAAU,CAAC;IACvC,QAAQ,CAAC,WAAW,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACpD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC;CAC/B;AAqFD;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,0BAA0B,GAC/B,OAAO,CAAC,cAAc,CAAC,CAEzB;AAMD,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,cAAc,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC;CACxD;AAED;;;;GAIG;AACH,wBAAsB,KAAK,CACzB,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CAAC,aAAa,CAAC,cAAc,CAAC,CAAC,CASxC;AAED,eAAO,MAAM,UAAU,QA2Bf,CAAC"}

package/dist/commands/quota.js

@@ -1,77 +1,133 @@
 /**
- * Quota command — authoritative Z.AI Coding Plan usage from the monitor API.
+ * Quota command — Provider-neutral quota dashboard (P4-03, ADR-0001).
+ *
+ * The command is presentation-only: it receives a dashboard builder
+ * through injected dependencies and wraps the resulting
+ * {@link QuotaDashboard} as base data with a TTY presentation override.
+ * Provider resolution, capability invocation, settled collection, and
+ * failure redaction live in {@link buildQuotaDashboard} so the command
+ * never imports a Provider monitor client or maps a Provider response.
+ *
+ * Default mode (effective Provider) propagates quota failures through
+ * the ordinary error path (thrown → invokeCommand). All-provider mode
+ * (`--all-providers`) uses settled collection, emits successful and
+ * failed entries, and yields exit 1 when any configured Provider fails.
  */
-import { getQuotaLimit, getTimeLimit, getTokensLimit, formatResetTime, } from "../lib/monitor-client.js";
-import { outputSuccess, getOutputMode } from "../lib/output.js";
-import { formatErrorOutput } from "../lib/errors.js";
-import { formatQuotaPretty } from "../lib/tty.js";
-export async function quota(_options = {}) {
-    try {
-        const data = await getQuotaLimit();
-        const timeLimit = getTimeLimit(data);
-        const tokensLimit = getTokensLimit(data);
-        const formatted = {
-            plan: data.level,
-            timeWindow: timeLimit
-                ? {
-                    used: timeLimit.currentValue,
-                    limit: timeLimit.usage,
-                    remaining: timeLimit.remaining,
-                    percentage: timeLimit.percentage,
-                    windowHours: timeLimit.unit,
-                    resetsAt: timeLimit.nextResetTime
-                        ? new Date(timeLimit.nextResetTime).toISOString()
-                        : null,
-                    resetsIn: timeLimit.nextResetTime ? formatResetTime(timeLimit.nextResetTime) : null,
-                    byTool: timeLimit.usageDetails,
-                }
-                : null,
-            tokens: tokensLimit
-                ? {
-                    percentage: tokensLimit.percentage,
-                    resetsAt: tokensLimit.nextResetTime
-                        ? new Date(tokensLimit.nextResetTime).toISOString()
-                        : null,
-                    resetsIn: tokensLimit.nextResetTime ? formatResetTime(tokensLimit.nextResetTime) : null,
-                }
-                : null,
-        };
-        const mode = getOutputMode();
-        if (mode === "tty") {
-            outputSuccess(formatQuotaPretty(formatted));
-        }
-        else {
-            outputSuccess(formatted);
-        }
+import { quotaFailureFromError } from "../capabilities/quota.js";
+import { executeProviderOperation } from "../lib/execution.js";
+import { ConfigurationError, UnsupportedCapabilityError } from "../lib/errors.js";
+import { getProviderDescriptor } from "../providers/selection.js";
+import { redactSecrets, configuredSecrets } from "../lib/redact.js";
+import { formatQuotaDashboard } from "../lib/tty.js";
+/**
+ * Invoke one Provider's quota Capability through shared execution. The
+ * Adapter transport performs a single attempt; the retry policy lives
+ * in `executeProviderOperation("quota", ...)`. Quota never uses the
+ * response cache.
+ */
+async function invokeProviderQuota(descriptor, env, sleep, random) {
+    const adapter = descriptor.create({ env });
+    const capability = adapter.quota;
+    if (!capability) {
+        throw new UnsupportedCapabilityError(descriptor.id, "quota");
     }
-    catch (error) {
-        console.error(formatErrorOutput(error));
-        process.exit(1);
+    return executeProviderOperation("quota", () => capability.invoke(), { sleep, random });
+}
+/**
+ * Default-mode dashboard. Resolves the effective Provider, requires it
+ * to be configured (ConfigurationError, exit 3, before transport), then
+ * invokes its quota Capability. Failures propagate through the ordinary
+ * error path.
+ */
+async function buildDefaultDashboard(deps) {
+    const descriptor = getProviderDescriptor(deps.effectiveProvider, deps.descriptors);
+    if (!descriptor.isConfigured(deps.env)) {
+        throw new ConfigurationError(`Provider "${deps.effectiveProvider}" is not configured. Set Z_AI_API_KEY or MINIMAX_API_KEY.`);
+    }
+    const success = await invokeProviderQuota(descriptor, deps.env, deps.sleep, deps.random);
+    return {
+        schemaVersion: 1,
+        effectiveProvider: deps.effectiveProvider,
+        providers: [success],
+    };
+}
+/**
+ * All-provider dashboard. Queries every configured Provider in static
+ * registry order using settled collection. No unconfigured Provider is
+ * invoked; the effective Provider is dashboard metadata only. Failures
+ * are normalized and recursively redacted before joining the dashboard.
+ * No configured Provider is a configuration failure, not an empty
+ * success.
+ */
+async function buildAllProvidersDashboard(deps) {
+    const configured = deps.descriptors.filter((d) => d.isConfigured(deps.env));
+    if (configured.length === 0) {
+        throw new ConfigurationError("No provider is configured. Set Z_AI_API_KEY and/or MINIMAX_API_KEY.");
     }
+    const secrets = configuredSecrets(deps.env);
+    const settled = await Promise.allSettled(configured.map((d) => invokeProviderQuota(d, deps.env, deps.sleep, deps.random)));
+    const providers = configured.map((d, i) => {
+        const result = settled[i];
+        if (result.status === "fulfilled") {
+            return result.value;
+        }
+        return redactSecrets(quotaFailureFromError(d.id, result.reason), secrets);
+    });
+    return {
+        schemaVersion: 1,
+        effectiveProvider: deps.effectiveProvider,
+        providers,
+    };
+}
+/**
+ * Build a {@link QuotaDashboard} for the selected mode. The effective
+ * Provider is resolved by the dispatcher (`index.ts`) and passed in as
+ * metadata; config validation happens here.
+ */
+export async function buildQuotaDashboard(deps) {
+    return deps.allProviders ? buildAllProvidersDashboard(deps) : buildDefaultDashboard(deps);
+}
+/**
+ * Run the quota command. Returns the dashboard as base data with a TTY
+ * presentation override. Exit code is 1 when any dashboard entry failed
+ * (all-provider mode); otherwise 0.
+ */
+export async function quota(deps) {
+    const dashboard = await deps.buildDashboard();
+    const hasFailure = dashboard.providers.some((p) => p.status === "error");
+    return {
+        kind: "data",
+        data: dashboard,
+        presentations: { tty: formatQuotaDashboard(dashboard) },
+        exitCode: hasFailure ? 1 : 0,
+    };
 }
 export const QUOTA_HELP = `
-Quota Command - Authoritative Z.AI Coding Plan usage from the monitor API
+Quota Command - Provider-normalized plan usage dashboard
 
 Usage: scoutline quota [options]
 
-Hits GET https://api.z.ai/api/monitor/usage/quota/limit directly (NOT the MCP
-endpoint) to return real-time plan usage, including:
-  - Plan tier (pro / lite / max)
-  - 5-hour rolling window: calls used / limit / remaining / reset time
-  - Per-tool breakdown (search-prime, web-reader, zread)
-  - Token budget percentage + reset time
+Reports plan usage for the effective Provider (or every configured
+Provider with --all-providers) as a normalized, schema-version-1
+dashboard (ADR-0001). Each entry carries named quota categories with
+current and optional weekly windows, counts, remaining percentage, and
+ISO reset time. No Provider-specific field crosses the Interface.
 
 Options:
-  (none yet — future versions may add --history for 24h/7d/30d windows)
+  --all-providers   Query every configured Provider in registry order.
+                    Successful and failed entries both appear; the
+                    command exits 1 when any Provider fails.
 
 Examples:
-  scoutline quota
-  scoutline quota -O pretty    # human-readable with progress bars
-  scoutline quota -O json      # envelope-wrapped for scripts
+  scoutline quota                  # effective Provider usage
+  scoutline quota --all-providers  # every configured Provider
+  scoutline quota -O pretty        # human-readable with progress bars
+  scoutline quota -O json          # envelope-wrapped for scripts
 
 Notes:
-  - This call hits a different endpoint than search/read/repo and is not
-    cached by the local response cache.
-  - Auth: tries raw API key first, falls back to Bearer prefix on 401.
+  - Quota is never cached by the local response cache.
+  - Default-mode failures propagate as ordinary errors (exit 3 for an
+    unconfigured effective Provider).
+  - All-provider mode never invokes an unconfigured Provider.
 `.trim();
 //# sourceMappingURL=quota.js.map

package/dist/commands/quota.js.map

@@ -1 +1 @@
-{"version":3,"file":"quota.js","sourceRoot":"","sources":["../../src/commands/quota.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,aAAa,EACb,YAAY,EACZ,cAAc,EACd,eAAe,GAChB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAMlD,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,QAAQ,GAAiB,EAAE;IACrD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,aAAa,EAAE,CAAC;QACnC,MAAM,SAAS,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QACrC,MAAM,WAAW,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;QAEzC,MAAM,SAAS,GAAG;YAChB,IAAI,EAAE,IAAI,CAAC,KAAK;YAChB,UAAU,EAAE,SAAS;gBACnB,CAAC,CAAC;oBACE,IAAI,EAAE,SAAS,CAAC,YAAY;oBAC5B,KAAK,EAAE,SAAS,CAAC,KAAK;oBACtB,SAAS,EAAE,SAAS,CAAC,SAAS;oBAC9B,UAAU,EAAE,SAAS,CAAC,UAAU;oBAChC,WAAW,EAAE,SAAS,CAAC,IAAI;oBAC3B,QAAQ,EAAE,SAAS,CAAC,aAAa;wBAC/B,CAAC,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,WAAW,EAAE;wBACjD,CAAC,CAAC,IAAI;oBACR,QAAQ,EAAE,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,eAAe,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,IAAI;oBACnF,MAAM,EAAE,SAAS,CAAC,YAAY;iBAC/B;gBACH,CAAC,CAAC,IAAI;YACR,MAAM,EAAE,WAAW;gBACjB,CAAC,CAAC;oBACE,UAAU,EAAE,WAAW,CAAC,UAAU;oBAClC,QAAQ,EAAE,WAAW,CAAC,aAAa;wBACjC,CAAC,CAAC,IAAI,IAAI,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC,WAAW,EAAE;wBACnD,CAAC,CAAC,IAAI;oBACR,QAAQ,EAAE,WAAW,CAAC,aAAa,CAAC,CAAC,CAAC,eAAe,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,IAAI;iBACxF;gBACH,CAAC,CAAC,IAAI;SACT,CAAC;QAEF,MAAM,IAAI,GAAG,aAAa,EAAE,CAAC;QAC7B,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;YACnB,aAAa,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC,CAAC;QAC9C,CAAC;aAAM,CAAC;YACN,aAAa,CAAC,SAAS,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC;QACxC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;CAwBzB,CAAC,IAAI,EAAE,CAAC"}
+{"version":3,"file":"quota.js","sourceRoot":"","sources":["../../src/commands/quota.ts"],"names":[],"mappings":"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"}

package/dist/commands/read.d.ts

@@ -1,6 +1,44 @@
 /**
- * Web reader command using Z.AI WebReader MCP
+ * Web reader command — thin handler over the Reader Capability
+ * (DESIGN.md §18, reader-migration-core-flows, reader-migration-tech-plan
+ * Ticket 04).
+ *
+ * The handler applies parse-level validation only (URL scheme, --extract
+ * mode), delegates to `capability.fetch(request)` through shared
+ * execution, then projects the normalized `ReaderFetchResult` into the
+ * public v1 envelope(s) (content read vs extract read). The Adapter
+ * (providers/zai/reader.ts) owns URL rewrite, credentials, transport,
+ * raw response parsing, cache identity, and retry/terminal
+ * classification; the handler owns projection (`--max-chars` truncation,
+ * `--extract` slicing), output-mode presentation, and the
+ * schema-version-1 envelope migration.
+ *
+ * Provider selection, capability support, configuration, Adapter
+ * construction, and adapter.reader agreement live in `src/index.ts`.
+ *
+ * Handler interface (P6-07A pattern): `deps: ReadHandlerDependencies`
+ * is REQUIRED — production and direct tests cross the same compile-
+ * checked Interface. An optional trailing `CommandContext` follows when
+ * a caller wants to surface per-invocation context; the handler does
+ * not currently read it. A `CommandContext` is NOT a valid substitute
+ * for `deps`.
+ *
+ * Output-mode behavior (core-flows table):
+ *
+ *   - data: the envelope object (content or extract).
+ *   - json / pretty: standard `{success, data, timestamp}` envelope.
+ *   - compact / markdown / refs / tty:
+ *       * content read → the `content` string directly (presentations).
+ *       * extract read → JSON fallback (the extract envelope object);
+ *         no presentation override because extracted items are data,
+ *         not prose.
+ *
+ * `--full-envelope` is silently accepted and ignored (D3): the v1
+ * envelope is always returned.
  */
+import type { CommandContext, CommandResult } from "../command-invocation.js";
+import type { ReaderCapability } from "../capabilities/reader.js";
+import type { ExecutionDependencies } from "../lib/execution.js";
 import { type ExtractMode } from "../lib/extract.js";
 export interface ReadOptions {
     format?: "markdown" | "text";
@@ -12,9 +50,45 @@ export interface ReadOptions {
     keepImgDataUrl?: boolean;
     withImagesSummary?: boolean;
     maxChars?: number;
+    /**
+     * Silently accepted and ignored at v1 (core-flows D3). The envelope
+     * is always returned. Retained on the options type so callers and
+     * `handleRead` parse it without errors; it never reaches the Adapter
+     * request, the cache identity, or the projection.
+     */
     fullEnvelope?: boolean;
     extract?: ExtractMode;
 }
-export declare function read(url: string, options?: ReadOptions): Promise<void>;
+/**
+ * Dependencies injected by `src/index.ts` after Provider selection,
+ * capability support check, configuration check, Adapter construction,
+ * and adapter.reader agreement. The handler never resolves a Provider
+ * descriptor itself. Required — a caller that omits `deps` is malformed
+ * and fails loudly (a `CommandContext` is NOT a valid substitute).
+ */
+export interface ReadHandlerDependencies {
+    readonly capability: ReaderCapability;
+    readonly execution: ExecutionDependencies;
+}
+/**
+ * Read web page content through the injected Reader Capability.
+ *
+ * Ordering:
+ *   1. Parse-level validation (URL scheme, --extract mode). Throws
+ *      `ValidationError` BEFORE the Adapter or shared execution is
+ *      reached.
+ *   2. Build the Provider-neutral request and delegate to
+ *      `executeProviderOperation` with shared cache + retry policy.
+ *   3. Project the normalized result:
+ *      - `--extract` slicing into the extract envelope (sets `mode`,
+ *        `items`, `originalItemCount`); `--max-chars` is IGNORED.
+ *      - Otherwise, `--max-chars` truncation on `content` (sets
+ *        `truncated`, `originalContentLength`).
+ *   4. Set presentations so text-oriented modes (compact/markdown/
+ *      refs/tty) emit `content` directly for content reads. Extract
+ *      reads omit presentations; text modes then fall back to JSON
+ *      (the extract envelope), matching the core-flows table.
+ */
+export declare function read(url: string, options: ReadOptions | undefined, deps: ReadHandlerDependencies, _context?: CommandContext): Promise<CommandResult>;
 export declare const READ_HELP: string;
 //# sourceMappingURL=read.d.ts.map