scoutline 0.2.0 → 0.6.0

package/dist/capabilities/repository.js

@@ -0,0 +1,172 @@
+/**
+ * Provider-neutral Repository Capability Contract (DESIGN.md §18,
+ * PRD FR-081, FR-083, FR-086, FR-089; NFR-004, NFR-006, NFR-007).
+ *
+ * This module declares the three repository operations (Search, Read File,
+ * Directory Listing), their provider-neutral request, identity, cache, and
+ * result shapes, and the total normalized cache decoders used by shared
+ * execution. It imports NO concrete Provider, transport, or Adapter. It
+ * does no path canonicalization, raw ZRead parsing, Provider field
+ * mapping, Provider selection, retries, or presentation.
+ *
+ * Scope of this file:
+ *   - request, operation, cache-identity, and result type contracts;
+ *   - total decoders for the three cacheable normalized result types
+ *     (`decodeRepositorySearch`, `decodeRepositoryFile`,
+ *     `decodeRepositoryDirectoryListing`);
+ *   - the discriminated `RepositoryOperationKind` union shared by shared
+ *     execution, retry policy, and diagnostics.
+ *
+ * P6-02 introduces ONLY this contract and the decoders. P6-03 supplies
+ * shared execution, P6-04 the Z.AI Adapter, and P6-05 the Explorer. The
+ * capability surface here is the boundary between those tickets and the
+ * commands; nothing in this file is allowed to widen the boundary.
+ */
+// ===========================================================================
+// Total normalized cache decoders
+// ===========================================================================
+//
+// Every decoder accepts `unknown`, returns the typed result or `null`,
+// never throws, and never trusts a generic cast. The shape contract is
+// local; the three adapters in P6-04 are responsible for producing
+// values that conform to the Result interfaces.
+//
+// Rules encoded in each decoder:
+//   - reject primitives and arrays at the top level (results are objects);
+//   - reject required scalar fields that are missing or of the wrong
+//     type;
+//   - reject arrays that are themselves nullable or contain malformed
+//     items — partial goodness is NEVER a success;
+//   - preserve exact order, exact strings, exact numeric values;
+//   - accept an empty array as valid (a future Adapter contract).
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Type guard for a non-empty string. `""` is rejected.
+ */
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+/**
+ * Type guard for a non-negative finite integer (0 or positive, no
+ * fractional part). `Number.NaN`, `Infinity`, and negatives are rejected.
+ */
+function isNonNegativeFiniteInteger(value) {
+    return (typeof value === "number" &&
+        Number.isFinite(value) &&
+        Number.isInteger(value) &&
+        value >= 0);
+}
+/**
+ * Decode a Search result from the cache. Returns the canonical
+ * `RepositorySearchResult` on success, `null` for any malformed value.
+ */
+export function decodeRepositorySearch(value) {
+    if (!isPlainObject(value))
+        return null;
+    if (value.schemaVersion !== 1)
+        return null;
+    if (typeof value.repository !== "string")
+        return null;
+    if (typeof value.query !== "string")
+        return null;
+    const language = value.language;
+    if (language !== "en" && language !== "zh")
+        return null;
+    if (typeof value.truncated !== "boolean")
+        return null;
+    if (!isNonNegativeFiniteInteger(value.originalTextLength))
+        return null;
+    const rawExcerpts = value.excerpts;
+    if (!Array.isArray(rawExcerpts))
+        return null;
+    const excerpts = [];
+    for (const item of rawExcerpts) {
+        if (!isPlainObject(item))
+            return null;
+        if (typeof item.text !== "string")
+            return null;
+        excerpts.push({ text: item.text });
+    }
+    return {
+        schemaVersion: 1,
+        repository: value.repository,
+        query: value.query,
+        language,
+        excerpts,
+        truncated: value.truncated,
+        originalTextLength: value.originalTextLength,
+    };
+}
+/**
+ * Decode a File result from the cache. Returns the canonical
+ * `RepositoryFileResult` on success, `null` otherwise. `path` MUST be
+ * non-empty — File is always non-root; `path: ""` is rejected here
+ * without performing any other path canonicalization.
+ */
+export function decodeRepositoryFile(value) {
+    if (!isPlainObject(value))
+        return null;
+    if (value.schemaVersion !== 1)
+        return null;
+    if (typeof value.repository !== "string")
+        return null;
+    if (!isNonEmptyString(value.path))
+        return null;
+    if (typeof value.content !== "string")
+        return null;
+    if (typeof value.truncated !== "boolean")
+        return null;
+    if (!isNonNegativeFiniteInteger(value.originalContentLength))
+        return null;
+    return {
+        schemaVersion: 1,
+        repository: value.repository,
+        path: value.path,
+        content: value.content,
+        truncated: value.truncated,
+        originalContentLength: value.originalContentLength,
+    };
+}
+/**
+ * Decode a Directory Listing from the cache. Returns the canonical
+ * `RepositoryDirectoryListing` on success, `null` otherwise. The
+ * listing's own `path` may be `""` (root); every entry's `name` and
+ * `path` MUST be non-empty. Empty entries arrays are valid (a future
+ * Adapter contract). Each entry preserves Provider sibling order
+ * verbatim.
+ */
+export function decodeRepositoryDirectoryListing(value) {
+    if (!isPlainObject(value))
+        return null;
+    if (typeof value.repository !== "string")
+        return null;
+    if (typeof value.path !== "string")
+        return null;
+    const rawEntries = value.entries;
+    if (!Array.isArray(rawEntries))
+        return null;
+    const entries = [];
+    for (const item of rawEntries) {
+        if (!isPlainObject(item))
+            return null;
+        if (!isNonEmptyString(item.name))
+            return null;
+        if (!isNonEmptyString(item.path))
+            return null;
+        if (item.kind !== "file" && item.kind !== "directory")
+            return null;
+        entries.push({
+            name: item.name,
+            path: item.path,
+            kind: item.kind,
+        });
+    }
+    return {
+        repository: value.repository,
+        path: value.path,
+        entries,
+    };
+}
+//# sourceMappingURL=repository.js.map

