@rasensio/aidlc 1.8.1 → 1.9.0

package/dist/operational/emit.js

@@ -0,0 +1,227 @@
+/**
+ * Operational-skill emission: plan building and staged, all-or-nothing execution.
+ *
+ * Reuses `InstallPlan`/`FileOp` — the same types the framework adapters produce —
+ * which buys skip-if-identical idempotence (NFR-7), dry-run equivalence, and
+ * `mergeBlock` support for codex without touching `SkillMeta` (AC-33).
+ *
+ * `executePlan` writes op-by-op, so a mid-plan failure leaves a partial tree. That
+ * is unacceptable under AC-45 and unrepairable under AC-10's collision refusal, so
+ * emission uses `executePlanStaged` instead: resolve and validate everything,
+ * stage every byte into one scratch directory, then commit by rename.
+ *
+ * Requirements: AC-15, AC-17, AC-45, AC-47, NFR-7
+ *
+ * @module
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { dirname, join, relative, sep } from 'node:path';
+import { adapters } from '../compile/adapters/index.js';
+import { mergeBlock } from '../compile/merger.js';
+import { canonicalBodyPath, packagerFor } from './packagers.js';
+import { serializeOperationalSkill } from './schema.js';
+/** Thrown when staging or committing fails. */
+export class EmitError extends Error {
+    committed;
+    constructor(reason, 
+    /** Ops whose rename already completed, when a commit fails part-way. */
+    committed = []) {
+        super(reason);
+        this.committed = committed;
+        this.name = 'EmitError';
+    }
+}
+// ---------------------------------------------------------------------------
+// Planning
+// ---------------------------------------------------------------------------
+/**
+ * Build the InstallPlan for one operational skill.
+ *
+ * Every packager is resolved **before** any op is produced, so a mixed
+ * supported/unsupported `platforms:` list throws during planning with nothing
+ * staged — AC-47's all-or-nothing guarantee.
+ *
+ * @param req - The emission request.
+ * @returns A plan whose ops cover the canonical body plus every platform artifact.
+ * @throws {UnsupportedPlatformError} When any configured platform lacks packaging.
+ */
+export function planEmit(req) {
+    // Resolve first — this is the AC-47 gate.
+    const packagers = req.platforms.map((p) => packagerFor(p));
+    const ops = [];
+    const warnings = [];
+    // 1. Canonical body — the single source of full instructions (AC-13).
+    ops.push({
+        kind: 'create',
+        path: canonicalBodyPath(req.skill.meta.name),
+        content: serializeOperationalSkill(req.skill),
+    });
+    // 2. Per-skill platform artifacts.
+    for (const packager of packagers) {
+        ops.push(...packager.plan(req.skill));
+    }
+    // 3. Index artifacts, one per index-shaped platform.
+    for (const packager of packagers) {
+        if (!packager.planIndex)
+            continue;
+        const op = packager.planIndex(req.allSkills);
+        if (op)
+            ops.push(op);
+    }
+    // 4. Platform validators, where the platform defines one. This is how the
+    //    ownership-marker placement stays honest: a first-line comment before
+    //    frontmatter fails claude-code's and cursor's own checks.
+    for (const op of ops) {
+        for (const platform of req.platforms) {
+            const adapter = adapters.get(platform);
+            if (!adapter)
+                continue;
+            const result = adapter.validate(op);
+            warnings.push(...result.warnings);
+            if (!result.valid) {
+                throw new EmitError(`emitted file ${op.path} fails ${platform} validation: ${result.errors.join('; ')}`);
+            }
+        }
+    }
+    return { ops, warnings };
+}
+// ---------------------------------------------------------------------------
+// Content resolution
+// ---------------------------------------------------------------------------
+/** Final on-disk content for one op, including merge-block composition. */
+function resolveContent(op, rootDir) {
+    if (op.kind === 'merge-block') {
+        const abs = join(rootDir, op.path);
+        const existing = existsSync(abs) ? readFileSync(abs, 'utf8') : '';
+        return mergeBlock(existing, op.blockId, op.content);
+    }
+    return op.content;
+}
+/** Reject any op path that escapes the project root. */
+function assertInsideRoot(rootDir, opPath) {
+    const abs = join(rootDir, opPath);
+    const rel = relative(rootDir, abs);
+    if (rel.startsWith('..') || rel.startsWith(`..${sep}`)) {
+        throw new EmitError(`refusing to write outside the project root: ${opPath}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Staged execution (AC-45)
+// ---------------------------------------------------------------------------
+/**
+ * Apply a plan atomically-as-possible.
+ *
+ * Three phases:
+ * 1. **Resolve and validate** — compute final content for every op. Pure. Every
+ *    predictable failure lands here, before a single byte is written.
+ * 2. **Stage** — write each op into one scratch directory outside every path the
+ *    project enumerates. On failure, remove the scratch dir and abort; the tree is
+ *    exactly as it was.
+ * 3. **Commit** — create parent directories, then rename each staged file onto its
+ *    target.
+ *
+ * Honest bound: phase 3 is a rename sequence, not one transaction. A failure there
+ * reports which renames completed, and the residual state is repaired by
+ * `--re-emit`, which is idempotent. Directories this run created are removed on a
+ * phase-3 failure only when still empty.
+ *
+ * Skip-if-identical is preserved, so re-emitting unchanged input writes nothing
+ * (NFR-7, AC-17).
+ *
+ * @param plan - The plan to apply.
+ * @param rootDir - Absolute project root.
+ * @returns What was written and skipped.
+ */
+export function executePlanStaged(plan, rootDir) {
+    // --- Phase 1: resolve + validate ---------------------------------------
+    const resolved = [];
+    for (const op of plan.ops) {
+        assertInsideRoot(rootDir, op.path);
+        resolved.push({
+            op,
+            content: resolveContent(op, rootDir),
+            abs: join(rootDir, op.path),
+        });
+    }
+    const toWrite = resolved.filter((r) => !(existsSync(r.abs) && readFileSync(r.abs, 'utf8') === r.content));
+    const filesSkipped = resolved
+        .filter((r) => !toWrite.includes(r))
+        .map((r) => r.op.path);
+    if (toWrite.length === 0) {
+        return { filesWritten: [], filesSkipped, warnings: [...plan.warnings] };
+    }
+    // --- Phase 2: stage ----------------------------------------------------
+    const scratch = join(rootDir, '.aidlc', `.tmp-emit-${process.pid}`);
+    const staged = [];
+    try {
+        mkdirSync(scratch, { recursive: true });
+        for (let i = 0; i < toWrite.length; i++) {
+            const { op, content, abs } = toWrite[i];
+            // Flat, index-keyed names: no nesting to recreate, and no chance of a
+            // staged file colliding with another op's directory.
+            const tmp = join(scratch, `${i}.staged`);
+            writeFileSync(tmp, content, 'utf8');
+            staged.push({ tmp, abs, path: op.path });
+        }
+    }
+    catch (err) {
+        rmSync(scratch, { recursive: true, force: true });
+        throw new EmitError(`staging failed, nothing was written: ${err.message}`);
+    }
+    // --- Phase 3: commit ---------------------------------------------------
+    const filesWritten = [];
+    const createdDirs = [];
+    try {
+        for (const { tmp, abs, path } of staged) {
+            const dir = dirname(abs);
+            if (!existsSync(dir)) {
+                mkdirSync(dir, { recursive: true });
+                createdDirs.push(dir);
+            }
+            renameSync(tmp, abs);
+            filesWritten.push(path);
+        }
+    }
+    catch (err) {
+        // Remove directories we created that are still empty, so a failed commit
+        // does not leave scaffolding behind.
+        for (const dir of createdDirs.reverse()) {
+            try {
+                rmSync(dir, { recursive: false });
+            }
+            catch {
+                // Non-empty (a rename landed inside it) — leave it.
+            }
+        }
+        rmSync(scratch, { recursive: true, force: true });
+        throw new EmitError(`commit failed after writing ${filesWritten.length}/${staged.length} files: ` +
+            `${err.message}. Repair with: aidlc add skill --re-emit`, filesWritten);
+    }
+    rmSync(scratch, { recursive: true, force: true });
+    return { filesWritten, filesSkipped, warnings: [...plan.warnings] };
+}
+/**
+ * Simulate `executePlanStaged` without touching the filesystem.
+ *
+ * Uses the same resolution, so `--dry-run` is provably equivalent to a real run.
+ *
+ * @param plan - The plan to simulate.
+ * @param rootDir - Absolute project root.
+ */
+export function dryRunPlanStaged(plan, rootDir) {
+    const filesWritten = [];
+    const filesSkipped = [];
+    for (const op of plan.ops) {
+        assertInsideRoot(rootDir, op.path);
+        const abs = join(rootDir, op.path);
+        const content = resolveContent(op, rootDir);
+        if (existsSync(abs) && readFileSync(abs, 'utf8') === content) {
+            filesSkipped.push(op.path);
+        }
+        else {
+            filesWritten.push(op.path);
+        }
+    }
+    return { filesWritten, filesSkipped, warnings: [...plan.warnings] };
+}
+//# sourceMappingURL=emit.js.map

package/dist/operational/emit.js.map

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

package/dist/operational/knowledge.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Knowledge-graph registration for operational skills.
+ *
+ * Registers each generated skill so `aidlc knowledge query <name>` finds it and a
+ * developer returning months later does not write a second skill for the same job
+ * (US-6, AC-28…AC-30, AC-49).
+ *
+ * Two properties are load-bearing and neither is free:
+ *
+ * - **The entity type is not gate-counted.** `custom:operational-skill` rather than
+ *   `module`, because the ideation seeding gate counts `module`, `convention`, and
+ *   `depends-on` (`knowledge/gate-criterion.ts`). Registering skills as modules
+ *   would let generated files satisfy a lifecycle gate meant to measure real
+ *   architecture.
+ * - **The id is namespaced and collisions are refused.** `addEntity` merges into any
+ *   pre-existing entity with the same id, and `mergeEntities` never overrides
+ *   `type` — so an unnamespaced id colliding with an existing `module` would stay
+ *   gate-counted *and* clobber an architecture fact. Registration therefore checks
+ *   the resolved type first and refuses rather than merging.
+ *
+ * Registration is best-effort: failure warns and generation still succeeds (AC-30).
+ *
+ * Requirements: AC-28, AC-29, AC-30, AC-49
+ *
+ * @module
+ */
+import type { OperationalSkill } from './schema.js';
+/** Entity type for operational skills — deliberately not gate-counted (AC-28). */
+export declare const OPERATIONAL_ENTITY_TYPE = "custom:operational-skill";
+/** Id prefix keeping operational entities out of the general id namespace. */
+export declare const OPERATIONAL_ID_PREFIX = "operational-skill-";
+/** Outcome of a registration attempt. */
+export interface RegistrationResult {
+    /** True when the entity now exists with the operational type. */
+    registered: boolean;
+    /** Non-fatal explanation when `registered` is false, or a merge note. */
+    warning?: string;
+    /** The entity id used. */
+    id: string;
+}
+/** Namespaced entity id for a skill name. */
+export declare function operationalEntityId(name: string): string;
+/**
+ * Register (or repair) an operational skill in the knowledge graph.
+ *
+ * Never throws: a graph problem must not lose a skill the user already confirmed
+ * (AC-30). Re-running for a skill whose files exist but whose entity is missing
+ * recreates it, which is the AC-49 repair path.
+ *
+ * @param projectRoot - Absolute project root.
+ * @param skill - The skill to register.
+ * @returns Whether the entity is now present, plus any warning to surface.
+ */
+export declare function registerOperationalSkill(projectRoot: string, skill: OperationalSkill): RegistrationResult;
+/**
+ * Is this skill already registered with the operational type?
+ *
+ * Used to decide whether a re-run needs to repair registration (AC-49).
+ *
+ * @param projectRoot - Absolute project root.
+ * @param name - Skill name.
+ */
+export declare function isOperationalSkillRegistered(projectRoot: string, name: string): boolean;
+//# sourceMappingURL=knowledge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../../src/operational/knowledge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,kFAAkF;AAClF,eAAO,MAAM,uBAAuB,6BAA6B,CAAC;AAElE,8EAA8E;AAC9E,eAAO,MAAM,qBAAqB,uBAAuB,CAAC;AAE1D,yCAAyC;AACzC,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,UAAU,EAAE,OAAO,CAAC;IACpB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0BAA0B;IAC1B,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,6CAA6C;AAC7C,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,gBAAgB,GACtB,kBAAkB,CAiEpB;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAoBvF"}

package/dist/operational/knowledge.js

@@ -0,0 +1,144 @@
+/**
+ * Knowledge-graph registration for operational skills.
+ *
+ * Registers each generated skill so `aidlc knowledge query <name>` finds it and a
+ * developer returning months later does not write a second skill for the same job
+ * (US-6, AC-28…AC-30, AC-49).
+ *
+ * Two properties are load-bearing and neither is free:
+ *
+ * - **The entity type is not gate-counted.** `custom:operational-skill` rather than
+ *   `module`, because the ideation seeding gate counts `module`, `convention`, and
+ *   `depends-on` (`knowledge/gate-criterion.ts`). Registering skills as modules
+ *   would let generated files satisfy a lifecycle gate meant to measure real
+ *   architecture.
+ * - **The id is namespaced and collisions are refused.** `addEntity` merges into any
+ *   pre-existing entity with the same id, and `mergeEntities` never overrides
+ *   `type` — so an unnamespaced id colliding with an existing `module` would stay
+ *   gate-counted *and* clobber an architecture fact. Registration therefore checks
+ *   the resolved type first and refuses rather than merging.
+ *
+ * Registration is best-effort: failure warns and generation still succeeds (AC-30).
+ *
+ * Requirements: AC-28, AC-29, AC-30, AC-49
+ *
+ * @module
+ */
+import { knowledgeExists, openKnowledge } from '../knowledge/engine.js';
+/** Entity type for operational skills — deliberately not gate-counted (AC-28). */
+export const OPERATIONAL_ENTITY_TYPE = 'custom:operational-skill';
+/** Id prefix keeping operational entities out of the general id namespace. */
+export const OPERATIONAL_ID_PREFIX = 'operational-skill-';
+/** Namespaced entity id for a skill name. */
+export function operationalEntityId(name) {
+    return `${OPERATIONAL_ID_PREFIX}${name}`;
+}
+/**
+ * Register (or repair) an operational skill in the knowledge graph.
+ *
+ * Never throws: a graph problem must not lose a skill the user already confirmed
+ * (AC-30). Re-running for a skill whose files exist but whose entity is missing
+ * recreates it, which is the AC-49 repair path.
+ *
+ * @param projectRoot - Absolute project root.
+ * @param skill - The skill to register.
+ * @returns Whether the entity is now present, plus any warning to surface.
+ */
+export function registerOperationalSkill(projectRoot, skill) {
+    const id = operationalEntityId(skill.meta.name);
+    // Projects that never adopted the knowledge graph are not forced into it.
+    if (!knowledgeExists(projectRoot)) {
+        return {
+            registered: false,
+            id,
+            warning: 'knowledge graph not initialized; skipped registration (run `aidlc knowledge add` later if wanted)',
+        };
+    }
+    let engine;
+    try {
+        engine = openKnowledge(projectRoot);
+    }
+    catch (err) {
+        return {
+            registered: false,
+            id,
+            warning: `could not open knowledge graph: ${err.message}`,
+        };
+    }
+    try {
+        // Refuse to merge across types. mergeEntities preserves the existing `type`,
+        // so merging here would silently rewrite someone else's record.
+        const existing = engine.index.getEntity(id);
+        if (existing && existing.type !== OPERATIONAL_ENTITY_TYPE) {
+            return {
+                registered: false,
+                id,
+                warning: `knowledge entity '${id}' already exists with type '${existing.type}'; ` +
+                    'refusing to overwrite it — the skill was written but not registered',
+            };
+        }
+        const result = engine.writer.addEntity({
+            id,
+            type: OPERATIONAL_ENTITY_TYPE,
+            name: skill.meta.name,
+            description: `Operational skill: ${skill.meta.description}`,
+            source: `.aidlc/operational-skills/${skill.meta.name}.md`,
+            tags: ['operational-skill', 'app-owned'],
+        });
+        return {
+            registered: true,
+            id,
+            ...(result.warnings.length > 0 ? { warning: result.warnings.join('; ') } : {}),
+        };
+    }
+    catch (err) {
+        return {
+            registered: false,
+            id,
+            warning: `registration failed: ${err.message}`,
+        };
+    }
+    finally {
+        try {
+            engine.close();
+        }
+        catch {
+            // Closing is best-effort; a close failure must not mask the result.
+        }
+    }
+}
+/**
+ * Is this skill already registered with the operational type?
+ *
+ * Used to decide whether a re-run needs to repair registration (AC-49).
+ *
+ * @param projectRoot - Absolute project root.
+ * @param name - Skill name.
+ */
+export function isOperationalSkillRegistered(projectRoot, name) {
+    if (!knowledgeExists(projectRoot))
+        return false;
+    let engine;
+    try {
+        engine = openKnowledge(projectRoot);
+    }
+    catch {
+        return false;
+    }
+    try {
+        const entity = engine.index.getEntity(operationalEntityId(name));
+        return entity?.type === OPERATIONAL_ENTITY_TYPE;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        try {
+            engine.close();
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+//# sourceMappingURL=knowledge.js.map

package/dist/operational/knowledge.js.map

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

package/dist/operational/packagers.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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 type { FileOp, PlatformId } from '../core/types.js';
+import type { OperationalSkill } from './schema.js';
+/** Directory holding canonical operational-skill bodies (AC-13, D-2). */
+export declare const OPERATIONAL_DIR = ".aidlc/operational-skills";
+/** Merge-block id for operational skills. Distinct from every framework id. */
+export declare const OPERATIONAL_BLOCK_ID = "aidlc-operational-skills";
+/** Windsurf index rule path — unprefixed, so it cannot collide with framework rules. */
+export declare const WINDSURF_INDEX_PATH = ".windsurf/rules/operational-skills.md";
+/**
+ * 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 declare function ownershipMarker(name: string): string;
+/** Packaging strategy for one platform. */
+export interface OperationalPackager {
+    readonly platform: PlatformId;
+    /** Per-skill file ops. Empty for index-shaped platforms. */
+    plan(skill: OperationalSkill): FileOp[];
+    /** One op covering all operational skills. Absent for per-skill platforms. */
+    planIndex?(skills: OperationalSkill[]): FileOp | null;
+}
+/** Thrown when a configured platform has no operational packaging (AC-16). */
+export declare class UnsupportedPlatformError extends Error {
+    readonly platform: string;
+    constructor(platform: string, supported: readonly string[]);
+}
+/** Relative path of a skill's canonical body. */
+export declare function canonicalBodyPath(name: string): string;
+/** Platforms with operational packaging, sorted for stable error messages. */
+export declare const supportedOperationalPlatforms: PlatformId[];
+/**
+ * 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 declare function packagerFor(platform: PlatformId): OperationalPackager;
+/** Does this platform have operational packaging? */
+export declare function hasOperationalPackaging(platform: string): boolean;
+//# sourceMappingURL=packagers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"packagers.d.ts","sourceRoot":"","sources":["../../src/operational/packagers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAMpD,yEAAyE;AACzE,eAAO,MAAM,eAAe,8BAA8B,CAAC;AAE3D,+EAA+E;AAC/E,eAAO,MAAM,oBAAoB,6BAA6B,CAAC;AAE/D,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,0CAA0C,CAAC;AAM3E;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAWD,2CAA2C;AAC3C,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,4DAA4D;IAC5D,IAAI,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAAC;IACxC,8EAA8E;IAC9E,SAAS,CAAC,CAAC,MAAM,EAAE,gBAAgB,EAAE,GAAG,MAAM,GAAG,IAAI,CAAC;CACvD;AAED,8EAA8E;AAC9E,qBAAa,wBAAyB,SAAQ,KAAK;aAE/B,QAAQ,EAAE,MAAM;gBAAhB,QAAQ,EAAE,MAAM,EAChC,SAAS,EAAE,SAAS,MAAM,EAAE;CAQ/B;AAED,iDAAiD;AACjD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtD;AA0LD,8EAA8E;AAC9E,eAAO,MAAM,6BAA6B,EAAE,UAAU,EAAiC,CAAC;AAExF;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,UAAU,GAAG,mBAAmB,CAMrE;AAED,qDAAqD;AACrD,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEjE"}