scoutline 0.1.0 → 0.6.0

package/dist/capabilities/vision.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Provider Vision Capability (DESIGN.md §8, PRD FR-020, FR-022 to FR-026,
+ * FR-050, NFR-004, NFR-006).
+ *
+ * Defines the normalized Vision Capability shared by every Provider that
+ * supports single-image interpretation. Commands pass a `VisionRequest`
+ * (a discriminated union over the eight operation shapes) and the
+ * shared `invokeVision` helper:
+ *
+ *   1. Maps the operation to a stable `vision.<operation>` Capability id.
+ *   2. Reads descriptor-level capability metadata (pure; no Adapter
+ *      construction). If the descriptor does not advertise the
+ *      Capability, throws `UnsupportedCapabilityError(provider, ...)`
+ *      BEFORE `descriptor.create()` is called. No credentials, no media,
+ *      no transport, no cache, no fallback Adapter are observed.
+ *   3. Calls `descriptor.create(context)` and defensively double-checks
+ *      the Adapter's `supports(operation)`. If the Adapter says no,
+ *      throws the same error before `invoke` runs.
+ *   4. Calls `adapter.vision.invoke(request)` and returns the normalized
+ *      text. Vision never uses the response cache and never falls back
+ *      to another Provider.
+ *
+ * This module imports no Provider transport and no Provider Adapter.
+ * The error class import below is from `lib/errors.ts` (a shared error
+ * contract, not Provider transport), which is the existing boundary
+ * pattern for the Search Capability Module. The retry wrapper lives
+ * above `invokeVision` and passes a `() => Promise<string>` closure so
+ * Vision can be invoked through `executeProviderOperation("vision",
+ * ...)` (DESIGN.md §10) without coupling this file to that contract.
+ *
+ * P3-01 introduces only the contract + the early-fail ordering proof.
+ * Real Z.AI and MiniMax `vision` Adapters arrive in P3-03; the
+ * built-in descriptor factories in `providers/types.ts` advertise
+ * `vision.<operation>` Capability metadata now so the support check is
+ * wired through descriptor metadata from the start.
+ */
+/**
+ * A Provider-neutral Vision request. Commands construct one of these
+ * shapes from their semantic arguments; Adapters map them to the
+ * Provider's transport shape. Adding a new operation requires extending
+ * this union, the `ProviderCapability` union in `providers/types.ts`,
+ * and the `ALL_VISION_OPERATIONS` set below.
+ */
+export type VisionRequest = {
+    operation: "interpret-image";
+    source: string;
+    instruction: string;
+} | {
+    operation: "ui-artifact";
+    source: string;
+    instruction: string;
+    outputType: "code" | "prompt" | "spec" | "description";
+} | {
+    operation: "extract-text";
+    source: string;
+    instruction: string;
+    programmingLanguage?: string;
+} | {
+    operation: "diagnose-error";
+    source: string;
+    instruction: string;
+    context?: string;
+} | {
+    operation: "diagram";
+    source: string;
+    instruction: string;
+    diagramType?: string;
+} | {
+    operation: "chart";
+    source: string;
+    instruction: string;
+    focus?: string;
+} | {
+    operation: "diff";
+    expectedSource: string;
+    actualSource: string;
+    instruction: string;
+} | {
+    operation: "video";
+    source: string;
+    instruction: string;
+};
+/** Convenience: the set of every supported operation. */
+export type VisionOperation = VisionRequest["operation"];
+/** Every operation that exists in the discriminated union. */
+export declare const ALL_VISION_OPERATIONS: ReadonlySet<VisionOperation>;
+/**
+ * Stable Capability id for a Vision operation. Each id matches a member
+ * of the `ProviderCapability` union declared in `providers/types.ts`.
+ * This mapping is the single source of truth: Adapters advertise the id;
+ * `invokeVision` reads it; commands never branch on the id directly.
+ */
+export declare function visionOperationToCapability(operation: VisionOperation): "vision.interpret-image" | "vision.ui-artifact" | "vision.extract-text" | "vision.diagnose-error" | "vision.diagram" | "vision.chart" | "vision.diff" | "vision.video";
+/**
+ * Vision Capability contract. Every Adapter that supports a Vision
+ * operation implements this interface and exposes it as `adapter.vision`.
+ * The Adapter owns Provider field mapping, transport, and credentials;
+ * commands call only these two methods.
+ *
+ * `supports` is a pure metadata check. It MUST NOT construct a
+ * transport, read a credential, inspect a source, or perform I/O. The
+ * shared `invokeVision` helper uses descriptor metadata first and
+ * `supports` only as a defensive double-check after `create()`.
+ */
+export interface VisionCapability {
+    /**
+     * Report whether the Adapter can perform `operation` against the
+     * current environment. Pure metadata; no construction.
+     */
+    supports(operation: VisionOperation): boolean;
+    /**
+     * Invoke the Provider and return the normalized text result. The
+     * Adapter owns credentials, transport lifecycle, Provider field
+     * mapping, and failure normalization. The Adapter closes its
+     * transport and never retries inside this method.
+     */
+    invoke(request: VisionRequest): Promise<string>;
+}
+/**
+ * Minimal Adapter shape `invokeVision` needs. Defined here (instead of
+ * importing from `providers/types.ts`) so this file remains free of
+ * any Provider imports — the Boundary rule for Capability Modules
+ * (ARCHITECTURE.md §2).
+ *
+ * The descriptor's `create(context)` returns a `ProviderAdapter`; the
+ * shared helper accepts anything that exposes `id` and an optional
+ * `vision` VisionCapability, matching the Phase 3 ProviderAdapter
+ * shape defined in DESIGN.md §5.
+ */
+export interface VisionInvocationDescriptor {
+    readonly id: string;
+    capabilities(): ReadonlySet<string>;
+    create(context: {
+        readonly env: NodeJS.ProcessEnv;
+    }): {
+        readonly id: string;
+        readonly vision?: VisionCapability;
+    };
+}
+/**
+ * Invoke a Vision request through a Provider descriptor. The support
+ * check happens BEFORE `descriptor.create()` (using descriptor
+ * metadata) and is then double-checked against the Adapter's
+ * `supports` after construction. Failures throw
+ * `UnsupportedCapabilityError` and never touch credentials, media,
+ * transport, cache, or a fallback Adapter.
+ *
+ * Phase 3 P3-01 introduces the contract and the early-fail ordering
+ * proof; Phase 3 P3-03 supplies the real Adapter implementations.
+ * Until then the built-in descriptors advertise metadata so the
+ * ordering is provable today.
+ */
+export declare function invokeVision(descriptor: VisionInvocationDescriptor, request: VisionRequest, context: {
+    readonly env: NodeJS.ProcessEnv;
+}): Promise<string>;
+//# sourceMappingURL=vision.d.ts.map