package/dist/capabilities/repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository.js","sourceRoot":"","sources":["../../src/capabilities/repository.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AA8NH,8EAA8E;AAC9E,kCAAkC;AAClC,8EAA8E;AAC9E,EAAE;AACF,uEAAuE;AACvE,uEAAuE;AACvE,mEAAmE;AACnE,gDAAgD;AAChD,EAAE;AACF,iCAAiC;AACjC,2EAA2E;AAC3E,qEAAqE;AACrE,YAAY;AACZ,sEAAsE;AACtE,mDAAmD;AACnD,iEAAiE;AACjE,kEAAkE;AAElE,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;GAEG;AACH,SAAS,gBAAgB,CAAC,KAAc;IACtC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;AACvD,CAAC;AAED;;;GAGG;AACH,SAAS,0BAA0B,CAAC,KAAc;IAChD,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QACtB,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC;QACvB,KAAK,IAAI,CAAC,CACX,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEvC,IAAI,KAAK,CAAC,aAAa,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3C,IAAI,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACtD,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAEjD,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;IAChC,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAExD,IAAI,OAAO,KAAK,CAAC,SAAS,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACtD,IAAI,CAAC,0BAA0B,CAAC,KAAK,CAAC,kBAAkB,CAAC;QAAE,OAAO,IAAI,CAAC;IAEvE,MAAM,WAAW,GAAG,KAAK,CAAC,QAAQ,CAAC;IACnC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7C,MAAM,QAAQ,GAA8B,EAAE,CAAC;IAC/C,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QACtC,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC/C,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACrC,CAAC;IAED,OAAO;QACL,aAAa,EAAE,CAAC;QAChB,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,QAAQ;QACR,QAAQ;QACR,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,kBAAkB,EAAE,KAAK,CAAC,kBAAkB;KAC7C,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEvC,IAAI,KAAK,CAAC,aAAa,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3C,IAAI,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACtD,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/C,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACnD,IAAI,OAAO,KAAK,CAAC,SAAS,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACtD,IAAI,CAAC,0BAA0B,CAAC,KAAK,CAAC,qBAAqB,CAAC;QAAE,OAAO,IAAI,CAAC;IAE1E,OAAO;QACL,aAAa,EAAE,CAAC;QAChB,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,qBAAqB,EAAE,KAAK,CAAC,qBAAqB;KACnD,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gCAAgC,CAC9C,KAAc;IAEd,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEvC,IAAI,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACtD,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAEhD,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC;IACjC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5C,MAAM,OAAO,GAAsB,EAAE,CAAC;IACtC,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QACtC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QAC9C,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QAC9C,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW;YAAE,OAAO,IAAI,CAAC;QACnE,OAAO,CAAC,IAAI,CAAC;YACX,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;SAChB,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,OAAO;KACR,CAAC;AACJ,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"}

package/dist/commands/cache.js

