@vibe-agent-toolkit/cli 0.2.0-rc.4 → 0.2.0-rc.6

package/dist/utils/config-loader.js

@@ -6,10 +6,16 @@
  */
 import { readFileSync, existsSync } from 'node:fs';
 import { dirname } from 'node:path';
-import { ProjectConfigSchema } from '@vibe-agent-toolkit/resources';
+import { parseConfigAllowingUnknownKeys, ProjectConfigSchema } from '@vibe-agent-toolkit/resources';
 import { safePath } from '@vibe-agent-toolkit/utils';
 import * as yaml from 'yaml';
 const CONFIG_FILENAME = 'vibe-agent-toolkit.config.yaml';
+/**
+ * Config paths already warned about for unknown keys, so one config governing
+ * many skills produces one line rather than one per skill. Cleared with the
+ * config cache, which is what a test isolating a fixture resets.
+ */
+const warnedConfigPaths = new Set();
 /**
  * A `vibe-agent-toolkit.config.yaml` exists but failed to parse or validate.
  *
@@ -61,12 +67,26 @@ export function loadConfig(projectRoot) {
         // eslint-disable-next-line security/detect-non-literal-fs-filename -- configPath is derived from projectRoot parameter
         const content = readFileSync(configPath, 'utf-8');
         const parsed = yaml.parse(content);
-        // Validate with canonical schema from resources package
-        const result = ProjectConfigSchema.safeParse(parsed);
-        if (!result.success) {
-            throw new Error(`Invalid configuration file: ${result.error.message}`);
-        }
-        return result.data;
+        // Validate with canonical schema from resources package.
+        //
+        // 🔑 The message comes from the shared formatter, NOT from `error.message`.
+        // In Zod 3 that property is a **JSON dump of the issue array**, and it was
+        // what an adopter got: five verbs exiting 2 in under a second on a blob that
+        // never named this file, never said which key was refused in words, and
+        // offered no remedy. Every strict block in the schema is a refusal an
+        // adopter has to be able to act on from the terminal alone.
+        // An UNKNOWN key warns and is dropped; every other validation failure still
+        // throws. See `parseConfigAllowingUnknownKeys` for the reasoning — briefly:
+        // a key VAT has no field for is a key VAT was already discarding, and
+        // turning that into an exit 2 broke commands that never read the section it
+        // was in. Warned once per config path, because `loadConfigCached` will
+        // otherwise re-warn for every skill under one project.
+        return parseConfigAllowingUnknownKeys(ProjectConfigSchema, parsed, (message) => {
+            if (warnedConfigPaths.has(configPath))
+                return;
+            warnedConfigPaths.add(configPath);
+            process.stderr.write(`${message}\n`);
+        }, { configPath });
     }
     catch (error) {
         if (error instanceof Error) {
@@ -113,6 +133,9 @@ const loadErrorCache = new Map();
 export function resetLoadedConfigCache() {
     loadedConfigCache.clear();
     loadErrorCache.clear();
+    // The warn-once ledger is part of this cache's state: a test that resets the
+    // caches and re-loads the same fixture expects to see the warning again.
+    warnedConfigPaths.clear();
 }
 /**
  * Cached variant of {@link loadConfig} keyed by `projectRoot`.

package/dist/utils/config-loader.js.map

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

package/dist/utils/issue-severity.d.ts

@@ -18,11 +18,18 @@
  * findings imports this; nobody writes a fourth copy. Same rule as
  * `resolveAssetReference` and `resolveSkillReference` in CLAUDE.md.
  */
