@rasensio/aidlc 1.8.1 → 1.9.0

package/dist/operational/packagers.js

@@ -0,0 +1,252 @@
+/**
+ * Per-platform packaging for operational skills.
+ *
+ * Mirrors the framework adapter seam — one canonical body, N platform-native
+ * files — but never passes through `loadSkills`/`parseSkillFile`, which require a
+ * lifecycle `phase` an operational skill does not have (D-1, AC-33).
+ *
+ * Two shapes, because two platforms have no natural one-skill-one-file form:
+ *
+ * - **Per-skill** (claude-code, kiro, cursor): one pointer file per skill.
+ * - **Index** (codex, windsurf): one artifact listing every operational skill.
+ *   Codex reads only `AGENTS.md`; windsurf has a per-file character budget that
+ *   O(n) rule files would exhaust.
+ *
+ * Every platform artifact is a **pointer** to the canonical body — the full
+ * instructions and the verification text live in
+ * `.aidlc/operational-skills/<name>.md` only. That scoping is what makes
+ * AC-35/AC-37/AC-38 well-defined.
+ *
+ * Requirements: AC-13, AC-14, AC-15, AC-16, AC-20, AC-47, AC-48
+ *
+ * @module
+ */
+import { MAX_FILE_CHARS } from '../compile/limits.js';
+import { canonicalSkillFilename, normalizeSkillName } from '../compile/naming.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Directory holding canonical operational-skill bodies (AC-13, D-2). */
+export const OPERATIONAL_DIR = '.aidlc/operational-skills';
+/** Merge-block id for operational skills. Distinct from every framework id. */
+export const OPERATIONAL_BLOCK_ID = 'aidlc-operational-skills';
+/** Windsurf index rule path — unprefixed, so it cannot collide with framework rules. */
+export const WINDSURF_INDEX_PATH = '.windsurf/rules/operational-skills.md';
+// ---------------------------------------------------------------------------
+// Ownership marker (AC-20)
+// ---------------------------------------------------------------------------
+/**
+ * Build the app-owned marker comment.
+ *
+ * Placement differs per target because two adapters validate that their files
+ * *begin* with frontmatter (`claude-code.ts`, `cursor.ts`), so a first-line
+ * comment would fail their own validators.
+ */
+export function ownershipMarker(name) {
+    return `<!-- aidlc:operational-skill ${name} — app-owned, not framework-managed -->`;
+}
+/** Marker for an index artifact covering many skills. */
+function indexMarker() {
+    return '<!-- aidlc:operational-skills — app-owned, not framework-managed -->';
+}
+/** Thrown when a configured platform has no operational packaging (AC-16). */
+export class UnsupportedPlatformError extends Error {
+    platform;
+    constructor(platform, supported) {
+        super(`platform '${platform}' has no operational-skill packaging; ` +
+            `supported platforms are: ${supported.join(', ')}`);
+        this.platform = platform;
+        this.name = 'UnsupportedPlatformError';
+    }
+}
+/** Relative path of a skill's canonical body. */
+export function canonicalBodyPath(name) {
+    return `${OPERATIONAL_DIR}/${canonicalSkillFilename(name)}`;
+}
+/** Pointer sentence shared by every platform artifact. */
+function pointerLine(skill) {
+    return `Read \`${canonicalBodyPath(skill.meta.name)}\` and follow its instructions.`;
+}
+/**
+ * Platform directory/file segment for an operational skill.
+ *
+ * `prefix: false` is the whole point — the `aidlc-` namespace stays
+ * framework-owned (AC-19, AC-41).
+ */
+function segment(name) {
+    return normalizeSkillName(name, { prefix: false });
+}
+// ---------------------------------------------------------------------------
+// Per-skill packagers
+// ---------------------------------------------------------------------------
+/** claude-code: `.claude/skills/<name>/SKILL.md` (AC-14). */
+const claudeCodePackager = {
+    platform: 'claude-code',
+    plan(skill) {
+        const dir = segment(skill.meta.name);
+        // Frontmatter first — claude-code's validator requires `---\n` at byte 0.
+        const content = [
+            '---',
+            `name: ${dir}`,
+            `description: ${skill.meta.description}`,
+            '---',
+            '',
+            ownershipMarker(skill.meta.name),
+            '',
+            pointerLine(skill),
+            '',
+        ].join('\n');
+        return [{ kind: 'create', path: `.claude/skills/${dir}/SKILL.md`, content }];
+    },
+};
+/** kiro: `.kiro/skills/<name>/SKILL.md`. */
+const kiroPackager = {
+    platform: 'kiro',
+    plan(skill) {
+        const dir = segment(skill.meta.name);
+        const content = [
+            '---',
+            `name: ${dir}`,
+            `description: ${skill.meta.description}`,
+            '---',
+            '',
+            ownershipMarker(skill.meta.name),
+            '',
+            pointerLine(skill),
+            '',
+        ].join('\n');
+        return [{ kind: 'create', path: `.kiro/skills/${dir}/SKILL.md`, content }];
+    },
+};
+/**
+ * cursor: `.cursor/rules/<name>.mdc`.
+ *
+ * The marker rides in frontmatter as `aidlc_kind`. Cursor's validator requires
+ * only that `description:` and `alwaysApply:` be present, so an extra key is
+ * permitted — verified before relying on it.
+ */
+const cursorPackager = {
+    platform: 'cursor',
+    plan(skill) {
+        const file = `${segment(skill.meta.name)}.mdc`;
+        const content = [
+            '---',
+            `description: ${skill.meta.description}`,
+            'globs:',
+            'alwaysApply: false',
+            'aidlc_kind: operational',
+            '---',
+            '',
+            pointerLine(skill),
+            '',
+        ].join('\n');
+        return [{ kind: 'create', path: `.cursor/rules/${file}`, content }];
+    },
+};
+// ---------------------------------------------------------------------------
+// Index packagers
+// ---------------------------------------------------------------------------
+/** Shared index body: marker, heading, one bullet per skill. */
+function indexLines(skills) {
+    const lines = [indexMarker(), '', '# Operational Skills', ''];
+    if (skills.length === 0) {
+        lines.push('_No operational skills are defined in this project._');
+        return lines;
+    }
+    lines.push('App-owned skills for repeatable operations. Each entry points at its canonical', 'body; read that file and follow its instructions.', '');
+    // Sorted by name so output does not depend on directory-read order (AC-17).
+    for (const skill of [...skills].sort((a, b) => a.meta.name.localeCompare(b.meta.name))) {
+        lines.push(`- **${skill.meta.name}** — ${skill.meta.description}. ` +
+            `Read \`${canonicalBodyPath(skill.meta.name)}\`.`);
+    }
+    return lines;
+}
+/**
+ * codex: one merge-block in `AGENTS.md`.
+ *
+ * Shares the file with the framework block but never its id — the framework uses
+ * `aidlc` (`codex.ts:161`), and `mergeBlock` preserves every byte outside its own
+ * delimiters, so the two coexist (AC-43 as refined by DD-2).
+ */
+const codexPackager = {
+    platform: 'codex',
+    plan() {
+        return [];
+    },
+    planIndex(skills) {
+        if (skills.length === 0)
+            return null;
+        return {
+            kind: 'merge-block',
+            path: 'AGENTS.md',
+            blockId: OPERATIONAL_BLOCK_ID,
+            content: indexLines(skills).join('\n'),
+        };
+    },
+};
+/**
+ * windsurf: one index rule file.
+ *
+ * One file regardless of skill count, but O(n) characters within it — so the
+ * per-file cap binds sooner, not later. On exceeding it the index degrades to a
+ * directory pointer rather than dropping the list, which keeps operational skills
+ * discoverable (US-6). The cross-plan total budget is deliberately not enforced;
+ * see AC-48's recorded limitation.
+ */
+const windsurfPackager = {
+    platform: 'windsurf',
+    plan() {
+        return [];
+    },
+    planIndex(skills) {
+        if (skills.length === 0)
+            return null;
+        const full = indexLines(skills).join('\n') + '\n';
+        if (full.length <= MAX_FILE_CHARS) {
+            return { kind: 'create', path: WINDSURF_INDEX_PATH, content: full };
+        }
+        const degraded = [
+            indexMarker(),
+            '',
+            '# Operational Skills',
+            '',
+            `This project defines ${skills.length} app-owned operational skills — too many to`,
+            'list within the windsurf rule size limit.',
+            '',
+            `Read \`${OPERATIONAL_DIR}/\` and follow the instructions in the relevant skill.`,
+            '',
+        ].join('\n');
+        return { kind: 'create', path: WINDSURF_INDEX_PATH, content: degraded };
+    },
+};
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+const PACKAGERS = new Map([
+    ['claude-code', claudeCodePackager],
+    ['kiro', kiroPackager],
+    ['cursor', cursorPackager],
+    ['codex', codexPackager],
+    ['windsurf', windsurfPackager],
+]);
+/** Platforms with operational packaging, sorted for stable error messages. */
+export const supportedOperationalPlatforms = [...PACKAGERS.keys()].sort();
+/**
+ * Look up the packager for a platform.
+ *
+ * @param platform - Platform identifier from `.aidlc/config.yaml`.
+ * @returns The packager.
+ * @throws {UnsupportedPlatformError} When the platform has no packaging (AC-16).
+ */
+export function packagerFor(platform) {
+    const packager = PACKAGERS.get(platform);
+    if (!packager) {
+        throw new UnsupportedPlatformError(platform, supportedOperationalPlatforms);
+    }
+    return packager;
+}
+/** Does this platform have operational packaging? */
+export function hasOperationalPackaging(platform) {
+    return PACKAGERS.has(platform);
+}
+//# sourceMappingURL=packagers.js.map