@@ -0,0 +1,203 @@
+/**
+ * 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`.
+ */
+// ---------------------------------------------------------------------------
+// Pure formatting helpers
+// ---------------------------------------------------------------------------
+/**
+ * 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 function formatBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes < 0)
+        return "0 B";
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ["KB", "MB", "GB", "TB"];
+    let value = bytes / 1024;
+    let unitIndex = 0;
+    while (value >= 1024 && unitIndex < units.length - 1) {
+        value /= 1024;
+        unitIndex += 1;
+    }
+    return `${value.toFixed(1)} ${units[unitIndex]}`;
+}
+/**
+ * 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 function formatTtl(ms) {
+    if (!Number.isFinite(ms) || ms <= 0)
+        return "0s";
+    if (ms % 3_600_000 === 0)
+        return `${ms / 3_600_000}h`;
+    if (ms % 60_000 === 0)
+        return `${ms / 60_000}m`;
+    return `${Math.round(ms / 1000)}s`;
+}
+/**
+ * Format the size cap (bytes) as e.g. `"100MB"`. Mirrors the
+ * `SCOUTLINE_CACHE_SIZE_MB` env-var spelling so the operator surface
+ * matches the documentation.
+ */
+function formatSizeCap(bytes) {
+    return `${Math.round(bytes / (1024 * 1024))}MB`;
+}
+/**
+ * Pluralize "entry"/"entries" for a count.
+ */
+function pluralEntry(count) {
+    return count === 1 ? "entry" : "entries";
+}
+/**
+ * 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 function formatCacheStats(stats) {
+    const lines = [];
+    lines.push(`Cache directory: ${stats.dir}`);
+    if (stats.enabled) {
+        lines.push(`Status: enabled (TTL ${formatTtl(stats.ttlMs)}, cap ${formatSizeCap(stats.sizeCapBytes)})`);
+    }
+    else {
+        lines.push(`Status: disabled`);
+    }
+    lines.push("");
+    lines.push("Response cache:");
+    lines.push(`  Entries: ${stats.responseCache.entries}`);
+    lines.push(`  Size: ${formatBytes(stats.responseCache.totalBytes)}`);
+    lines.push("");
+    lines.push("Tool cache:");
+    lines.push(`  Entries: ${stats.toolCache.entries}`);
+    lines.push(`  Size: ${formatBytes(stats.toolCache.totalBytes)}`);
+    return lines.join("\n");
+}
+/**
+ * Format a clear result as a one-line TTY notice.
+ */
+export function formatCacheClear(result) {
+    return (`Cleared ${result.responsesCleared} response ${pluralEntry(result.responsesCleared)} ` +
+        `and ${result.toolsCleared} tool ${pluralEntry(result.toolsCleared)} ` +
+        `(${formatBytes(result.bytesFreed)} freed)`);
+}
+/**
+ * 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 function formatDoctorCacheSummary(stats) {
+    if (!stats.enabled)
+        return "Cache: disabled";
+    return (`Cache: enabled, ${stats.responseCache.entries} response ${pluralEntry(stats.responseCache.entries)} ` +
+        `(${formatBytes(stats.responseCache.totalBytes)}), ${stats.toolCache.entries} tool ${pluralEntry(stats.toolCache.entries)} ` +
+        `(${formatBytes(stats.toolCache.totalBytes)}), ${stats.dir}`);
+}
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+/** All text modes share the same multi-line inventory rendering. */
+function statsPresentations(stats) {
+    const text = formatCacheStats(stats);
+    return { compact: text, markdown: text, refs: text, tty: text };
+}
+/** All text modes share the same one-line clear notice. */
+function clearPresentations(result) {
+    const text = formatCacheClear(result);
+    return { compact: text, markdown: text, refs: text, tty: text };
+}
+/**
+ * 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 async function cacheStatsCommand(deps) {
+    const stats = await deps.getStats();
+    return {
+        kind: "data",
+        data: stats,
+        presentations: statsPresentations(stats),
+    };
+}
+/**
+ * Run the `cache clear` subcommand. Returns the count of cleared
+ * entries and bytes freed as base data with a TTY presentation
+ * override.
+ */
+export async function cacheClearCommand(deps) {
+    const result = await deps.clear();
+    return {
+        kind: "data",
+        data: result,
+        presentations: clearPresentations(result),
+    };
+}
+export const CACHE_HELP = `
+Cache - Inspect and clear the local cache
+
+Usage:
+  scoutline cache stats   # show inventory of both cache subdirectories
+  scoutline cache clear   # delete every file in both cache subdirectories
+
+Subcommands:
+  stats   Print the cache directory, status (enabled/disabled, TTL, size
+          cap), and per-subdirectory entry count and total size for both
+          the response cache (~/.scoutline/cache/) and the tool cache
+          (~/.scoutline/tools/).
+  clear   Delete every file under <root>/cache/ and <root>/tools/. The
+          directories themselves are preserved so the next invocation
+          recreates entries without a directory-creation race. The
+          orphaned legacy ~/.cache/zai-cli/ directory is never touched.
+
+The cache root defaults to ~/.scoutline/ on every platform; override it
+with SCOUTLINE_CACHE_DIR (ZAI_MCP_CACHE_DIR and ZAI_CACHE_DIR are
+accepted as lower-precedence legacy aliases). Disable both caches with
+SCOUTLINE_CACHE=0 (legacy alias: ZAI_CACHE=0).
+
+Exit codes:
+  0  Success.
+  1  I/O error (reported as a sanitized JSON error envelope).
+
+Examples:
+  scoutline cache stats
+  scoutline cache clear
+  scoutline cache --help
+`.trim();
+//# sourceMappingURL=cache.js.map