package/dist/capabilities/vision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision.d.ts","sourceRoot":"","sources":["../../src/capabilities/vision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAQH;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GACrB;IACE,SAAS,EAAE,iBAAiB,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB,GACD;IACE,SAAS,EAAE,aAAa,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,aAAa,CAAC;CACxD,GACD;IACE,SAAS,EAAE,cAAc,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,GACD;IACE,SAAS,EAAE,gBAAgB,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACD;IACE,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GACD;IACE,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GACD;IACE,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB,GACD;IACE,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEN,yDAAyD;AACzD,MAAM,MAAM,eAAe,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;AAEzD,8DAA8D;AAC9D,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,eAAe,CAS7D,CAAC;AAMH;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,eAAe,GAExB,wBAAwB,GACxB,oBAAoB,GACpB,qBAAqB,GACrB,uBAAuB,GACvB,gBAAgB,GAChB,cAAc,GACd,aAAa,GACb,cAAc,CAmBjB;AAMD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,eAAe,GAAG,OAAO,CAAC;IAE9C;;;;;OAKG;IACH,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACjD;AAMD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,YAAY,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;IACpC,MAAM,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAA;KAAE,GAAG;QACpD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC;KACpC,CAAC;CACH;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,0BAA0B,EACtC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAA;CAAE,GAC3C,OAAO,CAAC,MAAM,CAAC,CAuBjB"}

package/dist/capabilities/vision.js

