scoutline 0.1.0 → 0.6.0

package/dist/capabilities/reader.js

@@ -0,0 +1,100 @@
+/**
+ * Provider-neutral Reader Capability Contract (core-flows D1, D2;
+ * tech-plan D1, D2).
+ *
+ * This module declares the single Reader operation (`reader-fetch`), its
+ * provider-neutral request, identity, cache, and result shapes, the total
+ * normalized cache decoder, and the `ReaderRawResponse` type capturing
+ * what the Z.AI WebReader MCP actually returns at runtime.
+ *
+ * It imports NO concrete Provider, transport, or Adapter. It does no URL
+ * rewriting, raw response parsing, Provider field mapping, Provider
+ * selection, retries, or presentation.
+ *
+ * Scope of this file:
+ *   - request, operation, cache-identity, and result type contracts;
+ *   - the discriminated `ReaderOperationKind` union;
+ *   - a total decoder for the cacheable normalized result
+ *     (`decodeReaderFetchResult`);
+ *   - the `ReaderRawResponse` type consumed by Ticket 02's `webRead`
+ *     signature fix.
+ *
+ * Ticket 01 introduces ONLY this contract and the decoder. Ticket 02
+ * fixes `webRead` to return `ReaderRawResponse`. Ticket 03 supplies the
+ * Z.AI Reader Adapter. Ticket 04 cuts the handler over. Nothing in this
+ * file is allowed to widen that boundary.
+ *
+ * Evidence base: [`artifacts/reader-webreader-characterization/`](../../../../.traycer/epics/4f065460-3416-4832-95a6-7ac5576fcfbc/artifacts/reader-webreader-characterization/index.md).
+ */
+// ===========================================================================
+// Total normalized cache decoder
+// ===========================================================================
+//
+// Accepts `unknown`, returns the typed result or `null`, never throws, and
+// never trusts a generic cast. Shape contract is local; the Adapter (Ticket
+// 03) is responsible for producing values that conform to
+// `ReaderFetchResult`.
+//
+// Rules encoded:
+//   - reject primitives and arrays at the top level (results are objects);
+//   - reject schemaVersion other than the literal number 1;
+//   - reject missing or non-string `url`, `finalUrl`, `content`;
+//   - reject empty `url`, `finalUrl`, `content` (the Capability requires
+//     non-empty content; an empty fetch is a miss, not a degenerate hit);
+//   - reject `title` that is neither a string nor null;
+//   - reject `contentFormat` other than the literal strings "markdown"
+//     or "text";
+//   - preserve `metadata` and `external` verbatim when present.
+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;
+}
+/**
+ * Decode a Reader fetch result from the cache. Returns the canonical
+ * `ReaderFetchResult` on success, `null` for any malformed value.
+ *
+ * `title: null` is a valid decoded value (the Adapter coerces missing
+ * or blank titles to null before writing; the decoder round-trips it).
+ */
+export function decodeReaderFetchResult(value) {
+    if (!isPlainObject(value))
+        return null;
+    // `schemaVersion` MUST be the literal number 1. The strict equality
+    // rejects numeric strings, bigints, and any future version.
+    if (value.schemaVersion !== 1)
+        return null;
+    if (!isNonEmptyString(value.url))
+        return null;
+    if (!isNonEmptyString(value.finalUrl))
+        return null;
+    if (!isNonEmptyString(value.content))
+        return null;
+    const title = value.title;
+    if (title !== null && typeof title !== "string")
+        return null;
+    const contentFormat = value.contentFormat;
+    if (contentFormat !== "markdown" && contentFormat !== "text")
+        return null;
+    // Optional fields preserved verbatim when present, omitted from the
+    // decoded result when absent so the round-trip equals the input shape.
+    // Built in one shot so `readonly` invariants on `ReaderFetchResult`
+    // are honored.
+    const hasMetadata = value.metadata !== undefined;
+    const hasExternal = value.external !== undefined;
+    return {
+        schemaVersion: 1,
+        url: value.url,
+        finalUrl: value.finalUrl,
+        title: title,
+        content: value.content,
+        contentFormat,
+        ...(hasMetadata ? { metadata: value.metadata } : {}),
+        ...(hasExternal ? { external: value.external } : {}),
+    };
+}
+//# sourceMappingURL=reader.js.map

