scoutline 0.2.0 → 0.6.0

package/dist/providers/zai/encoded-error.js

@@ -0,0 +1,169 @@
+/**
+ * Shared encoded MCP error envelope helpers (DESIGN.md §18).
+ *
+ * The ZRead and WebReader MCP transports occasionally surface a
+ * bare-string error envelope of the shape:
+ *
+ *     MCP error -<status>\n
+ *     error.code: <numeric>\n
+ *     error.message: <text>
+ *     <optional additional lines>
+ *
+ * The Repository Adapter (P6-04) and the Reader Adapter (Ticket 03)
+ * both recognise this shape BEFORE attempting any success parsing.
+ * Classification is centralized here so the taxonomy stays consistent
+ * across Adapter implementations; each Adapter supplies an operation
+ * `label` ("repository", "reader", …) that becomes part of the
+ * sanitized outward message. Auth-message labels (401/403) are NOT
+ * operation-specific and stay stable.
+ *
+ * Boundary rules:
+ *   - This module imports normalized errors only; it imports no
+ *     transport, no capability contract, and no other Adapter.
+ *   - The raw Provider body, `error.message`, `reset`, etc. are
+ *     discarded; outward messages and help text are stable sanitized
+ *     labels.
+ *
+ * Historical note: P6-04A corrected the original mapping (status 403
+ * must keep exact status 403, not collapse to 401) and P6-04B refined
+ * the exhausted-quota phrase matching so that the bare word "limit"
+ * inside "rate limited" does NOT trigger terminal QuotaError. Those
+ * corrections are baked in here.
+ */
+import { ApiError, AuthError, QuotaError, ScoutlineError } from "../../lib/errors.js";
+/** Regex that captures the status of an encoded MCP error envelope. */
+export const ENCODED_MCP_ERROR_RE = /^MCP error -(\d+)\b/;
+/**
+ * Test whether `raw` looks like an encoded MCP error envelope. Returning
+ * `true` forces the caller into the error classification path before any
+ * success parser runs. The presence of a numeric status on the first
+ * line is the only requirement; the body lines are still parsed lazily.
+ */
+export function looksLikeEncodedMcpError(raw) {
+    return typeof raw === "string" && ENCODED_MCP_ERROR_RE.test(raw);
+}
+/**
+ * Extract the numeric status code from an encoded MCP error envelope.
+ * Returns `null` when the prefix is not present or the trailing digits
+ * do not parse to a finite integer.
+ */
+export function extractEncodedStatus(raw) {
+    const m = raw.match(ENCODED_MCP_ERROR_RE);
+    if (!m)
+        return null;
+    const n = Number.parseInt(m[1], 10);
+    return Number.isFinite(n) ? n : null;
+}
+/** Extract the documented `error.code:` numeric value, if present. */
+export function extractEncodedCode(raw) {
+    const m = raw.match(/^error\.code:\s*(\d+)/m);
+    if (!m)
+        return null;
+    const n = Number.parseInt(m[1], 10);
+    return Number.isFinite(n) ? n : null;
+}
+/** Extract the documented `error.message:` line text, if present. */
+export function extractEncodedMessage(raw) {
+    const m = raw.match(/^error\.message:\s*([^\n]+)/m);
+    return m ? m[1] : null;
+}
+/**
+ * Classify an encoded MCP error into a normalized error.
+ *
+ * The caller MUST have established that the response is an encoded
+ * envelope (via {@link looksLikeEncodedMcpError}). This function NEVER
+ * embeds the raw Provider body, message, or help into the outward text;
+ * it uses stable sanitized labels instead.
+ *
+ * `label` is the operation name used in the outward ApiError / QuotaError
+ * messages (e.g. "repository", "reader"). Auth messages (401, 403) do
+ * not carry the label — they read "Z.AI authentication failed" regardless
+ * of which Adapter surfaced them.
+ *
+ * Mapping (DESIGN.md §18; corrected by P6-04A, refined by P6-04B):
+ *   - code 1310 OR explicit exhausted/limit/quota meaning
+ *                                            -> terminal QuotaError
+ *                                              (REGARDLESS of the encoded
+ *                                              status line; a non-429 line
+ *                                              with code 1310 is still an
+ *                                              exhausted-quota failure);
+ *   - 401                                 -> AuthError, status 401, terminal;
+ *   - 403                                 -> normalized ScoutlineError
+ *                                              with code AUTH_ERROR and
+ *                                              statusCode 403, terminal
+ *                                              (avoids widening the
+ *                                              global AuthError
+ *                                              constructor);
+ *   - 429 (without exhausted quota)       -> ApiError, status 429,
+ *                                              retryable through the shared
+ *                                              taxonomy;
+ *   - 5xx                                 -> ApiError matching status,
+ *                                              retryable;
+ *   - other 4xx                           -> ApiError matching status,
+ *                                              terminal;
+ *   - malformed envelope (no parseable status)
+ *                                            -> ApiError 502, retryable.
+ */
+export function classifyEncodedMcpError(raw, label) {
+    const status = extractEncodedStatus(raw);
+    if (status === null) {
+        // Malformed envelope: no parseable status. Retryable, sanitized.
+        return new ApiError(`Z.AI ${label} request failed`, 502);
+    }
+    const code = extractEncodedCode(raw);
+    const message = extractEncodedMessage(raw);
+    const lowerMessage = (message ?? "").toLowerCase();
+    // Exhausted quota: code 1310 OR explicit exhausted/quota/limit-reaching
+    // meaning. This branches BEFORE the status mapping so a non-429 encoded
+    // status line carrying code 1310 or an explicit exhausted message still
+    // becomes terminal `QuotaError`.
+    //
+    // The bare word "limit" is intentionally NOT matched on its own:
+    // "rate limited" is a transient retryable 429, not exhausted quota.
+    // "exhausted", "quota", and the multi-word phrases "limit reached" /
+    // "limit exceeded" are specific to the exhaustion context (P6-04B):
+    //   - "Weekly/Monthly Limit Exhausted"  -> "exhausted"
+    //   - "Quota has been exhausted"         -> "quota"
+    //   - "Monthly limit reached"            -> "limit reached"
+    //   - "usage limit exceeded"             -> "limit exceeded"
+    // Code 1310 is the authoritative numeric signal.
+    const isExhausted = code === 1310 ||
+        lowerMessage.includes("exhausted") ||
+        lowerMessage.includes("quota") ||
+        lowerMessage.includes("limit reached") ||
+        lowerMessage.includes("limit exceeded");
+    if (isExhausted) {
+        return new QuotaError(`Z.AI ${label} quota has been exhausted`, "Check your Z.AI quota and try again later");
+    }
+    if (status === 401) {
+        return new AuthError("Z.AI authentication failed");
+    }
+    if (status === 403) {
+        // 403 maps to AUTH_ERROR with status 403, terminal. Constructing
+        // a localized normalized ScoutlineError (rather than widening
+        // the global AuthError constructor) preserves the documented exact
+        // status code without affecting legacy call sites elsewhere in the
+        // codebase.
+        return new ScoutlineError("Z.AI authentication failed", "AUTH_ERROR", {
+            statusCode: 403,
+            retryable: false,
+            exitCode: 1,
+        });
+    }
+    // 5xx and other 429 -> retryable; other 4xx -> terminal. The retry
+    // classifier in `lib/execution.ts` reads `retryable` via the explicit
+    // ApiError flag, but the per-status mapping here matches DESIGN.md §10
+    // so the constructed errors carry the right shape regardless.
+    if (status === 429) {
+        return new ApiError(`Z.AI ${label} request failed`, 429);
+    }
+    if (status >= 500 && status <= 599) {
+        return new ApiError(`Z.AI ${label} request failed`, status);
+    }
+    if (status >= 400 && status <= 499) {
+        return new ApiError(`Z.AI ${label} request failed`, status);
+    }
+    // Unrecognized numeric status (e.g. 0, negative) -> retryable 502.
+    return new ApiError(`Z.AI ${label} request failed`, 502);
+}
+//# sourceMappingURL=encoded-error.js.map