@@ -0,0 +1,111 @@
+/**
+ * Provider Vision Capability (DESIGN.md §8, PRD FR-020, FR-022 to FR-026,
+ * FR-050, NFR-004, NFR-006).
+ *
+ * Defines the normalized Vision Capability shared by every Provider that
+ * supports single-image interpretation. Commands pass a `VisionRequest`
+ * (a discriminated union over the eight operation shapes) and the
+ * shared `invokeVision` helper:
+ *
+ *   1. Maps the operation to a stable `vision.<operation>` Capability id.
+ *   2. Reads descriptor-level capability metadata (pure; no Adapter
+ *      construction). If the descriptor does not advertise the
+ *      Capability, throws `UnsupportedCapabilityError(provider, ...)`
+ *      BEFORE `descriptor.create()` is called. No credentials, no media,
+ *      no transport, no cache, no fallback Adapter are observed.
+ *   3. Calls `descriptor.create(context)` and defensively double-checks
+ *      the Adapter's `supports(operation)`. If the Adapter says no,
+ *      throws the same error before `invoke` runs.
+ *   4. Calls `adapter.vision.invoke(request)` and returns the normalized
+ *      text. Vision never uses the response cache and never falls back
+ *      to another Provider.
+ *
+ * This module imports no Provider transport and no Provider Adapter.
+ * The error class import below is from `lib/errors.ts` (a shared error
+ * contract, not Provider transport), which is the existing boundary
+ * pattern for the Search Capability Module. The retry wrapper lives
+ * above `invokeVision` and passes a `() => Promise<string>` closure so
+ * Vision can be invoked through `executeProviderOperation("vision",
+ * ...)` (DESIGN.md §10) without coupling this file to that contract.
+ *
+ * P3-01 introduces only the contract + the early-fail ordering proof.
+ * Real Z.AI and MiniMax `vision` Adapters arrive in P3-03; the
+ * built-in descriptor factories in `providers/types.ts` advertise
+ * `vision.<operation>` Capability metadata now so the support check is
+ * wired through descriptor metadata from the start.
+ */
+import { UnsupportedCapabilityError } from "../lib/errors.js";
+/** Every operation that exists in the discriminated union. */
+export const ALL_VISION_OPERATIONS = new Set([
+    "interpret-image",
+    "ui-artifact",
+    "extract-text",
+    "diagnose-error",
+    "diagram",
+    "chart",
+    "diff",
+    "video",
+]);
+// ---------------------------------------------------------------------------
+// Operation → Capability id mapping (no Provider imports)
+// ---------------------------------------------------------------------------
+/**
+ * Stable Capability id for a Vision operation. Each id matches a member
+ * of the `ProviderCapability` union declared in `providers/types.ts`.
+ * This mapping is the single source of truth: Adapters advertise the id;
+ * `invokeVision` reads it; commands never branch on the id directly.
+ */
+export function visionOperationToCapability(operation) {
+    switch (operation) {
+        case "interpret-image":
+            return "vision.interpret-image";
+        case "ui-artifact":
+            return "vision.ui-artifact";
+        case "extract-text":
+            return "vision.extract-text";
+        case "diagnose-error":
+            return "vision.diagnose-error";
+        case "diagram":
+            return "vision.diagram";
+        case "chart":
+            return "vision.chart";
+        case "diff":
+            return "vision.diff";
+        case "video":
+            return "vision.video";
+    }
+}
+/**
+ * Invoke a Vision request through a Provider descriptor. The support
+ * check happens BEFORE `descriptor.create()` (using descriptor
+ * metadata) and is then double-checked against the Adapter's
+ * `supports` after construction. Failures throw
+ * `UnsupportedCapabilityError` and never touch credentials, media,
+ * transport, cache, or a fallback Adapter.
+ *
+ * Phase 3 P3-01 introduces the contract and the early-fail ordering
+ * proof; Phase 3 P3-03 supplies the real Adapter implementations.
+ * Until then the built-in descriptors advertise metadata so the
+ * ordering is provable today.
+ */
+export async function invokeVision(descriptor, request, context) {
+    const capabilityId = visionOperationToCapability(request.operation);
+    // Step 1: descriptor-level metadata. NO create(), NO construction.
+    if (!descriptor.capabilities().has(capabilityId)) {
+        throw new UnsupportedCapabilityError(descriptor.id, capabilityId);
+    }
+    // Step 2: create() is allowed now — it is side-effect-free, only
+    // captures the injected env. Credentials, transport, and SDK are
+    // built lazily inside Capability invocation.
+    const adapter = descriptor.create(context);
+    // Step 3: defensive double-check against the Adapter's own metadata.
+    // If the Adapter says no, fail closed before invoke runs.
+    const vision = adapter.vision;
+    if (!vision || !vision.supports(request.operation)) {
+        throw new UnsupportedCapabilityError(descriptor.id, capabilityId);
+    }
+    // Step 4: invoke. No cache lookup, no fallback Adapter. Retries live
+    // above this call in `executeProviderOperation("vision", ...)`.
+    return vision.invoke(request);
+}
+//# sourceMappingURL=vision.js.map

