@schnick371/devsteps-shared 1.1.0-next.3 → 2.0.0-next.1

package/dist/core/guide-acceptance.js

@@ -0,0 +1,311 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Durable guide acceptance progress records.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { constants, mkdir, open, readdir, readFile, rename, unlink, writeFile, } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { GuideAcceptanceCheckpoint, GuideAcceptanceStart, GuideProgressRecord, } from '../schemas/guide-acceptance.js';
+const REPORT_DIRECTORY = 'reports/acceptance-guides';
+const LOCK_WAIT_MS = 2000;
+const LOCK_RETRY_MS = 25;
+const REPORT_FILE_EXTENSION = '.md';
+const MANIFEST_START = '<!-- acceptance-guide-manifest:start -->';
+const MANIFEST_END = '<!-- acceptance-guide-manifest:end -->';
+export function redactGuideEvidence(value) {
+    return value
+        .replace(/(bearer\s+)[^\s]+/gi, '$1[REDACTED]')
+        .replace(/(token|password|secret|api[_-]?key)\s*[:=]\s*[^\s,;]+/gi, '$1=[REDACTED]');
+}
+export function verifyGuideDigest(content, expectedDigest) {
+    if (!/^sha256:[0-9a-f]{64}$/.test(expectedDigest))
+        return false;
+    return `sha256:${createHash('sha256').update(content, 'utf8').digest('hex')}` === expectedDigest;
+}
+async function loadGuideManifest(devstepsDir, guideId, guideRevision, guideDigest, guideDirectory = join(devstepsDir, '..', 'docs', 'agent-guides')) {
+    const directory = guideDirectory;
+    let files;
+    try {
+        files = await readdir(directory);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`Guide source not found: ${guideId}`);
+        }
+        throw error;
+    }
+    let selected;
+    for (const file of files.filter((entry) => entry.endsWith('.md'))) {
+        const content = await readFile(join(directory, file), 'utf8');
+        const block = content.split(MANIFEST_START)[1]?.split(MANIFEST_END)[0];
+        if (!block)
+            continue;
+        const json = block.replace(/```json|```/g, '').trim();
+        const manifest = JSON.parse(json);
+        if (manifest.guide_id === guideId) {
+            selected = { file, content, manifest };
+            break;
+        }
+    }
+    if (!selected)
+        throw new Error(`Guide source not found: ${guideId}`);
+    const { content, file, manifest } = selected;
+    const sourcePath = join(directory, file);
+    const sourceDigest = `sha256:${createHash('sha256').update(content, 'utf8').digest('hex')}`;
+    if (!verifyGuideDigest(content, guideDigest)) {
+        throw new Error(`Guide source digest mismatch: ${guideId}`);
+    }
+    if (manifest.revision !== guideRevision) {
+        throw new Error(`Guide manifest revision mismatch: ${guideId}`);
+    }
+    return {
+        manifest,
+        sourcePath: relative(join(devstepsDir, '..'), sourcePath),
+        sourceDigest,
+    };
+}
+function reportPath(devstepsDir, sessionId) {
+    const safeSessionId = sessionId.replace(/[^a-f0-9-]/gi, '');
+    return join(devstepsDir, REPORT_DIRECTORY, `${safeSessionId}.json`);
+}
+function lockPath(devstepsDir, sessionId) {
+    return reportPath(devstepsDir, sessionId).replace(/\.json$/, '.lock');
+}
+function readableReportPath(devstepsDir, sessionId) {
+    return reportPath(devstepsDir, sessionId).replace(/\.json$/, REPORT_FILE_EXTENSION);
+}
+export function guideAcceptanceReportPath(devstepsDir, sessionId) {
+    return relative(devstepsDir, readableReportPath(devstepsDir, sessionId));
+}
+function validateArtifactPath(artifactPath) {
+    if (!artifactPath)
+        return;
+    if (artifactPath.startsWith('/') ||
+        artifactPath.startsWith('\\') ||
+        /^[A-Za-z]:[\\/]/.test(artifactPath) ||
+        artifactPath.split(/[\\/]/).includes('..') ||
+        !artifactPath.startsWith('reports/acceptance-guides/')) {
+        throw new Error(`Guide artifact path is outside the allowlist: ${artifactPath}`);
+    }
+}
+async function acquireLock(path) {
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            const handle = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL);
+            await handle.close();
+            return async () => unlink(path).catch(() => undefined);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            if (Date.now() >= deadline)
+                throw new Error('Guide acceptance record is locked. Retry later.');
+            await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_MS));
+        }
+    }
+}
+async function writeRecord(devstepsDir, record) {
+    const path = reportPath(devstepsDir, record.session_id);
+    const temporaryPath = `${path}.tmp`;
+    await mkdir(join(devstepsDir, REPORT_DIRECTORY), { recursive: true });
+    await writeFile(temporaryPath, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+    await rename(temporaryPath, path);
+    const report = [
+        '# Guide Acceptance Progress',
+        '',
+        `- Session: ${record.session_id}`,
+        `- Guide: ${record.guide_id} ${record.guide_revision}`,
+        `- Mode: ${record.mode}`,
+        `- Status: ${record.status}`,
+        `- Current step: ${record.current_step ?? 'none'}`,
+        '',
+        '## Evidence',
+        '',
+        ...record.evidence.map((evidence) => `- ${evidence.checkpoint_id}: ${evidence.status} (attempt ${evidence.attempt})${evidence.summary ? ` - ${evidence.summary}` : ''}`),
+        '',
+    ].join('\n');
+    await writeFile(readableReportPath(devstepsDir, record.session_id), report, 'utf8');
+}
+async function readRecord(devstepsDir, sessionId) {
+    try {
+        const parsed = JSON.parse(await readFile(reportPath(devstepsDir, sessionId), 'utf8'));
+        const result = GuideProgressRecord.safeParse(parsed);
+        return result.success ? result.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function startGuideAcceptance(devstepsDir, input, guideDirectory) {
+    const start = GuideAcceptanceStart.parse(input);
+    const loaded = await loadGuideManifest(devstepsDir, start.guide_id, start.guide_revision, start.guide_digest, guideDirectory);
+    const checkpointOrder = loaded.manifest.checkpoints.map((checkpoint) => checkpoint.step_id);
+    if (start.fixture_id !== undefined &&
+        loaded.manifest.fixture?.id !== undefined &&
+        start.fixture_id !== loaded.manifest.fixture.id) {
+        throw new Error(`Guide fixture mismatch: ${start.fixture_id}`);
+    }
+    const maxAttempts = Math.max(start.max_attempts, ...loaded.manifest.checkpoints.map((checkpoint) => checkpoint.max_attempts ?? 1));
+    if (start.mode === 'human-guided-guide' && !start.human_checkpoint) {
+        throw new Error('Human-guided guide acceptance requires a human checkpoint');
+    }
+    const now = new Date().toISOString();
+    const record = GuideProgressRecord.parse({
+        schema_version: '1.0',
+        session_id: randomUUID(),
+        ...start,
+        human_guide_digest: loaded.manifest.human_guide.digest,
+        source_path: loaded.sourcePath,
+        source_digest: loaded.sourceDigest,
+        fixture_id: start.fixture_id ?? loaded.manifest.fixture?.id,
+        record_version: 1,
+        status: 'open',
+        started_at: now,
+        updated_at: now,
+        completed_checkpoints: [],
+        evidence: [],
+        checkpoint_order: checkpointOrder,
+        max_attempts: maxAttempts,
+        run_marker: start.run_marker,
+        current_step: checkpointOrder[0],
+        presented_checkpoint_id: start.mode === 'human-guided-guide' ? checkpointOrder[0] : undefined,
+    });
+    await writeRecord(devstepsDir, record);
+    return record;
+}
+export async function getGuideAcceptance(devstepsDir, sessionId) {
+    if (!/^[0-9a-f-]{36}$/i.test(sessionId))
+        return null;
+    return readRecord(devstepsDir, sessionId);
+}
+export async function resumeGuideAcceptance(devstepsDir, sessionId, input, guideDirectory) {
+    const current = await getGuideAcceptance(devstepsDir, sessionId);
+    if (!current)
+        throw new Error(`Guide acceptance session not found: ${sessionId}`);
+    const loaded = await loadGuideManifest(devstepsDir, current.guide_id, current.guide_revision, input.guide_digest, guideDirectory);
+    if (current.source_path !== loaded.sourcePath || current.guide_digest !== input.guide_digest) {
+        throw new Error(`Guide acceptance resume drift detected: ${sessionId}`);
+    }
+    if (input.fixture_id !== undefined && input.fixture_id !== current.fixture_id) {
+        throw new Error(`Guide acceptance resume fixture mismatch: ${sessionId}`);
+    }
+    if (input.run_marker !== undefined && input.run_marker !== current.run_marker) {
+        throw new Error(`Guide acceptance resume marker mismatch: ${sessionId}`);
+    }
+    if (input.current_step !== undefined && input.current_step !== current.current_step) {
+        throw new Error(`Guide acceptance resume step mismatch: ${sessionId}`);
+    }
+    return current;
+}
+export async function recordGuideCheckpoint(devstepsDir, sessionId, input) {
+    const checkpoint = GuideAcceptanceCheckpoint.parse({
+        ...input,
+        summary: redactGuideEvidence(input.summary ?? ''),
+    });
+    validateArtifactPath(checkpoint.artifact_path);
+    const release = await acquireLock(lockPath(devstepsDir, sessionId));
+    try {
+        const current = await readRecord(devstepsDir, sessionId);
+        if (!current)
+            throw new Error(`Guide acceptance session not found: ${sessionId}`);
+        if (current.status === 'completed' || current.status === 'aborted') {
+            throw new Error(`Guide acceptance session is already ${current.status}`);
+        }
+        if (checkpoint.expected_record_version !== undefined &&
+            checkpoint.expected_record_version !== current.record_version) {
+            throw new Error(`Guide acceptance record version is stale: ${sessionId}`);
+        }
+        if (current.checkpoint_order.length > 0 &&
+            !current.checkpoint_order.includes(checkpoint.checkpoint_id)) {
+            throw new Error(`Checkpoint is not declared by the guide: ${checkpoint.checkpoint_id}`);
+        }
+        if (current.mode === 'human-guided-guide') {
+            if (checkpoint.checkpoint_id !== current.presented_checkpoint_id) {
+                throw new Error('Human-guided acceptance must record the presented checkpoint');
+            }
+            if (checkpoint.human_answer === 'negative' && !checkpoint.cleanup_confirmed) {
+                throw new Error('A negative human answer requires confirmed checkpoint cleanup');
+            }
+            if (checkpoint.human_answer === 'negative' && checkpoint.status !== 'failed') {
+                throw new Error('A negative human answer must fail and repeat the checkpoint');
+            }
+        }
+        const previous = current.evidence.filter((evidence) => evidence.checkpoint_id === checkpoint.checkpoint_id);
+        if (previous.some((evidence) => evidence.status === 'passed' && checkpoint.status === 'failed')) {
+            throw new Error(`Checkpoint has contradictory evidence: ${checkpoint.checkpoint_id}`);
+        }
+        const nextCheckpoint = current.checkpoint_order.find((checkpointId) => !current.completed_checkpoints.includes(checkpointId));
+        if (checkpoint.status === 'passed' &&
+            nextCheckpoint &&
+            checkpoint.checkpoint_id !== nextCheckpoint) {
+            throw new Error(`Checkpoint is gated by ${nextCheckpoint}`);
+        }
+        const now = new Date().toISOString();
+        const completed = new Set(current.completed_checkpoints);
+        if (checkpoint.status === 'passed')
+            completed.add(checkpoint.checkpoint_id);
+        const terminalFailure = checkpoint.status === 'failed' &&
+            (checkpoint.failure_class !== 'transient' || checkpoint.attempt >= current.max_attempts);
+        const next = GuideProgressRecord.parse({
+            ...current,
+            record_version: current.record_version + 1,
+            status: terminalFailure ? 'failed' : 'in-progress',
+            updated_at: now,
+            completed_checkpoints: [...completed],
+            current_step: current.checkpoint_order.find((checkpointId) => !completed.has(checkpointId)),
+            presented_checkpoint_id: current.mode === 'human-guided-guide'
+                ? checkpoint.status === 'passed'
+                    ? current.checkpoint_order.find((checkpointId) => !completed.has(checkpointId))
+                    : current.presented_checkpoint_id
+                : undefined,
+            last_human_answer: checkpoint.human_answer,
+            evidence: [
+                ...current.evidence,
+                {
+                    ...checkpoint,
+                    recorded_at: now,
+                },
+            ],
+            failure_reason: terminalFailure ? checkpoint.summary : undefined,
+        });
+        await writeRecord(devstepsDir, next);
+        return next;
+    }
+    finally {
+        await release();
+    }
+}
+export async function finalizeGuideAcceptance(devstepsDir, sessionId, status, reason, cleanupConfirmed = false, residualStateVerified = false) {
+    const release = await acquireLock(lockPath(devstepsDir, sessionId));
+    try {
+        const current = await readRecord(devstepsDir, sessionId);
+        if (!current)
+            throw new Error(`Guide acceptance session not found: ${sessionId}`);
+        if (status === 'completed') {
+            const missing = current.checkpoint_order.filter((checkpointId) => !current.completed_checkpoints.includes(checkpointId));
+            if (missing.length > 0) {
+                throw new Error(`Cannot complete guide acceptance; checkpoints remain: ${missing.join(', ')}`);
+            }
+            if (!cleanupConfirmed || !residualStateVerified) {
+                throw new Error('Cannot complete guide acceptance; cleanup and residual-state verification are required');
+            }
+        }
+        const next = GuideProgressRecord.parse({
+            ...current,
+            status,
+            updated_at: new Date().toISOString(),
+            failure_reason: status === 'completed' ? undefined : reason,
+            cleanup_confirmed: cleanupConfirmed,
+            residual_state_verified: residualStateVerified,
+        });
+        await writeRecord(devstepsDir, next);
+        return next;
+    }
+    finally {
+        await release();
+    }
+}
+//# sourceMappingURL=guide-acceptance.js.map

package/dist/core/guide-acceptance.js.map

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

package/dist/core/guide-step-list.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The generated step list in a guide's description (BUG-213). An item with a v2
+ * process_definition carries its steps in its master document between two markers, rewritten by
+ * every add and update that writes the description or the definition, so the document never
+ * holds a step summary that drifted from the definition. Each step's full instruction stays in
+ * the definition and the guide view.
+ */
+import { WorkflowDefinitionV2 } from '../schemas/workflow-definition-v2.js';
+/** The marked section listing the definition's steps in authored order, numbered as a run starts. */
+export declare function renderGuideStepList(definition: WorkflowDefinitionV2): string;
+/**
+ * The description with the step list of a v2 definition: replaced where its markers stand,
+ * otherwise appended. Without a v2 definition the description stays as it is.
+ */
+export declare function withGuideStepList(description: string, definition: unknown): string;
+/**
+ * The description with its step list folded to one line, for an answer that must stay bounded
+ * however many steps the guide has (BUG-161). The markers stay, so a description sent back
+ * through update gets the full list again.
+ */
+export declare function foldGuideStepList(description: string): string;
+//# sourceMappingURL=guide-step-list.d.ts.map

package/dist/core/guide-step-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide-step-list.d.ts","sourceRoot":"","sources":["../../src/core/guide-step-list.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AA0B5E,qGAAqG;AACrG,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,oBAAoB,GAAG,MAAM,CA0B5E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,GAAG,MAAM,CAOlF;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAW7D"}

package/dist/core/guide-step-list.js

@@ -0,0 +1,91 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The generated step list in a guide's description (BUG-213). An item with a v2
+ * process_definition carries its steps in its master document between two markers, rewritten by
+ * every add and update that writes the description or the definition, so the document never
+ * holds a step summary that drifted from the definition. Each step's full instruction stays in
+ * the definition and the guide view.
+ */
+import { defaultAssignee, workflowStepChannel } from '../runtime/workflow-v2-parties.js';
+import { WorkflowDefinitionV2 } from '../schemas/workflow-definition-v2.js';
+const START = '<!-- devsteps:guide-steps -->';
+const END = '<!-- /devsteps:guide-steps -->';
+const SECTION = /<!-- devsteps:guide-steps -->[\s\S]*?<!-- \/devsteps:guide-steps -->/;
+const INTRO = "Generated from the guide's definition whenever it or this description is written. The party " +
+    "is the step's `who`, or for a step without one the party a together run gives it. The guide " +
+    'view shows each step in full, and every run keeps its events and evidence in its folder under ' +
+    '`.devsteps/runs/`.';
+/** One table cell: the first line of the text, pipes escaped, at most 120 characters. */
+function cell(text) {
+    const line = (text.split('\n').find((part) => part.trim() !== '') ?? '')
+        .trim()
+        .replace(/\|/g, '\\|');
+    return line.length > 120 ? `${line.slice(0, 119)}…` : line;
+}
+function party(step) {
+    if (step.kind === 'predicate')
+        return 'runtime';
+    return defaultAssignee('together', workflowStepChannel(step), step.who);
+}
+/** The marked section listing the definition's steps in authored order, numbered as a run starts. */
+export function renderGuideStepList(definition) {
+    const places = new Map((definition.sections ?? []).map((section) => [section.id, section.title]));
+    const withPlace = definition.steps.some((step) => step.section !== undefined);
+    const header = ['No.', 'Step', 'Party', ...(withPlace ? ['Where'] : [])];
+    const rows = definition.steps.map((step, index) => {
+        const title = step.title ?? step.instruction ?? step.human?.instruction ?? step.id;
+        const place = step.section === undefined ? '' : (places.get(step.section) ?? step.section);
+        const cells = [
+            String(index + 1),
+            cell(title),
+            party(step),
+            ...(withPlace ? [cell(place)] : []),
+        ];
+        return `| ${cells.join(' | ')} |`;
+    });
+    return [
+        START,
+        '## Guide steps',
+        '',
+        INTRO,
+        '',
+        `| ${header.join(' | ')} |`,
+        `| ${header.map(() => '---').join(' | ')} |`,
+        ...rows,
+        END,
+    ].join('\n');
+}
+/**
+ * The description with the step list of a v2 definition: replaced where its markers stand,
+ * otherwise appended. Without a v2 definition the description stays as it is.
+ */
+export function withGuideStepList(description, definition) {
+    const parsed = WorkflowDefinitionV2.safeParse(definition);
+    if (!parsed.success)
+        return description;
+    const list = renderGuideStepList(parsed.data);
+    if (SECTION.test(description))
+        return description.replace(SECTION, () => list);
+    const body = description.trimEnd();
+    return body === '' ? `${list}\n` : `${body}\n\n${list}\n`;
+}
+/**
+ * The description with its step list folded to one line, for an answer that must stay bounded
+ * however many steps the guide has (BUG-161). The markers stay, so a description sent back
+ * through update gets the full list again.
+ */
+export function foldGuideStepList(description) {
+    return description.replace(SECTION, (list) => {
+        const steps = list.split('\n').filter((line) => /^\| \d+ \|/.test(line)).length;
+        return [
+            START,
+            '## Guide steps',
+            '',
+            `${steps} steps, generated from the definition; get with fields ["description"] returns the list.`,
+            END,
+        ].join('\n');
+    });
+}
+//# sourceMappingURL=guide-step-list.js.map

package/dist/core/guide-step-list.js.map

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

package/dist/core/heuristic-classify.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Diataxis heuristic classifier — scoring vector approach (ADR-001)
+ * Pure function: no filesystem access, operates on text excerpts.
+ */
+/** Diataxis document types + extensions for DevSteps-specific content */
+export type DiataxisType = 'tutorial' | 'how-to' | 'reference' | 'explanation' | 'architecture' | 'research';
+/** Score vector: one [0.0, 1.0] score per type */
+export type ScoreVector = Record<DiataxisType, number>;
+/** Classification result for a single document */
+export interface ClassificationResult {
+    scores: ScoreVector;
+    winner: DiataxisType;
+    confidence: number;
+    mixed: boolean;
+    secondType?: DiataxisType;
+}
+/** Default threshold for mixed-type detection */
+export declare const MIXED_THRESHOLD = 0.4;
+/** Minimum H2/H3 subheading ratio to signal explanation type */
+export declare const SUBHEADING_RATIO_THRESHOLD = 0.08;
+/** Minimum table line ratio to signal reference type */
+export declare const TABLE_RATIO_THRESHOLD = 0.25;
+/** All Diataxis types */
+export declare const DIATAXIS_TYPES: DiataxisType[];
+/** Optional Scrum context for classification enrichment (STORY-293) */
+export interface HeuristicContext {
+    epic_title?: string;
+    story_title?: string;
+    epic_tags?: string[];
+}
+/**
+ * 9-pattern heuristic classifier from SPIKE-043 + structural heuristics (TASK-549)
+ * + optional Scrum-context boost (STORY-293).
+ * Returns a score vector (ADR-001: scoring approach, not binary).
+ *
+ * @param excerpt - First ~100 lines of the document
+ * @param filepath - Optional file path for path-based heuristics
+ * @param context - Optional Scrum context (Epic/Story title + tags) for bilingual boost
+ */
+export declare function heuristicClassify(excerpt: string, filepath?: string, context?: HeuristicContext): ClassificationResult;
+//# sourceMappingURL=heuristic-classify.d.ts.map

package/dist/core/heuristic-classify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heuristic-classify.d.ts","sourceRoot":"","sources":["../../src/core/heuristic-classify.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,yEAAyE;AACzE,MAAM,MAAM,YAAY,GACpB,UAAU,GACV,QAAQ,GACR,WAAW,GACX,aAAa,GACb,cAAc,GACd,UAAU,CAAC;AAEf,kDAAkD;AAClD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;AAEvD,kDAAkD;AAClD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,YAAY,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,CAAC,EAAE,YAAY,CAAC;CAC3B;AAED,iDAAiD;AACjD,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC,gEAAgE;AAChE,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,wDAAwD;AACxD,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAK1C,yBAAyB;AACzB,eAAO,MAAM,cAAc,EAAE,YAAY,EAOxC,CAAC;AAMF,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,gBAAgB,GACzB,oBAAoB,CA4HtB"}