@intentius/chant-lexicon-aws 0.124.51 → 0.124.54

package/dist/components/cfn-adopt.d.ts

@@ -0,0 +1,99 @@
+import { type AdoptionFile } from "@intentius/chant/lifecycle/adoption-file";
+import type { IndexDocument } from "@intentius/chant/lifecycle/index-document";
+import { type ImportabilityManifestEntry } from "../importable.js";
+import type { CfnChangeSet, CloudFormationClient } from "./cloud-executor.js";
+/** A CloudFormation template as chant builds it. */
+export interface CfnTemplate {
+    Metadata?: Record<string, unknown>;
+    Resources: Record<string, {
+        Type: string;
+        Properties?: Record<string, unknown>;
+        DeletionPolicy?: string;
+        UpdateReplacePolicy?: string;
+        [key: string]: unknown;
+    }>;
+    [key: string]: unknown;
+}
+/** One resource the adoption brings under the stack. */
+export interface CfnAdoptedResource {
+    node: string;
+    logicalId: string;
+    type: string;
+    identifier: Record<string, string>;
+    deletionPolicy: string;
+    /** The property the markers are written to, when the type has one chant can stamp. */
+    tagProperty?: string;
+    /** The marker tags the UPDATE writes. Empty for a type chant cannot tag. */
+    markers: Record<string, string>;
+}
+export interface CfnAdoptionPlan {
+    /** Why the adoption cannot run, each by name. Empty when it can. */
+    refusals: string[];
+    resources: CfnAdoptedResource[];
+    /** The IMPORT change set's template: the built one without markers or stack tags. */
+    importTemplate: CfnTemplate;
+    /** The UPDATE change set's template: the built one. */
+    markerTemplate: CfnTemplate;
+}
+export interface PlanCfnAdoptionInput {
+    /** The built template of the stack the resources join, from the source `chant import --index` wrote. */
+    template: CfnTemplate;
+    adoption: AdoptionFile;
+    /** The index version the adoption file names. */
+    index: IndexDocument;
+    /** Logical ids already in the stack (empty for a new stack). */
+    existing?: ReadonlySet<string>;
+    manifest?: ReadonlyMap<string, ImportabilityManifestEntry>;
+}
+/** The import identifier: the type's primary identifier properties zipped with the native id split on `|`. */
+export declare function cfnResourceIdentifier(primaryIdentifier: readonly string[], nativeId: string): Record<string, string> | undefined;
+/** Plan an adoption. Pure: reads nothing from the cloud. */
+export declare function planCfnAdoption(input: PlanCfnAdoptionInput): CfnAdoptionPlan;
+/** What the IMPORT change set's review shows, one line per resource. */
+export declare function cfnImportReview(plan: CfnAdoptionPlan): string[];
+/** What the marker UPDATE's review shows: each marker write, as tags only. */
+export declare function cfnMarkerReview(plan: CfnAdoptionPlan): string[];
+/** Why an IMPORT change set is not the one planned, or empty. */
+export declare function importChangeSetProblems(changeSet: CfnChangeSet, plan: CfnAdoptionPlan): string[];
+/** Why the marker UPDATE is not tags only on the imported resources, or empty. */
+export declare function markerChangeSetProblems(changeSet: CfnChangeSet, plan: CfnAdoptionPlan): string[];
+/** One change-set review: the step, the change set and what it writes. Approving executes it. */
+export type CfnAdoptionReview = (step: "import" | "markers", changeSet: CfnChangeSet, lines: string[]) => Promise<boolean>;
+export type CfnAdoptionOutcome = {
+    status: "adopted";
+    resources: CfnAdoptedResource[];
+    importChangeSet: string;
+    markerChangeSet?: string;
+} | {
+    status: "refused";
+    step: "plan" | "import" | "markers";
+    refusals: string[];
+} | {
+    status: "declined";
+    step: "import" | "markers";
+} | {
+    status: "failed";
+    step: "import" | "markers";
+    stackStatus: string;
+};
+export interface AdoptIntoStackOptions {
+    cfn: CloudFormationClient;
+    stackName: string;
+    plan: CfnAdoptionPlan;
+    review: CfnAdoptionReview;
+    parameters?: Record<string, string>;
+    waitOptions?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+    };
+}
+/**
+ * Run a planned adoption: the IMPORT change set, its review and execution,
+ * then the marker UPDATE, its tags-only check, review and execution. A
+ * refusal or a declined review deletes the change set it made and stops. A
+ * marker step that stops leaves the resources imported with Retain and
+ * without markers; running the adoption's UPDATE again (a plain deploy of
+ * the same template) writes them.
+ */
+export declare function adoptIntoStack(opts: AdoptIntoStackOptions): Promise<CfnAdoptionOutcome>;
+//# sourceMappingURL=cfn-adopt.d.ts.map

