scoutline 0.2.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (110) hide show
  1. package/README.md +240 -18
  2. package/dist/capabilities/diagnostics.d.ts +70 -32
  3. package/dist/capabilities/diagnostics.d.ts.map +1 -1
  4. package/dist/capabilities/diagnostics.js +97 -46
  5. package/dist/capabilities/diagnostics.js.map +1 -1
  6. package/dist/capabilities/reader.d.ts +227 -0
  7. package/dist/capabilities/reader.d.ts.map +1 -0
  8. package/dist/capabilities/reader.js +100 -0
  9. package/dist/capabilities/reader.js.map +1 -0
  10. package/dist/capabilities/repository.d.ts +221 -0
  11. package/dist/capabilities/repository.d.ts.map +1 -0
  12. package/dist/capabilities/repository.js +172 -0
  13. package/dist/capabilities/repository.js.map +1 -0
  14. package/dist/commands/cache.d.ts +106 -0
  15. package/dist/commands/cache.d.ts.map +1 -0
  16. package/dist/commands/cache.js +203 -0
  17. package/dist/commands/cache.js.map +1 -0
  18. package/dist/commands/doctor.d.ts +17 -6
  19. package/dist/commands/doctor.d.ts.map +1 -1
  20. package/dist/commands/doctor.js +42 -17
  21. package/dist/commands/doctor.js.map +1 -1
  22. package/dist/commands/read.d.ts +74 -14
  23. package/dist/commands/read.d.ts.map +1 -1
  24. package/dist/commands/read.js +257 -117
  25. package/dist/commands/read.js.map +1 -1
  26. package/dist/commands/repo.d.ts +53 -7
  27. package/dist/commands/repo.d.ts.map +1 -1
  28. package/dist/commands/repo.js +104 -123
  29. package/dist/commands/repo.js.map +1 -1
  30. package/dist/commands/repository-explorer.d.ts +147 -0
  31. package/dist/commands/repository-explorer.d.ts.map +1 -0
  32. package/dist/commands/repository-explorer.js +550 -0
  33. package/dist/commands/repository-explorer.js.map +1 -0
  34. package/dist/index.d.ts +20 -0
  35. package/dist/index.d.ts.map +1 -1
  36. package/dist/index.js +209 -34
  37. package/dist/index.js.map +1 -1
  38. package/dist/lib/cache.d.ts +123 -18
  39. package/dist/lib/cache.d.ts.map +1 -1
  40. package/dist/lib/cache.js +324 -49
  41. package/dist/lib/cache.js.map +1 -1
  42. package/dist/lib/errors.d.ts +24 -1
  43. package/dist/lib/errors.d.ts.map +1 -1
  44. package/dist/lib/errors.js +33 -2
  45. package/dist/lib/errors.js.map +1 -1
  46. package/dist/lib/execution.d.ts +119 -5
  47. package/dist/lib/execution.d.ts.map +1 -1
  48. package/dist/lib/execution.js +216 -10
  49. package/dist/lib/execution.js.map +1 -1
  50. package/dist/lib/index.d.ts +1 -1
  51. package/dist/lib/index.d.ts.map +1 -1
  52. package/dist/lib/index.js +1 -1
  53. package/dist/lib/index.js.map +1 -1
  54. package/dist/lib/mcp-client.d.ts +29 -5
  55. package/dist/lib/mcp-client.d.ts.map +1 -1
  56. package/dist/lib/mcp-client.js +88 -88
  57. package/dist/lib/mcp-client.js.map +1 -1
  58. package/dist/lib/tool-cache.d.ts +86 -0
  59. package/dist/lib/tool-cache.d.ts.map +1 -0
  60. package/dist/lib/tool-cache.js +123 -0
  61. package/dist/lib/tool-cache.js.map +1 -0
  62. package/dist/providers/minimax/adapter.d.ts +6 -4
  63. package/dist/providers/minimax/adapter.d.ts.map +1 -1
  64. package/dist/providers/minimax/adapter.js +64 -57
  65. package/dist/providers/minimax/adapter.js.map +1 -1
  66. package/dist/providers/minimax/coding-plan-client.d.ts +60 -0
  67. package/dist/providers/minimax/coding-plan-client.d.ts.map +1 -0
  68. package/dist/providers/minimax/coding-plan-client.js +204 -0
  69. package/dist/providers/minimax/coding-plan-client.js.map +1 -0
  70. package/dist/providers/minimax/media.d.ts +60 -6
  71. package/dist/providers/minimax/media.d.ts.map +1 -1
  72. package/dist/providers/minimax/media.js +147 -7
  73. package/dist/providers/minimax/media.js.map +1 -1
  74. package/dist/providers/minimax/quota-client.d.ts +13 -6
  75. package/dist/providers/minimax/quota-client.d.ts.map +1 -1
  76. package/dist/providers/minimax/quota-client.js +5 -0
  77. package/dist/providers/minimax/quota-client.js.map +1 -1
  78. package/dist/providers/minimax/vision-attestations.d.ts +23 -0
  79. package/dist/providers/minimax/vision-attestations.d.ts.map +1 -1
  80. package/dist/providers/minimax/vision-attestations.js +35 -10
  81. package/dist/providers/minimax/vision-attestations.js.map +1 -1
  82. package/dist/providers/minimax/vision-conformance.d.ts +8 -6
  83. package/dist/providers/minimax/vision-conformance.d.ts.map +1 -1
  84. package/dist/providers/minimax/vision-conformance.js +8 -6
  85. package/dist/providers/minimax/vision-conformance.js.map +1 -1
  86. package/dist/providers/minimax/vision-revisions.d.ts +8 -1
  87. package/dist/providers/minimax/vision-revisions.d.ts.map +1 -1
  88. package/dist/providers/minimax/vision-revisions.js +13 -6
  89. package/dist/providers/minimax/vision-revisions.js.map +1 -1
  90. package/dist/providers/selection.d.ts +3 -3
  91. package/dist/providers/selection.js +3 -3
  92. package/dist/providers/types.d.ts +66 -32
  93. package/dist/providers/types.d.ts.map +1 -1
  94. package/dist/providers/types.js.map +1 -1
  95. package/dist/providers/zai/adapter.d.ts.map +1 -1
  96. package/dist/providers/zai/adapter.js +71 -5
  97. package/dist/providers/zai/adapter.js.map +1 -1
  98. package/dist/providers/zai/encoded-error.d.ts +90 -0
  99. package/dist/providers/zai/encoded-error.d.ts.map +1 -0
  100. package/dist/providers/zai/encoded-error.js +169 -0
  101. package/dist/providers/zai/encoded-error.js.map +1 -0
  102. package/dist/providers/zai/reader.d.ts +82 -0
  103. package/dist/providers/zai/reader.d.ts.map +1 -0
  104. package/dist/providers/zai/reader.js +490 -0
  105. package/dist/providers/zai/reader.js.map +1 -0
  106. package/dist/providers/zai/repository.d.ts +76 -0
  107. package/dist/providers/zai/repository.d.ts.map +1 -0
  108. package/dist/providers/zai/repository.js +715 -0
  109. package/dist/providers/zai/repository.js.map +1 -0
  110. package/package.json +3 -3