package/dist/providers/zai/encoded-error.js.map

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

package/dist/providers/zai/reader.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Z.AI Reader Adapter (DESIGN.md §18; reader-migration-tech-plan D4;
+ * PRD FR-??? — reader migration Ticket 03).
+ *
+ * Owns the Provider-facing half of the provider-neutral Reader
+ * Capability defined in `src/capabilities/reader.ts`:
+ *
+ *   - URL rewrite (gist.github.com/<user>/<id> -> /raw) applied BEFORE
+ *     invocation; the rewritten URL surfaces as `finalUrl` in the
+ *     result. The rewrite is Z.AI-specific because Z.AI's WebReader
+ *     MCP recognizes the rewritten URL.
+ *   - a total parser for the characterized Z.AI WebReader response
+ *     (`ReaderRawResponse`: object on success, bare string for MCP-
+ *     level error envelopes);
+ *   - encoded MCP error classification BEFORE success parsing
+ *     (`quota` is terminal `QUOTA_ERROR`; the rest of the taxonomy
+ *     uses the shared retry/terminal classification); the parsing
+ *     helpers live in `./encoded-error.ts` and are shared with
+ *     `./repository.ts`;
+ *   - a single resolved-credential fingerprint per cache identity and
+ *     exact per-operation legacy cache candidate using Ticket 01's
+ *     `buildLegacyReaderCacheKey` helper;
+ *   - `decodeCached` delegates to Ticket 01's total decoder
+ *     (`decodeReaderFetchResult`);
+ *   - a fresh transport per invocation attempt and exactly one
+ *     best-effort close in `finally`; close failure never replaces
+ *     success nor masks the primary failure;
+ *   - no leakage of raw WebReader response types outside this module.
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - May import capability types, normalized errors, the Z.AI MCP
+ *     tool-name helpers, the legacy cache-key helper, the shared
+ *     `ZaiAdapterClientPort` typed client port, and the shared
+ *     encoded-error helpers.
+ *   - Must NOT import another Provider's Adapter, command
+ *     presentation, or extract/maxChars projection logic.
+ *
+ * Scope:
+ *   - implements the single `reader-fetch` operation only. URL scheme
+ *     validation, `--extract`, `--max-chars`, and `--full-envelope`
+ *     belong to the command layer (Ticket 04 cuts the handler over).
+ *   - descriptor metadata sequencing: Ticket 03 introduces this Adapter
+ *     handle and wires it through `ProviderAdapter.reader` WITHOUT
+ *     advertising `reader` on `createZaiDescriptor.capabilities()`;
+ *     Ticket 04 then flips the descriptor to advertise `reader` so
+ *     Provider selection and Doctor inventory derive from a single
+ *     source of truth, AND cuts `commands/read.ts` over to dispatch
+ *     through `adapter.reader.fetch`. This module owns no registry,
+ *     selection, or command cutover.
+ */
+import type { ZaiAdapterClientPort, ZaiMcpClientOptions } from "../types.js";
+import { type ReaderCapability } from "../../capabilities/reader.js";
+/**
+ * Production close bound (ms). Matches the existing
+ * `ZaiMcpClient.close(timeoutMs = 2000)` semantic; the Adapter races
+ * the close against a 2 second timer that resolves silently so a stuck
+ * close cannot stall the attempt. Tests may inject a shorter bound via
+ * {@link ZaiReaderCapabilityOptions.closeTimeoutMs}.
+ */
+export declare const ZAI_READER_CLOSE_BOUND_MS = 2000;
+/**
+ * Options accepted by {@link createZaiReaderCapability}.
+ *
+ * `closeTimeoutMs` defaults to {@link ZAI_READER_CLOSE_BOUND_MS}
+ * (2000 ms) — the existing `ZaiMcpClient.close(timeoutMs = 2000)`
+ * semantic. Tests may inject a shorter bound to bound a never-
+ * resolving `close()` without waiting for the production default.
+ */
+export interface ZaiReaderCapabilityOptions {
+    readonly env: NodeJS.ProcessEnv;
+    readonly clientFactory: (options: ZaiMcpClientOptions) => ZaiAdapterClientPort;
+    readonly closeTimeoutMs?: number;
+}
+/**
+ * Build the Z.AI Reader Capability. The capability is composed of a
+ * single typed `ReaderOperation` descriptor (`fetch`); the Adapter
+ * owns credentials, transport lifecycle, raw request/response mapping,
+ * URL rewrite, and error normalization. No transport, credential
+ * resolution, or I/O happens during construction.
+ */
+export declare function createZaiReaderCapability(options: ZaiReaderCapabilityOptions): ReaderCapability;
+//# sourceMappingURL=reader.d.ts.map

package/dist/providers/zai/reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../../src/providers/zai/reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAIH,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAM7E,OAAO,EAGL,KAAK,gBAAgB,EAItB,MAAM,8BAA8B,CAAC;AAEtC;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAie9C;;;;;;;GAOG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,oBAAoB,CAAC;IAC/E,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,0BAA0B,GAAG,gBAAgB,CAS/F"}