package/dist/capabilities/vision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision.js","sourceRoot":"","sources":["../../src/capabilities/vision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAgE9D,8DAA8D;AAC9D,MAAM,CAAC,MAAM,qBAAqB,GAAiC,IAAI,GAAG,CAAC;IACzE,iBAAiB;IACjB,aAAa;IACb,cAAc;IACd,gBAAgB;IAChB,SAAS;IACT,OAAO;IACP,MAAM;IACN,OAAO;CACR,CAAC,CAAC;AAEH,8EAA8E;AAC9E,0DAA0D;AAC1D,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B,CACzC,SAA0B;IAU1B,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,iBAAiB;YACpB,OAAO,wBAAwB,CAAC;QAClC,KAAK,aAAa;YAChB,OAAO,oBAAoB,CAAC;QAC9B,KAAK,cAAc;YACjB,OAAO,qBAAqB,CAAC;QAC/B,KAAK,gBAAgB;YACnB,OAAO,uBAAuB,CAAC;QACjC,KAAK,SAAS;YACZ,OAAO,gBAAgB,CAAC;QAC1B,KAAK,OAAO;YACV,OAAO,cAAc,CAAC;QACxB,KAAK,MAAM;YACT,OAAO,aAAa,CAAC;QACvB,KAAK,OAAO;YACV,OAAO,cAAc,CAAC;IAC1B,CAAC;AACH,CAAC;AAyDD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,UAAsC,EACtC,OAAsB,EACtB,OAA4C;IAE5C,MAAM,YAAY,GAAG,2BAA2B,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEpE,mEAAmE;IACnE,IAAI,CAAC,UAAU,CAAC,YAAY,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,0BAA0B,CAAC,UAAU,CAAC,EAAE,EAAE,YAAY,CAAC,CAAC;IACpE,CAAC;IAED,iEAAiE;IACjE,iEAAiE;IACjE,6CAA6C;IAC7C,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAE3C,qEAAqE;IACrE,0DAA0D;IAC1D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC9B,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,0BAA0B,CAAC,UAAU,CAAC,EAAE,EAAE,YAAY,CAAC,CAAC;IACpE,CAAC;IAED,qEAAqE;IACrE,gEAAgE;IAChE,OAAO,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AAChC,CAAC"}

package/dist/command-invocation.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Command Invocation Seam (DESIGN.md §2).
+ *
+ * This Module defines the pure invocation contract that separates
+ * command behaviour from process effects. `invokeCommand` owns
+ * invocation-local presentation, notice storage, and error conversion.
+ * The Node Adapter is the only Module that touches process streams,
+ * TTY state, and `process.exitCode`.
+ *
+ * Requirements: NFR-002, NFR-003, NFR-007.
+ */
+import type { OutputMode } from "./lib/output.js";
+export type TextOutputMode = "compact" | "markdown" | "refs" | "tty";
+export type CommandPresentations = Readonly<Partial<Record<TextOutputMode, string>>>;
+export interface DataCommandResult<T = unknown> {
+    readonly kind: "data";
+    readonly data: T;
+    readonly presentations?: CommandPresentations;
+    readonly exitCode?: number;
+}
+export interface TextCommandResult {
+    readonly kind: "text";
+    readonly text: string;
+    readonly exitCode?: number;
+}
+export type CommandResult<T = unknown> = DataCommandResult<T> | TextCommandResult;
+export interface CommandContext {
+    readonly stdinIsTTY: boolean;
+    readStdin(): Promise<string>;
+    notice(message: string): void;
+}
+export interface CommandInvocationAdapter {
+    readonly stdoutIsTTY: boolean;
+    readonly stdinIsTTY: boolean;
+    readonly environmentOutputMode?: string;
+    readStdin(): Promise<string>;
+    writeStdout(value: string): void;
+    writeStderr(value: string): void;
+    runQuietly<T>(operation: () => Promise<T>): Promise<T>;
+    setExitCode(value: number): void;
+}
+/**
+ * Run command behaviour through the invocation seam.
+ *
+ * 1. Create invocation-local context and notice storage.
+ * 2. Run command behaviour through `runQuietly`.
+ * 3. `runQuietly` restores dependency logging before returning.
+ * 4. Flush notices to stderr in encounter order.
+ * 5. Select a presentation override or the base data.
+ * 6. Write one final successful value to stdout.
+ * 7. Convert a thrown error into one structured stderr value.
+ * 8. Return an exit status without terminating the process.
+ *
+ * The trailing newline is appended at the Node Adapter boundary, not
+ * here, so `invokeCommand` itself is process-effect-free.
+ */
+export declare function invokeCommand(adapter: CommandInvocationAdapter, behavior: (context: CommandContext) => Promise<CommandResult>, outputMode: OutputMode, now?: () => number, secrets?: string[]): Promise<number>;
+//# sourceMappingURL=command-invocation.d.ts.map

