solveos-cli 0.1.0

package/dist/lib/security.js

@@ -0,0 +1,230 @@
+/**
+ * Security module for solveos-cli.
+ *
+ * Protects against:
+ * 1. Path traversal attacks — ensures all file operations stay within .solveos/
+ * 2. Prompt injection — scans user-supplied content for injection patterns
+ *    before it's used as AI agent context
+ *
+ * Since solveos-cli generates markdown that becomes LLM system prompts,
+ * indirect prompt injection is a real attack surface.
+ */
+import { resolve, relative } from "node:path";
+import { realpath } from "node:fs/promises";
+// ---------------------------------------------------------------------------
+// Path Validation
+// ---------------------------------------------------------------------------
+/**
+ * Validate that a target path resolves within a base directory.
+ * Prevents path traversal attacks (../../etc/passwd, symlinks, null bytes).
+ *
+ * @param basePath - The allowed root directory (e.g., /project/.solveos)
+ * @param targetPath - The path to validate (absolute or relative to basePath)
+ * @returns The resolved, validated absolute path
+ * @throws Error if the path escapes the base directory
+ */
+export function validatePath(basePath, targetPath) {
+    // Reject null bytes — used in null byte injection attacks
+    if (basePath.includes("\0") || targetPath.includes("\0")) {
+        throw new PathTraversalError("Null byte detected in path", targetPath, basePath);
+    }
+    const resolvedBase = resolve(basePath);
+    const resolvedTarget = resolve(resolvedBase, targetPath);
+    const rel = relative(resolvedBase, resolvedTarget);
+    // Check 1: relative path must not start with ".." (escaping base)
+    if (rel.startsWith("..")) {
+        throw new PathTraversalError(`Path resolves outside allowed directory`, targetPath, basePath);
+    }
+    // Check 2: empty relative path means target IS the base (allowed)
+    // Check 3: absolute paths that don't start with base are rejected
+    if (!resolvedTarget.startsWith(resolvedBase)) {
+        throw new PathTraversalError(`Path resolves outside allowed directory`, targetPath, basePath);
+    }
+    return resolvedTarget;
+}
+/**
+ * Validate path with symlink resolution.
+ * Resolves symlinks first, then validates the real path.
+ * Use this for operations where the target file already exists.
+ *
+ * @param basePath - The allowed root directory
+ * @param targetPath - The path to validate
+ * @returns The resolved, validated real path
+ * @throws Error if the real path escapes the base directory
+ */
+export async function validatePathWithSymlinks(basePath, targetPath) {
+    // First do the basic validation
+    const validated = validatePath(basePath, targetPath);
+    // Then resolve symlinks and re-validate
+    try {
+        const realBase = await realpath(basePath);
+        const realTarget = await realpath(validated);
+        const rel = relative(realBase, realTarget);
+        if (rel.startsWith("..") || !realTarget.startsWith(realBase)) {
+            throw new PathTraversalError(`Symlink resolves outside allowed directory`, targetPath, basePath);
+        }
+        return realTarget;
+    }
+    catch (err) {
+        // If realpath fails (file doesn't exist yet), the basic validation is sufficient
+        if (err.code === "ENOENT") {
+            return validated;
+        }
+        throw err;
+    }
+}
+/**
+ * Custom error for path traversal attempts.
+ */
+export class PathTraversalError extends Error {
+    attemptedPath;
+    basePath;
+    constructor(message, attemptedPath, basePath) {
+        super(`Path traversal detected: ${message} (attempted: "${attemptedPath}", base: "${basePath}")`);
+        this.name = "PathTraversalError";
+        this.attemptedPath = attemptedPath;
+        this.basePath = basePath;
+    }
+}
+/**
+ * Patterns that indicate prompt injection attempts.
+ * Ordered from most to least suspicious.
+ */
+const INJECTION_PATTERNS = [
+    // BLOCK-level: almost certainly injection attempts
+    {
+        name: "System prompt override",
+        regex: /ignore\s+(all\s+)?(previous|prior|above|earlier)\s+(instructions?|prompts?|rules?|directions?)/i,
+        severity: "block",
+    },
+    {
+        name: "System prompt reset",
+        regex: /forget\s+(all\s+)?(previous|prior|above|earlier)\s+(instructions?|context|conversation)/i,
+        severity: "block",
+    },
+    {
+        name: "Role switching",
+        regex: /you\s+are\s+now\s+(a|an|the)\s+(?!solveos)/i,
+        severity: "block",
+    },
+    {
+        name: "New system prompt injection",
+        regex: /\[?\s*system\s*\]?\s*:?\s*you\s+are/i,
+        severity: "block",
+    },
+    {
+        name: "Instruction boundary escape (XML)",
+        regex: /<\/?system>|<\/?instructions?>|<\/?prompt>/i,
+        severity: "block",
+    },
+    {
+        name: "Base64-encoded instruction injection",
+        regex: /(?:eval|decode|execute)\s*\(\s*(?:atob|base64|Buffer\.from)/i,
+        severity: "block",
+    },
+    {
+        name: "Hidden instruction delimiter",
+        regex: /---\s*(?:BEGIN|START)\s+(?:HIDDEN|SECRET|REAL)\s+(?:INSTRUCTIONS?|PROMPT)/i,
+        severity: "block",
+    },
+    // WARN-level: suspicious but possibly legitimate
+    {
+        name: "Disregard instruction",
+        regex: /(?:disregard|override|bypass|skip)\s+(?:the\s+)?(?:above|previous|prior|system)\s+(?:instructions?|rules?|constraints?)/i,
+        severity: "warn",
+    },
+    {
+        name: "Act as different entity",
+        regex: /(?:act|behave|pretend|respond)\s+(?:as|like)\s+(?:a|an|the|if\s+you\s+(?:are|were))/i,
+        severity: "warn",
+    },
+    {
+        name: "Jailbreak attempt",
+        regex: /(?:DAN|DUDE|jailbreak|do\s+anything\s+now)/i,
+        severity: "warn",
+    },
+    {
+        name: "Output manipulation",
+        regex: /(?:when\s+(?:asked|prompted|queried)|if\s+(?:anyone|someone)\s+asks)\s+.*(?:say|respond|output|answer)/i,
+        severity: "warn",
+    },
+    {
+        name: "Instruction in markdown comment",
+        regex: /<!--\s*(?:ignore|override|system|instruction)/i,
+        severity: "warn",
+    },
+];
+/**
+ * Scan content for prompt injection patterns.
+ *
+ * @param content - The text to scan (Plan Brief content, research summaries, etc.)
+ * @returns Scan result with detected patterns, severity, and matches.
+ */
+export function scanForInjection(content) {
+    const matches = [];
+    const lines = content.split("\n");
+    for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+        const line = lines[lineIdx];
+        for (const pattern of INJECTION_PATTERNS) {
+            const match = pattern.regex.exec(line);
+            if (match) {
+                matches.push({
+                    pattern: pattern.name,
+                    matched: match[0].slice(0, 100),
+                    severity: pattern.severity,
+                    line: lineIdx + 1,
+                });
+            }
+        }
+    }
+    // Determine highest severity
+    let severity = null;
+    if (matches.some((m) => m.severity === "block")) {
+        severity = "block";
+    }
+    else if (matches.length > 0) {
+        severity = "warn";
+    }
+    return {
+        detected: matches.length > 0,
+        severity,
+        matches,
+    };
+}
+// ---------------------------------------------------------------------------
+// Content Sanitization
+// ---------------------------------------------------------------------------
+/**
+ * Wrap user-supplied content with clear delimiters so the LLM can distinguish
+ * between system instructions and user content.
+ *
+ * This doesn't prevent injection but makes it harder for injected instructions
+ * to be confused with system-level prompts.
+ *
+ * @param content - The user-supplied content
+ * @param label - A label describing what this content is (e.g., "Plan Brief", "Research Summary")
+ * @returns Content wrapped with delimiters
+ */
+export function wrapUserContent(content, label) {
+    return [
+        `<user-content label="${label}">`,
+        content,
+        `</user-content>`,
+    ].join("\n");
+}
+/**
+ * Sanitize a filename to prevent path traversal via filename manipulation.
+ * Allows: alphanumeric, hyphens, underscores, dots.
+ * Rejects: slashes, null bytes, special characters.
+ */
+export function sanitizeFilename(name) {
+    // Reject null bytes
+    if (name.includes("\0")) {
+        throw new Error("Null byte detected in filename");
+    }
+    // Strip path separators and directory components
+    const base = name.replace(/.*[/\\]/, "");
+    // Replace unsafe characters
+    return base.replace(/[^a-zA-Z0-9._-]/g, "-").toLowerCase();
+}
+//# sourceMappingURL=security.js.map

