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.
- package/README.md +240 -18
- package/dist/capabilities/diagnostics.d.ts +70 -32
- package/dist/capabilities/diagnostics.d.ts.map +1 -1
- package/dist/capabilities/diagnostics.js +97 -46
- package/dist/capabilities/diagnostics.js.map +1 -1
- package/dist/capabilities/reader.d.ts +227 -0
- package/dist/capabilities/reader.d.ts.map +1 -0
- package/dist/capabilities/reader.js +100 -0
- package/dist/capabilities/reader.js.map +1 -0
- package/dist/capabilities/repository.d.ts +221 -0
- package/dist/capabilities/repository.d.ts.map +1 -0
- package/dist/capabilities/repository.js +172 -0
- package/dist/capabilities/repository.js.map +1 -0
- package/dist/commands/cache.d.ts +106 -0
- package/dist/commands/cache.d.ts.map +1 -0
- package/dist/commands/cache.js +203 -0
- package/dist/commands/cache.js.map +1 -0
- package/dist/commands/doctor.d.ts +17 -6
- package/dist/commands/doctor.d.ts.map +1 -1
- package/dist/commands/doctor.js +42 -17
- package/dist/commands/doctor.js.map +1 -1
- package/dist/commands/read.d.ts +74 -14
- package/dist/commands/read.d.ts.map +1 -1
- package/dist/commands/read.js +257 -117
- package/dist/commands/read.js.map +1 -1
- package/dist/commands/repo.d.ts +53 -7
- package/dist/commands/repo.d.ts.map +1 -1
- package/dist/commands/repo.js +104 -123
- package/dist/commands/repo.js.map +1 -1
- package/dist/commands/repository-explorer.d.ts +147 -0
- package/dist/commands/repository-explorer.d.ts.map +1 -0
- package/dist/commands/repository-explorer.js +550 -0
- package/dist/commands/repository-explorer.js.map +1 -0
- package/dist/index.d.ts +20 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +209 -34
- package/dist/index.js.map +1 -1
- package/dist/lib/cache.d.ts +123 -18
- package/dist/lib/cache.d.ts.map +1 -1
- package/dist/lib/cache.js +324 -49
- package/dist/lib/cache.js.map +1 -1
- package/dist/lib/errors.d.ts +24 -1
- package/dist/lib/errors.d.ts.map +1 -1
- package/dist/lib/errors.js +33 -2
- package/dist/lib/errors.js.map +1 -1
- package/dist/lib/execution.d.ts +119 -5
- package/dist/lib/execution.d.ts.map +1 -1
- package/dist/lib/execution.js +216 -10
- package/dist/lib/execution.js.map +1 -1
- package/dist/lib/index.d.ts +1 -1
- package/dist/lib/index.d.ts.map +1 -1
- package/dist/lib/index.js +1 -1
- package/dist/lib/index.js.map +1 -1
- package/dist/lib/mcp-client.d.ts +29 -5
- package/dist/lib/mcp-client.d.ts.map +1 -1
- package/dist/lib/mcp-client.js +88 -88
- package/dist/lib/mcp-client.js.map +1 -1
- package/dist/lib/tool-cache.d.ts +86 -0
- package/dist/lib/tool-cache.d.ts.map +1 -0
- package/dist/lib/tool-cache.js +123 -0
- package/dist/lib/tool-cache.js.map +1 -0
- package/dist/providers/minimax/adapter.d.ts +6 -4
- package/dist/providers/minimax/adapter.d.ts.map +1 -1
- package/dist/providers/minimax/adapter.js +64 -57
- package/dist/providers/minimax/adapter.js.map +1 -1
- package/dist/providers/minimax/coding-plan-client.d.ts +60 -0
- package/dist/providers/minimax/coding-plan-client.d.ts.map +1 -0
- package/dist/providers/minimax/coding-plan-client.js +204 -0
- package/dist/providers/minimax/coding-plan-client.js.map +1 -0
- package/dist/providers/minimax/media.d.ts +60 -6
- package/dist/providers/minimax/media.d.ts.map +1 -1
- package/dist/providers/minimax/media.js +147 -7
- package/dist/providers/minimax/media.js.map +1 -1
- package/dist/providers/minimax/quota-client.d.ts +13 -6
- package/dist/providers/minimax/quota-client.d.ts.map +1 -1
- package/dist/providers/minimax/quota-client.js +5 -0
- package/dist/providers/minimax/quota-client.js.map +1 -1
- package/dist/providers/minimax/vision-attestations.d.ts +23 -0
- package/dist/providers/minimax/vision-attestations.d.ts.map +1 -1
- package/dist/providers/minimax/vision-attestations.js +35 -10
- package/dist/providers/minimax/vision-attestations.js.map +1 -1
- package/dist/providers/minimax/vision-conformance.d.ts +8 -6
- package/dist/providers/minimax/vision-conformance.d.ts.map +1 -1
- package/dist/providers/minimax/vision-conformance.js +8 -6
- package/dist/providers/minimax/vision-conformance.js.map +1 -1
- package/dist/providers/minimax/vision-revisions.d.ts +8 -1
- package/dist/providers/minimax/vision-revisions.d.ts.map +1 -1
- package/dist/providers/minimax/vision-revisions.js +13 -6
- package/dist/providers/minimax/vision-revisions.js.map +1 -1
- package/dist/providers/selection.d.ts +3 -3
- package/dist/providers/selection.js +3 -3
- package/dist/providers/types.d.ts +66 -32
- package/dist/providers/types.d.ts.map +1 -1
- package/dist/providers/types.js.map +1 -1
- package/dist/providers/zai/adapter.d.ts.map +1 -1
- package/dist/providers/zai/adapter.js +71 -5
- package/dist/providers/zai/adapter.js.map +1 -1
- package/dist/providers/zai/encoded-error.d.ts +90 -0
- package/dist/providers/zai/encoded-error.d.ts.map +1 -0
- package/dist/providers/zai/encoded-error.js +169 -0
- package/dist/providers/zai/encoded-error.js.map +1 -0
- package/dist/providers/zai/reader.d.ts +82 -0
- package/dist/providers/zai/reader.d.ts.map +1 -0
- package/dist/providers/zai/reader.js +490 -0
- package/dist/providers/zai/reader.js.map +1 -0
- package/dist/providers/zai/repository.d.ts +76 -0
- package/dist/providers/zai/repository.d.ts.map +1 -0
- package/dist/providers/zai/repository.js +715 -0
- package/dist/providers/zai/repository.js.map +1 -0
- package/package.json +3 -3
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/capabilities/diagnostics.ts"],"names":[],"mappings":"AAAA
|
|
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":"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"}
|
|
@@ -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":"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"}
|