package/dist/components/cfn-adopt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cfn-adopt.d.ts","sourceRoot":"","sources":["../../src/components/cfn-adopt.ts"],"names":[],"mappings":"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"}

package/dist/components/cfn-adopt.js

@@ -0,0 +1,278 @@
+/**
+ * Adopting indexed resources into a CloudFormation stack (#4536; design and
+ * ruling on INTENTIUS/choudoufu#2284, 2026-10-26).
+ *
+ * The aws lexicon deploys CREATE and UPDATE change sets. A CREATE of a
+ * template that declares an existing bucket fails, so adoption takes two
+ * change sets:
+ *
+ * 1. IMPORT, with the template's markers left out. CloudFormation import
+ *    brings a resource under the stack without applying the template's
+ *    property values, so markers in the import template would never be
+ *    written, and the next UPDATE would then see no change and not write them
+ *    either. The import template also carries no stack tags.
+ * 2. UPDATE, with the template as built: it adds chant's marker tags to each
+ *    imported resource and the stack's own tags. It must be tags only: a
+ *    change to anything but the tag property, a replace, an add or a remove
+ *    refuses the run before it executes.
+ *
+ * The gate is chant's change-set review (Q3): each change set is shown before
+ * it is executed, through the caller's `review`, and the marker review lists
+ * each marker write as tags only. Nothing here asks a question of its own.
+ *
+ * Refused before any change set is made ({@link planCfnAdoption}): an
+ * adoption file that does not match its index version, a node the template
+ * does not declare under the file's `as`, a type CloudFormation cannot import
+ * or whose tags can only be set at create (../importable.ts), a resource with
+ * no DeletionPolicy (import needs one; `chant import --index` writes Retain,
+ * Q4), a resource already in the stack, and a template that would also create
+ * a resource. The index proposes; the live read decides: CloudFormation reads
+ * each object again when it imports it, by the identifier given here.
+ */
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { adoptionFileProblemsAgainst } from "@intentius/chant/lifecycle/adoption-file";
+import { adoptionRefusal, importabilityManifest } from "../importable.js";
+import { AWS_TAG_OWNERSHIP_KEYS, OWNERSHIP_METADATA_KEY } from "../ownership.js";
+import { isNoopChangeSet } from "./apply.js";
+const MARKER_KEYS = new Set(Object.values(AWS_TAG_OWNERSHIP_KEYS));
+/** The marker tags in a tag property's value, and the value without them. */
+function splitMarkers(tags, shape) {
+    const markers = {};
+    if (Array.isArray(tags) && shape !== "map") {
+        const rest = tags.filter((t) => {
+            const key = t?.Key;
+            const value = t?.Value;
+            if (typeof key === "string" && MARKER_KEYS.has(key)) {
+                if (typeof value === "string")
+                    markers[key] = value;
+                return false;
+            }
+            return true;
+        });
+        return { markers, rest };
+    }
+    if (tags && typeof tags === "object" && !Array.isArray(tags)) {
+        const rest = {};
+        for (const [k, v] of Object.entries(tags)) {
+            if (MARKER_KEYS.has(k)) {
+                if (typeof v === "string")
+                    markers[k] = v;
+            }
+            else
+                rest[k] = v;
+        }
+        return { markers, rest };
+    }
+    return { markers, rest: tags };
+}
+const isEmpty = (v) => v === undefined || (Array.isArray(v) && v.length === 0) || (typeof v === "object" && v !== null && !Array.isArray(v) && Object.keys(v).length === 0);
+/** The import identifier: the type's primary identifier properties zipped with the native id split on `|`. */
+export function cfnResourceIdentifier(primaryIdentifier, nativeId) {
+    const parts = nativeId.split("|");
+    if (primaryIdentifier.length === 0 || parts.length !== primaryIdentifier.length)
+        return undefined;
+    return Object.fromEntries(primaryIdentifier.map((p, i) => [p, parts[i]]));
+}
+/** Plan an adoption. Pure: reads nothing from the cloud. */
+export function planCfnAdoption(input) {
+    const manifest = input.manifest ?? importabilityManifest();
+    const existing = input.existing ?? new Set();
+    const refusals = adoptionFileProblemsAgainst(input.adoption, input.index);
+    const nodes = new Map(input.index.graph.nodes.map((n) => [n.id, n]));
+    const importTemplate = JSON.parse(JSON.stringify(input.template));
+    const markerTemplate = JSON.parse(JSON.stringify(input.template));
+    const resources = [];
+    const adopted = new Set();
+    for (const sel of input.adoption.select ?? []) {
+        const node = nodes.get(sel.node);
+        if (!node)
+            continue; // adoptionFileProblemsAgainst names it
+        const logicalId = sel.as;
+        adopted.add(logicalId);
+        const resource = input.template.Resources?.[logicalId];
+        if (!resource) {
+            refusals.push(`${sel.node}: the template declares no resource ${logicalId}`);
+            continue;
+        }
+        const type = resource.Type;
+        if (type !== node.kind)
+            refusals.push(`${logicalId}: the template declares ${type}, but ${sel.node} is ${node.kind}`);
+        if (sel.type !== undefined && sel.type !== type)
+            refusals.push(`${logicalId}: the adoption file names type ${sel.type}, but the template declares ${type}`);
+        const refusal = adoptionRefusal(type, manifest);
+        if (refusal)
+            refusals.push(`${logicalId}: ${refusal}`);
+        if (existing.has(logicalId))
+            refusals.push(`${logicalId} is already in the stack; nothing to import`);
+        const deletionPolicy = resource.DeletionPolicy;
+        if (typeof deletionPolicy !== "string") {
+            refusals.push(`${logicalId} declares no DeletionPolicy; CloudFormation import needs one (chant import --index writes Retain)`);
+        }
+        const entry = manifest.get(type);
+        const identifier = cfnResourceIdentifier(entry?.primaryIdentifier ?? [], node.nativeId ?? "");
+        if (!identifier) {
+            refusals.push(`${logicalId}: native id "${node.nativeId ?? ""}" does not split into ${type}'s primary identifier (${(entry?.primaryIdentifier ?? []).join(", ") || "none"})`);
+        }
+        const tagProperty = entry?.tagging?.taggable ? entry.tagging.tagProperty : undefined;
+        let markers = {};
+        if (tagProperty) {
+            const props = importTemplate.Resources[logicalId].Properties ?? {};
+            const split = splitMarkers(props[tagProperty], entry?.tagging?.tagShape);
+            markers = split.markers;
+            if (isEmpty(split.rest))
+                delete props[tagProperty];
+            else
+                props[tagProperty] = split.rest;
+            importTemplate.Resources[logicalId].Properties = props;
+        }
+        resources.push({
+            node: sel.node,
+            logicalId,
+            type,
+            identifier: identifier ?? {},
+            deletionPolicy: typeof deletionPolicy === "string" ? deletionPolicy : "",
+            ...(tagProperty ? { tagProperty } : {}),
+            markers,
+        });
+    }
+    for (const id of Object.keys(input.template.Resources ?? {}).sort()) {
+        if (!adopted.has(id) && !existing.has(id)) {
+            refusals.push(`the template also creates ${id}; adopt first, then add it in a later deploy (the marker UPDATE must be tags only)`);
+        }
+    }
+    // No stack tags on the IMPORT: the UPDATE writes them with the resource markers.
+    if (importTemplate.Metadata && OWNERSHIP_METADATA_KEY in importTemplate.Metadata) {
+        delete importTemplate.Metadata[OWNERSHIP_METADATA_KEY];
+        if (Object.keys(importTemplate.Metadata).length === 0)
+            delete importTemplate.Metadata;
+    }
+    resources.sort((a, b) => (a.logicalId < b.logicalId ? -1 : a.logicalId > b.logicalId ? 1 : 0));
+    return { refusals, resources, importTemplate, markerTemplate };
+}
+/** What the IMPORT change set's review shows, one line per resource. */
+export function cfnImportReview(plan) {
+    return plan.resources.map((r) => `import ${r.logicalId} (${r.type}) ${Object.entries(r.identifier).map(([k, v]) => `${k}=${v}`).join(" ")}, DeletionPolicy ${r.deletionPolicy}`);
+}
+/** What the marker UPDATE's review shows: each marker write, as tags only. */
+export function cfnMarkerReview(plan) {
+    return plan.resources.map((r) => Object.keys(r.markers).length > 0 && r.tagProperty
+        ? `marker write, tags only: ${r.logicalId} (${r.type}) ${r.tagProperty} += ${Object.entries(r.markers)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([k, v]) => `${k}=${v}`)
+            .join(", ")}`
+        : r.tagProperty
+            ? `no marker: ${r.logicalId} (${r.type}) carries no chant marker in the template; the stack owns it on its template alone`
+            : `no marker: ${r.logicalId} (${r.type}) has no tags chant can stamp; the stack owns it on its template alone`);
+}
+/** Why an IMPORT change set is not the one planned, or empty. */
+export function importChangeSetProblems(changeSet, plan) {
+    const problems = [];
+    if (changeSet.status === "FAILED")
+        problems.push(`the IMPORT change set failed: ${changeSet.statusReason ?? "no reason given"}`);
+    const want = new Set(plan.resources.map((r) => r.logicalId));
+    const seen = new Set();
+    for (const c of changeSet.changes) {
+        if (c.action !== "Import" || !want.has(c.logicalResourceId)) {
+            problems.push(`the IMPORT change set would ${c.action.toLowerCase()} ${c.logicalResourceId} (${c.resourceType}), which the adoption does not import`);
+        }
+        seen.add(c.logicalResourceId);
+    }
+    for (const id of want)
+        if (!seen.has(id) && changeSet.status !== "FAILED")
+            problems.push(`the IMPORT change set does not import ${id}`);
+    return problems;
+}
+function changeReplaces(c) {
+    return c.replacement || c.replacementMode === "True" || c.replacementMode === "Conditional";
+}
+/** Why the marker UPDATE is not tags only on the imported resources, or empty. */
+export function markerChangeSetProblems(changeSet, plan) {
+    const problems = [];
+    if (changeSet.status === "FAILED" && !isNoopChangeSet(changeSet)) {
+        problems.push(`the marker change set failed: ${changeSet.statusReason ?? "no reason given"}`);
+    }
+    const byId = new Map(plan.resources.map((r) => [r.logicalId, r]));
+    for (const c of changeSet.changes) {
+        const r = byId.get(c.logicalResourceId);
+        if (c.action !== "Modify" || !r) {
+            problems.push(`the marker change set would ${c.action.toLowerCase()} ${c.logicalResourceId} (${c.resourceType}); it may only add tags to the imported resources`);
+            continue;
+        }
+        if (changeReplaces(c))
+            problems.push(`the marker change set would replace ${c.logicalResourceId} (${c.resourceType})`);
+        const other = (c.details ?? []).filter((d) => d !== r.tagProperty);
+        if (other.length > 0)
+            problems.push(`the marker change set changes ${c.logicalResourceId}'s ${other.join(", ")}, not only its tags`);
+    }
+    return problems;
+}
+/**
+ * Run a planned adoption: the IMPORT change set, its review and execution,
+ * then the marker UPDATE, its tags-only check, review and execution. A
+ * refusal or a declined review deletes the change set it made and stops. A
+ * marker step that stops leaves the resources imported with Retain and
+ * without markers; running the adoption's UPDATE again (a plain deploy of
+ * the same template) writes them.
+ */
+export async function adoptIntoStack(opts) {
+    const { cfn, stackName, plan, review } = opts;
+    if (plan.refusals.length > 0)
+        return { status: "refused", step: "plan", refusals: plan.refusals };
+    if (plan.resources.length === 0)
+        return { status: "refused", step: "plan", refusals: ["the adoption names no resource"] };
+    if (!cfn.createImportChangeSet) {
+        return { status: "refused", step: "plan", refusals: ["this CloudFormation client cannot create an IMPORT change set"] };
+    }
+    const dir = mkdtempSync(join(tmpdir(), "chant-cfn-adopt-"));
+    try {
+        const importPath = join(dir, "import.template.json");
+        writeFileSync(importPath, JSON.stringify(plan.importTemplate, null, 2));
+        const resourcesToImport = plan.resources.map((r) => ({
+            resourceType: r.type,
+            logicalResourceId: r.logicalId,
+            resourceIdentifier: r.identifier,
+        }));
+        const imported = await cfn.createImportChangeSet({ stackName, templatePath: importPath, resourcesToImport, ...(opts.parameters ? { parameters: opts.parameters } : {}) });
+        const ref = { stackName, changeSetName: imported.changeSetName };
+        const importProblems = importChangeSetProblems(imported, plan);
+        if (importProblems.length > 0) {
+            await cfn.deleteChangeSet(ref);
+            return { status: "refused", step: "import", refusals: importProblems };
+        }
+        if (!(await review("import", imported, cfnImportReview(plan)))) {
+            await cfn.deleteChangeSet(ref);
+            return { status: "declined", step: "import" };
+        }
+        await cfn.executeChangeSet(ref);
+        const afterImport = await cfn.waitForStack(stackName, opts.waitOptions);
+        if (afterImport.stackStatus !== "IMPORT_COMPLETE")
+            return { status: "failed", step: "import", stackStatus: afterImport.stackStatus };
+        const markerPath = join(dir, "markers.template.json");
+        writeFileSync(markerPath, JSON.stringify(plan.markerTemplate, null, 2));
+        const marked = await cfn.createChangeSet({ stackName, templatePath: markerPath, ...(opts.parameters ? { parameters: opts.parameters } : {}) });
+        const markerRef = { stackName, changeSetName: marked.changeSetName };
+        if (isNoopChangeSet(marked)) {
+            await cfn.deleteChangeSet(markerRef);
+            return { status: "adopted", resources: plan.resources, importChangeSet: imported.changeSetName };
+        }
+        const markerProblems = markerChangeSetProblems(marked, plan);
+        if (markerProblems.length > 0) {
+            await cfn.deleteChangeSet(markerRef);
+            return { status: "refused", step: "markers", refusals: markerProblems };
+        }
+        if (!(await review("markers", marked, cfnMarkerReview(plan)))) {
+            await cfn.deleteChangeSet(markerRef);
+            return { status: "declined", step: "markers" };
+        }
+        await cfn.executeChangeSet(markerRef);
+        const afterMarkers = await cfn.waitForStack(stackName, opts.waitOptions);
+        if (afterMarkers.stackStatus !== "UPDATE_COMPLETE")
+            return { status: "failed", step: "markers", stackStatus: afterMarkers.stackStatus };
+        return { status: "adopted", resources: plan.resources, importChangeSet: imported.changeSetName, markerChangeSet: marked.changeSetName };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}

package/dist/components/cfn-imports.d.ts

@@ -0,0 +1,84 @@
+/**
+ * `Fn::ImportValue` between stacks (#4466): which exports a template
+ * declares, which it imports, and the names they go by.
+ *
+ * A stack that imports another stack's export reads that stack, the way a
+ * CDK app wires its stacks. The read sits inside the template, so core does
+ * not see it in the step. `cfn-deploy`'s `declaredReads` finds it here: an
+ * import of a name another `cfn-deploy` step's template exports is a read of
+ * `<component>.<output>`, which core writes into the importer's step under
+ * `imports` (`CfnDeployInput.imports`) and orders, holds and lists like any
+ * other read.
+ *
+ * A name is a string, or an `Fn::Sub` (or `Fn::Join`, or `Ref`) over
+ * parameters and pseudo parameters. It resolves where the values it reads
+ * are known: a parameter with a plain value in the step's `inputs` or a
+ * `Default` in the template, `AWS::StackName`, and the region's pseudo
+ * parameters when `AWS_REGION` or `AWS_DEFAULT_REGION` names the region.
+ * Anything else (`AWS::AccountId`, a resource attribute, a parameter wired
+ * from another stack, an intrinsic this does not follow) leaves the name
+ * unresolved, and the plan says so in a hole.
+ */
+/** A name an export or import goes by: resolved, or why not. */
+export type CfnName = {
+    name: string;
+} | {
+    unresolved: string;
+};
+/** One export a template declares: the output it is, and its name. */
+export type CfnExport = {
+    output: string;
+} & CfnName;
+/** One import in a template: where it sits, as a dotted path, the logical id it sits under, and its name. */
+export type CfnImport = {
+    at: string;
+    logicalId: string;
+} & CfnName;
+/** The template at `path`, read against `root` when relative, as JSON; `undefined` for one that cannot be read or parsed, or an archive reference. */
+export declare function readCfnTemplate(path: unknown, root?: string): Record<string, unknown> | undefined;
+/**
+ * The pseudo parameters this plan knows for `stack`: `AWS::StackName`, and
+ * `AWS::Region`, `AWS::Partition` and `AWS::URLSuffix` when the region is
+ * named. `AWS::AccountId` and `AWS::StackId` are not known before apply.
+ */
+export declare function cfnPseudoParameters(stack: string, env?: NodeJS.ProcessEnv): Record<string, string>;
+/**
+ * The values a name in `template` can read for `stack`: each parameter's
+ * `Default`, overlaid by the step's plain inputs (a string, a number or a
+ * boolean; a wired reference or `undefined` is not known), and the pseudo
+ * parameters.
+ */
+export declare function cfnKnownValues(template: Record<string, unknown> | undefined, stack: string, inputs: Record<string, unknown> | undefined, env?: NodeJS.ProcessEnv): Record<string, string>;
+/**
+ * The name `value` resolves to against `known`, or why it does not. A
+ * string is itself; `Fn::Sub` substitutes `${X}` from `known` and its own
+ * variables (`${!X}` is the literal `${X}`); `Ref` reads `known`;
+ * `Fn::Join` joins what it resolves. Any other shape is unresolved.
+ */
+export declare function resolveCfnName(value: unknown, known: Record<string, string>): CfnName;
+/** Every export `template` declares (`Outputs.<name>.Export.Name`), by output, sorted. */
+export declare function cfnExports(template: Record<string, unknown> | undefined, known: Record<string, string>): CfnExport[];
+/**
+ * Every `Fn::ImportValue` in `template`'s resources, outputs and conditions,
+ * with where it sits and the name it imports, in template order. An import
+ * whose argument is itself an import is listed once, unresolved.
+ */
+export declare function cfnImports(template: Record<string, unknown> | undefined, known: Record<string, string>): CfnImport[];
+/** The JSON Pointer `CfnDeployInput.imports[name]` sits at in a `cfn-deploy` step. */
+export declare function cfnImportPointer(name: string): string;
+/** The stand-in parameter that takes an import's place in a preview: `ChantImport`, the name's letters and digits, and a short digest so two names never share one. */
+export declare function cfnStandInParameter(name: string): string;
+/**
+ * A copy of `template` for a preview (#4466b): each `Fn::ImportValue` of a
+ * name in `names` is a `Ref` to a stand-in `String` parameter, which the
+ * preview fills with `cfnPlaceholder`. CloudFormation refuses a change set
+ * that imports an export that does not exist yet, so the importer of a stack
+ * the same change creates is planned against this copy. `standIns` maps each
+ * stand-in parameter to the export it stands for; a name the template never
+ * imports gets none.
+ */
+export declare function cfnTemplateWithStandIns(template: Record<string, unknown>, names: readonly string[], known: Record<string, string>): {
+    template: Record<string, unknown>;
+    standIns: Record<string, string>;
+};
+//# sourceMappingURL=cfn-imports.d.ts.map

package/dist/components/cfn-imports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cfn-imports.d.ts","sourceRoot":"","sources":["../../src/components/cfn-imports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH,gEAAgE;AAChE,MAAM,MAAM,OAAO,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhE,sEAAsE;AACtE,MAAM,MAAM,SAAS,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC;AAErD,6GAA6G;AAC7G,MAAM,MAAM,SAAS,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC;AAEpE,sJAAsJ;AACtJ,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAQjG;AAOD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAS/G;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC7C,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC3C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAcxB;AAUD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CA6CrF;AAED,0FAA0F;AAC1F,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EAAE,CAQpH;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EAAE,CAmBpH;AAED,sFAAsF;AACtF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,uKAAuK;AACvK,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B;IAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CA8BzE"}