package/dist/lib/security.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Shared type definitions for solveos-cli.
+ *
+ * Covers: cycle states, state transitions, configuration, artifacts,
+ * and runtime adapter interface. This file is the single source of truth
+ * for all type contracts.
+ *
+ * NOTE: This file contains types only — everything is erased at compile time.
+ */
+/**
+ * The 11 states of a solveOS cycle.
+ * Maps directly to the state machine in docs/plan.md.
+ */
+export declare enum CycleState {
+    INIT = "INIT",
+    RESEARCHING = "RESEARCHING",
+    PLANNING = "PLANNING",
+    VALIDATING_PLAN = "VALIDATING_PLAN",
+    BUILDING = "BUILDING",
+    VALIDATING_BUILD = "VALIDATING_BUILD",
+    REVIEWING_PRE = "REVIEWING_PRE",
+    READY_TO_SHIP = "READY_TO_SHIP",
+    SHIPPED = "SHIPPED",
+    REVIEWING_POST = "REVIEWING_POST",
+    CYCLE_COMPLETE = "CYCLE_COMPLETE"
+}
+/**
+ * All valid state transitions. Each tuple is [from, to].
+ * Invalid transitions are not representable as this type.
+ */
+export type StateTransition = [CycleState.INIT, CycleState.RESEARCHING] | [CycleState.INIT, CycleState.PLANNING] | [CycleState.RESEARCHING, CycleState.PLANNING] | [CycleState.PLANNING, CycleState.VALIDATING_PLAN] | [CycleState.PLANNING, CycleState.BUILDING] | [CycleState.VALIDATING_PLAN, CycleState.PLANNING] | [CycleState.VALIDATING_PLAN, CycleState.BUILDING] | [CycleState.BUILDING, CycleState.VALIDATING_BUILD] | [CycleState.BUILDING, CycleState.REVIEWING_PRE] | [CycleState.BUILDING, CycleState.READY_TO_SHIP] | [CycleState.VALIDATING_BUILD, CycleState.BUILDING] | [CycleState.VALIDATING_BUILD, CycleState.PLANNING] | [CycleState.VALIDATING_BUILD, CycleState.REVIEWING_PRE] | [CycleState.VALIDATING_BUILD, CycleState.READY_TO_SHIP] | [CycleState.REVIEWING_PRE, CycleState.BUILDING] | [CycleState.REVIEWING_PRE, CycleState.READY_TO_SHIP] | [CycleState.READY_TO_SHIP, CycleState.SHIPPED] | [CycleState.SHIPPED, CycleState.REVIEWING_POST] | [CycleState.SHIPPED, CycleState.CYCLE_COMPLETE] | [CycleState.REVIEWING_POST, CycleState.CYCLE_COMPLETE] | [CycleState.CYCLE_COMPLETE, CycleState.INIT];
+/** Gate toggle flags — each gate can be independently enabled/disabled. */
+export interface GateConfig {
+    research: boolean;
+    plan_validation: boolean;
+    build_validation: boolean;
+    review_pre_ship: boolean;
+    review_post_ship: boolean;
+}
+/** Domain setting — adjusts agent prompts and artifact templates. */
+export type Domain = "software" | "content" | "research" | "strategy" | "general";
+/** Interaction mode. */
+export type Mode = "interactive" | "auto";
+/** Work decomposition granularity for the Build phase. */
+export type Granularity = "coarse" | "standard" | "fine";
+/** Supported AI coding assistant runtimes. */
+export type Runtime = "opencode" | "claude-code" | "cursor" | "gemini" | "auto";
+/** Project-level configuration stored in .solveos/config.json. */
+export interface Config {
+    mode: Mode;
+    gates: GateConfig;
+    plan_validation_max_passes: number;
+    granularity: Granularity;
+    auto_advance: boolean;
+    domain: Domain;
+    runtime: Runtime;
+    hooks: HookConfig;
+}
+/** Hook configuration — controls context monitor and brief anchor behavior. */
+export interface HookConfig {
+    /** Enable the context monitor plugin. */
+    context_monitor: boolean;
+    /** Message count threshold before warning (proxy for context usage). Default 60. */
+    context_monitor_threshold: number;
+    /** Enable the brief anchor plugin. */
+    brief_anchor: boolean;
+    /** Tool call interval between brief anchor reminders during Build. Default 10. */
+    brief_anchor_interval: number;
+}
+/** The names of gates that can be skipped or completed. */
+export type GateName = "RESEARCH" | "PLAN_VALIDATION" | "BUILD_VALIDATION" | "REVIEW_PRE_SHIP" | "REVIEW_POST_SHIP";
+/** A single entry in the transitions log — records every state change. */
+export interface TransitionLogEntry {
+    from: CycleState;
+    to: CycleState;
+    at: string;
+    gate_skipped?: GateName;
+    gate_completed?: GateName;
+}
+/** Structured data tracked in .solveos/STATE.md. */
+export interface CycleStateData {
+    current_state: CycleState;
+    cycle_number: number;
+    gates_skipped: GateName[];
+    gates_completed: GateName[];
+    plan_validation_passes: number;
+    blockers: string[];
+    transitions_log: TransitionLogEntry[];
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * The Plan Brief — the central artifact of every solveOS cycle.
+ * Maps to the 8 questions from the solveOS framework.
+ */
+export interface PlanBrief {
+    /** What problem are we solving? */
+    problem: string;
+    /** Who is this for? */
+    audience: string;
+    /** What does success look like? */
+    goal: string;
+    /** How much time/effort are we willing to spend? */
+    appetite: string;
+    /** What are the constraints? (tech stack, style, etc.) */
+    constraints: string[];
+    /** How will we know this is done? (measurable criteria) */
+    success_criteria: string[];
+    /** What is the core assumption we're betting on? */
+    core_assumption: string;
+    /** Known rabbit holes to avoid. */
+    rabbit_holes: string[];
+    /** Explicitly out of scope. */
+    out_of_scope: string[];
+}
+/** Status of an individual work unit. */
+export type WorkUnitStatus = "pending" | "in_progress" | "completed" | "failed" | "skipped";
+/**
+ * An atomic unit of work within the Build phase.
+ * Each unit maps to at least one success criterion and can declare
+ * dependencies on other units.
+ */
+export interface WorkUnit {
+    /** Unique identifier within this execution plan (e.g., "unit-1"). */
+    id: string;
+    /** Human-readable name. */
+    name: string;
+    /** What this unit does — detailed enough for an agent to execute. */
+    description: string;
+    /** IDs of units that must complete before this one can start. */
+    depends_on: string[];
+    /** Which success criteria from the Plan Brief this unit verifies. */
+    criteria: string[];
+    /** Current execution status. */
+    status: WorkUnitStatus;
+    /** Output summary after execution (filled in by the executor). */
+    summary?: string;
+    /** Error message if the unit failed. */
+    error?: string;
+    /** Whether this was discovered during execution (not in original decomposition). */
+    discovered?: boolean;
+}
+/**
+ * A wave — a group of independent work units that can execute in parallel.
+ * All units in a wave have their dependencies satisfied by prior waves.
+ */
+export interface Wave {
+    /** Wave number (1-indexed). */
+    number: number;
+    /** IDs of work units in this wave. */
+    unit_ids: string[];
+    /** Wave status: pending until all units start, completed when all finish. */
+    status: "pending" | "in_progress" | "completed" | "failed";
+}
+/**
+ * The complete wave execution plan for a Build phase.
+ * Produced by decomposition + dependency analysis + wave grouping.
+ */
+export interface WaveExecutionPlan {
+    /** All work units. */
+    units: WorkUnit[];
+    /** Waves (ordered by execution sequence). */
+    waves: Wave[];
+    /** Granularity setting used for decomposition. */
+    granularity: Granularity;
+    /** Whether this plan has a single unit (bypasses wave overhead). */
+    single_unit: boolean;
+    /** Timestamp of plan creation. */
+    created_at: string;
+}
+/**
+ * Result of executing a wave execution plan.
+ */
+export interface WaveExecutionResult {
+    /** Overall status. */
+    status: "completed" | "partial" | "failed";
+    /** Number of units completed. */
+    units_completed: number;
+    /** Total number of units. */
+    units_total: number;
+    /** Discovered tasks added during execution. */
+    discovered_tasks: number;
+    /** Per-wave summaries. */
+    wave_summaries: WaveSummary[];
+    /** Completion timestamp. */
+    completed_at: string;
+}
+/**
+ * Summary of a single wave's execution.
+ */
+export interface WaveSummary {
+    /** Wave number. */
+    wave_number: number;
+    /** Units that completed successfully. */
+    completed: string[];
+    /** Units that failed. */
+    failed: string[];
+    /** Units that were skipped (due to dependency failures). */
+    skipped: string[];
+}
+/** Result of runtime detection. */
+export interface DetectResult {
+    /** Whether the runtime was detected. */
+    detected: boolean;
+    /** Human-readable name of the detected runtime. */
+    name: string;
+    /** Path to the runtime's config directory or file, if found. */
+    configPath?: string;
+}
+/**
+ * Interface that each runtime adapter must implement.
+ * Handles detection and installation for a specific AI coding assistant.
+ */
+export interface RuntimeAdapter {
+    /** Check if this runtime is available in the current project/environment. */
+    detect(): Promise<DetectResult>;
+    /** Install slash command .md files to the runtime's command directory. */
+    installCommands(sourceDir: string): Promise<void>;
+    /** Install agent .md files to the runtime's agent directory. */
+    installAgents(sourceDir: string): Promise<void>;
+    /** Install compiled hook .js files to the runtime's hook directory. */
+    installHooks(sourceDir: string): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,31 @@
+/**
+ * Shared type definitions for solveos-cli.
+ *
+ * Covers: cycle states, state transitions, configuration, artifacts,
+ * and runtime adapter interface. This file is the single source of truth
+ * for all type contracts.
+ *
+ * NOTE: This file contains types only — everything is erased at compile time.
+ */
+// ---------------------------------------------------------------------------
+// Cycle States
+// ---------------------------------------------------------------------------
+/**
+ * The 11 states of a solveOS cycle.
+ * Maps directly to the state machine in docs/plan.md.
+ */
+export var CycleState;
+(function (CycleState) {
+    CycleState["INIT"] = "INIT";
+    CycleState["RESEARCHING"] = "RESEARCHING";
+    CycleState["PLANNING"] = "PLANNING";
+    CycleState["VALIDATING_PLAN"] = "VALIDATING_PLAN";
+    CycleState["BUILDING"] = "BUILDING";
+    CycleState["VALIDATING_BUILD"] = "VALIDATING_BUILD";
+    CycleState["REVIEWING_PRE"] = "REVIEWING_PRE";
+    CycleState["READY_TO_SHIP"] = "READY_TO_SHIP";
+    CycleState["SHIPPED"] = "SHIPPED";
+    CycleState["REVIEWING_POST"] = "REVIEWING_POST";
+    CycleState["CYCLE_COMPLETE"] = "CYCLE_COMPLETE";
+})(CycleState || (CycleState = {}));
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,CAAN,IAAY,UAYX;AAZD,WAAY,UAAU;IACpB,2BAAa,CAAA;IACb,yCAA2B,CAAA;IAC3B,mCAAqB,CAAA;IACrB,iDAAmC,CAAA;IACnC,mCAAqB,CAAA;IACrB,mDAAqC,CAAA;IACrC,6CAA+B,CAAA;IAC/B,6CAA+B,CAAA;IAC/B,iCAAmB,CAAA;IACnB,+CAAiC,CAAA;IACjC,+CAAiC,CAAA;AACnC,CAAC,EAZW,UAAU,KAAV,UAAU,QAYrB"}

package/dist/workflows/state-machine.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Cycle state machine for solveos-cli.
+ *
+ * Tracks which phase/gate the user is in, enforces valid transitions,
+ * and provides helpers for state queries. Persistence (load/save to
+ * .solveos/STATE.md) is handled by the artifacts module.
+ *
+ * The transition map encodes all ~20 valid transitions from docs/plan.md.
+ * Invalid transitions throw — they are programming errors, not user errors.
+ */
+import { CycleState } from "../types.js";
+import type { CycleStateData, GateName, StateTransition } from "../types.js";
+export interface TransitionResult {
+    /** The transition that was applied. */
+    transition: StateTransition;
+    /** Updated state data after the transition. */
+    stateData: CycleStateData;
+    /** Gates that were skipped by this transition. */
+    gatesSkipped: GateName[];
+    /** Gate that was completed by this transition, if any. */
+    gateCompleted: GateName | null;
+    /** Whether the plan validation max passes was reached (escalation signal). */
+    planValidationEscalation: boolean;
+}
+/**
+ * Validate and apply a state transition.
+ *
+ * @param stateData - Current cycle state data.
+ * @param target - The desired next state.
+ * @param maxPlanValidationPasses - From config; defaults to 3.
+ * @returns TransitionResult with updated state data and metadata.
+ * @throws Error if the transition is invalid.
+ */
+export declare function transition(stateData: CycleStateData, target: CycleState, maxPlanValidationPasses?: number): TransitionResult;
+/**
+ * Get all valid next states from the current state.
+ */
+export declare function getNextStates(currentState: CycleState): CycleState[];
+/**
+ * Check if a transition is valid without applying it.
+ */
+export declare function isValidTransition(from: CycleState, to: CycleState): boolean;
+/**
+ * Create initial state data for a new cycle.
+ */
+export declare function createInitialState(cycleNumber?: number): CycleStateData;
+/**
+ * Get a human-readable description of the current state.
+ */
+export declare function describeState(state: CycleState): string;
+/**
+ * Get the suggested next command for a given state.
+ */
+export declare function suggestNextCommand(state: CycleState): string;
+//# sourceMappingURL=state-machine.d.ts.map

package/dist/workflows/state-machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.d.ts","sourceRoot":"","sources":["../../src/workflows/state-machine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,eAAe,EAAsB,MAAM,aAAa,CAAC;AAmJjG,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,UAAU,EAAE,eAAe,CAAC;IAC5B,+CAA+C;IAC/C,SAAS,EAAE,cAAc,CAAC;IAC1B,kDAAkD;IAClD,YAAY,EAAE,QAAQ,EAAE,CAAC;IACzB,0DAA0D;IAC1D,aAAa,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC/B,8EAA8E;IAC9E,wBAAwB,EAAE,OAAO,CAAC;CACnC;AAMD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,cAAc,EACzB,MAAM,EAAE,UAAU,EAClB,uBAAuB,GAAE,MAAU,GAClC,gBAAgB,CA4ElB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,UAAU,GAAG,UAAU,EAAE,CAEpE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,UAAU,EAChB,EAAE,EAAE,UAAU,GACb,OAAO,CAET;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,GAAE,MAAU,GAAG,cAAc,CAa1E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAevD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAe5D"}