package/dist/command-invocation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-invocation.d.ts","sourceRoot":"","sources":["../src/command-invocation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAKlD,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,GAAG,KAAK,CAAC;AAErE,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;AAErF,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,OAAO;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,aAAa,CAAC,EAAE,oBAAoB,CAAC;IAC9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,OAAO,IAAI,iBAAiB,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC;AAElF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7B,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IACxC,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7B,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,UAAU,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACvD,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAkCD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,wBAAwB,EACjC,QAAQ,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,aAAa,CAAC,EAC7D,UAAU,EAAE,UAAU,EACtB,GAAG,GAAE,MAAM,MAAiB,EAC5B,OAAO,CAAC,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,MAAM,CAAC,CAyCjB"}

package/dist/command-invocation.js

@@ -0,0 +1,95 @@
+/**
+ * Command Invocation Seam (DESIGN.md §2).
+ *
+ * This Module defines the pure invocation contract that separates
+ * command behaviour from process effects. `invokeCommand` owns
+ * invocation-local presentation, notice storage, and error conversion.
+ * The Node Adapter is the only Module that touches process streams,
+ * TTY state, and `process.exitCode`.
+ *
+ * Requirements: NFR-002, NFR-003, NFR-007.
+ */
+import { formatSuccessOutput, formatErrorOutput } from "./lib/output.js";
+import { getErrorExitCode } from "./lib/errors.js";
+import { redactSecrets, configuredSecrets } from "./lib/redact.js";
+const TEXT_OUTPUT_MODES = ["compact", "markdown", "refs", "tty"];
+function isTextOutputMode(mode) {
+    return TEXT_OUTPUT_MODES.includes(mode);
+}
+/**
+ * Select the final output string for a successful CommandResult.
+ *
+ * - `TextCommandResult`: the text is used verbatim regardless of mode.
+ * - `DataCommandResult` in a text-oriented mode: a command-supplied
+ *   presentation override is preferred; otherwise the base data is
+ *   formatted through `formatSuccessOutput`.
+ * - `DataCommandResult` in a data-oriented mode: base data formatted
+ *   through `formatSuccessOutput` (data → raw JSON, json/pretty →
+ *   success envelope).
+ */
+function selectOutput(result, outputMode, now) {
+    if (result.kind === "text") {
+        return result.text;
+    }
+    if (isTextOutputMode(outputMode)) {
+        const override = result.presentations?.[outputMode];
+        if (typeof override === "string") {
+            return override;
+        }
+    }
+    return formatSuccessOutput(result.data, outputMode, now);
+}
+/**
+ * Run command behaviour through the invocation seam.
+ *
+ * 1. Create invocation-local context and notice storage.
+ * 2. Run command behaviour through `runQuietly`.
+ * 3. `runQuietly` restores dependency logging before returning.
+ * 4. Flush notices to stderr in encounter order.
+ * 5. Select a presentation override or the base data.
+ * 6. Write one final successful value to stdout.
+ * 7. Convert a thrown error into one structured stderr value.
+ * 8. Return an exit status without terminating the process.
+ *
+ * The trailing newline is appended at the Node Adapter boundary, not
+ * here, so `invokeCommand` itself is process-effect-free.
+ */
+export async function invokeCommand(adapter, behavior, outputMode, now = Date.now, secrets) {
+    const notices = [];
+    const context = {
+        stdinIsTTY: adapter.stdinIsTTY,
+        readStdin: () => adapter.readStdin(),
+        notice: (message) => {
+            notices.push(message);
+        },
+    };
+    let result;
+    try {
+        result = await adapter.runQuietly(() => behavior(context));
+    }
+    catch (error) {
+        for (const notice of notices) {
+            adapter.writeStderr(notice);
+        }
+        // Recursively redact the thrown value at the outward boundary so any
+        // credential-shaped field embedded in the error tree — whether in
+        // `message`, `cause`, or any custom field — is replaced with the
+        // redaction marker before formatting. `formatErrorOutput` then
+        // performs an additional string-level pass on the message/help
+        // fields it actually serialises.
+        //
+        // B3: secrets resolved from an injected env (MainDependencies.env)
+        // are honoured here so a credential that exists only in the injected
+        // env is redacted even when absent from ambient process.env.
+        const resolvedSecrets = secrets ?? configuredSecrets();
+        const redactedError = redactSecrets(error, resolvedSecrets);
+        adapter.writeStderr(formatErrorOutput(redactedError, outputMode, resolvedSecrets));
+        return getErrorExitCode(error);
+    }
+    for (const notice of notices) {
+        adapter.writeStderr(notice);
+    }
+    adapter.writeStdout(selectOutput(result, outputMode, now));
+    return result.exitCode ?? 0;
+}
+//# sourceMappingURL=command-invocation.js.map

