@canonical/pragma-cli 0.34.0 → 0.36.0

package/dist/src/capabilities/create/create.verb.js

@@ -0,0 +1,438 @@
+/**
+ * The `create` verbs — `component` / `package` / `application`, the THREE
+ * binding-level VerbSpecs (the MCP/covenant/reference grammar). Their params
+ * DERIVE mechanically from the generators' own prompts, projected at build
+ * time into `createSurface.generated.ts` — no hand mirrors, no flag aliases:
+ * the prompt names ARE the param/MCP-arg names, the FLAG tokens are
+ * `buildOptionInfo`'s registered forms (a default-true confirm registers
+ * ONLY `--no-<kebab>` — the covenant and the doc gate speak that vocabulary
+ * through the mount's registered-syntax seam, L-CIS-2), and `component`'s
+ * params are the FRAMEWORK UNION of its three declared leaves plus a
+ * required, positional `framework` enum derived from the tree segments
+ * (L-CIS). The CLI mounts the
+ * generator TREE itself (`create component react [component-path]` — see
+ * `mount.ts`); these specs are what MCP tools and the emitted surface read.
+ *
+ * LAZY DISPATCH (R9 + lazy-React): NOTHING of summon-core is imported
+ * statically — not even the UI-free projection subpath: this module sits on
+ * the capabilities barrel, so `--help` and `__complete` pay its import cost
+ * on every spawn, and the projection helpers it needs (`decideInteraction`,
+ * `refusalMessage`, `toKebabCase`, …) are only ever called inside `run`.
+ * `run` lazily `import()`s `pickGenerator` + summon-core + the projection, so
+ * `buildProgram` / `--help` / `__complete` / reads never load summon-core or
+ * the generators — and `create --yes` never loads React. The lazy-graph
+ * guard in `lazy.test.ts` pins the boundary.
+ */
+import { isAbsolute } from "node:path";
+import { BIN_NAME } from "../../constants.js";
+import { PragmaError } from "../../kernel/error/index.js";
+import { COMPONENT_FRAMEWORKS, CREATE_GENERATORS } from "./constants.js";
+import { createFormatters, formatCreatePlan } from "./create.render.js";
+import { CREATE_SURFACE } from "./createSurface.generated.js";
+import { generatorToParams, promptToParam } from "./generatorToVerbSpec.js";
+import { assertInsideWorkspace } from "./pathJail.js";
+// =============================================================================
+// Params, derived from the projected surface (createSurface.generated.ts)
+// =============================================================================
+/**
+ * `framework` — the component tree segments as a REQUIRED positional enum
+ * (`create component <framework>`), values derived from the declared paths.
+ * Deliberately NO default: summon has no default framework, and neither does
+ * the projection of it.
+ */
+const FRAMEWORK_PARAM = {
+    kind: "enum",
+    name: "framework",
+    doc: "Component framework — the tree segment (`create component <framework>`).",
+    values: COMPONENT_FRAMEWORKS,
+    required: true,
+    positional: true,
+};
+/**
+ * The FRAMEWORK UNION of the component leaves' prompts (A4): first-seen order
+ * over the declared framework order; a prompt identical across all declaring
+ * frameworks keeps its default; a prompt whose default DIFFERS across
+ * frameworks omits it (`required: false` — the selected framework's own
+ * prompt default applies at run time); a prompt not present on every
+ * framework gets its doc suffixed with the declaring frameworks.
+ */
+function unionComponentParams() {
+    const paths = CREATE_GENERATORS.component.paths;
+    const byName = new Map();
+    const order = [];
+    for (const commandPath of paths) {
+        const framework = commandPath.split("/")[1];
+        for (const prompt of surfaceFor(commandPath).prompts) {
+            let entry = byName.get(prompt.name);
+            if (!entry) {
+                entry = { prompt, frameworks: [], defaults: [] };
+                byName.set(prompt.name, entry);
+                order.push(prompt.name);
+            }
+            entry.frameworks.push(framework);
+            entry.defaults.push(prompt.default);
+        }
+    }
+    return order.map((name) => {
+        const entry = byName.get(name);
+        const universal = entry.frameworks.length === paths.length;
+        const agreed = entry.defaults.every((value) => Object.is(value, entry.defaults[0]));
+        const param = promptToParam(agreed ? entry.prompt : { ...entry.prompt, default: undefined });
+        return {
+            ...param,
+            ...(universal
+                ? {}
+                : { doc: `${param.doc} (frameworks: ${entry.frameworks.join(", ")})` }),
+            ...(agreed ? {} : { required: false }),
+        };
+    });
+}
+/** The projected surface for a declared path (fails loud on a stale build). */
+function surfaceFor(commandPath) {
+    const surface = CREATE_SURFACE[commandPath];
+    if (!surface) {
+        throw new Error(`createSurface.generated.ts carries no entry for declared path "${commandPath}" — rerun the build`);
+    }
+    return surface;
+}
+const componentParams = [
+    FRAMEWORK_PARAM,
+    ...unionComponentParams(),
+];
+const packageParams = generatorToParams(surfaceFor("package").prompts);
+const applicationParams = generatorToParams(surfaceFor("application/react").prompts);
+/** The path param each noun jails (package writes into a name-derived subdir). */
+const PATH_PARAM = {
+    component: "componentPath",
+    package: undefined,
+    application: "appPath",
+};
+/**
+ * The two value classes the shared prompt validators reject as workspace
+ * ESCAPES — absolute, and any `..` segment: exactly the jail's own
+ * non-symlink classes, which the round-9 reorder moved onto the validator
+ * tier. Used to keep the jail-tier `recovery` hint on those rejections.
+ */
+const isEscapeValue = (value) => typeof value === "string" &&
+    (isAbsolute(value) || value.split(/[/\\]/).includes(".."));
+// =============================================================================
+// The lazy run — the one-line summon↔pragma seam per invocation
+// =============================================================================
+/**
+ * True when a dynamic import failed because the module could not be RESOLVED.
+ * summon-core + the generators are now bundled into the binary, so this should
+ * not arise; {@link loadCreateRuntime} keeps it as a defensive backstop that
+ * turns a resolution failure into a clean gate rather than a raw "internal bug"
+ * report. Matched structurally across bun (`ResolveMessage`) and node
+ * (`ERR_MODULE_NOT_FOUND`) so a genuine runtime error still propagates.
+ */
+export function isModuleNotFound(cause) {
+    if (!cause || typeof cause !== "object")
+        return false;
+    const { code, name, message } = cause;
+    return (code === "ERR_MODULE_NOT_FOUND" ||
+        code === "MODULE_NOT_FOUND" ||
+        name === "ResolveMessage" ||
+        (typeof message === "string" &&
+            /cannot find (module|package)/i.test(message)));
+}
+/**
+ * Load the create runtime — the generator selector and summon-core.
+ *
+ * Lazy, and the specifiers stay STATIC so they remain analysable: importing
+ * these pulls summon-core and with it React, which must stay off `--help`,
+ * completion and every read. The generators load their own templates from their
+ * own packages on first `generate()`.
+ *
+ * A resolution failure means a broken or pruned install, and
+ * {@link isModuleNotFound} turns it into a clean refusal rather than an
+ * internal-bug report.
+ */
+async function loadCreateRuntime() {
+    try {
+        const [summon, projection, pick] = await Promise.all([
+            import("@canonical/summon-core"),
+            import("@canonical/summon-core/projection"),
+            import("./pickGenerator.js"),
+        ]);
+        return { pickGenerator: pick.pickGenerator, summon, projection };
+    }
+    catch (cause) {
+        if (isModuleNotFound(cause)) {
+            throw new PragmaError({
+                code: "UNSUPPORTED",
+                message: "`create` cannot load its generator runtime — the `@canonical/summon-*` packages it depends on are missing from this install.",
+                recovery: {
+                    message: `Reinstall ${BIN_NAME} to restore its generator dependencies.`,
+                },
+            });
+        }
+        throw cause;
+    }
+}
+/** The create noun that declares a command path. */
+function kindOf(commandPath) {
+    for (const [kind, binding] of Object.entries(CREATE_GENERATORS)) {
+        if (binding.paths.includes(commandPath)) {
+            return kind;
+        }
+    }
+    throw PragmaError.internalError(`undeclared command path ${commandPath}`);
+}
+/**
+ * Build the `create` Task for one invocation of a declared COMMAND PATH: pick
+ * the generator, pre-validate the provided answers (the shared validator
+ * tier), jail its output path (the host backstop, after validation),
+ * decide the interaction mode (the ONE shared decision — same function, same
+ * inputs as the summon bin), and return `execute` wired to the strategy the
+ * mode names.
+ *
+ * `params` are the EXPLICIT answers only (CLI flags/positional; MCP args
+ * carry schema defaults, which is that transport's contract). MCP keeps its
+ * plan-first/confirm path untouched — `decideInteraction` is CLI-only.
+ *
+ * @param commandPath - The declared command path (`component/react`, …).
+ * @param params - The provided answers for this invocation.
+ * @param rt - The pragma runtime.
+ * @returns A `Promise<Task<GeneratorResult>>` (the union's third arm) the
+ *   dispatcher/MCP handler awaits into a Task before interpreting.
+ */
+export async function runCreate(commandPath, params, rt) {
+    // Lazy: importing these pulls summon-core (and with it React) — kept off every
+    // non-create path. The specifiers stay static so they remain analysable; the
+    // embedded `.ejs` manifest is injected here as the disk read's fallback.
+    const { pickGenerator, summon, projection } = await loadCreateRuntime();
+    const generator = pickGenerator(commandPath);
+    const kind = kindOf(commandPath);
+    // The tree segment is not an answer: drop a stray `framework` key so the
+    // generators (whose prompts never include it) see only their own answers.
+    const answers = { ...params };
+    delete answers.framework;
+    // Reject a flag/arg-provided answer that fails its prompt's own constraint,
+    // with a clean INVALID_INPUT (execute re-validates as a backstop). Runs
+    // BEFORE the jail: the path prompts' own validators reject absolute/`..`
+    // escapes, so an escaping output path fails the SHARED validator line in
+    // both hosts (the cross-CLI matrix) and the jail below stays the backstop
+    // its docblock claims.
+    const pathParam = PATH_PARAM[kind];
+    const invalid = summon.validateAnswers(generator.prompts, answers);
+    if (invalid !== null) {
+        // A rejection of the JAILED path param's escape classes (absolute /
+        // `..` — the two the round-9 reorder moved off the jail) attaches ONE
+        // workspace hint to BOTH classes — the jail's `..`-branch message —
+        // deliberately NOT reproducing the jail's per-branch hints (its
+        // absolute branch says "Use a path relative to the current
+        // directory."; those stay the jail's own, pinned in pathJail.test.ts).
+        // The message stays the validator's — the shared cross-host line. A
+        // non-escape rejection of the same param (e.g. casing) never carried
+        // recovery and still does not.
+        const escaped = pathParam !== undefined &&
+            invalid.startsWith(`Invalid --${projection.toKebabCase(pathParam)} `) &&
+            isEscapeValue(answers[pathParam]);
+        throw new PragmaError({
+            code: "INVALID_INPUT",
+            message: invalid,
+            ...(escaped
+                ? { recovery: { message: "The path must stay inside the workspace." } }
+                : {}),
+        });
+    }
+    // SEC-2: reject a path escaping the workspace BEFORE any effect runs — the
+    // host-level backstop behind the validators, and the only tier that catches
+    // a symlink RESOLVING outside the workspace.
+    if (pathParam)
+        assertInsideWorkspace(pathParam, answers[pathParam], rt.cwd);
+    // An ABSENT interaction context defaults to `yes: false` — nothing may
+    // silently auto-apply just because a caller forgot to say how it is driven.
+    const { isTTY, transport, yes, signal, abort } = rt.interaction ?? {
+        isTTY: false,
+        transport: "cli",
+        yes: false,
+    };
+    const stamp = summon.createGeneratorStamp(generator);
+    // MCP: params-or-error, plan-first/confirm — untouched by the decision
+    // table (an MCP call is never a terminal session).
+    if (transport === "mcp") {
+        const prompt = summon.mcpPrompt(answers);
+        rt.exec = {
+            cwd: rt.cwd,
+            promptHandler: prompt,
+            onEffectStart: summon.createStampOnEffectStart(stamp),
+            onLog: (_level, message) => process.stderr.write(`${message}\n`),
+            signal,
+        };
+        return summon.execute(generator, { prompt, params: answers, signal });
+    }
+    // The ONE interaction decision (R2) — the same function, over the same five
+    // inputs, as the summon bin. The mount refuses before ever loading this
+    // runtime; re-deriving here keeps direct kernel callers honest too.
+    const { mode } = projection.decideInteraction({
+        dryRun: rt.mutation?.preview === true,
+        undo: rt.mutation?.undo === true,
+        yes: yes === true,
+        isTTY: isTTY === true,
+        explicitComplete: projection.explicitAnswersComplete(generator.prompts, answers),
+    });
+    if (mode === "refuse") {
+        throw new PragmaError({
+            code: "INVALID_INPUT",
+            message: projection.refusalMessage(projection.missingExplicitFlags(generator.prompts, answers)),
+        });
+    }
+    // Wizard: ask exactly the pending prompts — the provided answers are
+    // explicit and pre-seeded; `collectAnswers` skips them and evaluates each
+    // conditional against the answers as they land (wizard-script parity).
+    if (mode === "wizard") {
+        // `onCancel` (H2): an in-Ink Ctrl-C during execution aborts the run so the
+        // interpreter stops writing — raw mode swallows the SIGINT, so the wizard
+        // drives the abort. Shared with setup by construction.
+        // `cwd` also reaches the wizard: its confirm-gate preview reads the same
+        // jail-checked write root the interpreter resolves effect paths against.
+        const session = summon.inkPrompt(generator, {
+            signal,
+            onCancel: abort,
+            cwd: rt.cwd,
+            // Flag-provided answers reach the wizard too: without the seed the
+            // confirm gate previews with them missing (undefined paths, wrong plan).
+            initialAnswers: answers,
+        });
+        // Thread the per-call write root: the interpreter resolves the generator's
+        // relative output paths against `rt.cwd` — the SAME dir the SEC-2 jail
+        // validated above — so the write can never escape the checked directory.
+        rt.exec = {
+            cwd: rt.cwd,
+            promptHandler: session.promptHandler,
+            onEffectStart: summon.createStampOnEffectStart(stamp, session.onEffectStart),
+            onEffectComplete: session.onEffectComplete,
+            onLog: session.onLog,
+            dispose: session.dispose,
+            signal,
+        };
+        return summon.execute(generator, {
+            prompt: session.promptHandler,
+            params: answers,
+            signal,
+        });
+    }
+    // run / batch-dry-run / batch-undo: flags + defaults, never a wizard —
+    // `autoPrompt` resolves each unprovided prompt to its default or fails
+    // loudly on a missing required answer. Same per-call write root as the
+    // wizard branch: `rt.cwd` feeds both the SEC-2 jail and the interpreter's
+    // effect-path base, atomically.
+    const prompt = summon.autoPrompt(answers);
+    rt.exec = {
+        cwd: rt.cwd,
+        promptHandler: prompt,
+        onEffectStart: summon.createStampOnEffectStart(stamp),
+        onLog: (_level, message) => process.stderr.write(`${message}\n`),
+        signal,
+    };
+    return summon.execute(generator, { prompt, params: answers, signal });
+}
+/**
+ * The shared capability: storeless, mutating, interactive, MCP-exposed.
+ *
+ * `destructive: false` is load-bearing (D4): create only WRITES NEW files, so it
+ * is explicitly non-destructive. Without it `annotationsFor` emits no
+ * `destructiveHint`, and MCP clients default an unset hint on a non-read-only
+ * tool to `true` — advertising create as destructive, the opposite of intent.
+ */
+export const CREATE_CAPABILITY = {
+    needsStore: false,
+    mutates: true,
+    destructive: false,
+    interactive: true,
+    mcp: {
+        expose: true,
+        annotations: { readOnlyHint: false, openWorldHint: false },
+    },
+};
+/**
+ * The shared output spec: the outcome formatters plus the dry-run seam.
+ *
+ * ONE constant because there are TWO specs per leaf — the binding-level verbs
+ * below (what MCP and the emitted surface read) and the per-leaf spec the
+ * mount synthesizes for `create component react …` (what a user actually
+ * runs). They describe the same generation, so a preview that reached only one
+ * of them would be a preview the CLI never showed.
+ *
+ * `formatPlan` renders through summon's own effect formatter instead of the
+ * kernel's raw dump, so the two bins describe the identical tree they write
+ * identically. `planData` stays unset — the effects the preview records ARE
+ * the plan — which is what leaves the `--format json` dry-run body exactly as
+ * it was.
+ *
+ * It resolves a PROMISE because {@link formatCreatePlan} loads that formatter
+ * behind a dynamic `import()`: this constant is reachable from the
+ * capabilities barrel, and the whole point of the lazy-dispatch boundary above
+ * is that nothing on that graph pays for summon-core on a `--help` spawn.
+ */
+export const CREATE_OUTPUT = {
+    formatters: createFormatters,
+    formatPlan: (_planData, effects, verbose) => formatCreatePlan(effects, verbose),
+};
+/**
+ * Build a create verb. `run` presents `Promise<Task<R>>` through the `Task<R>`
+ * arm by an honest cast at this one site (mirroring `sources update`): a literal
+ * `Promise<Task<R>>` arm in the union would poison async read-verb inference.
+ *
+ * The binding-level `run` maps its kind (+ `framework` for component) onto
+ * the declared command path — the MCP transport's view of the tree.
+ */
+function createVerb(kind, summary, params, examples) {
+    return {
+        path: ["create", kind],
+        summary,
+        params,
+        output: CREATE_OUTPUT,
+        examples,
+        capability: CREATE_CAPABILITY,
+        run: (params_, rt) => {
+            let commandPath;
+            if (kind === "component") {
+                const framework = String(params_.framework ?? "");
+                if (!COMPONENT_FRAMEWORKS.includes(framework)) {
+                    throw PragmaError.invalidInput("framework", framework, {
+                        validOptions: [...COMPONENT_FRAMEWORKS],
+                    });
+                }
+                commandPath = `component/${framework}`;
+            }
+            else {
+                commandPath = CREATE_GENERATORS[kind].paths[0];
+            }
+            return runCreate(commandPath, params_, rt);
+        },
+    };
+}
+/**
+ * The `create` verbs, one per declared generator binding — so adding a binding
+ * to {@link CREATE_GENERATORS} without surfacing it is a type error rather than
+ * a silent no-op. Key order is authoring order, which `index.ts` preserves into
+ * the command tree, `--help` and the emitted surface.
+ */
+export const createVerbs = {
+    component: createVerb("component", "Scaffold a React, Svelte, or Lit component.", componentParams, [
+        {
+            cmd: `${BIN_NAME} create component react src/components/Button`,
+            note: "React component with tests, stories, and styles",
+        },
+        {
+            cmd: `${BIN_NAME} create component svelte src/lib/Card --dry-run`,
+            note: "preview the files without writing",
+        },
+    ]),
+    package: createVerb("package", "Scaffold a new npm package for the monorepo.", packageParams, [
+        {
+            cmd: `${BIN_NAME} create package --name @canonical/my-lib --type library`,
+        },
+        {
+            cmd: `${BIN_NAME} create package --name @canonical/my-tool --no-run-install`,
+        },
+    ]),
+    application: createVerb("application", "Scaffold a full React application with SSR and routing.", applicationParams, [
+        { cmd: `${BIN_NAME} create application react my-app` },
+        { cmd: `${BIN_NAME} create application react my-app --relay` },
+    ]),
+};
+//# sourceMappingURL=create.verb.js.map