package/dist/operational/packagers.js.map

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

package/dist/operational/redact.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Best-effort credential redaction for generated operational skills.
+ *
+ * Two rules, and the second matters as much as the first (AC-11):
+ *
+ * - Credential **values** are redacted. A generated skill is instructions an
+ *   agent will later execute, and it is committed to the repo, so a pasted token
+ *   would become a secret at rest (NFR-3).
+ * - Credential **references** are preserved. `$GITHUB_TOKEN`,
+ *   `op://vault/item/field`, `arn:aws:secretsmanager:...` are legitimate
+ *   operational content; stripping them would produce a skill that cannot work.
+ *
+ * **This is explicitly best-effort and not a security guarantee.** Detection is
+ * pattern- plus entropy-based, so novel credential formats will pass through. The
+ * real control is the confirmation gate: redaction runs *before* the preview is
+ * rendered (AC-44), so a human sees the redacted text and nothing reaches disk
+ * without their approval. Callers must not present this as a guarantee to users.
+ *
+ * Requirements: AC-11, AC-44, NFR-3
+ *
+ * @module
+ */
+/** Placeholder substituted for a redacted value. */
+export declare const REDACTION_PLACEHOLDER = "<REDACTED>";
+/** Result of a redaction pass. */
+export interface RedactionResult {
+    /** Text with detected credential values replaced. */
+    text: string;
+    /**
+     * Human-readable labels for what was redacted (never the values themselves —
+     * echoing them back would defeat the purpose).
+     */
+    redacted: string[];
+}
+/**
+ * Redact credential values from text, preserving credential references.
+ *
+ * @param text - Text that may contain credentials.
+ * @returns The redacted text plus labels describing what was removed.
+ */
+export declare function redactSecrets(text: string): RedactionResult;
+/**
+ * Convenience: did this text contain anything that looked like a credential?
+ *
+ * @param text - Text to inspect.
+ * @returns True when `redactSecrets` would change the text.
+ */
+export declare function containsSecrets(text: string): boolean;
+//# sourceMappingURL=redact.d.ts.map