package/dist/capabilities/reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.js","sourceRoot":"","sources":["../../src/capabilities/reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAsOH,8EAA8E;AAC9E,iCAAiC;AACjC,8EAA8E;AAC9E,EAAE;AACF,2EAA2E;AAC3E,4EAA4E;AAC5E,0DAA0D;AAC1D,uBAAuB;AACvB,EAAE;AACF,iBAAiB;AACjB,2EAA2E;AAC3E,4DAA4D;AAC5D,iEAAiE;AACjE,yEAAyE;AACzE,0EAA0E;AAC1E,wDAAwD;AACxD,uEAAuE;AACvE,iBAAiB;AACjB,gEAAgE;AAEhE,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;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACpD,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEvC,oEAAoE;IACpE,4DAA4D;IAC5D,IAAI,KAAK,CAAC,aAAa,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAE3C,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9C,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IACnD,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IAElD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IAC1B,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAE7D,MAAM,aAAa,GAAG,KAAK,CAAC,aAAa,CAAC;IAC1C,IAAI,aAAa,KAAK,UAAU,IAAI,aAAa,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IAE1E,oEAAoE;IACpE,uEAAuE;IACvE,oEAAoE;IACpE,eAAe;IACf,MAAM,WAAW,GAAG,KAAK,CAAC,QAAQ,KAAK,SAAS,CAAC;IACjD,MAAM,WAAW,GAAG,KAAK,CAAC,QAAQ,KAAK,SAAS,CAAC;IACjD,OAAO;QACL,aAAa,EAAE,CAAC;QAChB,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,KAAK,EAAE,KAAsB;QAC7B,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,aAAa;QACb,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpD,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACrD,CAAC;AACJ,CAAC"}

package/dist/capabilities/repository.d.ts

