scoutline 0.15.0 → 0.17.0

package/dist/commands/config.d.ts

@@ -14,7 +14,7 @@
  * registry layer (API keys never ride argv, AGENTS.md).
  */
 import type { CommandResult } from "../command-invocation.js";
-import { type ScoutlineConfig } from "../lib/config-store.js";
+import { type FanoutNoticeContext, type ScoutlineConfig } from "../lib/config-store.js";
 export interface ConfigGetDependencies {
     /** Read the current config (production: `readConfig`). */
     readonly read: () => Promise<ScoutlineConfig>;
@@ -24,6 +24,22 @@ export interface ConfigGetDependencies {
 export interface ConfigSetDependencies {
     /** Strict set (production: `setConfigValue`). */
     readonly set: (path: string, value: string) => Promise<ScoutlineConfig>;
+    /**
+     * Success-path notice channel (production: the invocation context's
+     * `notice`, stderr). Used for registry-mandated warnings like the
+     * fan-out cost sentence (search-fanout DESIGN D7) — visible in every
+     * output mode while stdout stays data-only. Optional so presentation
+     * doubles stay minimal.
+     */
+    readonly notify?: (message: string) => void;
+    /**
+     * Eligibility context (env + provider registry) the fan-out cost
+     * notice needs to name only the routed providers that would actually
+     * bill — the same arm set `resolveFanoutPlan` computes (review fix,
+     * PR #36). Optional: without it the notice falls back to the blanket
+     * sentence instead of naming raw routing entries.
+     */
+    readonly noticeContext?: FanoutNoticeContext;
 }
 export interface ConfigUnsetDependencies {
     /** Unset (production: `unsetConfigValue`). */

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

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/commands/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAkB,MAAM,0BAA0B,CAAC;AAC9E,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,wBAAwB,CAAC;AAQhC,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,CAAC;IAC9C,wFAAwF;IACxF,QAAQ,CAAC,OAAO,EAAE,MAAM,MAAM,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,qBAAqB;IACpC,iDAAiD;IACjD,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;CACzE;AAED,MAAM,WAAW,uBAAuB;IACtC,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;CAC5D;AA+CD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAyBjC;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC,CAQ1D;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,uBAAuB,GAC5B,OAAO,CAAC,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAO1C;AAED,eAAO,MAAM,WAAW,QA6ChB,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/commands/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAkB,MAAM,0BAA0B,CAAC;AAC9E,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACrB,MAAM,wBAAwB,CAAC;AAQhC,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,CAAC;IAC9C,wFAAwF;IACxF,QAAQ,CAAC,OAAO,EAAE,MAAM,MAAM,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,qBAAqB;IACpC,iDAAiD;IACjD,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;IACxE;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,mBAAmB,CAAC;CAC9C;AAED,MAAM,WAAW,uBAAuB;IACtC,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;CAC5D;AAgDD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAyBjC;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC,CAoB1D;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,uBAAuB,GAC5B,OAAO,CAAC,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAO1C;AAED,eAAO,MAAM,WAAW,QAsDhB,CAAC"}

package/dist/commands/config.js

@@ -46,6 +46,8 @@ function valueAtPath(config, path) {
         return config.routing?.[trimmed.slice("routing.".length)];
     if (trimmed === "fallbackEnabled")
         return config.fallbackEnabled;
+    if (trimmed === "fanout")
+        return config.fanout;
     const providerMatch = /^providers\.([a-z0-9-]+)(?:\.[A-Za-z0-9-]+)*$/.exec(trimmed);
     if (providerMatch?.[1])
         return config.providers[providerMatch[1]];
@@ -78,7 +80,7 @@ export async function configGetCommand(path, deps) {
         // silent "(not set)"; other unknown paths list the valid roots.
         throw path.trim().startsWith("routing.")
             ? unknownConfigKeyError(path)
-            : new ValidationError(`Unknown config key "${path}".`, 'Valid keys: routing, routing.<capability>, fallbackEnabled, providers.<id>. Run "scoutline config --help".');
+            : new ValidationError(`Unknown config key "${path}".`, 'Valid keys: routing, routing.<capability>, fallbackEnabled, fanout, providers.<id>. Run "scoutline config --help".');
     }
     const raw = valueAtPath(config, path);
     const redacted = redactSecrets(raw ?? null, secrets);
@@ -95,6 +97,18 @@ export async function configGetCommand(path, deps) {
 export async function configSetCommand(path, value, deps) {
     const updated = await deps.set(path, value);
     const raw = valueAtPath(updated, path);
+    // Registry-mandated enable-time warning (fan-out cost sentence, D7):
+    // emitted as a stderr notice so it reaches every output mode while
+    // stdout stays data-only. The registry supplies the sentence for the
+    // UPDATED config plus the eligibility context — with `routing.search`
+    // set it names only the routed arms that are ELIGIBLE (configured ∩
+    // search-capable, the same set `resolveFanoutPlan` computes) instead
+    // of claiming ALL configured providers or naming raw routing entries
+    // that would not bill (review fix, PR #36).
+    const key = resolveConfigKey(path);
+    if (key?.setTrueNotice !== undefined && raw === true) {
+        deps.notify?.(key.setTrueNotice(updated, deps.noticeContext));
+    }
     return {
         kind: "data",
         data: { path: path.trim(), value: raw },
@@ -126,6 +140,12 @@ Keys:
   routing.<capability>        Ordered provider list for one capability.
                              Example: scoutline config set routing.search tavily,brave
   fallbackEnabled             true|false — the always-on provider fallback switch.
+  fanout                      true|false — the multi-provider search fan-out
+                             switch (default false; enabling warns about the
+                             billable cost — every configured search provider,
+                             or the routing.search subset when routed).
+                             Remove the standing switch with
+                             \`scoutline config unset fanout\`.
   providers.<id>              Provider configuration (view only; credential
                              values are always masked).
 
@@ -138,7 +158,8 @@ Behaviour:
         provider's environment variable (API keys never belong in command
         arguments).
   unset Removes a routing capability (and the table when the last entry
-        goes), the whole routing table, or the fallbackEnabled switch.
+        goes), the whole routing table, the fallbackEnabled switch, or
+        the fanout switch.
 
 Routing semantics: when no --provider / SCOUTLINE_PROVIDER pin exists,
 the routed list orders provider selection for that capability — the
@@ -155,7 +176,9 @@ Examples:
   scoutline config get routing
   scoutline config set routing.search tavily,brave
   scoutline config set fallbackEnabled false
+  scoutline config set fanout true
   scoutline config unset routing.search
+  scoutline config unset fanout
   scoutline config --help
 `.trim();
 //# sourceMappingURL=config.js.map

package/dist/commands/config.js.map

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

package/dist/commands/repo.d.ts

@@ -23,8 +23,57 @@
  * before reaching the Explorer rather than silently degrading.
  */
 import type { CommandContext, CommandResult } from "../command-invocation.js";
-import type { RepositoryCapability } from "../capabilities/repository.js";
+import type { RepositoryBrief, RepositoryCapability, RepositoryTreeResult, RepoBriefFocus } from "../capabilities/repository.js";
 import type { ExecutionDependencies } from "../lib/execution.js";
+/**
+ * Sealed v1 probe set. Opening the set later is additive — do NOT
+ * mutate this constant at runtime.
+ */
+export declare const REPO_BRIEF_FOCUS: readonly RepoBriefFocus[];
+/**
+ * Probe query constants per DESIGN D7. These are NOT constructed at
+ * call time — they are literal constants so the brief's evidence
+ * chain (search.query inside the envelope) is reproducible byte-for-
+ * byte across providers and reruns.
+ */
+export declare const README_QUERY = "README";
+export declare const MANIFEST_QUERY = "package.json pyproject.toml Cargo.toml go.mod";
+/**
+ * Pure tree-derived file selection (DESIGN D1 / D7 steps 5–8). The
+ * tree is the path inventory — search excerpts carry no paths, so
+ * file selection MUST be tree-derived. The returned `manifests` array
+ * is in canonical kind order; `readme` is the single shallowest
+ * README match. Non-file entries (directories) are ignored even when
+ * their `name` happens to look like a README/manifest.
+ */
+export declare function selectBriefFiles(tree: RepositoryTreeResult): {
+    readme?: string;
+    manifests: string[];
+};
+/**
+ * Parse the `--focus` flag value. Splits on `,`, trims, drops empties,
+ * validates against the sealed `REPO_BRIEF_FOCUS` set, dedupes
+ * preserving first occurrence, and rejects empty-after-processing.
+ *
+ * The error message names the sealed set so a consumer can fix the
+ * value without consulting docs (DESIGN D7 step 3).
+ */
+export declare function parseBriefFocus(raw: string): readonly RepoBriefFocus[];
+/**
+ * Parse the `--depth` flag value. Positive integer (≥ 1); `undefined`
+ * means "unset — use the Explorer's default". Accepts only numbers and
+ * numeric strings (CLI parses flags as strings); every other runtime
+ * type — booleans, null, objects — is rejected BEFORE coercion so a
+ * `true` can never ride `Number(true) === 1` past validation.
+ */
+export declare function parseBriefDepth(raw: unknown): number | undefined;
+/**
+ * Parse the `--max-chars` flag value. Positive integer (≥ 1);
+ * `undefined` means "unset — use the Explorer's default upper bound".
+ * Same runtime-type gate as `parseBriefDepth`: only numbers and numeric
+ * strings are coerced.
+ */
+export declare function parseBriefMaxChars(raw: unknown): number | undefined;
 export interface RepoSearchOptions {
     language?: "en" | "zh";
     maxChars?: number;
@@ -39,6 +88,25 @@ export interface RepoReadOptions {
     maxChars?: number;
     noCache?: boolean;
 }
+export interface RepoBriefOptions {
+    /**
+     * Requested focus, a subset of the sealed `REPO_BRIEF_FOCUS` set, in
+     * caller order. Omitted defaults to all four. Non-empty; each token
+     * must be a sealed member (DESIGN D7 step 3). Duplicate tokens are
+     * collapsed preserving first occurrence, matching `parseBriefFocus`,
+     * so direct handler callers cannot smuggle duplicates into the
+     * envelope's `focus` field.
+     */
+    focus?: readonly RepoBriefFocus[];
+    /** Tree-only scope (DESIGN D3: search/read have no path parameter). */
+    path?: string;
+    /** Tree-only depth; defaults to the Explorer's default (1). */
+    depth?: number;
+    /** Per-call search/read budget; tree is never character-limited. */
+    maxChars?: number;
+    /** Bypasses the response cache for every probe. */
+    noCache?: boolean;
+}
 /**
  * Dependencies injected by `src/index.ts` after Provider selection,
  * capability support check, configuration check, Adapter
@@ -49,6 +117,14 @@ export interface RepoReadOptions {
 export interface RepoHandlerDependencies {
     readonly capability: RepositoryCapability;
     readonly execution: ExecutionDependencies;
+    /**
+     * Invocation-resolved credential values used to redact failed-probe
+     * error messages. Injected by `src/index.ts` already resolved from
+     * the invocation's env (including injected credentials absent from
+     * ambient `process.env`). Omitted → the ambient `configuredSecrets()`
+     * fallback, mirroring `invokeCommand`'s output/error boundary.
+     */
+    readonly secrets?: readonly string[];
 }
 /**
  * Repository Search. Validates parse-level request shape, delegates
@@ -69,5 +145,24 @@ export declare function repoTree(repo: string, options: RepoTreeOptions, deps: R
  * and returns the normalized File result as base data.
  */
 export declare function repoRead(repo: string, path: string, options: RepoReadOptions, deps: RepoHandlerDependencies, _context?: CommandContext): Promise<CommandResult>;
+/**
+ * Repository Brief. Composes the three Explorer operations into one
+ * schema-version-1 envelope (DESIGN D2/D3/D4). Fixed probe order:
+ * tree → search("README") → search(manifest names) → read loop (README
+ * first, then manifests in canonical kind order, cap 4 total reads).
+ *
+ * Parse-level validation (DESIGN D7): `validateRepo`, `--depth` and
+ * `--max-chars` positive integers, `--focus` a non-empty subset of the
+ * sealed set (default all four). Forwarding (DESIGN D3): `--no-cache`
+ * to every call; `--max-chars` to searches/reads only (the tree is
+ * never character-limited); `--depth`/`--path` to the tree only.
+ *
+ * Every Explorer call runs settled (DESIGN D6): a throw becomes a
+ * `failed` probe record and the brief continues. Exit policy: ≥1 probe
+ * `ok` → `{kind: "data"}` (exit 0); every probe terminal and failed →
+ * the last error is rethrown so the executor routes it through the
+ * standard stderr boundary (exit 1).
+ */
+export declare function repoBrief(repo: string, options: RepoBriefOptions, deps: RepoHandlerDependencies, _context?: CommandContext): Promise<CommandResult<RepositoryBrief>>;
 export declare const REPO_HELP: string;
 //# sourceMappingURL=repo.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"repo.d.ts","sourceRoot":"","sources":["../../src/commands/repo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAC1E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AA2BjE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,qBAAqB,CAAC;CAC3C;AAMD;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,iBAAiB,EAC1B,IAAI,EAAE,uBAAuB,EAC7B,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,aAAa,CAAC,CAaxB;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,uBAAuB,EAC7B,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,aAAa,CAAC,CAgBxB;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,uBAAuB,EAC7B,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,aAAa,CAAC,CAUxB;AAcD,eAAO,MAAM,SAAS,QAoEd,CAAC"}
+{"version":3,"file":"repo.d.ts","sourceRoot":"","sources":["../../src/commands/repo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,KAAK,EACV,eAAe,EACf,oBAAoB,EAEpB,oBAAoB,EAGpB,cAAc,EAGf,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAgCjE;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,cAAc,EAK5C,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,YAAY,WAAW,CAAC;AACrC,eAAO,MAAM,cAAc,kDACsB,CAAC;AAkElD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,oBAAoB,GACzB;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,CAgB1C;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,cAAc,EAAE,CA2BtE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAUhE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAUnE;AAMD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAClC,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,qBAAqB,CAAC;IAC1C;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAMD;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,iBAAiB,EAC1B,IAAI,EAAE,uBAAuB,EAC7B,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,aAAa,CAAC,CAaxB;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,uBAAuB,EAC7B,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,aAAa,CAAC,CAgBxB;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,uBAAuB,EAC7B,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,aAAa,CAAC,CAUxB;AAwFD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,gBAAgB,EACzB,IAAI,EAAE,uBAAuB,EAC7B,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC,CAuLzC;AAcD,eAAO,MAAM,SAAS,QAsFd,CAAC"}