agent-bober 0.12.0 → 0.17.0

package/dist/incident/rollback.js

@@ -0,0 +1,328 @@
+/**
+ * Rollback awareness helpers (Sprint 21).
+ *
+ * Reads changelog.jsonl for an incident, identifies ChangeEntries that are
+ * effective-status 'executed' (not yet rolled back), and provides:
+ *
+ *   planRollback  — returns a RollbackPlan with steps in reverse execution order.
+ *   executeRollback — runs each step via the Sprint 20 risky-action gate (per-step).
+ *   presentPlan   — renders the plan to a human-readable string for CLI output.
+ *
+ * Escalation design note (Sprint 21):
+ *   True checkpoint-based escalation is deferred to Sprint 24 (full /bober-incident
+ *   flow). Escalation here consists of:
+ *     1. A 'rollback_halted' timeline event with remaining step ids.
+ *     2. A stderr warning via writeWarn.
+ *     3. result.escalated=true + result.remaining=[...] returned to the caller.
+ *   Sprint 24 can wrap this return value in a real checkpoint if needed.
+ *
+ * JSONL semantics: changelog.jsonl is append-only; "latest line per id wins".
+ * When a change is executed, Sprint 20 writes two lines (pending, executed).
+ * After rollback, Sprint 21 appends a third line (rolled-back). Effective status
+ * is determined by the LAST line in file-order with a given id.
+ *
+ * Reverse execution order: sort by the FIRST entry's executedAt (when the action
+ * originally ran), then reverse. File order guarantees write monotonicity.
+ *
+ * Sprint 21 — src/incident/rollback.ts
+ */
+import { open, mkdir, readFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { join } from "node:path";
+import { appendChange, appendTimeline } from "./timeline.js";
+import { executeAction } from "../orchestrator/deploy/execute.js";
+// ── Private helpers ────────────────────────────────────────────────────────────
+/**
+ * Append a single newline-terminated JSON line to filePath.
+ * Creates the directory if absent. Guarantees mode 0600.
+ * Mirrors appendOneLine from timeline.ts — inlined to avoid touching Sprint 19 code.
+ */
+async function appendOneLine(filePath, record) {
+    const dir = join(filePath, "..");
+    await mkdir(dir, { recursive: true });
+    const line = JSON.stringify(record) + "\n";
+    const flags = constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT;
+    const fh = await open(filePath, flags, 0o600);
+    try {
+        await fh.chmod(0o600);
+        await fh.write(line);
+    }
+    finally {
+        await fh.close();
+    }
+}
+/**
+ * Read all ChangeEntry lines from changelog.jsonl.
+ * Returns all raw lines (not grouped) in file order.
+ * Returns [] if the file does not exist.
+ */
+async function readChangelog(projectRoot, incidentId) {
+    const changelogPath = join(projectRoot, ".bober", "incidents", incidentId, "changelog.jsonl");
+    try {
+        const raw = await readFile(changelogPath, "utf-8");
+        return raw
+            .split("\n")
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Append a RollbackExecutionEntry to rollback-execution.jsonl.
+ * The file is created lazily on first write (Sprint 19 createIncident does NOT
+ * pre-create it — only 5 jsonl files are initialized).
+ */
+async function appendRollbackExecution(projectRoot, incidentId, entry) {
+    const filePath = join(projectRoot, ".bober", "incidents", incidentId, "rollback-execution.jsonl");
+    await appendOneLine(filePath, entry);
+}
+// ── planRollback ───────────────────────────────────────────────────────────────
+/**
+ * Build a RollbackPlan from a changelog.
+ *
+ * Effective-status semantics (latest-line-wins):
+ *   For each unique `id`, group all entries; the LAST entry in file order
+ *   determines the effective status. Only `executed` entries are rollbackable.
+ *
+ * Reverse execution order:
+ *   Steps are sorted ascending by the FIRST entry's executedAt (the original
+ *   execution time), then reversed. This means the most recent action is
+ *   rolled back first.
+ *
+ * --since semantics (changeId-based, strict-after):
+ *   Only changes whose FIRST entry's executedAt is strictly greater than the
+ *   --since changeId's first entry's executedAt are included.
+ *
+ * @param projectRoot  Absolute path to the project root.
+ * @param incidentId   Incident to plan a rollback for.
+ * @param opts         Optional PlanRollbackOpts.
+ * @throws Error if opts.since references a non-existent changeId.
+ */
+export async function planRollback(projectRoot, incidentId, opts = {}) {
+    const entries = await readChangelog(projectRoot, incidentId);
+    const warnings = [];
+    // Group by id; track first entry (for original time + inverse) and last entry (for effective status).
+    const byId = new Map();
+    for (const e of entries) {
+        const existing = byId.get(e.id);
+        if (existing) {
+            existing.last = e;
+        }
+        else {
+            byId.set(e.id, { first: e, last: e });
+        }
+    }
+    let unrollbackable = 0;
+    const candidates = [];
+    for (const group of byId.values()) {
+        // Defensive: missing or empty inverse.description → warn and skip.
+        // Sprint 19 schema requires inverse, but we handle malformed/legacy data.
+        if (!group.first.inverse?.description ||
+            group.first.inverse.description.trim() === "") {
+            unrollbackable += 1;
+            warnings.push(`Change "${group.first.description}" (${group.first.id}) has no recorded inverse; skipped.`);
+            continue;
+        }
+        // Effective status filter: only 'executed' entries are rollbackable.
+        // 'rolled-back', 'rolled-back-failed', 'pending', 'failed' are excluded.
+        if (group.last.status === "executed") {
+            candidates.push(group);
+        }
+    }
+    // --since filter (changeId-based, strict-after semantics).
+    let filtered = candidates;
+    if (opts.since !== undefined) {
+        const pivot = byId.get(opts.since);
+        if (!pivot) {
+            throw new Error(`--since changeId "${opts.since}" not found in changelog`);
+        }
+        const pivotTime = pivot.first.executedAt;
+        filtered = candidates.filter((c) => c.first.executedAt > pivotTime);
+        warnings.push(`--since filter applied: showing ${filtered.length} of ${candidates.length} rollbackable changes.`);
+    }
+    // Sort ascending by original executedAt, then reverse to get newest-first.
+    filtered.sort((a, b) => (a.first.executedAt < b.first.executedAt ? -1 : 1));
+    filtered.reverse();
+    const steps = filtered.map(({ first }) => ({
+        originalChangeId: first.id,
+        originalDescription: first.description,
+        inverseDescription: first.inverse.description,
+        ...(first.inverse.command !== undefined ? { inverseCommand: first.inverse.command } : {}),
+        originalExecutedAt: first.executedAt,
+    }));
+    return {
+        incidentId,
+        totalChanges: byId.size,
+        rollbackableChanges: steps.length,
+        unrollbackableChanges: unrollbackable,
+        steps,
+        warnings,
+    };
+}
+// ── presentPlan ────────────────────────────────────────────────────────────────
+/**
+ * Render a RollbackPlan to a human-readable string for CLI output.
+ *
+ * Always includes:
+ * - Header with incident ID
+ * - Change counts (total, rollbackable, unrollbackable)
+ * - Numbered steps in reverse execution order
+ * - Warnings section (if any)
+ */
+export function presentPlan(plan) {
+    const lines = [];
+    lines.push(`Rollback plan for incident ${plan.incidentId}:`);
+    lines.push("");
+    lines.push(`Total changes: ${plan.totalChanges}`);
+    lines.push(`Rollbackable: ${plan.rollbackableChanges}`);
+    lines.push(`Unrollbackable: ${plan.unrollbackableChanges}${plan.unrollbackableChanges > 0 ? " (see warnings)" : ""}`);
+    lines.push("");
+    if (plan.steps.length === 0) {
+        lines.push("(no rollbackable steps)");
+    }
+    else {
+        lines.push("Proposed steps (in reverse execution order):");
+        plan.steps.forEach((s, idx) => {
+            lines.push(`  ${idx + 1}. Undo "${s.originalDescription}"`);
+            lines.push(`     → ${s.inverseDescription}`);
+            if (s.inverseCommand)
+                lines.push(`     $ ${s.inverseCommand}`);
+        });
+    }
+    if (plan.warnings.length > 0) {
+        lines.push("");
+        lines.push("Warnings:");
+        for (const w of plan.warnings)
+            lines.push(`  - ${w}`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+// ── executeRollback ────────────────────────────────────────────────────────────
+/**
+ * Execute a RollbackPlan step by step.
+ *
+ * Each step is a risky action that MUST pass through the Sprint 20 gate
+ * individually. This means N rollback steps → N gate invocations.
+ *
+ * On success of each step:
+ *   - Appends a ChangeEntry with id=originalChangeId, status='rolled-back'.
+ *   - Appends a RollbackExecutionEntry with status='rolled-back'.
+ *
+ * On failure of any step:
+ *   - Appends a ChangeEntry with id=originalChangeId, status='rolled-back-failed'.
+ *   - Appends a RollbackExecutionEntry with status='rolled-back-failed'.
+ *   - Halts the sequence (remaining steps are NOT attempted).
+ *   - Emits a 'rollback_halted' timeline event.
+ *   - Returns result.escalated=true with result.remaining=[unrolled steps].
+ *
+ * @param projectRoot  Absolute path to the project root.
+ * @param incidentId   Incident to execute the rollback for.
+ * @param plan         The plan produced by planRollback.
+ * @param opts         Optional injections (config, executor, writeWarn, now).
+ */
+export async function executeRollback(projectRoot, incidentId, plan, opts = {}) {
+    const now = opts.now ?? (() => new Date());
+    const writeWarn = opts.writeWarn ?? ((m) => process.stderr.write(m));
+    await appendTimeline(projectRoot, incidentId, {
+        timestamp: now().toISOString(),
+        eventKind: "rollback_started",
+        source: "deployer",
+        summary: `Rollback started: ${plan.steps.length} step(s) planned`,
+    });
+    let succeeded = 0;
+    for (let i = 0; i < plan.steps.length; i++) {
+        const step = plan.steps[i];
+        // Construct the ProposedAction for this rollback step.
+        // The rollback step is always classified as risky — undoing a change is itself
+        // a destructive operation that requires the same gate discipline.
+        const proposed = {
+            id: `rollback-${step.originalChangeId}`,
+            description: step.inverseDescription,
+            classification: "risky",
+            reasoning: `Rolling back change ${step.originalChangeId}: ${step.originalDescription}`,
+            ...(step.inverseCommand !== undefined ? { command: step.inverseCommand } : {}),
+            inverse: {
+                // The inverse-of-inverse is to re-apply the original change.
+                // We don't have the original command stored in ChangeEntry — see briefing §9.
+                description: `Re-apply original change: ${step.originalDescription}`,
+            },
+        };
+        const stepStart = Date.now();
+        const result = await executeAction(proposed, incidentId, projectRoot, opts.config, { executor: opts.executor, writeWarn, now });
+        const durationMs = Date.now() - stepStart;
+        if (result.status === "executed") {
+            // Mark the ORIGINAL ChangeEntry as rolled-back (use original id).
+            await appendChange(projectRoot, incidentId, {
+                id: step.originalChangeId,
+                type: "rollback",
+                executedAt: now().toISOString(),
+                description: `Rolled back: ${step.originalDescription}`,
+                inverse: { description: `Re-apply: ${step.originalDescription}` },
+                status: "rolled-back",
+            });
+            await appendRollbackExecution(projectRoot, incidentId, {
+                timestamp: now().toISOString(),
+                originalChangeId: step.originalChangeId,
+                inverseDescription: step.inverseDescription,
+                status: "rolled-back",
+                durationMs,
+            });
+            succeeded += 1;
+        }
+        else {
+            // Failure (or aborted). Halt the sequence.
+            const errMsg = result.error ??
+                `rollback step aborted: ${result.reason ?? "unknown"}`;
+            await appendChange(projectRoot, incidentId, {
+                id: step.originalChangeId,
+                type: "rollback-failed",
+                executedAt: now().toISOString(),
+                description: `Rollback FAILED for: ${step.originalDescription}`,
+                inverse: { description: `Re-apply: ${step.originalDescription}` },
+                status: "rolled-back-failed",
+            });
+            await appendRollbackExecution(projectRoot, incidentId, {
+                timestamp: now().toISOString(),
+                originalChangeId: step.originalChangeId,
+                inverseDescription: step.inverseDescription,
+                status: "rolled-back-failed",
+                durationMs,
+                errorMessage: errMsg,
+            });
+            const remaining = plan.steps.slice(i + 1);
+            await appendTimeline(projectRoot, incidentId, {
+                timestamp: now().toISOString(),
+                eventKind: "rollback_halted",
+                source: "deployer",
+                summary: `Rollback HALTED at step ${i + 1}/${plan.steps.length}: ${errMsg}. ` +
+                    `Remaining: ${remaining.map((s) => s.originalChangeId).join(", ")}`,
+            });
+            writeWarn(`[bober rollback] HALTED — step ${i + 1} (${step.originalChangeId}) failed: ${errMsg}. ` +
+                `${remaining.length} step(s) NOT rolled back: ${remaining.map((s) => s.originalChangeId).join(", ")}\n`);
+            return {
+                attempted: i + 1,
+                succeeded,
+                failed: 1,
+                remaining,
+                escalated: true,
+            };
+        }
+    }
+    await appendTimeline(projectRoot, incidentId, {
+        timestamp: now().toISOString(),
+        eventKind: "rollback_completed",
+        source: "deployer",
+        summary: `Rollback completed: ${succeeded}/${plan.steps.length} step(s) succeeded`,
+    });
+    return {
+        attempted: plan.steps.length,
+        succeeded,
+        failed: 0,
+        remaining: [],
+        escalated: false,
+    };
+}
+//# sourceMappingURL=rollback.js.map

package/dist/incident/rollback.js.map

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

package/dist/incident/timeline.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Incident timeline append helpers (Sprint 19).
+ *
+ * Every helper that writes a domain artifact (observations.jsonl,
+ * actions.jsonl, changelog.jsonl, runbook-execution.jsonl) ALSO appends
+ * a corresponding event to timeline.jsonl in the same mutex tick. This
+ * makes "show me what happened in chronological order" a single file read.
+ *
+ * Append atomicity: fs.open with O_WRONLY|O_APPEND|O_CREAT plus explicit
+ * fh.chmod(0o600) after open — mirrors the audit.ts pattern from Sprint 13.
+ * fs.appendFile is NOT used because it does not reliably honor the mode
+ * argument across all Node versions (see audit.ts header comment).
+ *
+ * POSIX O_APPEND atomicity: single-line records are well under PIPE_BUF
+ * (4096 bytes), so cross-process appends are safe in practice.
+ *
+ * Concurrent appends to the same incident are serialized via a per-incidentId
+ * Promise-chain mutex. Unrelated incidents proceed in parallel.
+ *
+ * setIncidentStatus uses atomic temp-file + rename to avoid a torn write
+ * if the process crashes mid-update.
+ *
+ * Sprint 19 — src/incident/timeline.ts
+ */
+import type { BoberConfig } from "../config/schema.js";
+import { type IncidentId, type IncidentMetadata, type IncidentStatus, type IncidentSummary, type TimelineEvent, type ObservationEntry, type ActionEntry, type ChangeEntry, type RunbookExecutionEntry } from "./types.js";
+import type { VerifyResult } from "./resolution-verify.js";
+/**
+ * Derive a short kebab-case slug from a symptom string.
+ *
+ * Rules:
+ * 1. Lowercase the input.
+ * 2. Split on whitespace; take the first 3 non-empty tokens.
+ * 3. For each token, strip all characters outside [a-z0-9] (unicode is stripped).
+ * 4. Join surviving tokens with '-'.
+ * 5. Strip leading/trailing hyphens.
+ * 6. Truncate to 30 characters (hard limit).
+ * 7. If the result is empty (empty input / all-punctuation / unicode-only), return 'untitled'.
+ *
+ * Exported for unit testing.
+ */
+export declare function deriveSlug(symptom: string): string;
+/**
+ * Create a new incident artifact directory with all required files.
+ *
+ * Layout created:
+ * ```
+ * .bober/incidents/<incidentId>/
+ *   incident.json           — metadata (JSON)
+ *   timeline.jsonl          — chronological master event log (JSONL, empty)
+ *   observations.jsonl      — verified facts (JSONL, empty)
+ *   actions.jsonl           — actions taken/proposed (JSONL, empty)
+ *   changelog.jsonl         — deploys/config changes (JSONL, empty)
+ *   runbook-execution.jsonl — runbook step results (JSONL, empty)
+ *   hypotheses.md           — current hypotheses (Markdown, empty)
+ *   diagnoses/              — diagnosis JSON files from bober-diagnoser
+ * ```
+ *
+ * @param symptom  Human-readable description of the incident trigger.
+ * @param projectRoot  Absolute path to the project root (caller resolves this).
+ * @returns The new incident ID, e.g. 'inc-20260524-500-errors-on'.
+ */
+export declare function createIncident(symptom: string, projectRoot: string): Promise<IncidentId>;
+/**
+ * Append a TimelineEvent to timeline.jsonl.
+ *
+ * This is the only append helper that writes ONLY to timeline.jsonl.
+ * All other append helpers call this implicitly via the double-write pattern.
+ */
+export declare function appendTimeline(projectRoot: string, incidentId: IncidentId, event: TimelineEvent): Promise<void>;
+/**
+ * Append an ObservationEntry to observations.jsonl AND emit a timeline event.
+ *
+ * Both writes happen inside the same mutex tick so they are ordered
+ * deterministically relative to other concurrent appends on this incident.
+ */
+export declare function appendObservation(projectRoot: string, incidentId: IncidentId, entry: ObservationEntry): Promise<void>;
+/**
+ * Append an ActionEntry to actions.jsonl AND emit a timeline event.
+ */
+export declare function appendAction(projectRoot: string, incidentId: IncidentId, entry: ActionEntry): Promise<void>;
+/**
+ * Append a ChangeEntry to changelog.jsonl AND emit a timeline event.
+ *
+ * Throws a ZodError if `entry.inverse` is missing — the field is REQUIRED
+ * at the schema level so Sprint 21 rollback awareness can always find an
+ * inverse for every executed change.
+ *
+ * The zod validation runs BEFORE the mutex is entered so no file is
+ * touched if validation fails.
+ */
+export declare function appendChange(projectRoot: string, incidentId: IncidentId, entry: ChangeEntry): Promise<void>;
+/**
+ * Append a RunbookExecutionEntry to runbook-execution.jsonl AND emit a
+ * timeline event.
+ */
+export declare function appendRunbookExecution(projectRoot: string, incidentId: IncidentId, entry: RunbookExecutionEntry): Promise<void>;
+/** Options for the resolution gate (Sprint 22) + postmortem trigger (Sprint 23) + telemetry (Sprint 28). */
+export interface SetStatusOpts {
+    /** REQUIRED when status='resolved' (unless overrideToken given). Must have verified=true. */
+    verifyResult?: VerifyResult;
+    /** REQUIRED when status='resolved' AND no verifyResult. Format: 'SKIP_METRIC_VERIFY: <reason>'. Empty reason rejects. */
+    overrideToken?: string;
+    /** When true (and status === 'resolved'), trigger async postmortem generation after the
+     *  status write. Only the explicit literal false disables auto-gen. Default: true.
+     *  Sprint 23. */
+    autoPostmortem?: boolean;
+    /** Test seam: if provided, the function calls back with the Promise that resolves when
+     *  postmortem synthesis completes. Production callers leave this undefined and rely on
+     *  fire-and-forget behavior. Sprint 23. */
+    onPostmortemPromise?: (p: Promise<void>) => void;
+    /** Sprint 28 — optional config for telemetry. When provided and telemetry.enabled=true,
+     *  an 'incident-resolved' event is emitted (fire-and-forget) after the status write.
+     *  Callers that don't have config available leave this undefined; no telemetry fires. */
+    config?: BoberConfig;
+    /** Sprint 28 — absolute project root for telemetry file path resolution.
+     *  Required when config is provided for telemetry emit. */
+    telemetryProjectRoot?: string;
+}
+/**
+ * Update the status field in incident.json atomically.
+ *
+ * If status is 'resolved', sets resolvedAt to now (ISO-8601) automatically.
+ * Any additional fields in `extras` are merged in.
+ *
+ * Sprint 22 resolution gate: when transitioning to 'resolved', one of the
+ * following MUST be provided via opts:
+ *   1. opts.verifyResult with verified=true — metric verification passed.
+ *   2. opts.overrideToken matching 'SKIP_METRIC_VERIFY: <reason>' with a
+ *      non-empty, non-whitespace reason — operator override with audit trail.
+ * Any other call to setIncidentStatus(id, 'resolved') will THROW.
+ *
+ * Uses temp-file + POSIX rename for crash safety.
+ */
+export declare function setIncidentStatus(projectRoot: string, incidentId: IncidentId, status: IncidentStatus, extras?: Partial<Omit<IncidentMetadata, "incidentId" | "symptom" | "createdAt" | "status">>, opts?: SetStatusOpts): Promise<void>;
+/**
+ * List all incidents in .bober/incidents/, sorted by createdAt descending.
+ *
+ * Gracefully handles:
+ * - Missing .bober/incidents/ directory → returns [].
+ * - Malformed incident.json → logged via logger.warn, skipped.
+ *
+ * ENOENT on readdir is caught and returns []. Any other readdir error is
+ * re-thrown (do NOT silence unexpected failures).
+ */
+export declare function listIncidents(projectRoot: string): Promise<IncidentSummary[]>;
+//# sourceMappingURL=timeline.d.ts.map

package/dist/incident/timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../../src/incident/timeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAOL,KAAK,UAAU,EACf,KAAK,gBAAgB,EAErB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAC3B,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAsD3D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAWlD;AAID;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,UAAU,CAAC,CAiDrB;AAID;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,IAAI,CAAC,CASf;AAID;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,IAAI,CAAC,CAsBf;AAID;;GAEG;AACH,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,IAAI,CAAC,CAsBf;AAID;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,IAAI,CAAC,CAuBf;AAID;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAsBf;AAOD,4GAA4G;AAC5G,MAAM,WAAW,aAAa;IAC5B,6FAA6F;IAC7F,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,yHAAyH;IACzH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;qBAEiB;IACjB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;+CAE2C;IAC3C,mBAAmB,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;IACjD;;6FAEyF;IACzF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;+DAC2D;IAC3D,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,cAAc,EACtB,MAAM,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,gBAAgB,EAAE,YAAY,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC,CAAC,EAC3F,IAAI,CAAC,EAAE,aAAa,GACnB,OAAO,CAAC,IAAI,CAAC,CA+Gf;AAID;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CA0CnF"}