@svenroth-ai/shipwright 0.24.1-next.0

package/server/dist/core/actions-schema-validator.js

@@ -0,0 +1,394 @@
+/*
+ * Actions.json structural validator.
+ *
+ * Iterate 3 section 03 — plan.md § 7 O24. The loader is pure I/O; this
+ * validator catches the five schema failure modes that the external
+ * review flagged:
+ *   1. Duplicate action ids
+ *   2. Invalid defaults.autonomy enum
+ *   3. Empty phases[]
+ *   4. Missing required action fields (command_template on external_launch)
+ *   5. Unsupported modal_fields entry (stale `complexity:radio:...` per AD-03.13)
+ *
+ * Placeholder-level validation (unknown placeholder tokens inside
+ * command_template) is the responsibility of
+ * `actions-substitute.validateTemplate`. This module deliberately stays
+ * structure-only so the two concerns compose.
+ *
+ * Returns a list of errors rather than throwing — the route layer
+ * decides how to surface them (HTTP 400 with structured code on the
+ * first error, or aggregated diagnostics for the GET /actions route).
+ */
+import { CLI_FLAG_PATTERN, PARAM_NAME_PATTERN } from "../types/action-schema.js";
+import { BUILTIN_INITIAL_PROMPT_ACTIONS, SLASH_COMMAND_PATTERN, } from "./actions-substitute.js";
+const VALID_PARAM_TYPES = new Set(["boolean", "enum", "string"]);
+const PARAMETERS_PLACEHOLDER = "{task.parameters?}";
+/**
+ * iterate/fix-adopt-prompt-shape § 1 — actions can satisfy the
+ * "schema → template references parameters" check by EITHER using the
+ * legacy `{task.parameters?}` placeholder OR the new
+ * `{task.initial_prompt}` placeholder (which embeds parameters into
+ * the quoted initial-prompt string).
+ */
+const INITIAL_PROMPT_PLACEHOLDER = "{task.initial_prompt}";
+// iterate-2026-06-11-custom-action-slash-command — whitespace-tolerant match
+// for `{task.initial_prompt}`. The substituter trims placeholder keys, so
+// `{ task.initial_prompt }` expands too; section 8 must detect the spaced form
+// or the missing-slash case re-surfaces as a 500 (a literal includes() misses it).
+const INITIAL_PROMPT_PLACEHOLDER_RE = /\{\s*task\.initial_prompt\s*\}/;
+/**
+ * Modal field allowlist (per AD-03.13). `complexity:radio:small,medium,large`
+ * is explicitly removed; the new iterate modal uses complexity auto-detect
+ * at skill-invocation time, not a pre-launch field.
+ *
+ * iterate-2026-05-14 lead-foundation-task-schema: 5 leadwright-routing
+ * names added (`domain`, `priority`, `complexityHint`, `tags`,
+ * `blockedBy`). They follow the same bare-name rule — anything with a
+ * `:type:` suffix (e.g. `complexity:radio:...`) is still rejected.
+ */
+const SUPPORTED_MODAL_FIELDS = new Set([
+    "title",
+    "phase",
+    "description",
+    "autonomy",
+    "project", // read-only strip or dropdown — not user-input but may appear in modal_fields for the `all projects` branch
+    // lead-foundation-task-schema (iterate-2026-05-14, leadwright Phase 1)
+    "domain",
+    "priority",
+    "complexityHint",
+    "tags",
+    "blockedBy",
+]);
+const VALID_AUTONOMY = new Set(["guided", "autonomous"]);
+export function validateActionsSchema(actions) {
+    const errors = [];
+    // 1. Duplicate action ids.
+    const ids = new Set();
+    for (const a of actions.actions) {
+        if (ids.has(a.id)) {
+            errors.push({ code: "duplicate_action_id", id: a.id });
+        }
+        ids.add(a.id);
+    }
+    // 2. Invalid defaults.autonomy enum.
+    if (!VALID_AUTONOMY.has(actions.defaults.autonomy)) {
+        errors.push({
+            code: "invalid_autonomy_enum",
+            value: actions.defaults.autonomy,
+        });
+    }
+    // 3. Empty phases[].
+    if (!Array.isArray(actions.phases) || actions.phases.length === 0) {
+        errors.push({ code: "empty_phases" });
+    }
+    // 4. Missing command_template on external_launch kind.
+    for (const a of actions.actions) {
+        if (a.kind === "external_launch") {
+            if (typeof a.command_template !== "string" || a.command_template.trim() === "") {
+                errors.push({ code: "missing_command_template", actionId: a.id });
+            }
+        }
+    }
+    // 5. Unsupported modal_fields entries.
+    for (const a of actions.actions) {
+        if (!a.modal_fields)
+            continue;
+        for (const field of a.modal_fields) {
+            // Field may include a type suffix like `complexity:radio:...`; treat
+            // anything with a colon as type-tagged and lookup by the bare name.
+            const bare = field.split(":")[0];
+            if (!SUPPORTED_MODAL_FIELDS.has(bare) || field !== bare) {
+                // `field !== bare` catches `complexity:radio:...` even if `complexity`
+                // alone were somehow in the allowlist (it isn't, but defense-in-depth).
+                errors.push({
+                    code: "unsupported_modal_field",
+                    actionId: a.id,
+                    field,
+                });
+            }
+        }
+    }
+    // preview.enabled type guard (not in the review list, but a JSON-
+    // coerced junk value here would silently break the route's
+    // precedence chain).
+    const previewEnabled = actions.preview?.enabled;
+    if (previewEnabled !== true &&
+        previewEnabled !== false &&
+        previewEnabled !== "auto") {
+        errors.push({
+            code: "invalid_preview_enabled",
+            value: previewEnabled,
+        });
+    }
+    // 6. Parameters / phase_parameters validation per action.
+    const phaseIds = new Set(actions.phases.map((p) => p.id));
+    for (const action of actions.actions) {
+        validateActionParameters(action, phaseIds, errors);
+    }
+    // 7. Phase.supports_autonomy type-guard (iterate/v030-five-ux-fixes P3).
+    for (const phase of actions.phases) {
+        const v = phase.supports_autonomy;
+        if (v !== undefined && typeof v !== "boolean") {
+            errors.push({
+                code: "invalid_phase_supports_autonomy",
+                phaseId: phase.id,
+                value: v,
+            });
+        }
+    }
+    // 8. slash_command for custom {task.initial_prompt} actions
+    //    (iterate-2026-06-11-custom-action-slash-command). A NON-builtin action
+    //    that fuses the prompt via {task.initial_prompt} MUST declare a well-formed
+    //    slash_command — else buildSlashCommand returns null → UnknownActionError
+    //    (400 launch / 500 dry-run). Fail loud at load instead. Builtins are exempt
+    //    (hardcoded slash); actions on {task.description?} don't need it.
+    for (const action of actions.actions) {
+        const usesInitialPrompt = INITIAL_PROMPT_PLACEHOLDER_RE.test(action.command_template ?? "");
+        if (!usesInitialPrompt)
+            continue;
+        if (BUILTIN_INITIAL_PROMPT_ACTIONS.has(action.id))
+            continue;
+        // Trim so a whitespace-only value is "missing" and a padded-but-valid one
+        // (" /x ") is accepted, consistent with buildSlashCommand.
+        const slash = typeof action.slash_command === "string"
+            ? action.slash_command.trim()
+            : "";
+        if (slash === "") {
+            errors.push({ code: "missing_slash_command", actionId: action.id });
+        }
+        else if (!SLASH_COMMAND_PATTERN.test(slash)) {
+            errors.push({
+                code: "invalid_slash_command",
+                actionId: action.id,
+                slash_command: action.slash_command,
+            });
+        }
+    }
+    return errors;
+}
+/**
+ * Validate `parameters` and `phase_parameters` for a single action.
+ * Pushes any errors into the shared `errors` list.
+ *
+ * Checks performed (matching plan § 6):
+ *  - Each ParamSchema is structurally well-formed.
+ *  - cli_flag / cli_flag_map values pass the CLI_FLAG_PATTERN allowlist.
+ *  - cli_flag_map values are non-empty (skip-emission == omission).
+ *  - cli_flag_map keys are subset of the enum (when both present).
+ *  - default values match type/pattern/enum.
+ *  - String pattern compiles as a valid regex.
+ *  - Names are unique within the same schema block.
+ *  - phase_parameters keys exist in actions.phases[].id.
+ *  - command_template contains {task.parameters?} when params are defined.
+ *  - Inverse warning when template has the placeholder but no params defined.
+ */
+function validateActionParameters(action, phaseIds, errors) {
+    const hasParams = !!action.parameters && action.parameters.length > 0;
+    const hasPhaseParams = !!action.phase_parameters &&
+        Object.values(action.phase_parameters).some((arr) => arr.length > 0);
+    const hasParamsPlaceholder = action.command_template?.includes(PARAMETERS_PLACEHOLDER) ?? false;
+    const hasInitialPromptPlaceholder = action.command_template?.includes(INITIAL_PROMPT_PLACEHOLDER) ?? false;
+    const hasAnyPlaceholder = hasParamsPlaceholder || hasInitialPromptPlaceholder;
+    // Template-Konsistenz: parameters defined but neither placeholder → fail.
+    // Either {task.parameters?} (legacy) or {task.initial_prompt} (new in
+    // iterate/fix-adopt-prompt-shape) satisfies the requirement.
+    if ((hasParams || hasPhaseParams) && !hasAnyPlaceholder) {
+        errors.push({
+            code: "missing_parameters_placeholder",
+            actionId: action.id,
+        });
+    }
+    // Inverse warning: a parameter-bearing placeholder is present but no
+    // parameters/phase_params defined. Only fires for the legacy
+    // {task.parameters?} (which would be a no-op); {task.initial_prompt}
+    // is meaningful even without parameters (it still emits the slash
+    // command itself).
+    if (!hasParams && !hasPhaseParams && hasParamsPlaceholder) {
+        errors.push({
+            code: "orphan_parameters_placeholder",
+            actionId: action.id,
+            severity: "warning",
+        });
+    }
+    if (action.parameters) {
+        validateParamArray(action.id, "parameters", action.parameters, errors);
+    }
+    if (action.phase_parameters) {
+        for (const [phaseKey, params] of Object.entries(action.phase_parameters)) {
+            if (!phaseIds.has(phaseKey)) {
+                errors.push({
+                    code: "unknown_phase_parameter_key",
+                    actionId: action.id,
+                    phaseKey,
+                });
+            }
+            validateParamArray(action.id, `phase_parameters.${phaseKey}`, params, errors);
+        }
+    }
+}
+function validateParamArray(actionId, blockLabel, params, errors) {
+    const seenNames = new Set();
+    for (const param of params) {
+        // Name pattern.
+        if (!PARAM_NAME_PATTERN.test(param.name)) {
+            errors.push({
+                code: "invalid_param_name",
+                actionId,
+                block: blockLabel,
+                name: param.name,
+            });
+        }
+        // Duplicate name within the same block.
+        if (seenNames.has(param.name)) {
+            errors.push({
+                code: "duplicate_param_name",
+                actionId,
+                block: blockLabel,
+                name: param.name,
+            });
+        }
+        seenNames.add(param.name);
+        // Type allowlist.
+        if (!VALID_PARAM_TYPES.has(param.type)) {
+            errors.push({
+                code: "invalid_param_type",
+                actionId,
+                name: param.name,
+                type: param.type,
+            });
+        }
+        // Enum required and non-empty when type === "enum".
+        if (param.type === "enum") {
+            if (!Array.isArray(param.enum) || param.enum.length === 0) {
+                errors.push({
+                    code: "invalid_param_enum",
+                    actionId,
+                    name: param.name,
+                });
+            }
+        }
+        // cli_flag pattern.
+        if (param.cli_flag !== undefined) {
+            if (!CLI_FLAG_PATTERN.test(param.cli_flag)) {
+                errors.push({
+                    code: "invalid_cli_flag",
+                    actionId,
+                    name: param.name,
+                    cli_flag: param.cli_flag,
+                });
+            }
+        }
+        // cli_flag_map values pattern + no empties + keys subset of enum.
+        if (param.cli_flag_map) {
+            const enumSet = new Set(param.enum ?? []);
+            for (const [key, flag] of Object.entries(param.cli_flag_map)) {
+                if (flag === "" || !CLI_FLAG_PATTERN.test(flag)) {
+                    errors.push({
+                        code: "invalid_cli_flag",
+                        actionId,
+                        name: param.name,
+                        cli_flag_map_key: key,
+                        cli_flag: flag,
+                    });
+                }
+                if (param.enum && !enumSet.has(key)) {
+                    errors.push({
+                        code: "invalid_cli_flag_map",
+                        actionId,
+                        name: param.name,
+                        cli_flag_map_key: key,
+                    });
+                }
+            }
+        }
+        // Pattern defensive compile.
+        if (param.pattern !== undefined) {
+            try {
+                // Defensive compile-check of a developer-authored action-schema pattern
+                // (trusted config, not user input) — no ReDoS-from-untrusted-input vector.
+                // nosemgrep: javascript.lang.security.audit.detect-non-literal-regexp.detect-non-literal-regexp
+                new RegExp(param.pattern);
+            }
+            catch (err) {
+                errors.push({
+                    code: "invalid_param_pattern",
+                    actionId,
+                    name: param.name,
+                    pattern: param.pattern,
+                    detail: String(err).slice(0, 200),
+                });
+            }
+        }
+        // Default value validation.
+        if (param.default !== undefined) {
+            if (!isDefaultValid(param)) {
+                errors.push({
+                    code: "invalid_default_value",
+                    actionId,
+                    name: param.name,
+                    default: param.default,
+                });
+            }
+        }
+        // iterate/fix-adopt-prompt-shape — boolean params with default:true
+        // are unrepresentable under opt-in semantics: an unchecked checkbox
+        // means "no flag emitted", so the default-true becomes effectively
+        // unreachable. Reject at load time so users don't author broken
+        // schemas. Required-boolean-default-true is rejected separately
+        // below (the only escape is required+default fallback for STRINGS).
+        if (param.type === "boolean" && param.default === true) {
+            errors.push({
+                code: "invalid_default_value",
+                actionId,
+                name: param.name,
+                default: param.default,
+                reason: "boolean default:true is unrepresentable under opt-in semantics",
+            });
+        }
+        // iterate/v030-five-ux-fixes (P6) — boolean + required is also
+        // unrepresentable under opt-in. The enable-checkbox IS the value for
+        // booleans, so a "required" boolean would either need to be forced-on
+        // (= effectively default:true, already rejected) or allow the user to
+        // submit unchecked (= unsatisfied required gate). Either way, the
+        // schema models a state that opt-in semantics can't reach. Hard-reject
+        // at load time so misauthored configs fail loudly instead of silently
+        // breaking the submit-gate at runtime.
+        if (param.type === "boolean" && param.required === true) {
+            errors.push({
+                code: "invalid_param_required",
+                actionId,
+                name: param.name,
+                reason: "boolean + required is unrepresentable under opt-in semantics",
+            });
+        }
+    }
+}
+function isDefaultValid(param) {
+    const def = param.default;
+    if (param.type === "boolean") {
+        return typeof def === "boolean";
+    }
+    if (typeof def !== "string")
+        return false;
+    if (param.type === "enum") {
+        return Array.isArray(param.enum) && param.enum.includes(def);
+    }
+    // type === "string"
+    if (param.pattern) {
+        try {
+            // `param.pattern` is a developer-authored action-schema pattern (trusted
+            // config, validated at load time), not user input. Semgrep false positive.
+            // nosemgrep: javascript.lang.security.audit.detect-non-literal-regexp.detect-non-literal-regexp
+            const re = new RegExp(param.pattern);
+            if (!re.test(def))
+                return false;
+        }
+        catch {
+            // Pattern invalid; default validity is unreachable — flagged via
+            // invalid_param_pattern separately.
+            return false;
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=actions-schema-validator.js.map

package/server/dist/core/actions-schema-validator.js.map

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

package/server/dist/core/actions-substitute.d.ts

@@ -0,0 +1,115 @@
+import type { ResolvedParam } from "../types/action-schema.js";
+export type ShellForm = "powershell" | "cmd" | "posix";
+export interface SubstitutionContext {
+    project: {
+        id: string;
+        path: string;
+    };
+    task: {
+        uuid: string;
+        title: string;
+        description?: string;
+        phase: string;
+        phase_label: string;
+        autonomy?: "guided" | "autonomous";
+        /**
+         * Pre-resolved CLI parameters from the route handler. Empty array
+         * and `undefined` are treated identically (no flags emitted).
+         * The substituter trusts cli_flag has been validated against the
+         * allowlist; values are still per-shell escaped here.
+         */
+        parameters?: ResolvedParam[];
+    };
+    pluginDirs: string[];
+    /**
+     * Allowlist of valid `{task.phase}` ids. Validated against the
+     * resolved `actions.phases[].id` set by the caller (route handler).
+     * When provided, substitutePlaceholders throws UnknownPhaseError on
+     * a mismatch.
+     */
+    allowedPhaseIds: Set<string>;
+    /**
+     * The action id being substituted — used only for error reporting
+     * (so InvalidPlaceholderError can surface actionId alongside the
+     * offending placeholder).
+     */
+    actionId: string;
+    /**
+     * iterate-2026-06-11-custom-action-slash-command — a CUSTOM action's declared
+     * slash command (action-schema `slash_command`, e.g. `/content-orchestrator`).
+     * Lets `{task.initial_prompt}` fuse slash + description into ONE positional
+     * for non-builtin ids. Ignored for builtins; absent/malformed → UnknownActionError.
+     */
+    slashCommand?: string;
+}
+export declare class InvalidPlaceholderError extends Error {
+    readonly placeholder: string;
+    readonly actionId: string;
+    readonly template: string;
+    constructor(placeholder: string, actionId: string, template: string);
+}
+export declare class InvalidTitleError extends Error {
+    constructor();
+}
+export declare class InvalidParameterError extends Error {
+    readonly cli_flag: string;
+    constructor(cli_flag: string, reason: string);
+}
+export declare class UnknownActionError extends Error {
+    readonly actionId: string;
+    constructor(actionId: string);
+}
+export declare class UnknownPhaseError extends Error {
+    readonly phase: string;
+    constructor(phase: string);
+}
+export declare class UnsupportedShellError extends Error {
+    readonly shellForm: string;
+    constructor(shellForm: string);
+}
+export declare const BUILTIN_INITIAL_PROMPT_ACTIONS: ReadonlySet<string>;
+export declare const SLASH_COMMAND_PATTERN: RegExp;
+/**
+ * Substitute placeholders in `template` for a given shell form. Throws
+ * on unknown placeholders, title newlines, parameter newlines, unknown
+ * phase ids, and unsupported shell forms. A multi-line task description
+ * is flattened (not rejected) — see flattenDescription.
+ */
+export declare function substitutePlaceholders(template: string, ctx: SubstitutionContext, shellForm: ShellForm): string;
+/**
+ * Parallel evaluation across all three shell forms. Useful for the
+ * launch route which returns `{powershell, cmd, posix}` to the client.
+ * Each form is evaluated independently so an escape-drift bug in one
+ * can't corrupt the others.
+ */
+export declare function substituteAllForms(template: string, ctx: SubstitutionContext): {
+    powershell: string;
+    cmd: string;
+    posix: string;
+};
+/**
+ * Convenience wrapper: the route layer's single entry point for producing
+ * the 3 shell forms from a command template + context. Delegates directly
+ * to substituteAllForms but reads better at the call site.
+ */
+export declare function buildExternalLaunchCommand(args: {
+    template: string;
+    ctx: SubstitutionContext;
+}): {
+    powershell: string;
+    cmd: string;
+    posix: string;
+};
+/**
+ * Dry-run validator used by the actions route to verify every
+ * `command_template` is substitution-safe at load time. Constructs a
+ * synthetic context with representative values and re-runs all three
+ * shell forms. Returns the first error encountered, or null on success.
+ *
+ * Does NOT raise UnknownPhaseError — the validator's job is to catch
+ * placeholder typos and shape corruption, not to fail-close when a
+ * phase allowlist is empty (e.g. during initial setup). The actual
+ * phase check runs at launch time with the real task state.
+ */
+export declare function validateTemplate(template: string, actionId: string, phaseIds: string[], slashCommand?: string): InvalidPlaceholderError | null;
+//# sourceMappingURL=actions-substitute.d.ts.map

package/server/dist/core/actions-substitute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions-substitute.d.ts","sourceRoot":"","sources":["../../src/core/actions-substitute.ts"],"names":[],"mappings":"AA4CA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,KAAK,GAAG,OAAO,CAAC;AAEvD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE;QACP,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,QAAQ,GAAG,YAAY,CAAC;QACnC;;;;;WAKG;QACH,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;KAC9B,CAAC;IACF,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB;;;;;OAKG;IACH,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBACd,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CASpE;AAED,qBAAa,iBAAkB,SAAQ,KAAK;;CAO3C;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBACd,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAK7C;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBACd,QAAQ,EAAE,MAAM;CAO7B;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBACX,KAAK,EAAE,MAAM;CAK1B;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBACf,SAAS,EAAE,MAAM;CAK9B;AAuDD,eAAO,MAAM,8BAA8B,EAAE,WAAW,CAAC,MAAM,CAI7D,CAAC;AAKH,eAAO,MAAM,qBAAqB,QAAgC,CAAC;AA8RnE;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,mBAAmB,EACxB,SAAS,EAAE,SAAS,GACnB,MAAM,CAwDR;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,mBAAmB,GACvB;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAMpD;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,mBAAmB,CAAC;CAC1B,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAErD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAAE,EAClB,YAAY,CAAC,EAAE,MAAM,GACpB,uBAAuB,GAAG,IAAI,CA+BhC"}