@seedcli/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Seed CLI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/command/help.d.ts

@@ -0,0 +1,59 @@
+import type { Command } from "../types/command.js";
+export interface HelpOptions {
+    /** Custom header text */
+    header?: string;
+    /** Show command aliases (default: true) */
+    showAliases?: boolean;
+    /** Show hidden commands (default: false) */
+    showHidden?: boolean;
+    /** Alphabetical sort (default: true) */
+    sortCommands?: boolean;
+    /** CLI brand name */
+    brand?: string;
+    /** CLI version */
+    version?: string;
+}
+/**
+ * Generate help text for the entire CLI (global help).
+ *
+ * Output format:
+ * ```
+ * mycli v1.0.0
+ *
+ * USAGE
+ *   mycli <command> [options]
+ *
+ * COMMANDS
+ *   deploy    Deploy the application
+ *   dev       Start development mode
+ *   db        Database commands
+ *
+ * FLAGS
+ *   --help, -h       Show help
+ *   --version, -v    Show version
+ * ```
+ */
+export declare function renderGlobalHelp(commands: Command[], options?: HelpOptions): string;
+/**
+ * Generate help text for a specific command.
+ *
+ * Output format:
+ * ```
+ * Deploy the application
+ *
+ * USAGE
+ *   mycli deploy <environment> [options]
+ *
+ * ARGUMENTS
+ *   environment    Target environment (required)
+ *
+ * FLAGS
+ *   --force, -f          Force deployment (default: false)
+ *   --replicas, -r <n>   Number of replicas
+ *
+ * SUBCOMMANDS
+ *   rollback    Rollback the deployment
+ * ```
+ */
+export declare function renderCommandHelp(cmd: Command, options?: HelpOptions): string;
+//# sourceMappingURL=help.d.ts.map

package/dist/command/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/command/help.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAInD,MAAM,WAAW,WAAW;IAC3B,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4CAA4C;IAC5C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,wCAAwC;IACxC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,qBAAqB;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kBAAkB;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAID;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,GAAE,WAAgB,GAAG,MAAM,CAyDvF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,WAAgB,GAAG,MAAM,CAyEjF"}

package/dist/command/help.js