package/dist/commands/cache.js.map

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

package/dist/commands/doctor.d.ts

@@ -27,14 +27,25 @@ export interface DoctorDiagnosticsDependencies {
     readonly env: NodeJS.ProcessEnv;
     readonly sleep: (ms: number) => Promise<void>;
     readonly random: () => number;
+    /**
+     * Pre-formatted one-line cache summary (Cache Module Unification
+     * Ticket 03). The dispatcher formats this from `cacheStats()` output
+     * before invoking the report builder; the report builder only embeds
+     * it. Optional for backward compatibility with existing tests that
+     * don't cover the cache surface. When omitted, the returned report
+     * simply leaves out the `cache` field.
+     */
+    readonly cacheSummary?: string;
 }
 /**
- * Build a schema-version-1 {@link DiagnosticsReport}. Report metadata is
- * built from static descriptors without constructing any Adapter. 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.
+ * 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 declare function buildDiagnosticsReport(deps: DoctorDiagnosticsDependencies): Promise<DiagnosticsReport>;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAEV,iBAAiB,EAElB,MAAM,gCAAgC,CAAC;AASxC,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAsB,MAAM,uBAAuB,CAAC;AAMhG,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,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;AA6CD;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,6BAA6B,GAClC,OAAO,CAAC,iBAAiB,CAAC,CA4B5B;AA4CD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAKhE;AAMD,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACxD;AAED;;;;GAIG;AACH,wBAAsB,MAAM,CAC1B,IAAI,EAAE,yBAAyB,GAC9B,OAAO,CAAC,aAAa,CAAC,iBAAiB,CAAC,CAAC,CAO3C;AAED,eAAO,MAAM,WAAW,QAqChB,CAAC"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAEV,iBAAiB,EAElB,MAAM,gCAAgC,CAAC;AASxC,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAsB,MAAM,uBAAuB,CAAC;AAMhG,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,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;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AA6CD;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,6BAA6B,GAClC,OAAO,CAAC,iBAAiB,CAAC,CAkC5B;AA4CD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAKhE;AAMD,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACxD;AAED;;;;GAIG;AACH,wBAAsB,MAAM,CAC1B,IAAI,EAAE,yBAAyB,GAC9B,OAAO,CAAC,aAAa,CAAC,iBAAiB,CAAC,CAAC,CAO3C;AAED,eAAO,MAAM,WAAW,QAuDhB,CAAC"}

package/dist/commands/doctor.js

@@ -17,7 +17,7 @@
  * Under `--no-tools` the command returns after metadata + configured-state
  * evaluation and constructs no Adapter and no transport (FR-034).
  */
-import { SHARED_CAPABILITIES, ZAI_ONLY_CAPABILITIES, diagnosticErrorFromError, } from "../capabilities/diagnostics.js";
+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";
@@ -43,12 +43,14 @@ async function probeProvider(descriptor, env, sleep, random) {
     });
 }
 /**
- * Build a schema-version-1 {@link DiagnosticsReport}. Report metadata is
- * built from static descriptors without constructing any Adapter. 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.
+ * 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);
@@ -64,16 +66,21 @@ export async function buildDiagnosticsReport(deps) {
             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: SHARED_CAPABILITIES,
-        zaiOnlyCapabilities: ZAI_ONLY_CAPABILITIES,
+        sharedCapabilities: deriveSharedCapabilities(deps.descriptors),
+        zaiOnlyCapabilities: deriveZaiOnlyCapabilities(deps.descriptors),
         node: {
             version: process.version,
             visionMcpCompatible: nodeMajor() >= 22,
         },
         providers,
+        ...(cache !== undefined ? { cache } : {}),
     };
 }
 /**
@@ -140,18 +147,36 @@ 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:
-
-  search, vision.interpret-image, quota, diagnostics
+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.
 
-The following Capabilities are Z.AI-only in the base release and are
-not selected by the effective Provider for other families:
-  reader, repository-exploration, raw-provider-tools, code-mode,
-  image-diff, video-analysis
+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 every connectivity probe (metadata-only). Under
@@ -162,7 +187,7 @@ Options:
 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.
+       failed; successful entries are still reported.
 
 Examples:
   scoutline doctor                 # full diagnostics