package/dist/operational/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../src/operational/redact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,oDAAoD;AACpD,eAAO,MAAM,qBAAqB,eAAe,CAAC;AAElD,kCAAkC;AAClC,MAAM,WAAW,eAAe;IAC9B,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAgED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAkC3D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD"}

package/dist/operational/redact.js

@@ -0,0 +1,135 @@
+/**
+ * Best-effort credential redaction for generated operational skills.
+ *
+ * Two rules, and the second matters as much as the first (AC-11):
+ *
+ * - Credential **values** are redacted. A generated skill is instructions an
+ *   agent will later execute, and it is committed to the repo, so a pasted token
+ *   would become a secret at rest (NFR-3).
+ * - Credential **references** are preserved. `$GITHUB_TOKEN`,
+ *   `op://vault/item/field`, `arn:aws:secretsmanager:...` are legitimate
+ *   operational content; stripping them would produce a skill that cannot work.
+ *
+ * **This is explicitly best-effort and not a security guarantee.** Detection is
+ * pattern- plus entropy-based, so novel credential formats will pass through. The
+ * real control is the confirmation gate: redaction runs *before* the preview is
+ * rendered (AC-44), so a human sees the redacted text and nothing reaches disk
+ * without their approval. Callers must not present this as a guarantee to users.
+ *
+ * Requirements: AC-11, AC-44, NFR-3
+ *
+ * @module
+ */
+/** Placeholder substituted for a redacted value. */
+export const REDACTION_PLACEHOLDER = '<REDACTED>';
+/**
+ * Named provider token shapes. Anchored on distinctive prefixes so they do not
+ * fire on ordinary prose.
+ */
+const TOKEN_PATTERNS = [
+    { label: 'GitHub token', re: /\bgh[pousr]_[A-Za-z0-9]{16,}\b/g },
+    { label: 'GitHub fine-grained token', re: /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g },
+    { label: 'AWS access key id', re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g },
+    { label: 'Slack token', re: /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g },
+    { label: 'Google API key', re: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+    { label: 'Stripe key', re: /\b[sr]k_(?:live|test)_[0-9A-Za-z]{16,}\b/g },
+    { label: 'OpenAI key', re: /\bsk-[A-Za-z0-9]{20,}\b/g },
+    { label: 'Anthropic key', re: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g },
+    { label: 'npm token', re: /\bnpm_[A-Za-z0-9]{30,}\b/g },
+    { label: 'JSON Web Token', re: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g },
+    { label: 'private key block', re: /-----BEGIN (?:[A-Z ]+ )?PRIVATE KEY-----[\s\S]*?-----END (?:[A-Z ]+ )?PRIVATE KEY-----/g },
+];
+/**
+ * `KEY=value` / `key: value` assignments whose *name* implies a secret. The value
+ * is redacted only when it is a literal — a `$VAR` or secret-manager reference on
+ * the right-hand side is a reference, not a value, and is kept.
+ */
+const ASSIGNMENT_RE = /\b([A-Za-z_][A-Za-z0-9_]*(?:SECRET|TOKEN|PASSWORD|PASSWD|APIKEY|API_KEY|ACCESS_KEY|PRIVATE_KEY|CREDENTIAL)[A-Za-z0-9_]*)\s*[:=]\s*(['"]?)([^\s'"#]+)\2/gi;
+/**
+ * Right-hand sides that are references rather than values, and must survive.
+ * Preserving these is required by AC-11, not merely nice to have.
+ */
+const REFERENCE_RE = /^(?:\$|\$\{|%|<|op:\/\/|vault:|secret:|arn:aws:secretsmanager:|projects\/[^/]+\/secrets\/|sm:\/\/|env:|process\.env)/i;
+/** Shannon entropy in bits per character. */
+function entropy(s) {
+    const freq = new Map();
+    for (const ch of s)
+        freq.set(ch, (freq.get(ch) ?? 0) + 1);
+    let h = 0;
+    for (const n of freq.values()) {
+        const p = n / s.length;
+        h -= p * Math.log2(p);
+    }
+    return h;
+}
+/**
+ * Does this look like a high-entropy secret rather than a word or a path?
+ *
+ * Conservative on purpose: a false positive silently mangles a legitimate skill,
+ * and the confirmation gate is the real backstop.
+ */
+function looksLikeSecret(token) {
+    if (token.length < 24)
+        return false;
+    if (REFERENCE_RE.test(token))
+        return false;
+    // Paths, URLs, and dotted identifiers are common and are not secrets.
+    if (/[/\\]/.test(token) || token.includes('://'))
+        return false;
+    // Require mixed character classes — long lowercase words are not secrets.
+    const classes = [/[a-z]/, /[A-Z]/, /[0-9]/].filter((re) => re.test(token)).length;
+    if (classes < 2)
+        return false;
+    return entropy(token) >= 3.5;
+}
+/**
+ * Redact credential values from text, preserving credential references.
+ *
+ * @param text - Text that may contain credentials.
+ * @returns The redacted text plus labels describing what was removed.
+ */
+export function redactSecrets(text) {
+    const redacted = [];
+    let out = text;
+    // 1. Named provider token shapes.
+    for (const { label, re } of TOKEN_PATTERNS) {
+        out = out.replace(re, () => {
+            if (!redacted.includes(label))
+                redacted.push(label);
+            return REDACTION_PLACEHOLDER;
+        });
+    }
+    // 2. Secret-named assignments with a literal right-hand side.
+    out = out.replace(ASSIGNMENT_RE, (match, key, quote, value) => {
+        if (REFERENCE_RE.test(value))
+            return match; // a reference — preserve (AC-11)
+        if (value === REDACTION_PLACEHOLDER)
+            return match; // already handled above
+        const label = `value assigned to ${key}`;
+        if (!redacted.includes(label))
+            redacted.push(label);
+        return `${key}=${quote}${REDACTION_PLACEHOLDER}${quote}`.replace('=', match.includes(':') && !match.includes('=') ? ': ' : '=');
+    });
+    // 3. Free-standing high-entropy strings.
+    out = out.replace(/[A-Za-z0-9+/_=-]{24,}/g, (token) => {
+        if (token === REDACTION_PLACEHOLDER)
+            return token;
+        if (!looksLikeSecret(token))
+            return token;
+        const label = 'high-entropy string';
+        if (!redacted.includes(label))
+            redacted.push(label);
+        return REDACTION_PLACEHOLDER;
+    });
+    return { text: out, redacted };
+}
+/**
+ * Convenience: did this text contain anything that looked like a credential?
+ *
+ * @param text - Text to inspect.
+ * @returns True when `redactSecrets` would change the text.
+ */
+export function containsSecrets(text) {
+    return redactSecrets(text).redacted.length > 0;
+}
+//# sourceMappingURL=redact.js.map

package/dist/operational/redact.js.map

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

package/dist/operational/schema.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Operational-skill schema: frontmatter shape, parsing, serialization, and name
+ * validation.
+ *
+ * Deliberately NOT `SkillMeta`. `SkillMeta` requires `phase: PhaseName`
+ * (`core/types.ts`) and `parseSkillFile` throws without it
+ * (`compile/loaders.ts:84`) — an operational skill has no lifecycle phase, which
+ * is the constraint behind decision D-1's separate emit path (AC-33, AC-39).
+ *
+ * Requirements: AC-19, AC-20, AC-33, AC-39, AC-42
+ *
+ * @module
+ */
+/** Maximum length of an operational skill name (matches the platform cap). */
+export declare const MAX_OPERATIONAL_NAME_LENGTH = 64;
+/** The literal `kind` value that marks a skill as app-owned (AC-20). */
+export declare const OPERATIONAL_KIND = "operational";
+/** Frontmatter of an operational skill (AC-39). */
+export interface OperationalSkillMeta {
+    /** Skill name; validated by `validateOperationalSkillName`. */
+    name: string;
+    /** One-line summary of the operation the skill performs. */
+    description: string;
+    /** Always `'operational'` — the positive ownership marker (AC-20). */
+    kind: typeof OPERATIONAL_KIND;
+    /** Tool that generated the skill, e.g. `aidlc-add-skill`. */
+    generated_by: string;
+    /** `@rasensio/aidlc-content` version whose verify steps are inlined. */
+    content_version: string;
+    /** Optional natural-language trigger description. */
+    trigger?: string;
+    /**
+     * Repo-relative paths the skill operates on. The ONLY source of paths for the
+     * AC-38 existence check — prose and fenced code blocks are never scanned, which
+     * is how the false-failure exclusion is satisfied structurally.
+     */
+    paths?: string[];
+}
+/** A parsed operational skill: frontmatter plus markdown body. */
+export interface OperationalSkill {
+    meta: OperationalSkillMeta;
+    body: string;
+}
+/** Thrown when a name or frontmatter violates the schema. */
+export declare class OperationalSchemaError extends Error {
+    constructor(reason: string);
+}
+/**
+ * Validate an operational skill name before it is used in any filesystem path.
+ *
+ * This runs before path construction, not after, because the name reaches
+ * `.aidlc/operational-skills/<name>.md` and four platform directories. The
+ * charset alone excludes every traversal character; the explicit separator and
+ * dot-segment checks are defence in depth so that relaxing the charset later
+ * cannot silently reopen traversal.
+ *
+ * @param name - Candidate skill name.
+ * @throws {OperationalSchemaError} When the name is unusable or reserved.
+ */
+export declare function validateOperationalSkillName(name: string): void;
+/**
+ * Serialize an operational skill to frontmatter + body.
+ *
+ * Keys are emitted in `KEY_ORDER` and optional keys are omitted when absent, so
+ * the same input always produces the same bytes — the ordering half of AC-17.
+ *
+ * @param skill - The skill to serialize.
+ * @returns Full file content, frontmatter first.
+ */
+export declare function serializeOperationalSkill(skill: OperationalSkill): string;
+/**
+ * Parse an operational skill file into frontmatter and body.
+ *
+ * @param raw - Full file content.
+ * @returns The parsed skill.
+ * @throws {OperationalSchemaError} On missing/unclosed frontmatter, a missing or
+ *   wrongly-typed required field, or an invalid name.
+ */
+export declare function parseOperationalSkill(raw: string): OperationalSkill;
+//# sourceMappingURL=schema.d.ts.map

package/dist/operational/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/operational/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,8EAA8E;AAC9E,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAyB9C,wEAAwE;AACxE,eAAO,MAAM,gBAAgB,gBAAgB,CAAC;AAM9C,mDAAmD;AACnD,MAAM,WAAW,oBAAoB;IACnC,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,IAAI,EAAE,OAAO,gBAAgB,CAAC;IAC9B,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,eAAe,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,kEAAkE;AAClE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,oBAAoB,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,6DAA6D;AAC7D,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,MAAM,EAAE,MAAM;CAI3B;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CA+C/D;AAmBD;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CA0BzE;AAMD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAmEnE"}