popeye-cli 2.1.0 → 2.7.0

package/dist/pipeline/skills/constitution-generator.js

@@ -0,0 +1,210 @@
+/**
+ * Deterministic constitution generation — no AI call required.
+ * Produces skills/POPEYE_CONSTITUTION.md from templates + inferred tech stack.
+ * Includes pipeline governance invariants that never change.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+// ─── Constants ──────────────────────────────────────────
+const CONSTITUTION_FILENAME = 'POPEYE_CONSTITUTION.md';
+const PIPELINE_VERSION = '1.0';
+// ─── Public API ─────────────────────────────────────────
+/**
+ * Generate the project constitution file if it doesn't already exist.
+ * Entirely deterministic — built from templates and tech stack data.
+ *
+ * @param context - Constitution generation context
+ */
+export function generateConstitution(context) {
+    const { skillsDir } = context;
+    if (shouldSkipConstitution(skillsDir)) {
+        return;
+    }
+    if (!existsSync(skillsDir)) {
+        mkdirSync(skillsDir, { recursive: true });
+    }
+    const content = buildConstitutionContent(context);
+    const constitutionPath = join(skillsDir, CONSTITUTION_FILENAME);
+    writeFileSync(constitutionPath, content, 'utf-8');
+}
+/**
+ * Check if constitution generation should be skipped.
+ * Returns true if the file already exists (hand-written or prior run).
+ *
+ * @param skillsDir - Path to the skills directory
+ * @returns true if generation should be skipped
+ */
+export function shouldSkipConstitution(skillsDir) {
+    const constitutionPath = join(skillsDir, CONSTITUTION_FILENAME);
+    return existsSync(constitutionPath);
+}
+// ─── Content Assembly ───────────────────────────────────
+/**
+ * Build the full constitution markdown content.
+ *
+ * @param context - Constitution generation context
+ * @returns Complete markdown string
+ */
+function buildConstitutionContent(context) {
+    const { projectName, language, techStack, sessionGuidance } = context;
+    const date = new Date().toISOString().split('T')[0];
+    const sections = [
+        `# Project Constitution: ${projectName}`,
+        '',
+        `Generated: ${date} | Language: ${language} | Pipeline: v${PIPELINE_VERSION}`,
+        '',
+        getTechStackSection(techStack),
+        getArchitectureRules(techStack),
+        getCodeQualityRules(),
+        getGovernanceRules(),
+        getConstraintsSection(language, sessionGuidance),
+        getImmutabilitySection(),
+    ];
+    return sections.join('\n');
+}
+// ─── Template Sections ──────────────────────────────────
+/**
+ * Generate the tech stack section from inferred stack data.
+ *
+ * @param techStack - Inferred tech stack
+ * @returns Markdown section
+ */
+export function getTechStackSection(techStack) {
+    const lines = ['## Tech Stack'];
+    if (techStack.language)
+        lines.push(`- Language: ${techStack.language}`);
+    if (techStack.backend)
+        lines.push(`- Framework: ${techStack.backend}`);
+    if (techStack.frontend)
+        lines.push(`- Frontend: ${techStack.frontend}`);
+    if (techStack.database)
+        lines.push(`- Database: ${techStack.database}`);
+    if (techStack.orm)
+        lines.push(`- ORM: ${techStack.orm}`);
+    if (techStack.testing)
+        lines.push(`- Testing: ${techStack.testing}`);
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Generate architecture rules based on the tech stack.
+ *
+ * @param techStack - Inferred tech stack
+ * @returns Markdown section
+ */
+export function getArchitectureRules(techStack) {
+    const rules = [];
+    let ruleNum = 1;
+    if (techStack.backend?.includes('FastAPI')) {
+        rules.push(`${ruleNum++}. All API endpoints MUST use async/await`);
+    }
+    if (techStack.backend?.includes('Express')) {
+        rules.push(`${ruleNum++}. Use Express middleware pattern for cross-cutting concerns`);
+    }
+    if (techStack.backend?.includes('Django')) {
+        rules.push(`${ruleNum++}. Follow Django app structure conventions`);
+    }
+    if (techStack.orm?.includes('SQLAlchemy')) {
+        rules.push(`${ruleNum++}. Database access exclusively via SQLAlchemy ORM`);
+    }
+    if (techStack.orm?.includes('Prisma')) {
+        rules.push(`${ruleNum++}. Database access exclusively via Prisma client`);
+    }
+    if (techStack.language?.includes('Python')) {
+        rules.push(`${ruleNum++}. Environment variables via python-dotenv, never hardcoded`);
+        rules.push(`${ruleNum++}. PEP8 style with type hints on all functions`);
+    }
+    if (techStack.language?.includes('TypeScript')) {
+        rules.push(`${ruleNum++}. TypeScript strict mode, no implicit any`);
+        rules.push(`${ruleNum++}. Environment variables via dotenv, never hardcoded`);
+    }
+    if (techStack.frontend?.includes('React')) {
+        rules.push(`${ruleNum++}. React components use functional patterns with hooks`);
+    }
+    if (techStack.frontend?.includes('Next')) {
+        rules.push(`${ruleNum++}. Next.js App Router conventions for routing and layouts`);
+    }
+    // Always add a generic rule if nothing specific matched
+    if (rules.length === 0) {
+        rules.push('1. Environment variables never hardcoded in source code');
+        rules.push('2. Clear separation of concerns between modules');
+    }
+    return ['## Architecture Rules', ...rules, ''].join('\n');
+}
+/**
+ * Generate code quality rules (constant across all projects).
+ *
+ * @returns Markdown section
+ */
+export function getCodeQualityRules() {
+    return [
+        '## Code Quality',
+        '1. Maximum 500 lines per source file',
+        '2. Unit tests for every module (happy path + edge case + failure)',
+        '3. Standard logging (no unstructured print statements)',
+        '4. Docstrings/JSDoc on public functions',
+        '',
+    ].join('\n');
+}
+/**
+ * Generate governance rules (pipeline invariants, constant).
+ *
+ * @returns Markdown section
+ */
+function getGovernanceRules() {
+    return [
+        '## Governance Rules',
+        '1. Consensus threshold: 0.95 with minimum 2 reviewers',
+        '2. All artifacts are immutable once stored (new versions create new files)',
+        '3. No placeholder content in production code or generated output',
+        '4. Gate failures route to RECOVERY_LOOP before phase retry',
+        '5. Constitution modifications during pipeline execution are forbidden',
+        '6. Change Requests required for scope changes after INTAKE',
+        '',
+    ].join('\n');
+}
+/**
+ * Generate language-specific and session-specific constraints.
+ *
+ * @param language - Project language
+ * @param sessionGuidance - Optional session guidance text
+ * @returns Markdown section
+ */
+export function getConstraintsSection(language, sessionGuidance) {
+    const lines = ['## Project Constraints'];
+    const langConstraints = {
+        python: ['- Python 3.11+ required', '- Use virtual environment (venv) for all operations'],
+        typescript: ['- Node.js 18+ required', '- ESM modules (import/export, .js extensions)'],
+        fullstack: [
+            '- Python 3.11+ for backend, Node.js 18+ for frontend',
+            '- Monorepo structure with clear app boundaries',
+        ],
+        website: ['- Node.js 18+ required', '- SSG/SSR optimization for performance and SEO'],
+        all: [
+            '- Python 3.11+ for backend, Node.js 18+ for frontend and website',
+            '- Monorepo structure with clear app boundaries',
+        ],
+    };
+    const constraints = langConstraints[language] ?? langConstraints.python;
+    lines.push(...constraints);
+    if (sessionGuidance) {
+        lines.push('', '### Session-Specific Guidance');
+        lines.push(sessionGuidance.slice(0, 500));
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Generate the immutability notice (constant).
+ *
+ * @returns Markdown section
+ */
+function getImmutabilitySection() {
+    return [
+        '## Immutability',
+        'This document MUST NOT be modified during pipeline execution.',
+        'Any modification triggers constitution verification failure at next gate.',
+        '',
+    ].join('\n');
+}
+//# sourceMappingURL=constitution-generator.js.map

package/dist/pipeline/skills/constitution-generator.js.map

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

package/dist/pipeline/skills/coverage-gate.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Skill Coverage Gate — deterministic assertion that every active role
+ * has recorded usage (or is explicitly exempt).
+ *
+ * Called at CONSENSUS_ROLE_PLANS and PRODUCTION_GATE gates.
+ */
+import type { PipelineRole, PipelinePhase, PipelineState } from '../types.js';
+import type { SkillUsageEvent } from './usage-registry.js';
+/** Canonical phase order — used for phase-aware deferral in coverage checks. */
+export declare const PHASE_ORDER: PipelinePhase[];
+export interface RoleUsageRequirement {
+    phases: PipelinePhase[];
+    minEvents: number;
+    conditional?: 'always' | 'if_recovery' | 'if_arbitrated' | 'if_journal_triggered';
+}
+export declare const ROLE_REQUIRED_USAGE: Record<PipelineRole, RoleUsageRequirement>;
+export interface CoverageMissing {
+    role: PipelineRole;
+    expectedPhases: PipelinePhase[];
+    reason: string;
+}
+export interface CoverageResult {
+    pass: boolean;
+    missing: CoverageMissing[];
+    covered: PipelineRole[];
+    /** Roles skipped because their required phases haven't been reached yet (v2.4.5) */
+    deferred: PipelineRole[];
+}
+/**
+ * Assert that all active roles have recorded skill usage
+ * according to their requirements.
+ *
+ * Args:
+ *   activeRoles: Roles currently active in the pipeline.
+ *   events: All recorded skill usage events.
+ *   pipeline: Full pipeline state for conditional checks.
+ *   currentPhase: Current pipeline phase for phase-aware deferral (v2.4.5).
+ *     Omit for strict mode (checks all roles regardless of phase).
+ *
+ * Returns:
+ *   CoverageResult with pass/fail and details.
+ */
+export declare function assertSkillCoverage(activeRoles: PipelineRole[], events: SkillUsageEvent[], pipeline: PipelineState, currentPhase?: PipelinePhase): CoverageResult;
+//# sourceMappingURL=coverage-gate.d.ts.map

package/dist/pipeline/skills/coverage-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-gate.d.ts","sourceRoot":"","sources":["../../../src/pipeline/skills/coverage-gate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAI3D,gFAAgF;AAChF,eAAO,MAAM,WAAW,EAAE,aAAa,EAItC,CAAC;AAIF,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,QAAQ,GAAG,aAAa,GAAG,eAAe,GAAG,sBAAsB,CAAC;CACnF;AAED,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,YAAY,EAAE,oBAAoB,CAwB1E,CAAC;AAIF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,YAAY,CAAC;IACnB,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,oFAAoF;IACpF,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,YAAY,EAAE,EAC3B,MAAM,EAAE,eAAe,EAAE,EACzB,QAAQ,EAAE,aAAa,EACvB,YAAY,CAAC,EAAE,aAAa,GAC3B,cAAc,CAmEhB"}

package/dist/pipeline/skills/coverage-gate.js

@@ -0,0 +1,143 @@
+/**
+ * Skill Coverage Gate — deterministic assertion that every active role
+ * has recorded usage (or is explicitly exempt).
+ *
+ * Called at CONSENSUS_ROLE_PLANS and PRODUCTION_GATE gates.
+ */
+// ─── Phase Order (must match orchestrator/gate phase sequence) ────
+/** Canonical phase order — used for phase-aware deferral in coverage checks. */
+export const PHASE_ORDER = [
+    'INTAKE', 'CONSENSUS_MASTER_PLAN', 'ARCHITECTURE', 'CONSENSUS_ARCHITECTURE',
+    'ROLE_PLANNING', 'CONSENSUS_ROLE_PLANS', 'IMPLEMENTATION', 'QA_VALIDATION',
+    'REVIEW', 'AUDIT', 'PRODUCTION_GATE', 'RECOVERY_LOOP', 'DONE', 'STUCK',
+];
+export const ROLE_REQUIRED_USAGE = {
+    DISPATCHER: { phases: [], minEvents: 0 },
+    ARCHITECT: { phases: ['ARCHITECTURE'], minEvents: 1 },
+    DB_EXPERT: { phases: ['ROLE_PLANNING'], minEvents: 1 },
+    BACKEND_PROGRAMMER: { phases: ['ROLE_PLANNING'], minEvents: 1 },
+    FRONTEND_PROGRAMMER: { phases: ['ROLE_PLANNING'], minEvents: 1 },
+    WEBSITE_PROGRAMMER: { phases: ['ROLE_PLANNING'], minEvents: 1 },
+    UI_UX_SPECIALIST: { phases: ['ROLE_PLANNING'], minEvents: 1 },
+    MARKETING_EXPERT: { phases: ['ROLE_PLANNING'], minEvents: 1 },
+    SOCIAL_EXPERT: { phases: ['ROLE_PLANNING'], minEvents: 1 },
+    QA_TESTER: { phases: ['ROLE_PLANNING', 'QA_VALIDATION'], minEvents: 1 },
+    REVIEWER: { phases: ['REVIEW'], minEvents: 1 },
+    ARBITRATOR: { phases: [], minEvents: 0, conditional: 'if_arbitrated' },
+    DEBUGGER: { phases: ['RECOVERY_LOOP'], minEvents: 0, conditional: 'if_recovery' },
+    AUDITOR: { phases: ['AUDIT'], minEvents: 1 },
+    JOURNALIST: {
+        phases: [
+            'CONSENSUS_MASTER_PLAN', 'CONSENSUS_ARCHITECTURE', 'CONSENSUS_ROLE_PLANS',
+            'AUDIT', 'PRODUCTION_GATE', 'RECOVERY_LOOP', 'DONE',
+        ],
+        minEvents: 1,
+        conditional: 'if_journal_triggered',
+    },
+    RELEASE_MANAGER: { phases: ['DONE'], minEvents: 1 },
+};
+// ─── Assertion Logic ─────────────────────────────────────
+/**
+ * Assert that all active roles have recorded skill usage
+ * according to their requirements.
+ *
+ * Args:
+ *   activeRoles: Roles currently active in the pipeline.
+ *   events: All recorded skill usage events.
+ *   pipeline: Full pipeline state for conditional checks.
+ *   currentPhase: Current pipeline phase for phase-aware deferral (v2.4.5).
+ *     Omit for strict mode (checks all roles regardless of phase).
+ *
+ * Returns:
+ *   CoverageResult with pass/fail and details.
+ */
+export function assertSkillCoverage(activeRoles, events, pipeline, currentPhase) {
+    const missing = [];
+    const covered = [];
+    const deferred = [];
+    // Resolve phase index; -1 means unknown/omitted -> strict mode (check all)
+    const currentIdx = currentPhase ? PHASE_ORDER.indexOf(currentPhase) : -1;
+    for (const role of activeRoles) {
+        const requirement = ROLE_REQUIRED_USAGE[role];
+        if (!requirement) {
+            // Reason: Unknown role — skip rather than crash
+            continue;
+        }
+        // Meta-only roles (DISPATCHER) with minEvents 0 and no conditional
+        if (requirement.minEvents === 0 && !requirement.conditional) {
+            covered.push(role);
+            continue;
+        }
+        // Conditional roles — check if their condition is met
+        if (requirement.conditional) {
+            const isRequired = isConditionalRequired(requirement.conditional, pipeline);
+            if (!isRequired) {
+                // Condition not met — not required, count as covered
+                covered.push(role);
+                continue;
+            }
+        }
+        // v2.4.5: Phase-aware deferral — skip roles whose phases are all after currentPhase.
+        // Only applies when currentIdx >= 0 (known phase). Unknown phase = strict mode.
+        if (currentIdx >= 0 && requirement.phases.length > 0) {
+            const anyPhaseReached = requirement.phases.some((p) => PHASE_ORDER.indexOf(p) <= currentIdx);
+            if (!anyPhaseReached) {
+                // Reason: Role's required phases are all after currentPhase — defer check
+                deferred.push(role);
+                continue;
+            }
+        }
+        // Check if role has at least minEvents usage events
+        const roleEvents = events.filter((e) => e.role === role);
+        const effectiveMin = Math.max(requirement.minEvents, 1);
+        if (roleEvents.length >= effectiveMin) {
+            covered.push(role);
+        }
+        else {
+            missing.push({
+                role,
+                expectedPhases: requirement.phases,
+                reason: roleEvents.length === 0
+                    ? `No skill usage recorded for ${role}`
+                    : `Only ${roleEvents.length}/${effectiveMin} usage events for ${role}`,
+            });
+        }
+    }
+    return {
+        pass: missing.length === 0,
+        missing,
+        covered,
+        deferred,
+    };
+}
+// ─── Conditional Helpers ─────────────────────────────────
+function isConditionalRequired(conditional, pipeline) {
+    switch (conditional) {
+        case 'always':
+            return true;
+        case 'if_recovery':
+            return pipeline.recoveryCount > 0;
+        case 'if_arbitrated':
+            return hasArbitratedConsensus(pipeline);
+        case 'if_journal_triggered':
+            return hasJournalTriggered(pipeline);
+        default:
+            return false;
+    }
+}
+/** Check if any arbitration occurred during consensus phases. */
+function hasArbitratedConsensus(pipeline) {
+    // Reason: Arbitration artifacts are created when consensus requires arbitrator intervention
+    const arbitrationArtifacts = pipeline.artifacts.filter((a) => a.type === 'arbitration');
+    return arbitrationArtifacts.length > 0;
+}
+/** Check if any journalist-triggering phases have completed. */
+function hasJournalTriggered(pipeline) {
+    const journalPhases = [
+        'CONSENSUS_MASTER_PLAN', 'CONSENSUS_ARCHITECTURE', 'CONSENSUS_ROLE_PLANS',
+        'AUDIT', 'PRODUCTION_GATE', 'RECOVERY_LOOP', 'DONE',
+    ];
+    const completedPhases = new Set(Object.keys(pipeline.gateResults));
+    return journalPhases.some((phase) => completedPhases.has(phase));
+}
+//# sourceMappingURL=coverage-gate.js.map

package/dist/pipeline/skills/coverage-gate.js.map

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

package/dist/pipeline/skills/generator.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Project-specific skill generation.
+ * Uses a single AI call to generate tailored system prompts for active roles,
+ * then writes them as .md files with YAML frontmatter to the project's skills/ dir.
+ * Falls back to defaults with project-specific constraints on AI failure.
+ */
+import type { PipelineRole } from '../types.js';
+import type { ArtifactManager } from '../artifact-manager.js';
+import type { SkillGenerationContext, SkillsGenerationMarker, TechStack } from './types.js';
+/**
+ * Generate project-specific skill .md files for all active roles.
+ * Skips roles that already have a .md file in the skills directory.
+ * Stores the raw AI response as a skill_generation_log artifact.
+ *
+ * @param context - Skill generation context with project details
+ * @param artifactManager - Optional artifact manager for logging
+ */
+export declare function generateProjectSkills(context: SkillGenerationContext, artifactManager?: ArtifactManager): Promise<void>;
+/**
+ * Check if a skill file should be generated for a role.
+ * Returns false if the role already has a .md file (hand-written or prior run).
+ *
+ * @param skillsDir - Path to the skills directory
+ * @param role - Pipeline role to check
+ * @returns true if the role needs a generated skill file
+ */
+export declare function shouldGenerateSkill(skillsDir: string, role: PipelineRole): boolean;
+/**
+ * Build the AI prompt that requests system prompts for all roles at once.
+ *
+ * @param context - Generation context
+ * @param roles - Roles needing prompts
+ * @param techStack - Inferred tech stack
+ * @returns Formatted prompt string
+ */
+export declare function buildSkillGenPrompt(context: SkillGenerationContext, roles: PipelineRole[], techStack: TechStack): string;
+/**
+ * Parse and validate the AI response as a JSON record of role prompts.
+ * Falls back per-role: missing or invalid entries are excluded.
+ *
+ * @param response - Raw AI response text
+ * @param expectedRoles - Roles we requested prompts for
+ * @returns Validated record of role -> system prompt
+ */
+export declare function parseSkillPrompts(response: string, expectedRoles: PipelineRole[]): Record<string, string>;
+/**
+ * Render a skill definition as a Markdown file with YAML frontmatter.
+ * Format matches what the SkillLoader's parseSkillMarkdown() expects.
+ *
+ * @param role - Pipeline role
+ * @param systemPrompt - The system prompt body
+ * @param constraints - Combined constraint identifiers
+ * @param requiredOutputs - Required output types
+ * @param dependsOn - Upstream role dependencies
+ * @returns Complete markdown string
+ */
+export declare function renderSkillMarkdown(role: PipelineRole, systemPrompt: string, constraints: string[], requiredOutputs: string[], dependsOn: PipelineRole[]): string;
+/**
+ * Write the generation marker file to track what was generated.
+ *
+ * @param skillsDir - Path to the skills directory
+ * @param marker - Marker data to persist
+ */
+export declare function writeGenerationMarker(skillsDir: string, marker: SkillsGenerationMarker): void;
+//# sourceMappingURL=generator.d.ts.map

package/dist/pipeline/skills/generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../../src/pipeline/skills/generator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAG9D,OAAO,KAAK,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAY5F;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,sBAAsB,EAC/B,eAAe,CAAC,EAAE,eAAe,GAChC,OAAO,CAAC,IAAI,CAAC,CAuFf;AAID;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAGlF;AAID;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE,YAAY,EAAE,EACrB,SAAS,EAAE,SAAS,GACnB,MAAM,CAmCR;AAID;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,YAAY,EAAE,GAC5B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAoBxB;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,YAAY,EAClB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EAAE,EACrB,eAAe,EAAE,MAAM,EAAE,EACzB,SAAS,EAAE,YAAY,EAAE,GACxB,MAAM,CAuBR;AAID;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,sBAAsB,GAC7B,IAAI,CAGN"}