package/dist/src/capabilities/create/create.verb.js.map

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

package/dist/src/capabilities/create/createHelp.js

@@ -0,0 +1,47 @@
+/**
+ * Pragma's presentation of a `create` leaf's grouped help — the host half of
+ * the summon-core help seam (`CommanderHost.renderHelp`): the projection
+ * decides the STRUCTURE (usage, description, the option groups, the host's
+ * flag rows), this module effects pragma's house style over it, composed from
+ * the same kernel primitives every other help page uses
+ * (`kernel/project/cli/helpFormat.ts`) — a dim `Usage:` label, bold headings,
+ * cyan-term/dim-description columns. Colour therefore rides the kernel's one
+ * gate (chalk's TTY detection plus the style seam's `NO_COLOR` zeroing), so
+ * piped output — the cross-CLI structural-parity surface — stays plain bytes.
+ */
+import { helpColumns, helpHeading, helpUsage, } from "../../kernel/project/cli/helpFormat.js";
+/**
+ * A row's description with the shared renderer's default-value suffix — the
+ * same bytes `renderGroupedHelp` appends, so the structural-parity cells
+ * compare the fact, not two spellings of it.
+ */
+function describeOption(description, defaultValue) {
+    return defaultValue
+        ? `${description} (default: ${JSON.stringify(defaultValue)})`
+        : description;
+}
+/** Render a `create` leaf's grouped help in pragma's house style. */
+export const renderCreateHelp = (usage, description, groups, hostFlags) => {
+    const sections = [
+        ["Global Options", hostFlags.map((flag) => [flag.flags, flag.description])],
+        ...[...groups].map(([groupName, options]) => [
+            groupName,
+            options.map((opt) => [
+                opt.flags,
+                describeOption(opt.description, opt.defaultValue),
+            ]),
+        ]),
+    ];
+    // One column width across ALL sections so the flag column aligns section to
+    // section (the root help does the same for its noun column).
+    const width = Math.max(...sections.flatMap(([, rows]) => rows.map(([term]) => term.length)), 0);
+    const lines = [helpUsage(usage)];
+    if (description)
+        lines.push("", description);
+    for (const [heading, rows] of sections) {
+        lines.push("", helpHeading(heading), ...helpColumns(rows, width));
+    }
+    // Commander prints `formatHelp`'s return verbatim — terminate the page.
+    return `${lines.join("\n")}\n`;
+};
+//# sourceMappingURL=createHelp.js.map