@@ -0,0 +1,216 @@
+// ─── Help Renderer ───
+/**
+ * Generate help text for the entire CLI (global help).
+ *
+ * Output format:
+ * ```
+ * mycli v1.0.0
+ *
+ * USAGE
+ *   mycli <command> [options]
+ *
+ * COMMANDS
+ *   deploy    Deploy the application
+ *   dev       Start development mode
+ *   db        Database commands
+ *
+ * FLAGS
+ *   --help, -h       Show help
+ *   --version, -v    Show version
+ * ```
+ */
+export function renderGlobalHelp(commands, options = {}) {
+    const { header, showAliases = true, showHidden = false, sortCommands = true, brand = "cli", version, } = options;
+    const lines = [];
+    // Header
+    if (header) {
+        lines.push(header);
+    }
+    else if (version) {
+        lines.push(`${brand} v${version}`);
+    }
+    else {
+        lines.push(brand);
+    }
+    lines.push("");
+    // Usage
+    lines.push("USAGE");
+    lines.push(`  ${brand} <command> [options]`);
+    lines.push("");
+    // Commands
+    const visibleCmds = commands.filter((cmd) => showHidden || !cmd.hidden);
+    if (sortCommands) {
+        visibleCmds.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    if (visibleCmds.length > 0) {
+        lines.push("COMMANDS");
+        // Calculate padding for alignment
+        const maxNameLen = Math.max(...visibleCmds.map((cmd) => formatCommandName(cmd, showAliases).length));
+        for (const cmd of visibleCmds) {
+            const name = formatCommandName(cmd, showAliases);
+            const padding = " ".repeat(Math.max(2, maxNameLen - name.length + 4));
+            const desc = cmd.description ?? "";
+            lines.push(`  ${name}${padding}${desc}`);
+        }
+        lines.push("");
+    }
+    // Global flags
+    lines.push("FLAGS");
+    lines.push("  --help, -h       Show help");
+    lines.push("  --version, -v    Show version");
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Generate help text for a specific command.
+ *
+ * Output format:
+ * ```
+ * Deploy the application
+ *
+ * USAGE
+ *   mycli deploy <environment> [options]
+ *
+ * ARGUMENTS
+ *   environment    Target environment (required)
+ *
+ * FLAGS
+ *   --force, -f          Force deployment (default: false)
+ *   --replicas, -r <n>   Number of replicas
+ *
+ * SUBCOMMANDS
+ *   rollback    Rollback the deployment
+ * ```
+ */
+export function renderCommandHelp(cmd, options = {}) {
+    const { brand = "cli", showAliases = true, showHidden = false } = options;
+    const lines = [];
+    // Description
+    if (cmd.description) {
+        lines.push(cmd.description);
+        lines.push("");
+    }
+    // Aliases
+    if (showAliases && cmd.alias && cmd.alias.length > 0) {
+        lines.push(`ALIASES`);
+        lines.push(`  ${cmd.alias.join(", ")}`);
+        lines.push("");
+    }
+    // Usage line
+    lines.push("USAGE");
+    lines.push(`  ${brand} ${buildUsageLine(cmd)}`);
+    lines.push("");
+    // Arguments
+    const argEntries = Object.entries(cmd.args ?? {});
+    if (argEntries.length > 0) {
+        lines.push("ARGUMENTS");
+        const maxNameLen = Math.max(...argEntries.map(([name]) => name.length));
+        for (const [name, def] of argEntries) {
+            const padding = " ".repeat(Math.max(2, maxNameLen - name.length + 4));
+            const meta = formatArgMeta(def);
+            lines.push(`  ${name}${padding}${meta}`);
+        }
+        lines.push("");
+    }
+    // Flags
+    const flagEntries = Object.entries(cmd.flags ?? {}).filter(([, def]) => !def.hidden);
+    if (flagEntries.length > 0) {
+        lines.push("FLAGS");
+        const formattedFlags = flagEntries.map(([name, def]) => ({
+            label: formatFlagLabel(name, def),
+            meta: formatFlagMeta(def),
+        }));
+        const maxLabelLen = Math.max(...formattedFlags.map((f) => f.label.length));
+        for (const { label, meta } of formattedFlags) {
+            const padding = " ".repeat(Math.max(2, maxLabelLen - label.length + 4));
+            lines.push(`  ${label}${padding}${meta}`);
+        }
+        lines.push("");
+    }
+    // Subcommands
+    const subcommands = (cmd.subcommands ?? []).filter((sub) => showHidden || !sub.hidden);
+    if (subcommands.length > 0) {
+        lines.push("SUBCOMMANDS");
+        const maxNameLen = Math.max(...subcommands.map((sub) => sub.name.length));
+        for (const sub of subcommands) {
+            const padding = " ".repeat(Math.max(2, maxNameLen - sub.name.length + 4));
+            const desc = sub.description ?? "";
+            lines.push(`  ${sub.name}${padding}${desc}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+// ─── Formatting Helpers ───
+function formatCommandName(cmd, showAliases) {
+    let name = cmd.name;
+    if (showAliases && cmd.alias && cmd.alias.length > 0) {
+        name += ` (${cmd.alias.join(", ")})`;
+    }
+    return name;
+}
+function buildUsageLine(cmd) {
+    const parts = [cmd.name];
+    // Add positional args
+    for (const [name, def] of Object.entries(cmd.args ?? {})) {
+        if (def.required) {
+            parts.push(`<${name}>`);
+        }
+        else {
+            parts.push(`[${name}]`);
+        }
+    }
+    // Add [options] if there are flags
+    const flagCount = Object.keys(cmd.flags ?? {}).length;
+    if (flagCount > 0) {
+        parts.push("[options]");
+    }
+    return parts.join(" ");
+}
+function formatArgMeta(def) {
+    const parts = [];
+    if (def.description) {
+        parts.push(def.description);
+    }
+    const argMetaChoices = def.choices;
+    if (argMetaChoices && argMetaChoices.length > 0) {
+        parts.push(`(${argMetaChoices.join(" | ")})`);
+    }
+    if (def.required) {
+        parts.push("(required)");
+    }
+    if (def.default !== undefined) {
+        parts.push(`(default: ${def.default})`);
+    }
+    return parts.join(" ");
+}
+function formatFlagLabel(name, def) {
+    let label = `--${name}`;
+    if (def.alias) {
+        label = `-${def.alias}, ${label}`;
+    }
+    // Add value placeholder
+    if (def.type !== "boolean") {
+        const placeholder = def.type === "number" || def.type === "number[]" ? "<n>" : "<value>";
+        label += ` ${placeholder}`;
+    }
+    return label;
+}
+function formatFlagMeta(def) {
+    const parts = [];
+    if (def.description) {
+        parts.push(def.description);
+    }
+    const flagMetaChoices = def.choices;
+    if (flagMetaChoices && flagMetaChoices.length > 0) {
+        parts.push(`(${flagMetaChoices.join(" | ")})`);
+    }
+    if (def.required) {
+        parts.push("(required)");
+    }
+    if (def.default !== undefined) {
+        parts.push(`(default: ${def.default})`);
+    }
+    return parts.join(" ");
+}
+//# sourceMappingURL=help.js.map

package/dist/command/help.js.map

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

package/dist/command/parser.d.ts

@@ -0,0 +1,27 @@
+import type { Command } from "../types/command.js";
+export declare class ParseError extends Error {
+    constructor(message: string);
+}
+export interface ParseResult {
+    args: Record<string, unknown>;
+    flags: Record<string, unknown>;
+    command: string | undefined;
+    argv: string[];
+    raw: string[];
+}
+/**
+ * Parse raw argv against a command's arg/flag definitions.
+ *
+ * Flow:
+ * 1. Separate positional args from flags using node:util parseArgs
+ * 2. Coerce types (string → number where needed)
+ * 3. Apply defaults for missing optional values
+ * 4. Validate required, choices, custom validators
+ * 5. Return typed { args, flags } object
+ */
+export declare function parse(argv: string[], cmd: Command): ParseResult;
+/**
+ * Levenshtein distance between two strings.
+ */
+export declare function levenshtein(a: string, b: string): number;
+//# sourceMappingURL=parser.d.ts.map

package/dist/command/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/command/parser.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAInD,qBAAa,UAAW,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAI3B;AAID,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,EAAE,CAAC;CACd;AAID;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,OAAO,GAAG,WAAW,CAqG/D;AAmKD;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAuBxD"}

package/dist/command/parser.js

@@ -0,0 +1,259 @@
+import { parseArgs } from "node:util";
+// ─── Error Types ───
+export class ParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ParseError";
+    }
+}
+// ─── Parser ───
+/**
+ * Parse raw argv against a command's arg/flag definitions.
+ *
+ * Flow:
+ * 1. Separate positional args from flags using node:util parseArgs
+ * 2. Coerce types (string → number where needed)
+ * 3. Apply defaults for missing optional values
+ * 4. Validate required, choices, custom validators
+ * 5. Return typed { args, flags } object
+ */
+export function parse(argv, cmd) {
+    const argDefs = cmd.args ?? {};
+    const flagDefs = cmd.flags ?? {};
+    // Build parseArgs options from flag definitions
+    const options = {};
+    for (const [name, def] of Object.entries(flagDefs)) {
+        const flagType = def.type;
+        if (flagType === "boolean") {
+            options[name] = { type: "boolean" };
+        }
+        else if (flagType === "string[]" || flagType === "number[]") {
+            // Arrays are "string" with multiple: true (we coerce number[] later)
+            options[name] = { type: "string", multiple: true };
+        }
+        else {
+            // string, number — parseArgs treats both as "string" (we coerce number later)
+            options[name] = { type: "string" };
+        }
+        if (def.alias) {
+            options[name].short = def.alias;
+        }
+    }
+    // Parse with node:util parseArgs
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            options,
+            strict: true,
+            allowPositionals: true,
+        });
+    }
+    catch (err) {
+        if (err instanceof Error) {
+            throw new ParseError(err.message);
+        }
+        throw err;
+    }
+    // ─── Process positional args ───
+    const argEntries = Object.entries(argDefs);
+    const args = {};
+    for (let i = 0; i < argEntries.length; i++) {
+        const [name, def] = argEntries[i];
+        const raw = parsed.positionals[i];
+        if (raw === undefined) {
+            if (def.default !== undefined) {
+                args[name] = def.default;
+            }
+            else if (def.required) {
+                throw new ParseError(formatMissingArg(name, def, cmd));
+            }
+            else {
+                args[name] = undefined;
+            }
+            continue;
+        }
+        args[name] = coerceArgValue(name, raw, def);
+        validateArg(name, args[name], def);
+    }
+    // ─── Process flags ───
+    const flags = {};
+    for (const [name, def] of Object.entries(flagDefs)) {
+        const raw = parsed.values[name];
+        if (raw === undefined) {
+            if (def.default !== undefined) {
+                flags[name] = def.default;
+            }
+            else if (def.required) {
+                throw new ParseError(formatMissingFlag(name, def));
+            }
+            else {
+                flags[name] = undefined;
+            }
+            continue;
+        }
+        flags[name] = coerceFlagValue(name, raw, def);
+        validateFlag(name, flags[name], def);
+    }
+    return {
+        args,
+        flags,
+        command: cmd.name,
+        argv: parsed.positionals,
+        raw: argv,
+    };
+}
+// ─── Type Coercion ───
+function coerceArgValue(name, raw, def) {
+    if (def.type === "number") {
+        const num = Number(raw);
+        if (Number.isNaN(num)) {
+            throw new ParseError(`Invalid value for argument "${name}"\n\n  Expected: number\n  Received: "${raw}"`);
+        }
+        return num;
+    }
+    return raw;
+}
+function coerceFlagValue(name, raw, def) {
+    switch (def.type) {
+        case "boolean":
+            return raw;
+        case "number": {
+            const num = Number(raw);
+            if (Number.isNaN(num)) {
+                throw new ParseError(`Invalid value for flag "--${name}"\n\n  Expected: number\n  Received: "${raw}"`);
+            }
+            return num;
+        }
+        case "string":
+            return raw;
+        case "string[]":
+            if (Array.isArray(raw)) {
+                return raw.map(String);
+            }
+            return [String(raw)];
+        case "number[]": {
+            const items = Array.isArray(raw) ? raw : [raw];
+            return items.map((item) => {
+                const num = Number(item);
+                if (Number.isNaN(num)) {
+                    throw new ParseError(`Invalid value for flag "--${name}"\n\n  Expected: number[]\n  Received item: "${item}"`);
+                }
+                return num;
+            });
+        }
+        default:
+            return raw;
+    }
+}
+// ─── Validation ───
+function validateArg(name, value, def) {
+    // Choices validation
+    const argChoices = def.choices;
+    if (argChoices && argChoices.length > 0) {
+        if (!argChoices.includes(String(value))) {
+            const choicesStr = argChoices.map((c) => `"${c}"`).join(", ");
+            const suggestion = findClosest(String(value), argChoices);
+            let msg = `Invalid value for argument "${name}"\n\n  Expected one of: ${choicesStr}\n  Received: "${value}"`;
+            if (suggestion) {
+                msg += `\n\n  Did you mean "${suggestion}"?`;
+            }
+            throw new ParseError(msg);
+        }
+    }
+    // Custom validator
+    if (def.validate) {
+        const result = def.validate(value);
+        if (result === false) {
+            throw new ParseError(`Validation failed for argument "${name}"`);
+        }
+        if (typeof result === "string") {
+            throw new ParseError(`Validation failed for argument "${name}": ${result}`);
+        }
+    }
+}
+function validateFlag(name, value, def) {
+    // Choices validation (only for string flags)
+    const flagChoices = def.choices;
+    if (flagChoices && flagChoices.length > 0) {
+        if (!flagChoices.includes(String(value))) {
+            const choicesStr = flagChoices.map((c) => `"${c}"`).join(", ");
+            const suggestion = findClosest(String(value), flagChoices);
+            let msg = `Invalid value for flag "--${name}"\n\n  Expected one of: ${choicesStr}\n  Received: "${value}"`;
+            if (suggestion) {
+                msg += `\n\n  Did you mean "${suggestion}"?`;
+            }
+            throw new ParseError(msg);
+        }
+    }
+    // Custom validator
+    if (def.validate) {
+        const result = def.validate(value);
+        if (result === false) {
+            throw new ParseError(`Validation failed for flag "--${name}"`);
+        }
+        if (typeof result === "string") {
+            throw new ParseError(`Validation failed for flag "--${name}": ${result}`);
+        }
+    }
+}
+// ─── Error Formatting ───
+function formatMissingArg(name, def, cmd) {
+    let msg = `Missing required argument "${name}"`;
+    if (def.description) {
+        msg += `\n\n  ${def.description}`;
+    }
+    const missingArgChoices = def.choices;
+    if (missingArgChoices && missingArgChoices.length > 0) {
+        msg += `\n  Expected one of: ${missingArgChoices.join(", ")}`;
+    }
+    msg += `\n\n  Usage: ${cmd.name} <${name}>`;
+    return msg;
+}
+function formatMissingFlag(name, def) {
+    let msg = `Missing required flag "--${name}"`;
+    if (def.description) {
+        msg += `\n\n  ${def.description}`;
+    }
+    return msg;
+}
+// ─── Utilities ───
+/**
+ * Find the closest match to `input` from `candidates` using Levenshtein distance.
+ * Returns null if no candidate is close enough (distance > 3).
+ */
+function findClosest(input, candidates) {
+    let bestMatch = null;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const candidate of candidates) {
+        const dist = levenshtein(input.toLowerCase(), candidate.toLowerCase());
+        if (dist < bestDistance) {
+            bestDistance = dist;
+            bestMatch = candidate;
+        }
+    }
+    return bestDistance <= 3 ? bestMatch : null;
+}
+/**
+ * Levenshtein distance between two strings.
+ */
+export function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    // Use a single-row DP approach for space efficiency
+    const row = Array.from({ length: n + 1 }, (_, i) => i);
+    for (let i = 1; i <= m; i++) {
+        let prev = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            const val = Math.min(row[j] + 1, // deletion
+            prev + 1, // insertion
+            row[j - 1] + cost);
+            row[j - 1] = prev;
+            prev = val;
+        }
+        row[n] = prev;
+    }
+    return row[n];
+}
+//# sourceMappingURL=parser.js.map

package/dist/command/parser.js.map

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

package/dist/command/router.d.ts

@@ -0,0 +1,34 @@
+import type { Command } from "../types/command.js";
+export interface RouteResult {
+    /** The matched command (null if not found) */
+    command: Command | null;
+    /** Remaining argv after stripping command tokens */
+    argv: string[];
+    /** Suggestions if command was not found */
+    suggestions: CommandSuggestion[];
+}
+export interface CommandSuggestion {
+    name: string;
+    description?: string;
+    distance: number;
+}
+/**
+ * Route argv to a registered command.
+ *
+ * Algorithm:
+ * 1. Split argv into tokens
+ * 2. Try exact match (including aliases)
+ * 3. Try subcommand matching (e.g., ["db", "migrate"] → db.subcommands.migrate)
+ * 4. If no match, compute fuzzy suggestions
+ * 5. Return { command, argv, suggestions }
+ */
+export declare function route(argv: string[], commands: Command[]): RouteResult;
+/**
+ * Flatten all commands (including subcommands) into a flat list.
+ * Useful for help generation.
+ */
+export declare function flattenCommands(commands: Command[], prefix?: string): Array<{
+    fullName: string;
+    command: Command;
+}>;
+//# sourceMappingURL=router.d.ts.map

package/dist/command/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/command/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAKnD,MAAM,WAAW,WAAW;IAC3B,8CAA8C;IAC9C,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,oDAAoD;IACpD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,2CAA2C;IAC3C,WAAW,EAAE,iBAAiB,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CACjB;AAID;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,WAAW,CA4BtE;AA+CD;;;GAGG;AACH,wBAAgB,eAAe,CAC9B,QAAQ,EAAE,OAAO,EAAE,EACnB,MAAM,SAAK,GACT,KAAK,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAa/C"}