package/dist/command-invocation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-invocation.js","sourceRoot":"","sources":["../src/command-invocation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAsCnE,MAAM,iBAAiB,GAA8B,CAAC,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;AAE5F,SAAS,gBAAgB,CAAC,IAAgB;IACxC,OAAQ,iBAAuC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACjE,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,YAAY,CAAC,MAAqB,EAAE,UAAsB,EAAE,GAAiB;IACpF,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC3B,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;IAED,IAAI,gBAAgB,CAAC,UAAU,CAAC,EAAE,CAAC;QACjC,MAAM,QAAQ,GAAG,MAAM,CAAC,aAAa,EAAE,CAAC,UAAU,CAAC,CAAC;QACpD,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACjC,OAAO,QAAQ,CAAC;QAClB,CAAC;IACH,CAAC;IAED,OAAO,mBAAmB,CAAC,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAAiC,EACjC,QAA6D,EAC7D,UAAsB,EACtB,GAAG,GAAiB,IAAI,CAAC,GAAG,EAC5B,OAAkB;IAElB,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,MAAM,OAAO,GAAmB;QAC9B,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,SAAS,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE;QACpC,MAAM,EAAE,CAAC,OAAe,EAAE,EAAE;YAC1B,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;KACF,CAAC;IAEF,IAAI,MAAqB,CAAC;IAC1B,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IAC7D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;QACD,qEAAqE;QACrE,kEAAkE;QAClE,iEAAiE;QACjE,+DAA+D;QAC/D,+DAA+D;QAC/D,iCAAiC;QACjC,EAAE;QACF,mEAAmE;QACnE,qEAAqE;QACrE,6DAA6D;QAC7D,MAAM,eAAe,GAAG,OAAO,IAAI,iBAAiB,EAAE,CAAC;QACvD,MAAM,aAAa,GAAG,aAAa,CAAC,KAAK,EAAE,eAAe,CAAY,CAAC;QACvE,OAAO,CAAC,WAAW,CAAC,iBAAiB,CAAC,aAAa,EAAE,UAAU,EAAE,eAAe,CAAC,CAAC,CAAC;QACnF,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;IAED,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAED,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC;IAE3D,OAAO,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAC;AAC9B,CAAC"}