package/dist/src/capabilities/create/createHelp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createHelp.js","sourceRoot":"","sources":["../../../../src/capabilities/create/createHelp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EACL,WAAW,EACX,WAAW,EACX,SAAS,GACV,MAAM,wCAAwC,CAAC;AAQhD;;;;GAIG;AACH,SAAS,cAAc,CAAC,WAAmB,EAAE,YAAqB;IAChE,OAAO,YAAY;QACjB,CAAC,CAAC,GAAG,WAAW,cAAc,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,GAAG;QAC7D,CAAC,CAAC,WAAW,CAAC;AAClB,CAAC;AAED,qEAAqE;AACrE,MAAM,CAAC,MAAM,gBAAgB,GAA6B,CACxD,KAAK,EACL,WAAW,EACX,MAAM,EACN,SAAS,EACT,EAAE;IACF,MAAM,QAAQ,GAAkB;QAC9B,CAAC,gBAAgB,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;QAC3E,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,CAChB,CAAC,CAAC,SAAS,EAAE,OAAO,CAAC,EAAe,EAAE,CAAC;YACrC,SAAS;YACT,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC;gBACnB,GAAG,CAAC,KAAK;gBACT,cAAc,CAAC,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC,YAAY,CAAC;aAClD,CAAC;SACH,CACF;KACF,CAAC;IAEF,4EAA4E;IAC5E,6DAA6D;IAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CACpB,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EACpE,CAAC,CACF,CAAC;IAEF,MAAM,KAAK,GAAa,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3C,IAAI,WAAW;QAAE,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,WAAW,CAAC,CAAC;IAC7C,KAAK,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,QAAQ,EAAE,CAAC;QACvC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,WAAW,CAAC,OAAO,CAAC,EAAE,GAAG,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;IACpE,CAAC;IACD,wEAAwE;IACxE,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;AACjC,CAAC,CAAC"}