@opensip-cli/core 0.1.0

package/dist/plugins/manifest-loader.js

@@ -0,0 +1,410 @@
+// @fitness-ignore-file file-length-limit -- one cohesive manifest pipeline: the static reader (loadToolManifest), the single admission gate (admitTool), and their private validate/normalize/hash/diagnose helpers form one read→validate→admit subsystem over the raw-vs-admitted compatibility contract. The helpers are admission-internal (not reused elsewhere); hoisting them out would scatter one contract across files. Grew past the 400-line soft limit with the per-field normalization helpers.
+/**
+ * @fileoverview Static manifest reader + the single admission gate
+ * (launch, raw-vs-admitted compatibility contract).
+ *
+ * `loadToolManifest` reads a tool's static front matter **before**
+ * importing its runtime `Tool` module:
+ *
+ *   - **bundled** / **installed** — `package.json#opensipTools` in the tool's
+ *     own package dir (one read for both; the discovery walker already
+ *     touches these package.json files).
+ *   - **project-local** / **user-global** — a JSON sidecar
+ *     (`opensip-tool.manifest.json`) in the tool's directory, since an
+ *     authored tool is authored content, not an installed npm package with a
+ *     package.json marker. Both authored sources read the SAME sidecar; only
+ *     their trust posture differs (deny-by-default vs trusted-by-default),
+ *     which is the admission caller's concern, not the loader's.
+ *
+ * It validates the raw identity subset (`kind: 'tool'`, `id`, `commands`),
+ * derives `name`/`version` from the package.json's own top-level fields
+ * (the manifest block does NOT redeclare them — single source of truth),
+ * validates concrete additive descriptors such as `capabilities`, and returns
+ * `undefined` (with a structured logger diagnostic) on a malformed or missing
+ * manifest. A missing `apiVersion` is still representable as a
+ * `RawToolPluginManifest` so `admitTool` can reject it with a compatibility
+ * diagnostic. It NEVER imports the tool module.
+ *
+ * `admitTool` is the single gate the bundled and external paths share: it
+ * records `ToolProvenance` (incl. a `manifestHash` over the canonical
+ * manifest JSON) and runs `checkCompatibility(manifest.apiVersion)`:
+ *   - compatible                       → `admit`
+ *   - incompatible + not requested     → `skip` (with diagnostic)
+ *   - incompatible + explicitly asked  → `fail-closed` (with diagnostic)
+ * It emits exactly one structured logger evt per decision.
+ *
+ * Both functions are pure over real filesystem reads of package.json /
+ * the sidecar — no tool-module import, no module singletons. They stay in
+ * core (the kernel) and import nothing from contracts/cli/tools-runtime.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { logger } from '../lib/logger.js';
+import { checkCompatibility } from '../tools/compatibility.js';
+import { PLUGIN_API_VERSION } from '../tools/manifest.js';
+import { isRecord, isStringArray } from './json-guards.js';
+import { normalizeDiscovery } from './manifest-discovery.js';
+/**
+ * Filename of the project-local manifest sidecar. A project-local tool is
+ * authored content under `<project>/opensip-cli/…`, not an installed npm
+ * package, so it has no `package.json#opensipTools` marker — it declares
+ * its identity via this JSON sidecar (deliberately NOT an executable
+ * `.mjs`, so the host reads identity without running tool code).
+ */
+export const PROJECT_LOCAL_MANIFEST_FILE = 'opensip-tool.manifest.json';
+/** `module` field stamped on every structured log event from this file. */
+const LOADER_MODULE = 'core:plugins';
+/**
+ * Read + validate a tool's static `ToolPluginManifest` for the given
+ * source, WITHOUT importing the tool's runtime module.
+ *
+ *   - `bundled` / `installed` — reads `<dir>/package.json`, taking identity
+ *     from the `opensipTools` block and `name`/`version` from the
+ *     package.json's own top-level fields.
+ *   - `project-local` / `user-global` — reads
+ *     `<dir>/opensip-tool.manifest.json` (the JSON sidecar), which carries the
+ *     full identity inline. Both authored sources share the sidecar branch.
+ *
+ * @param source Where the tool came from — selects the manifest location.
+ * @param dir The tool's package/authoring directory.
+ * @returns The validated manifest, or `undefined` (with a structured
+ *   `plugin.manifest.read_failed` diagnostic) when the file is missing,
+ *   unparseable, or fails identity validation.
+ */
+export function loadToolManifest(source, dir) {
+    // Both authored sources (project-local + user-global) declare identity via
+    // the JSON sidecar; bundled/installed read package.json#opensipTools.
+    const authored = source === 'project-local' || source === 'user-global';
+    const raw = authored ? readSidecar(dir) : readPackageManifest(dir);
+    if (raw === undefined) {
+        diagnose(dir, source, 'manifest file missing or unreadable');
+        return undefined;
+    }
+    const manifest = validateManifest(raw.block, raw.name, raw.version);
+    if (manifest === undefined) {
+        diagnose(dir, source, raw.reason ?? 'manifest failed identity validation');
+        return undefined;
+    }
+    return manifest;
+}
+/**
+ * Run the single compatibility gate over a manifest and produce an
+ * {@link AdmissionResult}. Records `ToolProvenance` (source + identity +
+ * `manifestHash`) regardless of verdict, then maps the
+ * `checkCompatibility` outcome to a decision:
+ *
+ *   - compatible                          → `admit`
+ *   - incompatible + `!explicitlyRequested` → `skip`
+ *   - incompatible + `explicitlyRequested`  → `fail-closed`
+ *
+ * Emits exactly one structured logger evt per decision
+ * (`plugin.manifest.loaded` / `plugin.incompatible.skipped` /
+ * `plugin.incompatible.failed`). Never throws, never imports the tool.
+ *
+ * @param args.manifest The validated manifest (from {@link loadToolManifest}).
+ * @param args.source Where the tool came from.
+ * @param args.dir The tool's resolved directory (recorded as `resolvedPath`).
+ * @param args.packageName npm package name, when known (bundled/installed).
+ * @param args.explicitlyRequested Whether the user named this tool directly
+ *   (e.g. via a plugin pin) — promotes an incompatible `skip` to `fail-closed`.
+ */
+export function admitTool(args) {
+    const { manifest, source, dir, packageName, explicitlyRequested } = args;
+    const manifestHash = hashManifest(manifest);
+    const provenance = {
+        source,
+        id: manifest.id,
+        ...(manifest.stableId ? { stableId: manifest.stableId } : {}),
+        version: manifest.version,
+        ...(packageName === undefined ? {} : { packageName }),
+        resolvedPath: dir,
+        manifestHash,
+    };
+    const verdict = checkCompatibility(manifest.apiVersion);
+    if (verdict.kind === 'compatible') {
+        const admittedManifest = {
+            ...manifest,
+            // `verdict.kind === 'compatible'` ⇒ apiVersion equals the engine epoch (a
+            // defined number); the `?? PLUGIN_API_VERSION` fallback is never reached
+            // when compatible — it only narrows the type to `number` without a
+            // non-null assertion.
+            apiVersion: manifest.apiVersion ?? PLUGIN_API_VERSION,
+        };
+        logger.info({
+            evt: 'plugin.manifest.loaded',
+            module: LOADER_MODULE,
+            id: manifest.id,
+            source,
+            apiVersion: admittedManifest.apiVersion,
+            engine: undefined,
+            manifestHash,
+            decision: 'admit',
+        });
+        return { decision: 'admit', provenance, verdict, manifest: admittedManifest };
+    }
+    // incompatible
+    const diagnostic = verdict.reason;
+    if (explicitlyRequested) {
+        logger.error({
+            evt: 'plugin.incompatible.failed',
+            module: LOADER_MODULE,
+            id: manifest.id,
+            source,
+            apiVersion: verdict.declared,
+            engine: verdict.engine,
+            manifestHash,
+            decision: 'fail-closed',
+            diagnostic,
+        });
+        return { decision: 'fail-closed', provenance, verdict, diagnostic };
+    }
+    logger.warn({
+        evt: 'plugin.incompatible.skipped',
+        module: LOADER_MODULE,
+        id: manifest.id,
+        source,
+        apiVersion: verdict.declared,
+        engine: verdict.engine,
+        manifestHash,
+        decision: 'skip',
+        diagnostic,
+    });
+    return { decision: 'skip', provenance, verdict, diagnostic };
+}
+/**
+ * Read `<dir>/package.json` and extract the `opensipTools` block plus the
+ * top-level `name`/`version`. Returns `undefined` when the file is missing
+ * or unparseable, or when there is no object-shaped `opensipTools` block.
+ */
+function readPackageManifest(dir) {
+    const json = readJson(join(dir, 'package.json'));
+    if (json === undefined)
+        return undefined;
+    const block = json.opensipTools;
+    if (!isRecord(block))
+        return undefined;
+    return { block, name: json.name, version: json.version };
+}
+/**
+ * Read the project-local JSON sidecar. The sidecar IS the manifest block
+ * and carries `name`/`version` inline (there is no package.json alongside
+ * an authored project-local tool).
+ */
+function readSidecar(dir) {
+    const json = readJson(join(dir, PROJECT_LOCAL_MANIFEST_FILE));
+    if (json === undefined)
+        return undefined;
+    return { block: json, name: json.name, version: json.version };
+}
+/**
+ * Validate the identity subset of a manifest block and assemble a typed
+ * `RawToolPluginManifest`. `name`/`version` come from the package.json's own
+ * fields (bundled/installed) or inline (sidecar). Returns `undefined` (with
+ * a `reason` is reported by the caller) on any identity violation.
+ */
+/** Narrow an unknown value to a non-empty string (the manifest identity-field guard). */
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value !== '';
+}
+/** Narrow to an optional non-empty string: absent, or a non-empty string. */
+function isAbsentOrNonEmptyString(value) {
+    return value === undefined || isNonEmptyString(value);
+}
+/**
+ * Validate the optional `capabilities` slot. Returns `undefined` when absent
+ * (additive — no declared domains), the normalized array when valid, or the
+ * `'invalid'` sentinel when present-but-malformed (the caller then rejects the
+ * whole manifest). Keeps the absent/invalid distinction out of the main
+ * validator's control flow.
+ */
+function validateOptionalCapabilities(raw) {
+    if (raw === undefined)
+        return undefined;
+    return normalizeCapabilities(raw) ?? 'invalid';
+}
+function validateManifest(block, name, version) {
+    if (block.kind !== 'tool')
+        return undefined;
+    if (!isNonEmptyString(block.id))
+        return undefined;
+    if (!isNonEmptyString(name))
+        return undefined;
+    if (!isNonEmptyString(version))
+        return undefined;
+    const commands = normalizeCommands(block.commands);
+    if (commands === undefined)
+        return undefined;
+    const apiVersion = block.apiVersion;
+    if (apiVersion !== undefined && typeof apiVersion !== 'number')
+        return undefined;
+    // ADR-0048: the tool's stable machine identity (UUID). Additive + optional —
+    // present-but-non-string fails validation, mirroring the `id` guard above.
+    // MUST be carried onto the manifest: the drift guard (assertManifestMatchesTool)
+    // matches it against the runtime `metadata.id`, and capability-domain ownership
+    // (registerCapabilityDomainsFromManifest) stamps `ownerToolId = stableId ?? id`.
+    // Dropping it here silently breaks graph-adapter discovery (owner never matches
+    // the tool's UUID `metadata.id`).
+    if (!isAbsentOrNonEmptyString(block.stableId))
+        return undefined;
+    const stableId = block.stableId;
+    // §5.3 (launch): the `capabilities` slot. Absent ⇒ no declared domains;
+    // present-but-malformed ⇒ the whole manifest is invalid (the `'invalid'`
+    // sentinel), mirroring the strict `commands` parse above.
+    const capabilities = validateOptionalCapabilities(block.capabilities);
+    if (capabilities === 'invalid')
+        return undefined;
+    // Reserved for future community/catalog (see ToolPluginManifestBase).
+    // We explicitly copy them through as `unknown` (additive) so they survive
+    // load → admit without loss. This is the lightweight consumer hygiene
+    // (roadmap item 3) — authors get structural round-tripping now; future
+    // releases can add non-fatal warnings or concrete schemas without
+    // breaking GA-era manifests. The admission gate already treats extra
+    // fields permissively; this just makes the intent explicit.
+    const compatibility = block.compatibility;
+    const distribution = block.distribution;
+    const extensionMetadata = block.extensionMetadata;
+    return {
+        kind: 'tool',
+        id: block.id,
+        ...(stableId === undefined ? {} : { stableId }),
+        name,
+        version,
+        ...(apiVersion === undefined ? {} : { apiVersion }),
+        commands,
+        ...(capabilities === undefined ? {} : { capabilities }),
+        ...(compatibility === undefined ? {} : { compatibility }),
+        ...(distribution === undefined ? {} : { distribution }),
+        ...(extensionMetadata === undefined ? {} : { extensionMetadata }),
+    };
+}
+/** Closed set of valid `contributionKind` values for a capability declaration. */
+const CONTRIBUTION_KINDS = [
+    'module-export',
+    'manifest-entry',
+    'file',
+];
+/**
+ * Validate + normalize a PRESENT `capabilities` array to
+ * `ToolCapabilityDeclaration[]`. Each entry needs a non-empty string `id`,
+ * a numeric `apiVersion`, and a `contributionKind` in the closed set;
+ * `contributionSchema` is `unknown` (the kernel carries no Zod) and is
+ * passed through verbatim. Returns the declarations on success, or
+ * `undefined` when the slot is malformed (the caller fails the manifest,
+ * mirroring `normalizeCommands`). The absent case is handled by the caller.
+ */
+function normalizeCapabilities(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const out = [];
+    for (const entry of value) {
+        if (!isRecord(entry))
+            return undefined;
+        if (typeof entry.id !== 'string' || entry.id === '')
+            return undefined;
+        if (typeof entry.apiVersion !== 'number')
+            return undefined;
+        const kind = entry.contributionKind;
+        if (!isContributionKind(kind))
+            return undefined;
+        // `discovery` is optional, but a PRESENT-but-malformed descriptor fails the
+        // manifest (mirroring the strict `contributionKind` check above).
+        const discovery = normalizeDiscovery(entry.discovery);
+        if (discovery.status === 'invalid')
+            return undefined;
+        out.push({
+            id: entry.id,
+            apiVersion: entry.apiVersion,
+            // `contributionSchema` is unknown by contract — pass through as-is
+            // (may legitimately be absent for a domain that validates inside its
+            // own registrar).
+            contributionSchema: entry.contributionSchema,
+            contributionKind: kind,
+            ...(discovery.status === 'ok' ? { discovery: discovery.descriptor } : {}),
+        });
+    }
+    return out;
+}
+/** Type guard for the closed `CapabilityContributionKind` union. */
+function isContributionKind(value) {
+    return typeof value === 'string' && CONTRIBUTION_KINDS.includes(value);
+}
+/**
+ * Validate + normalize the `commands` array to `ToolCommandManifest[]`.
+ * Each entry must carry a string `name` + `description`; optional
+ * `aliases` must be a string array. Returns `undefined` on any violation.
+ */
+function normalizeCommands(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const out = [];
+    for (const entry of value) {
+        if (!isRecord(entry))
+            return undefined;
+        if (typeof entry.name !== 'string' || entry.name === '')
+            return undefined;
+        if (typeof entry.description !== 'string')
+            return undefined;
+        const { aliases } = entry;
+        if (aliases !== undefined && !isStringArray(aliases))
+            return undefined;
+        out.push({
+            name: entry.name,
+            description: entry.description,
+            ...(aliases === undefined ? {} : { aliases }),
+        });
+    }
+    return out;
+}
+function hashManifest(manifest) {
+    const canonical = JSON.stringify({
+        kind: manifest.kind,
+        id: manifest.id,
+        name: manifest.name,
+        version: manifest.version,
+        apiVersion: manifest.apiVersion ?? null,
+        commands: manifest.commands.map((c) => ({
+            name: c.name,
+            description: c.description,
+            aliases: c.aliases ?? null,
+        })),
+    });
+    return createHash('sha256').update(canonical, 'utf8').digest('hex');
+}
+/**
+ * Read + JSON-parse a file, returning the parsed object or `undefined`
+ * when the file is missing, unreadable, unparseable, or not an object.
+ * Mirrors the JSON-read pattern in `marker-discovery.ts` (best-effort,
+ * never throws) so the discovery surfaces share one read style.
+ */
+function readJson(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch (error) {
+        // Best-effort read (mirrors marker-discovery.ts): a malformed/unreadable
+        // manifest file is a skip, not a crash — but we surface WHY at debug so a
+        // genuinely broken file is diagnosable rather than silently invisible.
+        logger.debug({
+            evt: 'plugin.manifest.read_failed',
+            module: LOADER_MODULE,
+            path,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
+    }
+}
+/** Emit the structured read-failure diagnostic (debug — a missing/malformed manifest is a skip, not a crash). */
+function diagnose(dir, source, reason) {
+    logger.debug({
+        evt: 'plugin.manifest.read_failed',
+        module: LOADER_MODULE,
+        dir,
+        source,
+        reason,
+    });
+}
+//# sourceMappingURL=manifest-loader.js.map

package/dist/plugins/manifest-loader.js.map

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

package/dist/plugins/marker-discovery.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview Generic marker-based plugin discovery.
+ *
+ * Walks ancestor `node_modules/` directories from a project root, looking
+ * for packages whose `package.json` declares an `opensipTools.kind` value
+ * matching the requested kind. Returns the deduplicated list (first
+ * occurrence walking outward wins, matching Node's nearest-ancestor
+ * module resolution).
+ *
+ * `MarkerKind` is the closed union of HOST marker kinds — just `'tool'` now
+ * (whole-subcommand Tool plugins, a host concern). The former DOMAIN markers
+ * (`'fit-pack'`, `'sim-pack'`, `'graph-adapter'`) were RETIRED from this union
+ * once discovery became descriptor-driven (§5.3): a tool's manifest declares its
+ * own marker kind, the generic substrate discovers it via the string-typed
+ * {@link discoverPackagesByDeclaredKind}, and nothing in the host compiles in the
+ * domain vocabulary. Use {@link readDeclaredKind} for any kind that is not the
+ * host `'tool'` marker.
+ *
+ * Why a marker rather than a name pattern (for `'tool'`): a name-prefix rule
+ * breaks down once organisations publish their own scoped tool packages. The
+ * marker decouples publication scope from plugin shape.
+ */
+/**
+ * The closed vocabulary of HOST `opensipTools.kind` markers — `'tool'` only.
+ * Domain markers (fit-pack/sim-pack/graph-adapter) are NOT here anymore: they are
+ * declared per-tool in manifests and discovered via {@link discoverPackagesByDeclaredKind}
+ * (§5.3). The workspace-invariant test validates a package.json marker against
+ * `'tool'` PLUS the marker kinds the bundled manifests declare — descriptor-driven,
+ * not a compiled-in domain list.
+ */
+export declare const MARKER_KINDS: readonly ["tool"];
+/** The closed union of HOST `opensipTools.kind` marker values — currently just `'tool'`. */
+export type MarkerKind = (typeof MARKER_KINDS)[number];
+/** Inputs for {@link discoverPackagesByMarker}: the project root to walk from and the marker kind to discover. */
+export interface MarkerDiscoveryOptions {
+    /** Absolute path to the project root. */
+    readonly projectDir: string;
+    /** Which marker kind to discover. */
+    readonly kind: MarkerKind;
+}
+/** A package discovered by its closed-union marker kind, with name, on-disk directory, and the echoed kind. */
+export interface DiscoveredMarkerPackage {
+    /** npm package name, e.g. '@opensip-cli/fitness' or '@my-co/fit'. */
+    readonly name: string;
+    /** Absolute path to the package's directory inside node_modules. */
+    readonly packageDir: string;
+    /** Echoed back so callers consuming multiple kinds can multiplex. */
+    readonly kind: MarkerKind;
+}
+/**
+ * Narrow an unknown string to MarkerKind. Used by readMarkerKind below
+ * and re-exported for callers that need to validate dynamic input.
+ */
+export declare function isMarkerKind(value: unknown): value is MarkerKind;
+/**
+ * Walk up from `projectDir` looking for `node_modules/` directories.
+ * For each one, scan top-level entries (and one level into scoped
+ * directories like `@opensip-cli/`) for packages declaring
+ * `opensipTools.kind === options.kind`. Return the deduplicated list.
+ *
+ * Same-named packages are returned once — the first occurrence walking
+ * from `projectDir` outward wins, matching Node's nearest-ancestor
+ * resolution behavior.
+ */
+export declare function discoverPackagesByMarker(options: MarkerDiscoveryOptions): DiscoveredMarkerPackage[];
+/**
+ * Scan EXACTLY ONE `node_modules` directory for packages declaring
+ * `opensipTools.kind === kind` — no ancestor walk. Used for fixed plugin
+ * host dirs (`~/.opensip-cli/plugins/tool/node_modules`,
+ * `<project>/.runtime/plugins/tool/node_modules`) where walking up would
+ * wrongly pull in `$HOME/node_modules` or unrelated ancestor trees.
+ */
+export declare function discoverPackagesInNodeModules(nodeModulesDir: string, kind: MarkerKind): DiscoveredMarkerPackage[];
+/**
+ * A package discovered by its declared `opensipTools.kind`, with the kind as a
+ * raw string (NOT narrowed to the closed `MarkerKind` union). This is the shape
+ * the generic capability-discovery substrate consumes — a domain's marker kind
+ * comes from its manifest descriptor, so it cannot be a compile-time union member.
+ */
+export interface DiscoveredDeclaredPackage {
+    readonly name: string;
+    readonly packageDir: string;
+    readonly kind: string;
+}
+/**
+ * Walk ancestor `node_modules/` directories from `projectDir`, returning every
+ * package whose `package.json` declares `opensipTools.kind === kind` for the
+ * given raw-string kind. The string-typed generalization of
+ * {@link discoverPackagesByMarker}: the closed-union version is a thin wrapper
+ * over this. Deduplicated; first occurrence walking outward wins.
+ */
+export declare function discoverPackagesByDeclaredKind(projectDir: string, kind: string): DiscoveredDeclaredPackage[];
+/**
+ * Read the declared `opensipTools.kind` from a package's package.json.
+ * Returns the kind if it parses, is a string, and matches the closed
+ * MarkerKind union; otherwise undefined. Parse failures are logged at
+ * debug — a malformed package.json under node_modules is not a discovery
+ * concern, just an entry to skip.
+ *
+ * Exported as the canonical host-tool marker reader. Domain markers such as
+ * fit-pack and graph-adapter are descriptor-driven and use the string-typed
+ * `readDeclaredKind` / `discoverPackagesByDeclaredKind` path.
+ */
+export declare function readMarkerKind(packageDir: string): MarkerKind | undefined;
+/**
+ * Read the RAW `opensipTools.kind` string from a package's package.json — the
+ * string-typed sibling of {@link readMarkerKind}, with no closed-union narrowing.
+ * Returns the string if it parses and is a string; otherwise undefined. Parse
+ * failures are logged at debug (a malformed node_modules package.json is an
+ * entry to skip, not a discovery error). The generic discovery substrate reads
+ * declared kinds through this one function so there is no second implementation
+ * to drift.
+ */
+export declare function readDeclaredKind(packageDir: string): string | undefined;
+//# sourceMappingURL=marker-discovery.d.ts.map

package/dist/plugins/marker-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"marker-discovery.d.ts","sourceRoot":"","sources":["../../src/plugins/marker-discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AASH;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,mBAAoB,CAAC;AAE9C,4FAA4F;AAC5F,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,kHAAkH;AAClH,MAAM,WAAW,sBAAsB;IACrC,yCAAyC;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B;AAED,+GAA+G;AAC/G,MAAM,WAAW,uBAAuB;IACtC,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,sBAAsB,GAC9B,uBAAuB,EAAE,CAQ3B;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,UAAU,GACf,uBAAuB,EAAE,CAM3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,yBAAyB,EAAE,CAc7B;AAkCD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAGzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAmBvE"}