@@ -1 +1 @@
1
- {"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/capabilities/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,EAAE,cAAc,EAA2B,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,oCAAoC,EAAE,MAAM,4CAA4C,CAAC;AA2ClG,8EAA8E;AAC9E,+BAA+B;AAC/B,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAkC,uBAAuB,EAAE,CAAC;AAE5F,SAAS,uBAAuB;IAC9B,MAAM,IAAI,GAAyB,CAAC,QAAQ,EAAE,wBAAwB,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC;IAChG,KAAK,MAAM,EAAE,IAAI,oCAAoC,EAAE,EAAE,CAAC;QACxD,IAAI,CAAC,IAAI,CAAC,2BAA2B,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAsB;IACtD,QAAQ;IACR,wBAAwB;IACxB,oBAAoB;IACpB,WAAW;IACX,YAAY;IACZ,gBAAgB;CACjB,CAAC;AAEF,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAc;IAKrD,MAAM,IAAI,GACR,KAAK,YAAY,cAAc,CAAC,CAAC,CAAE,KAAK,CAAC,IAA2B,CAAC,CAAC,CAAC,eAAe,CAAC;IACzF,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,MAAM,MAAM,GAAiE;QAC3E,IAAI;QACJ,OAAO;KACR,CAAC;IACF,IAAI,KAAK,YAAY,cAAc,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;QAClD,MAAM,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IAC3B,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}
1
+ {"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/capabilities/diagnostics.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,227 @@
1
+ /**
2
+ * Provider-neutral Reader Capability Contract (core-flows D1, D2;
3
+ * tech-plan D1, D2).
4
+ *
5
+ * This module declares the single Reader operation (`reader-fetch`), its
6
+ * provider-neutral request, identity, cache, and result shapes, the total
7
+ * normalized cache decoder, and the `ReaderRawResponse` type capturing
8
+ * what the Z.AI WebReader MCP actually returns at runtime.
9
+ *
10
+ * It imports NO concrete Provider, transport, or Adapter. It does no URL
11
+ * rewriting, raw response parsing, Provider field mapping, Provider
12
+ * selection, retries, or presentation.
13
+ *
14
+ * Scope of this file:
15
+ * - request, operation, cache-identity, and result type contracts;
16
+ * - the discriminated `ReaderOperationKind` union;
17
+ * - a total decoder for the cacheable normalized result
18
+ * (`decodeReaderFetchResult`);
19
+ * - the `ReaderRawResponse` type consumed by Ticket 02's `webRead`
20
+ * signature fix.
21
+ *
22
+ * Ticket 01 introduces ONLY this contract and the decoder. Ticket 02
23
+ * fixes `webRead` to return `ReaderRawResponse`. Ticket 03 supplies the
24
+ * Z.AI Reader Adapter. Ticket 04 cuts the handler over. Nothing in this
25
+ * file is allowed to widen that boundary.
26
+ *
27
+ * Evidence base: [`artifacts/reader-webreader-characterization/`](../../../../.traycer/epics/4f065460-3416-4832-95a6-7ac5576fcfbc/artifacts/reader-webreader-characterization/index.md).
28
+ */
29
+ import type { ProviderId } from "../providers/types.js";
30
+ /**
31
+ * The single Reader Capability operation. Cache identity partitions by
32
+ * the composite `${capability}-${operation}` literal; the v2 partitioned
33
+ * key shape is
34
+ * `v2.reader-reader-fetch.<provider>.<credential-hash>.<request-hash>.json`.
35
+ *
36
+ * `--extract` and `--max-chars` are handler-level projections and do
37
+ * NOT participate in the cache identity (tech-plan D1, D2).
38
+ */
39
+ export type ReaderOperationKind = "reader-fetch";
40
+ /**
41
+ * Provider-neutral Reader fetch request. `url` MUST be supplied
42
+ * explicitly (the handler rejects non-`http(s)` values at parse time
43
+ * with `VALIDATION_ERROR` before this request reaches the Adapter).
44
+ *
45
+ * Every field except `url` participates in the v0.2 legacy cache key
46
+ * (`buildLegacyReaderCacheKey`) and in the v2 partitioned cache identity
47
+ * (`buildProviderCacheKey`). `--extract`, `--max-chars`, `--full-envelope`,
48
+ * `--no-cache`, and output mode NEVER appear here — they are projections
49
+ * applied after the cached normalized result.
50
+ *
51
+ * Field name parity with the v0.2 `webRead` request shape is intentional;
52
+ * the Adapter maps each field to the Z.AI WebReader MCP argument of the
53
+ * same semantics. The field order in the v0.2 insertion-order key is
54
+ * locked by the legacy helper, not by this interface.
55
+ */
56
+ export interface ReaderFetchRequest {
57
+ readonly url: string;
58
+ readonly format?: "markdown" | "text";
59
+ readonly retainImages?: boolean;
60
+ readonly withLinksSummary?: boolean;
61
+ readonly noGfm?: boolean;
62
+ readonly keepImgDataUrl?: boolean;
63
+ readonly withImagesSummary?: boolean;
64
+ readonly timeout?: number;
65
+ }
66
+ /**
67
+ * Normalized Reader fetch result. `schemaVersion: 1` is the breaking
68
+ * migration shape (core-flows D1 — `data`-mode returns the envelope,
69
+ * not a raw string).
70
+ *
71
+ * `truncated` and `originalContentLength` are NOT part of this contract.
72
+ * They are handler-level projections applied by `commands/read.ts` after
73
+ * the cached normalized result is produced (tech-plan D5). The cache
74
+ * stores the full content; truncation state is recomputed on every read.
75
+ *
76
+ * `title` is `string | null`. Every observed Z.AI WebReader response
77
+ * carries a non-empty string title (see characterization artifact), but
78
+ * the contract keeps the nullable arm for forward-compat and for
79
+ * Adapter-side coercion of empty / whitespace-only titles.
80
+ *
81
+ * `metadata` and `external` are typed `unknown` defensively. The
82
+ * characterization probe observed both as flat object maps, but the
83
+ * contract does not promote or restructure them — they pass through
84
+ * verbatim from the Provider.
85
+ */
86
+ export interface ReaderFetchResult {
87
+ readonly schemaVersion: 1;
88
+ /** Exactly what the caller passed to the operation. */
89
+ readonly url: string;
90
+ /**
91
+ * The URL the operation actually fetched. Differs from `url` only when
92
+ * a Provider-side rewrite occurred (e.g. `gist.github.com/<id>` →
93
+ * `gist.github.com/<id>/raw`).
94
+ */
95
+ readonly finalUrl: string;
96
+ /** Page title if the Provider returned one; `null` if absent or blank. */
97
+ readonly title: string | null;
98
+ /** Page content as markdown or plain text per `format`. */
99
+ readonly content: string;
100
+ /** Mirrors the request `format`; defaults to `"markdown"`. */
101
+ readonly contentFormat: "markdown" | "text";
102
+ /** Optional Provider-derived metadata blob; preserved verbatim. */
103
+ readonly metadata?: unknown;
104
+ /** Optional Provider-derived external-resource blob; preserved verbatim. */
105
+ readonly external?: unknown;
106
+ }
107
+ /**
108
+ * Object shape of a successful Z.AI WebReader MCP response. Field names
109
+ * mirror the wire shape observed in the characterization probe. Every
110
+ * field is optional at the wire layer — the Capability decoder enforces
111
+ * the stronger invariants (`title`, `url`, `content` must be non-empty
112
+ * strings) before promoting any value into a `ReaderFetchResult`.
113
+ *
114
+ * `description` is declared here so the Adapter can read it without
115
+ * crashing on rich pages (the probe confirmed `description` appears
116
+ * both at the top level and inside `metadata` for rich pages). The v1
117
+ * envelope does NOT surface it; it is dropped during normalization.
118
+ */
119
+ export interface ReaderRawObjectResponse {
120
+ readonly title?: string;
121
+ readonly description?: string;
122
+ readonly url?: string;
123
+ readonly content?: string;
124
+ readonly metadata?: unknown;
125
+ readonly external?: unknown;
126
+ }
127
+ /**
128
+ * The complete raw shape returned by `scoutline.zai.reader.webReader` at
129
+ * runtime. Either a structured object (the common case) or a bare
130
+ * `string` carrying an MCP-level error envelope (the characterization
131
+ * probe captured the exact shape: `"MCP error -500: ..."`).
132
+ *
133
+ * Ticket 02 widens the existing `webRead` method's TypeScript signature from
134
+ * the inaccurate `Promise<string>` to `Promise<ReaderRawResponse>` so
135
+ * raw-tool callers (`scoutline.zai.reader.*`) and the future Reader
136
+ * Adapter both see an honest path.
137
+ *
138
+ * The Capability decoder (`decodeReaderFetchResult`) only trusts
139
+ * object-shape values that satisfy the required field set. A raw
140
+ * `string` is malformed at the Capability layer — it represents a
141
+ * transport-level error that the Adapter must convert into a normalized
142
+ * `API_ERROR` 502 per the failure-handling table, not a fetch result.
143
+ */
144
+ export type ReaderRawResponse = ReaderRawObjectResponse | string;
145
+ /**
146
+ * Provider-owned legacy cache candidate. Old Z.AI v0.2 read cache entries
147
+ * encode the raw WebReader response under the public dotted tool name
148
+ * (`scoutline.zai.reader.webReader`). The Adapter supplies the decoder
149
+ * so shared cache code never inspects Provider response shapes. An
150
+ * invalid decode is a cache miss.
151
+ */
152
+ export interface LegacyReaderCacheCandidate<Result> {
153
+ readonly key: string;
154
+ decode(value: unknown): Result | null;
155
+ }
156
+ /**
157
+ * Identity used to read and write a Provider-partitioned Reader cache
158
+ * entry. `credentialFingerprint` is the full lowercase SHA-256 hex
159
+ * digest of the resolved credential and is NEVER re-hashed by cache
160
+ * code. `request` is the normalized Capability request.
161
+ */
162
+ export interface ReaderCacheIdentity<Request, Result> {
163
+ readonly provider: ProviderId;
164
+ readonly capability: "reader";
165
+ readonly operation: ReaderOperationKind;
166
+ readonly credentialFingerprint: string;
167
+ readonly request: Readonly<Request>;
168
+ readonly legacyCandidates: readonly LegacyReaderCacheCandidate<Result>[];
169
+ }
170
+ /**
171
+ * Generic Reader operation descriptor. The Adapter supplies one of these
172
+ * for the `reader-fetch` operation it supports. The Adapter owns
173
+ * Provider field mapping, credentials, transport lifecycle, and error
174
+ * normalization. Commands and shared execution call only these four
175
+ * methods.
176
+ *
177
+ * Same shape as P6-02's `RepositoryOperation` — the surface is
178
+ * unchanged; only the operation count differs (Reader has one).
179
+ */
180
+ export interface ReaderOperation<Request, Result> {
181
+ readonly kind: ReaderOperationKind;
182
+ /**
183
+ * Validate the request before any Provider access. Throws
184
+ * `ValidationError` for missing required fields and
185
+ * `UnsupportedOptionError` for Provider-specific options the Adapter
186
+ * does not accept. Validation MUST occur before credential resolution
187
+ * or transport construction.
188
+ */
189
+ validate(request: Request): void;
190
+ /**
191
+ * Build the cache identity for a request. Called only after
192
+ * `validate` succeeds. The Adapter resolves its credential once and
193
+ * returns full fingerprint, canonical request, and zero or more
194
+ * legacy candidates. Candidate construction MUST NOT read ambient
195
+ * environment.
196
+ */
197
+ cacheIdentity(request: Request): ReaderCacheIdentity<Request, Result>;
198
+ /**
199
+ * Total decoder for cached normalized entries. Accepts an `unknown`
200
+ * value, validates shape, and returns the typed result or `null`.
201
+ * NEVER throws, NEVER trusts a generic cast.
202
+ */
203
+ decodeCached(value: unknown): Result | null;
204
+ /**
205
+ * Invoke the Provider and return the normalized result. The Adapter
206
+ * closes its transport and never retries inside this method; shared
207
+ * execution owns retry policy.
208
+ */
209
+ invoke(request: Request): Promise<Result>;
210
+ }
211
+ /**
212
+ * Reader Capability contract. Every Adapter that supports reader
213
+ * fetching implements this interface and exposes it as
214
+ * `adapter.reader` (Ticket 03 onwards).
215
+ */
216
+ export interface ReaderCapability {
217
+ readonly fetch: ReaderOperation<ReaderFetchRequest, ReaderFetchResult>;
218
+ }
219
+ /**
220
+ * Decode a Reader fetch result from the cache. Returns the canonical
221
+ * `ReaderFetchResult` on success, `null` for any malformed value.
222
+ *
223
+ * `title: null` is a valid decoded value (the Adapter coerces missing
224
+ * or blank titles to null before writing; the decoder round-trips it).
225
+ */
226
+ export declare function decodeReaderFetchResult(value: unknown): ReaderFetchResult | null;
227
+ //# sourceMappingURL=reader.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../src/capabilities/reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAMxD;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,GAAG,cAAc,CAAC;AAMjD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,uDAAuD;IACvD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,QAAQ,CAAC,aAAa,EAAE,UAAU,GAAG,MAAM,CAAC;IAC5C,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAMD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,iBAAiB,GAAG,uBAAuB,GAAG,MAAM,CAAC;AAMjE;;;;;;GAMG;AACH,MAAM,WAAW,0BAA0B,CAAC,MAAM;IAChD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;CACvC;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB,CAAC,OAAO,EAAE,MAAM;IAClD,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,mBAAmB,CAAC;IACxC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IACpC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,0BAA0B,CAAC,MAAM,CAAC,EAAE,CAAC;CAC1E;AAMD;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe,CAAC,OAAO,EAAE,MAAM;IAC9C,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC;;;;;;OAMG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACtE;;;;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,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC,kBAAkB,EAAE,iBAAiB,CAAC,CAAC;CACxE;AAiCD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,GAAG,IAAI,CAiChF"}
@@ -0,0 +1,100 @@
1
+ /**
2
+ * Provider-neutral Reader Capability Contract (core-flows D1, D2;
3
+ * tech-plan D1, D2).
4
+ *
5
+ * This module declares the single Reader operation (`reader-fetch`), its
6
+ * provider-neutral request, identity, cache, and result shapes, the total
7
+ * normalized cache decoder, and the `ReaderRawResponse` type capturing
8
+ * what the Z.AI WebReader MCP actually returns at runtime.
9
+ *
10
+ * It imports NO concrete Provider, transport, or Adapter. It does no URL
11
+ * rewriting, raw response parsing, Provider field mapping, Provider
12
+ * selection, retries, or presentation.
13
+ *
14
+ * Scope of this file:
15
+ * - request, operation, cache-identity, and result type contracts;
16
+ * - the discriminated `ReaderOperationKind` union;
17
+ * - a total decoder for the cacheable normalized result
18
+ * (`decodeReaderFetchResult`);
19
+ * - the `ReaderRawResponse` type consumed by Ticket 02's `webRead`
20
+ * signature fix.
21
+ *
22
+ * Ticket 01 introduces ONLY this contract and the decoder. Ticket 02
23
+ * fixes `webRead` to return `ReaderRawResponse`. Ticket 03 supplies the
24
+ * Z.AI Reader Adapter. Ticket 04 cuts the handler over. Nothing in this
25
+ * file is allowed to widen that boundary.
26
+ *
27
+ * Evidence base: [`artifacts/reader-webreader-characterization/`](../../../../.traycer/epics/4f065460-3416-4832-95a6-7ac5576fcfbc/artifacts/reader-webreader-characterization/index.md).
28
+ */
29
+ // ===========================================================================
30
+ // Total normalized cache decoder
31
+ // ===========================================================================
32
+ //
33
+ // Accepts `unknown`, returns the typed result or `null`, never throws, and
34
+ // never trusts a generic cast. Shape contract is local; the Adapter (Ticket
35
+ // 03) is responsible for producing values that conform to
36
+ // `ReaderFetchResult`.
37
+ //
38
+ // Rules encoded:
39
+ // - reject primitives and arrays at the top level (results are objects);
40
+ // - reject schemaVersion other than the literal number 1;
41
+ // - reject missing or non-string `url`, `finalUrl`, `content`;
42
+ // - reject empty `url`, `finalUrl`, `content` (the Capability requires
43
+ // non-empty content; an empty fetch is a miss, not a degenerate hit);
44
+ // - reject `title` that is neither a string nor null;
45
+ // - reject `contentFormat` other than the literal strings "markdown"
46
+ // or "text";
47
+ // - preserve `metadata` and `external` verbatim when present.
48
+ function isPlainObject(value) {
49
+ return typeof value === "object" && value !== null && !Array.isArray(value);
50
+ }
51
+ /**
52
+ * Type guard for a non-empty string. `""` is rejected.
53
+ */
54
+ function isNonEmptyString(value) {
55
+ return typeof value === "string" && value.length > 0;
56
+ }
57
+ /**
58
+ * Decode a Reader fetch result from the cache. Returns the canonical
59
+ * `ReaderFetchResult` on success, `null` for any malformed value.
60
+ *
61
+ * `title: null` is a valid decoded value (the Adapter coerces missing
62
+ * or blank titles to null before writing; the decoder round-trips it).
63
+ */
64
+ export function decodeReaderFetchResult(value) {
65
+ if (!isPlainObject(value))
66
+ return null;
67
+ // `schemaVersion` MUST be the literal number 1. The strict equality
68
+ // rejects numeric strings, bigints, and any future version.
69
+ if (value.schemaVersion !== 1)
70
+ return null;
71
+ if (!isNonEmptyString(value.url))
72
+ return null;
73
+ if (!isNonEmptyString(value.finalUrl))
74
+ return null;
75
+ if (!isNonEmptyString(value.content))
76
+ return null;
77
+ const title = value.title;
78
+ if (title !== null && typeof title !== "string")
79
+ return null;
80
+ const contentFormat = value.contentFormat;
81
+ if (contentFormat !== "markdown" && contentFormat !== "text")
82
+ return null;
83
+ // Optional fields preserved verbatim when present, omitted from the
84
+ // decoded result when absent so the round-trip equals the input shape.
85
+ // Built in one shot so `readonly` invariants on `ReaderFetchResult`
86
+ // are honored.
87
+ const hasMetadata = value.metadata !== undefined;
88
+ const hasExternal = value.external !== undefined;
89
+ return {
90
+ schemaVersion: 1,
91
+ url: value.url,
92
+ finalUrl: value.finalUrl,
93
+ title: title,
94
+ content: value.content,
95
+ contentFormat,
96
+ ...(hasMetadata ? { metadata: value.metadata } : {}),
97
+ ...(hasExternal ? { external: value.external } : {}),
98
+ };
99
+ }
100
+ //# sourceMappingURL=reader.js.map
@@ -0,0 +1 @@
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"}
@@ -0,0 +1,221 @@
1
+ /**
2
+ * Provider-neutral Repository Capability Contract (DESIGN.md §18,
3
+ * PRD FR-081, FR-083, FR-086, FR-089; NFR-004, NFR-006, NFR-007).
4
+ *
5
+ * This module declares the three repository operations (Search, Read File,
6
+ * Directory Listing), their provider-neutral request, identity, cache, and
7
+ * result shapes, and the total normalized cache decoders used by shared
8
+ * execution. It imports NO concrete Provider, transport, or Adapter. It
9
+ * does no path canonicalization, raw ZRead parsing, Provider field
10
+ * mapping, Provider selection, retries, or presentation.
11
+ *
12
+ * Scope of this file:
13
+ * - request, operation, cache-identity, and result type contracts;
14
+ * - total decoders for the three cacheable normalized result types
15
+ * (`decodeRepositorySearch`, `decodeRepositoryFile`,
16
+ * `decodeRepositoryDirectoryListing`);
17
+ * - the discriminated `RepositoryOperationKind` union shared by shared
18
+ * execution, retry policy, and diagnostics.
19
+ *
20
+ * P6-02 introduces ONLY this contract and the decoders. P6-03 supplies
21
+ * shared execution, P6-04 the Z.AI Adapter, and P6-05 the Explorer. The
22
+ * capability surface here is the boundary between those tickets and the
23
+ * commands; nothing in this file is allowed to widen the boundary.
24
+ */
25
+ import type { ProviderId } from "../providers/types.js";
26
+ /**
27
+ * Discriminated union over the three repository operations. Shared
28
+ * execution maps each kind to its retry policy branch and diagnostics
29
+ * inventory. The union is the public source of truth; consumers iterate
30
+ * by listing each literal explicitly when they need a runtime set.
31
+ */
32
+ export type RepositoryOperationKind = "repository-search" | "repository-read-file" | "repository-list-directory";
33
+ /**
34
+ * Provider-neutral Search request. `language` MUST be supplied explicitly
35
+ * (default `"en"` applied at the command layer before validation); empty
36
+ * or whitespace-only `query` is invalid at validate time.
37
+ */
38
+ export interface RepositorySearchRequest {
39
+ readonly repository: string;
40
+ readonly query: string;
41
+ readonly language: "en" | "zh";
42
+ }
43
+ /**
44
+ * Provider-neutral File request. `path` is a non-empty
45
+ * repository-relative POSIX path; `path: ""` (root) is invalid for File
46
+ * and is rejected by the cache decoder.
47
+ */
48
+ export interface RepositoryFileRequest {
49
+ readonly repository: string;
50
+ readonly path: string;
51
+ }
52
+ /**
53
+ * Provider-neutral Directory Listing request. `path: ""` is the
54
+ * repository root; every other path is a non-empty repository-relative
55
+ * POSIX path.
56
+ */
57
+ export interface RepositoryDirectoryRequest {
58
+ readonly repository: string;
59
+ readonly path: string;
60
+ }
61
+ /**
62
+ * Provider-neutral directory or file entry. `name` is the final segment
63
+ * and `path` is the repository-relative POSIX path of the entry
64
+ * itself. Both fields are non-empty strings — root-level entries are
65
+ * impossible because a directory entry sits below the listing's
66
+ * `path`. Order is Provider-supplied and preserved.
67
+ */
68
+ export interface RepositoryEntry {
69
+ readonly name: string;
70
+ readonly path: string;
71
+ readonly kind: "file" | "directory";
72
+ }
73
+ /** Search excerpt: only text. ZRead does not supply reliable metadata. */
74
+ export interface RepositorySearchExcerpt {
75
+ readonly text: string;
76
+ }
77
+ /**
78
+ * Normalized Provider-derived Search result. `schemaVersion: 1` is the
79
+ * breaking migration shape from P6 (`data-mode scripting impact`).
80
+ */
81
+ export interface RepositorySearchResult {
82
+ readonly schemaVersion: 1;
83
+ readonly repository: string;
84
+ readonly query: string;
85
+ readonly language: "en" | "zh";
86
+ readonly excerpts: readonly RepositorySearchExcerpt[];
87
+ readonly truncated: boolean;
88
+ readonly originalTextLength: number;
89
+ }
90
+ /**
91
+ * Normalized File result. `path` is a non-empty repository-relative
92
+ * POSIX path; the cache decoder rejects `path: ""` because File is
93
+ * always non-root. `truncated` carries the existing ellipsis rule.
94
+ */
95
+ export interface RepositoryFileResult {
96
+ readonly schemaVersion: 1;
97
+ readonly repository: string;
98
+ readonly path: string;
99
+ readonly content: string;
100
+ readonly truncated: boolean;
101
+ readonly originalContentLength: number;
102
+ }
103
+ /**
104
+ * Normalized Directory Listing result. `path: ""` means the
105
+ * repository root. `entries` is never `null` and preserves sibling
106
+ * order from the Provider. Each entry's `name` and `path` are
107
+ * non-empty.
108
+ */
109
+ export interface RepositoryDirectoryListing {
110
+ readonly repository: string;
111
+ readonly path: string;
112
+ readonly entries: readonly RepositoryEntry[];
113
+ }
114
+ /**
115
+ * Normalized Repository Tree result, composed of provider-ordered
116
+ * `snapshots`. `path: ""` means tree root. `depth` is the integer
117
+ * tree depth applied at the Explorer layer. Tree is Explorer
118
+ * projection and is not a cacheable `RepositoryOperation.decodeCached`
119
+ * implementation; this type remains public because Explorer surfaces
120
+ * it.
121
+ */
122
+ export interface RepositoryTreeResult {
123
+ readonly schemaVersion: 1;
124
+ readonly repository: string;
125
+ readonly path: string;
126
+ readonly depth: number;
127
+ readonly snapshots: readonly RepositoryDirectoryListing[];
128
+ }
129
+ /**
130
+ * Provider-owned legacy cache candidate. Old Z.AI keys encode the
131
+ * raw v0.2 tool response; the Adapter supplies the decoder so shared
132
+ * cache code never inspects Provider response shapes. An invalid
133
+ * decode is a cache miss.
134
+ */
135
+ export interface LegacyRepositoryCacheCandidate<Result> {
136
+ readonly key: string;
137
+ decode(value: unknown): Result | null;
138
+ }
139
+ /**
140
+ * Identity used to read and write a Provider-partitioned cache entry.
141
+ * `credentialFingerprint` is the full lowercase SHA-256 hex digest of
142
+ * the resolved credential and is NEVER re-hashed by cache code.
143
+ * `request` is the normalized Capability request.
144
+ */
145
+ export interface RepositoryCacheIdentity<Request, Result> {
146
+ readonly provider: ProviderId;
147
+ readonly capability: "repository-exploration";
148
+ readonly operation: RepositoryOperationKind;
149
+ readonly credentialFingerprint: string;
150
+ readonly request: Readonly<Request>;
151
+ readonly legacyCandidates: readonly LegacyRepositoryCacheCandidate<Result>[];
152
+ }
153
+ /**
154
+ * Generic operation descriptor. Each Adapter supplies one of these for
155
+ * each operation it supports. The Adapter owns Provider field mapping,
156
+ * credentials, transport lifecycle, and error normalization. Commands
157
+ * and shared execution call only these four methods.
158
+ */
159
+ export interface RepositoryOperation<Request, Result> {
160
+ readonly kind: RepositoryOperationKind;
161
+ /**
162
+ * Validate the request before any Provider access. Throws
163
+ * `ValidationError` for missing required fields and
164
+ * `UnsupportedOptionError` for Provider-specific options the Adapter
165
+ * does not accept. Validation MUST occur before credential resolution
166
+ * or transport construction.
167
+ */
168
+ validate(request: Request): void;
169
+ /**
170
+ * Build the cache identity for a request. Called only after
171
+ * `validate` succeeds. The Adapter resolves its credential once and
172
+ * returns full fingerprint, canonical request, and zero or more
173
+ * legacy candidates. Candidate construction MUST NOT read ambient
174
+ * environment.
175
+ */
176
+ cacheIdentity(request: Request): RepositoryCacheIdentity<Request, Result>;
177
+ /**
178
+ * Total decoder for cached normalized entries. Accepts an `unknown`
179
+ * value, validates shape, and returns the typed result or `null`.
180
+ * NEVER throws, NEVER trusts a generic cast.
181
+ */
182
+ decodeCached(value: unknown): Result | null;
183
+ /**
184
+ * Invoke the Provider and return the normalized result. The Adapter
185
+ * closes its transport and never retries inside this method;
186
+ * shared execution owns retry policy.
187
+ */
188
+ invoke(request: Request): Promise<Result>;
189
+ }
190
+ /**
191
+ * Repository Capability contract. Every Adapter that supports
192
+ * repository exploration implements this interface and exposes it as
193
+ * `adapter.repository` (P6-04 and beyond).
194
+ */
195
+ export interface RepositoryCapability {
196
+ readonly search: RepositoryOperation<RepositorySearchRequest, RepositorySearchResult>;
197
+ readonly readFile: RepositoryOperation<RepositoryFileRequest, RepositoryFileResult>;
198
+ readonly listDirectory: RepositoryOperation<RepositoryDirectoryRequest, RepositoryDirectoryListing>;
199
+ }
200
+ /**
201
+ * Decode a Search result from the cache. Returns the canonical
202
+ * `RepositorySearchResult` on success, `null` for any malformed value.
203
+ */
204
+ export declare function decodeRepositorySearch(value: unknown): RepositorySearchResult | null;
205
+ /**
206
+ * Decode a File result from the cache. Returns the canonical
207
+ * `RepositoryFileResult` on success, `null` otherwise. `path` MUST be
208
+ * non-empty — File is always non-root; `path: ""` is rejected here
209
+ * without performing any other path canonicalization.
210
+ */
211
+ export declare function decodeRepositoryFile(value: unknown): RepositoryFileResult | null;
212
+ /**
213
+ * Decode a Directory Listing from the cache. Returns the canonical
214
+ * `RepositoryDirectoryListing` on success, `null` otherwise. The
215
+ * listing's own `path` may be `""` (root); every entry's `name` and
216
+ * `path` MUST be non-empty. Empty entries arrays are valid (a future
217
+ * Adapter contract). Each entry preserves Provider sibling order
218
+ * verbatim.
219
+ */
220
+ export declare function decodeRepositoryDirectoryListing(value: unknown): RepositoryDirectoryListing | null;
221
+ //# sourceMappingURL=repository.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/capabilities/repository.ts"],"names":[],"mappings":"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"}