-import { type ValidationIssue } from '@vibe-agent-toolkit/schema';
-/** A `validation.severity` map as it appears in config, or nothing. */
-export interface SeverityOverrides {
-    severity?: Record<string, string> | undefined;
-}
+import { type SeverityConfig, type ValidationIssue } from '@vibe-agent-toolkit/schema';
+/**
+ * A `validation.severity` map as it appears in config, or nothing.
+ *
+ * ⚠️ **Do not re-hand-roll this as `Record<string, string>`.** It was that, and
+ * the key space is now the registry enum PLUS `CUSTOM:<name>` — a `Partial`
+ * mapped type whose values are `SeverityLevel | undefined`. A
+ * `Record<string, string>` is not assignable to it and broke every consumer the
+ * moment the custom key space landed. `SeverityConfig` is the schema's own
+ * `Pick<ValidationConfig, 'severity'>`, so the two cannot drift again.
+ */
+export type SeverityOverrides = SeverityConfig;
 /**
  * Re-severity findings against a `validation.severity` map, dropping the codes
  * resolved to `ignore`.

package/dist/utils/issue-severity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"issue-severity.d.ts","sourceRoot":"","sources":["../../src/utils/issue-severity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAmC,KAAK,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAEnG,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;CAC/C;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,UAAU,EAAE,iBAAiB,GAAG,SAAS,GACxC,eAAe,EAAE,CAenB"}
+{"version":3,"file":"issue-severity.d.ts","sourceRoot":"","sources":["../../src/utils/issue-severity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GAAG,cAAc,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,UAAU,EAAE,iBAAiB,GAAG,SAAS,GACxC,eAAe,EAAE,CAenB"}

package/dist/utils/issue-severity.js

@@ -18,7 +18,7 @@
  * findings imports this; nobody writes a fourth copy. Same rule as
  * `resolveAssetReference` and `resolveSkillReference` in CLAUDE.md.
  */