package/dist/commands/cache.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Cache command — local cache inspection and clearing
+ * (Cache Module Unification Ticket 03).
+ *
+ * The command is presentation-only: it receives already-resolved stats
+ * or clear results through injected dependencies and wraps them with a
+ * TTY presentation override. Directory resolution, env-var policy, and
+ * on-disk I/O live in `src/lib/cache.ts` (Ticket 01). The dispatcher
+ * (`src/index.ts`) wires production to the real `cacheStats()` and
+ * `clearAllCaches()` and threads them through these dependencies; tests
+ * inject doubles.
+ *
+ * Output format (core-flows artifact):
+ *
+ * ```text
+ * Cache directory: ~/.scoutline/
+ * Status: enabled (TTL 24h, cap 100MB)
+ *
+ * Response cache:
+ *   Entries: 47
+ *   Size: 12.3 MB
+ *
+ * Tool cache:
+ *   Entries: 1
+ *   Size: 8.2 KB
+ * ```
+ *
+ * L1 fix: Doctor's one-line cache summary is computed from the same
+ * `cacheStats()` shape but formatted by the dispatcher, not by this
+ * module. See `formatDoctorCacheSummary`.
+ */
+import type { CommandResult } from "../command-invocation.js";
+export interface CacheStatsReport {
+    readonly dir: string;
+    readonly enabled: boolean;
+    readonly ttlMs: number;
+    readonly sizeCapBytes: number;
+    readonly responseCache: {
+        readonly entries: number;
+        readonly totalBytes: number;
+    };
+    readonly toolCache: {
+        readonly entries: number;
+        readonly totalBytes: number;
+    };
+}
+export interface CacheClearReport {
+    readonly responsesCleared: number;
+    readonly toolsCleared: number;
+    readonly bytesFreed: number;
+}
+/**
+ * Format a byte count as e.g. `"12.3 MB"`, `"8.2 KB"`, `"510 B"`. Used
+ * by `cache stats` presentation and by Doctor's one-line summary. Pure:
+ * no I/O, no env reads.
+ */
+export declare function formatBytes(bytes: number): string;
+/**
+ * Format a TTL in ms as `"24h"`, `"30m"`, or `"60s"`. Chooses the
+ * largest whole-unit that divides the input evenly so the default
+ * 24h renders as `24h` rather than `86400000ms`.
+ */
+export declare function formatTtl(ms: number): string;
+/**
+ * Format the inventory of both caches as a multi-line TTY block per
+ * the core-flows artifact. Used as the TTY/compact/markdown/refs
+ * presentation for `cache stats`. Pure.
+ */
+export declare function formatCacheStats(stats: CacheStatsReport): string;
+/**
+ * Format a clear result as a one-line TTY notice.
+ */
+export declare function formatCacheClear(result: CacheClearReport): string;
+/**
+ * Format the one-line Doctor cache summary from a `cacheStats()` value.
+ * The dispatcher calls this before invoking `buildDiagnosticsReport`;
+ * the report builder embeds the result verbatim. Examples:
+ *
+ * ```text
+ * Cache: enabled, 47 response entries (12.3 MB), 1 tool entry (8.2 KB), ~/.scoutline/
+ * Cache: disabled
+ * ```
+ *
+ * Pure: never reads env or touches the filesystem.
+ */
+export declare function formatDoctorCacheSummary(stats: CacheStatsReport): string;
+export interface CacheStatsDependencies {
+    readonly getStats: () => Promise<CacheStatsReport>;
+}
+export interface CacheClearDependencies {
+    readonly clear: () => Promise<CacheClearReport>;
+}
+/**
+ * Run the `cache stats` subcommand. Returns the inventory as base data
+ * with a TTY presentation override. Exit code is always 0 on success;
+ * I/O failures propagate as ordinary errors through the dispatcher.
+ */
+export declare function cacheStatsCommand(deps: CacheStatsDependencies): Promise<CommandResult<CacheStatsReport>>;
+/**
+ * Run the `cache clear` subcommand. Returns the count of cleared
+ * entries and bytes freed as base data with a TTY presentation
+ * override.
+ */
+export declare function cacheClearCommand(deps: CacheClearDependencies): Promise<CommandResult<CacheClearReport>>;
+export declare const CACHE_HELP: string;
+//# sourceMappingURL=cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/commands/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAkB,MAAM,0BAA0B,CAAC;AAS9E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAClF,QAAQ,CAAC,SAAS,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/E;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAMD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWjD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAK5C;AAkBD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAmBhE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAMjE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAOxE;AAMD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACjD;AAkBD;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,aAAa,CAAC,gBAAgB,CAAC,CAAC,CAO1C;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,aAAa,CAAC,gBAAgB,CAAC,CAAC,CAO1C;AAED,eAAO,MAAM,UAAU,QA8Bf,CAAC"}