@@ -0,0 +1,221 @@
+/**
+ * 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.
+ */
+import type { ProviderId } from "../providers/types.js";
+/**
+ * Discriminated union over the three repository operations. Shared
+ * execution maps each kind to its retry policy branch and diagnostics
+ * inventory. The union is the public source of truth; consumers iterate
+ * by listing each literal explicitly when they need a runtime set.
+ */
+export type RepositoryOperationKind = "repository-search" | "repository-read-file" | "repository-list-directory";
+/**
+ * Provider-neutral Search request. `language` MUST be supplied explicitly
+ * (default `"en"` applied at the command layer before validation); empty
+ * or whitespace-only `query` is invalid at validate time.
+ */
+export interface RepositorySearchRequest {
+    readonly repository: string;
+    readonly query: string;
+    readonly language: "en" | "zh";
+}
+/**
+ * Provider-neutral File request. `path` is a non-empty
+ * repository-relative POSIX path; `path: ""` (root) is invalid for File
+ * and is rejected by the cache decoder.
+ */
+export interface RepositoryFileRequest {
+    readonly repository: string;
+    readonly path: string;
+}
+/**
+ * Provider-neutral Directory Listing request. `path: ""` is the
+ * repository root; every other path is a non-empty repository-relative
+ * POSIX path.
+ */
+export interface RepositoryDirectoryRequest {
+    readonly repository: string;
+    readonly path: string;
+}
+/**
+ * Provider-neutral directory or file entry. `name` is the final segment
+ * and `path` is the repository-relative POSIX path of the entry
+ * itself. Both fields are non-empty strings — root-level entries are
+ * impossible because a directory entry sits below the listing's
+ * `path`. Order is Provider-supplied and preserved.
+ */
+export interface RepositoryEntry {
+    readonly name: string;
+    readonly path: string;
+    readonly kind: "file" | "directory";
+}
+/** Search excerpt: only text. ZRead does not supply reliable metadata. */
+export interface RepositorySearchExcerpt {
+    readonly text: string;
+}
+/**
+ * Normalized Provider-derived Search result. `schemaVersion: 1` is the
+ * breaking migration shape from P6 (`data-mode scripting impact`).
+ */
+export interface RepositorySearchResult {
+    readonly schemaVersion: 1;
+    readonly repository: string;
+    readonly query: string;
+    readonly language: "en" | "zh";
+    readonly excerpts: readonly RepositorySearchExcerpt[];
+    readonly truncated: boolean;
+    readonly originalTextLength: number;
+}
+/**
+ * Normalized File result. `path` is a non-empty repository-relative
+ * POSIX path; the cache decoder rejects `path: ""` because File is
+ * always non-root. `truncated` carries the existing ellipsis rule.
+ */
+export interface RepositoryFileResult {
+    readonly schemaVersion: 1;
+    readonly repository: string;
+    readonly path: string;
+    readonly content: string;
+    readonly truncated: boolean;
+    readonly originalContentLength: number;
+}
+/**
+ * Normalized Directory Listing result. `path: ""` means the
+ * repository root. `entries` is never `null` and preserves sibling
+ * order from the Provider. Each entry's `name` and `path` are
+ * non-empty.
+ */
+export interface RepositoryDirectoryListing {
+    readonly repository: string;
+    readonly path: string;
+    readonly entries: readonly RepositoryEntry[];
+}
+/**
+ * Normalized Repository Tree result, composed of provider-ordered
+ * `snapshots`. `path: ""` means tree root. `depth` is the integer
+ * tree depth applied at the Explorer layer. Tree is Explorer
+ * projection and is not a cacheable `RepositoryOperation.decodeCached`
+ * implementation; this type remains public because Explorer surfaces
+ * it.
+ */
+export interface RepositoryTreeResult {
+    readonly schemaVersion: 1;
+    readonly repository: string;
+    readonly path: string;
+    readonly depth: number;
+    readonly snapshots: readonly RepositoryDirectoryListing[];
+}
+/**
+ * Provider-owned legacy cache candidate. Old Z.AI keys encode the
+ * raw v0.2 tool response; the Adapter supplies the decoder so shared
+ * cache code never inspects Provider response shapes. An invalid
+ * decode is a cache miss.
+ */
+export interface LegacyRepositoryCacheCandidate<Result> {
+    readonly key: string;
+    decode(value: unknown): Result | null;
+}
+/**
+ * Identity used to read and write a Provider-partitioned cache entry.
+ * `credentialFingerprint` is the full lowercase SHA-256 hex digest of
+ * the resolved credential and is NEVER re-hashed by cache code.
+ * `request` is the normalized Capability request.
+ */
+export interface RepositoryCacheIdentity<Request, Result> {
+    readonly provider: ProviderId;
+    readonly capability: "repository-exploration";
+    readonly operation: RepositoryOperationKind;
+    readonly credentialFingerprint: string;
+    readonly request: Readonly<Request>;
+    readonly legacyCandidates: readonly LegacyRepositoryCacheCandidate<Result>[];
+}
+/**
+ * Generic operation descriptor. Each Adapter supplies one of these for
+ * each operation it supports. The Adapter owns Provider field mapping,
+ * credentials, transport lifecycle, and error normalization. Commands
+ * and shared execution call only these four methods.
+ */
+export interface RepositoryOperation<Request, Result> {
+    readonly kind: RepositoryOperationKind;
+    /**
+     * Validate the request before any Provider access. Throws
+     * `ValidationError` for missing required fields and
+     * `UnsupportedOptionError` for Provider-specific options the Adapter
+     * does not accept. Validation MUST occur before credential resolution
+     * or transport construction.
+     */
+    validate(request: Request): void;
+    /**
+     * Build the cache identity for a request. Called only after
+     * `validate` succeeds. The Adapter resolves its credential once and
+     * returns full fingerprint, canonical request, and zero or more
+     * legacy candidates. Candidate construction MUST NOT read ambient
+     * environment.
+     */
+    cacheIdentity(request: Request): RepositoryCacheIdentity<Request, Result>;
+    /**
+     * Total decoder for cached normalized entries. Accepts an `unknown`
+     * value, validates shape, and returns the typed result or `null`.
+     * NEVER throws, NEVER trusts a generic cast.
+     */
+    decodeCached(value: unknown): Result | null;
+    /**
+     * Invoke the Provider and return the normalized result. The Adapter
+     * closes its transport and never retries inside this method;
+     * shared execution owns retry policy.
+     */
+    invoke(request: Request): Promise<Result>;
+}
+/**
+ * Repository Capability contract. Every Adapter that supports
+ * repository exploration implements this interface and exposes it as
+ * `adapter.repository` (P6-04 and beyond).
+ */
+export interface RepositoryCapability {
+    readonly search: RepositoryOperation<RepositorySearchRequest, RepositorySearchResult>;
+    readonly readFile: RepositoryOperation<RepositoryFileRequest, RepositoryFileResult>;
+    readonly listDirectory: RepositoryOperation<RepositoryDirectoryRequest, RepositoryDirectoryListing>;
+}
+/**
+ * Decode a Search result from the cache. Returns the canonical
+ * `RepositorySearchResult` on success, `null` for any malformed value.
+ */
+export declare function decodeRepositorySearch(value: unknown): RepositorySearchResult | null;
+/**
+ * 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 declare function decodeRepositoryFile(value: unknown): RepositoryFileResult | null;
+/**
+ * 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 declare function decodeRepositoryDirectoryListing(value: unknown): RepositoryDirectoryListing | null;
+//# sourceMappingURL=repository.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/capabilities/repository.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAMxD;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAC/B,mBAAmB,GACnB,sBAAsB,GACtB,2BAA2B,CAAC;AAMhC;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAMD;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;CACrC;AAED,0EAA0E;AAC1E,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACtD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;CACxC;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;CAC9C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,SAAS,0BAA0B,EAAE,CAAC;CAC3D;AAMD;;;;;GAKG;AACH,MAAM,WAAW,8BAA8B,CAAC,MAAM;IACpD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;CACvC;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB,CAAC,OAAO,EAAE,MAAM;IACtD,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,wBAAwB,CAAC;IAC9C,QAAQ,CAAC,SAAS,EAAE,uBAAuB,CAAC;IAC5C,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IACpC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,8BAA8B,CAAC,MAAM,CAAC,EAAE,CAAC;CAC9E;AAMD;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB,CAAC,OAAO,EAAE,MAAM;IAClD,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC;;;;;;OAMG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,uBAAuB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC1E;;;;OAIG;IACH,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5C;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC3C;AAMD;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC,uBAAuB,EAAE,sBAAsB,CAAC,CAAC;IACtF,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC,qBAAqB,EAAE,oBAAoB,CAAC,CAAC;IACpF,QAAQ,CAAC,aAAa,EAAE,mBAAmB,CACzC,0BAA0B,EAC1B,0BAA0B,CAC3B,CAAC;CACH;AA4CD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,sBAAsB,GAAG,IAAI,CA+BpF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,GAAG,IAAI,CAkBhF;AAED;;;;;;;GAOG;AACH,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,OAAO,GACb,0BAA0B,GAAG,IAAI,CA0BnC"}

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":"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"}

package/dist/capabilities/search.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Search Capability Contract (DESIGN.md §7, PRD FR-010 through FR-016).
+ *
+ * Defines the normalized meaning shared by every Search Provider.
+ * Commands consume the Capability through `SearchCapability.invoke`,
+ * which returns `SearchSource[]` in the Provider-agnostic shape. All
+ * Provider-specific fields (rank, occurrence count, count, summary
+ * truncation, field projection, presentation) remain command meaning.
+ *
+ * The Cache Identity contract (`SearchCacheIdentity`,
+ * `LegacySearchCacheCandidate`) is declared here so P2-02 can wire
+ * Provider-partitioned cache keys without further type changes.
+ *
+ * Phase 2 implements only this contract. The Z.AI and MiniMax Search
+ * Adapters arrive in P2-03 and P2-04; the production registry arrives
+ * in P2-05. The Provider descriptors advertised in P2-01 already
+ * declare the search Capability, so command wiring can begin once the
+ * Adapters exist.
+ */
+import type { ProviderId } from "../providers/types.js";
+/** Recency filter accepted by Z.AI; MiniMax rejects it. */
+export type SearchRecency = "oneDay" | "oneWeek" | "oneMonth" | "oneYear" | "noLimit";
+/**
+ * Provider controls accepted by the Search Capability. Every field is
+ * optional. MiniMax rejects `domain`, `recency`, `contentSize`, and
+ * `location` with `UNSUPPORTED_OPTION` before any SDK access.
+ */
+export interface SearchControls {
+    domain?: string;
+    recency?: SearchRecency;
+    contentSize?: "medium" | "high";
+    location?: "cn" | "us";
+}
+/**
+ * A Search request. `query` must contain at least one non-whitespace
+ * character; the Capability's `validate` enforces this and throws
+ * `ValidationError` otherwise.
+ */
+export interface SearchRequest {
+    query: string;
+    controls?: Readonly<SearchControls>;
+}
+/**
+ * Normalized Search result. Adapters populate this from their Provider
+ * response shape; commands merge, deduplicate, project, truncate, and
+ * rank downstream. Provider-only fields are discarded.
+ */
+export interface SearchSource {
+    title: string;
+    url: string;
+    summary: string;
+    source?: string;
+    date?: string;
+}
+/**
+ * Provider-owned legacy cache candidate. Old Z.AI keys encode raw
+ * `WebSearchResult[]`; the Adapter supplies the decoder so shared cache
+ * code never inspects Provider response shapes. Invalid decode is a
+ * cache miss.
+ */
+export interface LegacySearchCacheCandidate {
+    readonly key: string;
+    decode(value: unknown): readonly SearchSource[] | null;
+}
+/**
+ * Identity used to read and write a Provider-partitioned cache entry.
+ * `credentialFingerprint` is the full lowercase SHA-256 hex digest of
+ * the active credential and is never hashed a second time by cache
+ * code. Request identity uses recursively key-sorted JSON of only
+ * `query` and Provider controls.
+ */
+export interface SearchCacheIdentity {
+    readonly provider: ProviderId;
+    readonly capability: "search";
+    readonly credentialFingerprint: string;
+    readonly request: Readonly<SearchRequest>;
+    readonly legacyCandidates?: readonly LegacySearchCacheCandidate[];
+}
+/**
+ * Search Capability contract. Every Adapter that supports Search
+ * implements this interface and is consumed by shared execution. The
+ * Adapter owns Provider field mapping; commands call only these three
+ * methods.
+ */
+export interface SearchCapability {
+    /**
+     * Validate a request before any Provider access. Throws
+     * `ValidationError` for an empty or whitespace-only query, and
+     * `UnsupportedOptionError` for Provider-specific options the Adapter
+     * does not accept. Validation must occur before credential resolution
+     * or transport construction.
+     */
+    validate(request: SearchRequest): void;
+    /**
+     * Build the cache identity for a request. Called only after
+     * `validate` succeeds. `compatibility.legacyCount` is the optional
+     * command count; it may enter only `legacyCandidates` and never the
+     * new request identity.
+     */
+    cacheIdentity(request: SearchRequest, compatibility?: {
+        readonly legacyCount?: number;
+    }): SearchCacheIdentity;
+    /**
+     * Invoke the Provider and return normalized sources. The Adapter
+     * closes its transport and never retries inside this method; shared
+     * execution owns retry policy.
+     */
+    invoke(request: SearchRequest): Promise<readonly SearchSource[]>;
+}
+//# sourceMappingURL=search.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/capabilities/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAMxD,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GACrB,QAAQ,GACR,SAAS,GACT,UAAU,GACV,SAAS,GACT,SAAS,CAAC;AAEd;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,WAAW,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAChC,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;CACrC;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAMD;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,YAAY,EAAE,GAAG,IAAI,CAAC;CACxD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC;IAC9B,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC;IAC1C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,0BAA0B,EAAE,CAAC;CACnE;AAMD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IAEvC;;;;;OAKG;IACH,aAAa,CACX,OAAO,EAAE,aAAa,EACtB,aAAa,CAAC,EAAE;QAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAChD,mBAAmB,CAAC;IAEvB;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAAC;CAClE"}

package/dist/capabilities/search.js

@@ -0,0 +1,21 @@
+/**
+ * Search Capability Contract (DESIGN.md §7, PRD FR-010 through FR-016).
+ *
+ * Defines the normalized meaning shared by every Search Provider.
+ * Commands consume the Capability through `SearchCapability.invoke`,
+ * which returns `SearchSource[]` in the Provider-agnostic shape. All
+ * Provider-specific fields (rank, occurrence count, count, summary
+ * truncation, field projection, presentation) remain command meaning.
+ *
+ * The Cache Identity contract (`SearchCacheIdentity`,
+ * `LegacySearchCacheCandidate`) is declared here so P2-02 can wire
+ * Provider-partitioned cache keys without further type changes.
+ *
+ * Phase 2 implements only this contract. The Z.AI and MiniMax Search
+ * Adapters arrive in P2-03 and P2-04; the production registry arrives
+ * in P2-05. The Provider descriptors advertised in P2-01 already
+ * declare the search Capability, so command wiring can begin once the
+ * Adapters exist.
+ */
+export {};
+//# sourceMappingURL=search.js.map

package/dist/capabilities/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/capabilities/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}