-import { resolveSeverity } from '@vibe-agent-toolkit/schema';
+import { resolveSeverity, } from '@vibe-agent-toolkit/schema';
 /**
  * Re-severity findings against a `validation.severity` map, dropping the codes
  * resolved to `ignore`.

package/dist/utils/issue-severity.js.map

@@ -1 +1 @@
-{"version":3,"file":"issue-severity.js","sourceRoot":"","sources":["../../src/utils/issue-severity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAkB,eAAe,EAAwB,MAAM,4BAA4B,CAAC;AAOnG;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAkC,EAClC,UAAyC;IAEzC,MAAM,SAAS,GAAG,UAAU,EAAE,QAAQ,CAAC;IACvC,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC;IAEhD,MAAM,QAAQ,GAAsB,EAAE,CAAC;IACvC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,IAAI,SAAS,CAAC,EAAE,CAAC;YAC/B,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrB,SAAS;QACX,CAAC;QACD,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,CAAC,IAAiB,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC;QACnF,IAAI,QAAQ,KAAK,QAAQ;YAAE,SAAS;QACpC,QAAQ,CAAC,IAAI,CAAC,QAAQ,KAAK,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}
+{"version":3,"file":"issue-severity.js","sourceRoot":"","sources":["../../src/utils/issue-severity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAEL,eAAe,GAGhB,MAAM,4BAA4B,CAAC;AAcpC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAkC,EAClC,UAAyC;IAEzC,MAAM,SAAS,GAAG,UAAU,EAAE,QAAQ,CAAC;IACvC,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC;IAEhD,MAAM,QAAQ,GAAsB,EAAE,CAAC;IACvC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,IAAI,SAAS,CAAC,EAAE,CAAC;YAC/B,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrB,SAAS;QACX,CAAC;QACD,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,CAAC,IAAiB,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC;QACnF,IAAI,QAAQ,KAAK,QAAQ;YAAE,SAAS;QACpC,QAAQ,CAAC,IAAI,CAAC,QAAQ,KAAK,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/utils/projection-query.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Populating a tree's resource projection and putting it somewhere ASKABLE —
+ * the shared half of every command that runs SQL over it.
+ *
+ * `vat resources query` runs one statement a person typed; `vat resources check`
+ * runs the statements a project wrote down. They differ in what they do with
+ * rows and in nothing else: same population, same store selection, same
+ * ephemeral fallback, same cache tell. This module is that "and in nothing
+ * else", stated once so the two cannot drift into answering about different
+ * corpora.
+ *
+ * ## 🚨 The SQL ALWAYS runs against a per-run in-memory database. Never the store.
+ *
+ * This is a correctness property, not an optimisation choice, and it was learned
+ * the expensive way. The on-disk projection store is **one database per VAT
+ * release, shared by every root on the machine** (`defaultStoreDirectory()` is
+ * `tmpdir/.vat-cache/<version>/projection-<shapeDigest>`), it retains three tree
+ * hashes per root, and its blob tier is never evicted and carries no tree key at
+ * all. `ProjectionStore.readExtent` narrows by `(rootId, treeHash)`; **arbitrary
+ * SQL does not**, and cannot be made to — a `WHERE` clause the caller wrote is
+ * not a key predicate.
+ *
+ * So running a user's statement against the file-backed store answered from
+ * every projection on the machine. Measured on a two-file scratch repository:
+ * `SELECT COUNT(*) FROM resource_realizations` returned **3** with no store and
+ * **5,779** with one, and `WHERE path LIKE 'packages/%'` returned paths from a
+ * different repository entirely. That is a wrong answer and a cross-project
+ * disclosure of link text, heading text and frontmatter — the same material
+ * `store.ts` cites as the reason it chmods the cache `0o700`.
+ *
+ * ⇒ The store's job is to make the POPULATION cheap, and that is all. Whatever
+ * `populate()` returns — served from the store or derived — is written into a
+ * fresh in-memory database that holds this tree and nothing else, and the SQL
+ * runs there. The saving is untouched (it was always in the population: on this
+ * repository {@link ProjectionProvenance.populationMs} reads 1.16-1.18 s derived
+ * against 0.29-0.31 s served), and "one tree, one answer" stops being a claim
+ * about how callers behave and becomes a property of the shape.
+ *
+ * ## The store never reaches a caller
+ *
+ * Work runs against an `ask` closure rather than a store handle. That is
+ * deliberate: `utils/projection-store.ts` is the one module in the toolkit that
+ * knows `@vibe-agent-toolkit/projection-sqlite` exists, and handing commands a
+ * backend-typed object would spread that knowledge to every future verb. A
+ * closure also puts the legible-failure wrapper on the single path that can
+ * throw, so no command can forget it.
+ */
+import type { Logger } from './logger.js';
+/** Where the POPULATION a statement ran against came from. */
+export type PopulationOrigin = 'derived' | 'store';
+/**
+ * What a run's rows are, and where they came from.
+ *
+ * ⚠️ There is deliberately no `engine` field beside these. An earlier version
+ * published one (`sqlite | ephemeral`) to say which database answered the SQL;
+ * it is gone because the answer is now always the same — see the header — and a
+ * field with one possible value tells a reader nothing while implying the other
+ * value is reachable.
+ */
+export interface ProjectionProvenance {
+    /**
+     * 🔑 The cache tell. Reported rather than inferred, because it CANNOT be
+     * inferred: a correct store hit and a correct re-derivation produce identical
+     * rows. A hit short-circuits `populate()` before the builder exists, so no
+     * contributor timing is filed — an empty record list IS the hit.
+     *
+     * It describes the POPULATION, which is the only thing the store now affects.
+     */
+    readonly population: PopulationOrigin;
+    /**
+     * 🔑 What that origin was WORTH. {@link population} says whether the
+     * projection was served or re-derived; this says what the difference cost, so
+     * the tell stops being a bare label a reader has to take on faith.
+     *
+     * Measured as THIS field, by running `vat resources query 'SELECT COUNT(*) AS
+     * n FROM blobs'` against this repository three times per arm with the parse
+     * cache warm: **1.16-1.18 s derived against 0.29-0.31 s served**. With a cold
+     * parse cache the derived arm is 33-35 s, so the pair above is the store's
+     * saving and not the parse cache's.
+     *
+     * The wall time of the SHARED setup and nothing else: everything
+     * {@link withQueriedProjection} does before it hands control to the caller's
+     * work — opening the population cache (which, when a store is selected, is a
+     * `git write-tree` spawn plus the backend's dynamic import and
+     * `openSqliteProjectionStore()`), the git tracker, `buildResourceProjection`,
+     * opening the ephemeral database, and writing the blob tier and the extent
+     * into it.
+     *
+     * ⚠️ The population cache's CLOSE is outside it, necessarily: that runs in
+     * `withPopulationCache`'s `finally`, after the caller's work returns, and a
+     * span that ends before the work begins cannot contain it. It is a handle
+     * release, not population.
+     *
+     * 🪤 **The span's start is load-bearing, and moving it inward is silent.**
+     * This shipped with the clock started on the first line INSIDE
+     * `withPopulationCache`'s callback — which put the population-cache open, the
+     * only part of the setup a store adds, OUTSIDE the measurement, and only on
+     * the arm where a store exists. Measured on a two-file corpus with identical
+     * total wall time on both arms: no store 0.145 of 0.146 s, cold store 0.0475
+     * of 0.161 s. Same work, `populationSecs` three times apart, and a reader
+     * comparing a no-store run to a warm-store run read a 42x saving where the
+     * honest totals differ by 1.75x. The field was added to stop the cache tell
+     * being a label taken on faith and had become the artifact instead. A
+     * measurement that flatters one arm is this repository's most-repeated
+     * defect; the system suite now pins `populationSecs / durationSecs > 0.6` on a
+     * cold run so the next inward move is red rather than quiet.
+     *
+     * ## Why it belongs on shared provenance rather than on one verb
+     *
+     * Both verbs pay it, identically, because it is the half of the run they hold
+     * in common — a `check` that runs forty statements and a `query` that runs one
+     * do the same population first. And a per-statement cost is UNREADABLE without
+     * it: `vat resources check` publishes what each rule's SQL cost, and a reader
+     * handed forty small numbers and a large total has no way to tell an expensive
+     * rule from a setup everybody shares. Absent this field the only arithmetic
+     * available is "total minus the statements", which silently attributes the
+     * shared setup to whichever rule the reader is looking at.
+     *
+     * ⚠️ Measured with `performance.now()`, not `Date.now()`. A warm population
+     * lands well under a millisecond on a small tree, and a millisecond-granularity
+     * clock reports that as `0` — which reads as "not measured" rather than "very
+     * fast", turning the best case the store has into its least credible number.
+     *
+     * ⚠️ Deliberately ONE number, not a breakdown. Splitting it into crawl, parse
+     * and store-load is a real question and it is the lab's: an instrument that
+     * gets reviewed and re-run, rather than a product document that would then owe
+     * every consumer a stable sub-phase vocabulary.
+     */
+    readonly populationMs: number;
+}
+/**
+ * How much of the tree the population actually covered.
+ *
+ * ## Why this is not a field on {@link ProjectionProvenance}
+ *
+ * Provenance is a fact both verbs PUBLISH verbatim — "these rows were served or
+ * re-derived" is the same sentence in either document. This is a fact a verb
+ * REASONS with, and only one of them has anything to reason about: `vat
+ * resources query` prints the rows a person selected, so its reader can see the
+ * extent for themselves, while `vat resources check` prints a verdict and a
+ * count of rules. Only the second can pass vacuously, and only the second needs
+ * to know.
+ *
+ * ## 🔑 The failure it exists to make visible
+ *
+ * `vat resources check` reported how many CHECKS ran; nothing said how many ROWS
+ * they ran against. So "four checks passed over eight thousand files" and "four
+ * checks passed over ZERO files" were byte-identical documents, and the second
+ * was a green gate asserting nothing. A broad `.gitignore`, a shallow or sparse
+ * checkout, a root that resolved elsewhere, or an extent source that enumerated
+ * nothing all produce it — and `buildResourceProjection` DECLINES ignored
+ * members rather than flagging them, so an emptied enumeration leaves no trace
+ * in the tables either.
+ */
+export interface PopulationExtent {
+    /**
+     * One per `(extentId, path)` row the population enumerated.
+     *
+     * 🪤 Realizations rather than any other count, because every alternative
+     * fails to reach zero on the case that matters: `roots` always holds exactly
+     * one row (the invariant thrown for below), so a total over all twelve tables
+     * is never 0; `blobs` is content-keyed and deduped, so it counts parse REACH
+     * and already has its own guard in `onBlobPopulation`; and `resources` counts
+     * identities, which a corpus can legitimately have none of while enumerating
+     * plenty. One row per enumerated path is non-zero exactly when something was
+     * enumerated.
+     */
+    readonly membersEnumerated: number;
+}
+/** Run one read-only statement against the populated projection. */
+export type AskProjection = (sql: string, ...parameters: readonly string[]) => readonly Record<string, unknown>[];
+/**
+ * Compile every statement a run intends to ask, against the schema and NO rows,
+ * before anything is populated.
+ *
+ * ## 🔑 What this buys, measured
+ *
+ * SQLite resolves table and column names when a statement is *prepared*, not
+ * when it is stepped — so a typo is knowable before a single row exists. It was
+ * not knowable in practice, because the only place a statement met the schema
+ * was after the projection had been built. On a real adopter tree, `SELECT path,
+ * no_such_column …` cost **8.3 s**, every millisecond of it spent building a
+ * projection the statement could never have read. The same typo now costs the
+ * price of an empty in-memory database — one extra `createSchema` into
+ * `:memory:`, which is the whole overhead this adds on the happy path.
+ *
+ * It also moves the KIND refusals — a second statement, an `ATTACH`, a `PRAGMA`
+ * — in front of the population, so a statement rejected for what it is costs no
+ * more than one rejected for what it names.
+ *
+ * ⚠️ **This is a pre-flight, not a second gate.** `ask` still compiles and runs
+ * the real statement against the real projection, and nothing here is trusted in
+ * place of that. A statement that compiles here can still fail there — SQLite
+ * resolves names against a schema, and this is the same schema, but a run-time
+ * error (a bad cast, an overflow) belongs to stepping and is unreachable from a
+ * prepare.
+ *
+ * ⚠️ It deliberately does not STEP anything. Stepping is where a check's
+ * unbounded cost lives, and a preflight that ran `WITH RECURSIVE …` would hang
+ * before the run it exists to make cheap had begun.
+ *
+ * @param statements - Every statement the run will ask, in any order
+ * @throws The same legible failure `ask` throws, for the first statement that
+ *   does not compile
+ */
+export declare function assertQueriesCompile(statements: readonly string[]): Promise<void>;
+/**
+ * Populate the tree, load it into something askable, and hand the caller a way
+ * to ask.
+ *
+ * @param options - The run
+ * @param options.root - Absolute corpus root
+ * @param options.logger - Where blob-stage refusals are reported (stderr, so a
+ *   parseable document on stdout stays parseable)
+ * @param options.preflight - Every statement this run intends to ask, compiled
+ *   against the empty schema BEFORE the population starts. See
+ *   {@link assertQueriesCompile}
+ * @param work - Given the asker, where its rows came from, and how much of the
+ *   tree they cover. The store is open for exactly this call and closed however
+ *   it ends
+ * @returns Whatever `work` returned
+ */
+export declare function withQueriedProjection<T>(options: {
+    root: string;
+    logger: Logger;
+    preflight?: readonly string[];
+}, work: (ask: AskProjection, provenance: ProjectionProvenance, extent: PopulationExtent) => Promise<T> | T): Promise<T>;
+/**
+ * Turn a rejected statement into a message that names the surface it missed.
+ *
+ * ## Why this wrapper exists
+ *
+ * VAT ships no schema version, by standing rule — the *cache* is safe across a
+ * shape change because its digest self-invalidates, but submitted SQL is not: it
+ * simply breaks. Pre-1.0 that is acceptable. A raw SQLite error reaching the
+ * user is not, because `no such column: contentHash` says nothing about what the
+ * column is called now. It matters more for a CHECK than for a query: a query's
+ * author is at the keyboard, while a check's author wrote it months ago and the
+ * person reading the failure is someone else.
+ *
+ * ⚠️ **A legibility wrapper, not a validator.** It does not parse SQL and does
+ * not check a statement before running it — it reacts to a failure by listing
+ * what the query COULD have named. When the statement mentions a known table,
+ * that table's columns are listed, which is the case that actually answers "what
+ * moved"; otherwise the table names are, which at least answers "what is there".
+ *
+ * 🪤 **Only a name that was not found gets the listing.** The engine also refuses
+ * a write and this backend refuses a second statement, and neither is answered by
+ * a column list — appending one says the problem is the schema when the problem
+ * is what the caller asked for. A wrapper that decorates every failure identically
+ * teaches the reader to skip the decoration, which costs the case it was written for.
+ *
+ * Matching is a plain lowercase substring test rather than a regex: the input is
+ * user text, and a pattern built from it is both a lint failure here and a
+ * needless hazard.
+ *
+ * @param sql - The statement that was submitted
+ * @param message - What the engine said
+ * @returns The message to surface, with the queryable surface appended when the
+ *   failure was a name this projection does not have
+ */
+export declare function describeQueryFailure(sql: string, message: string): string;
+//# sourceMappingURL=projection-query.d.ts.map

package/dist/utils/projection-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection-query.d.ts","sourceRoot":"","sources":["../../src/utils/projection-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAYH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAkB1C,8DAA8D;AAC9D,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,CAAC;AAEnD;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0DG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,oEAAoE;AACpE,MAAM,MAAM,aAAa,GAAG,CAC1B,GAAG,EAAE,MAAM,EACX,GAAG,UAAU,EAAE,SAAS,MAAM,EAAE,KAC7B,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,oBAAoB,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBvF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,EACxE,IAAI,EAAE,CACJ,GAAG,EAAE,aAAa,EAClB,UAAU,EAAE,oBAAoB,EAChC,MAAM,EAAE,gBAAgB,KACrB,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAClB,OAAO,CAAC,CAAC,CAAC,CA4FZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAezE"}