@caelo-cms/provisioning 0.10.47 → 0.10.49

package/dist/agent/systemd.js

@@ -0,0 +1,171 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * Installs, re-pins and removes the agent's systemd --user units (#696
+ * Phase 4c). Every command goes through a {@link HostRunner} and the unit
+ * directory is a parameter, so tests run against a fake and a temp dir —
+ * nothing here touches the real systemd of the machine running the tests.
+ *
+ * User units stop with the user's last session unless the user "lingers";
+ * {@link installAgentUnits} turns lingering on (allowed for oneself on
+ * systemd-logind's default policy) and, where it may not, says which one
+ * command an administrator runs.
+ */
+import { closeSync, ftruncateSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync, writeSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { agentServiceUnit, agentTimerUnit, pinnedAgentVersion, } from "./units.js";
+/** The real host: this user's systemd user-unit directory. */
+export function currentAgentHost(runner) {
+    const config = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+    return {
+        runner,
+        unitDir: join(config, "systemd", "user"),
+        user: process.env.USER || process.env.LOGNAME || "",
+        platform: process.platform,
+    };
+}
+/**
+ * Why the agent cannot be installed on this host, or null. Linux with a
+ * systemd user manager is the supported target; macOS (Docker Desktop) is
+ * a development setup, and there `upgrade` is run by hand.
+ */
+export async function agentHostProblem(host) {
+    if (host.platform !== "linux") {
+        return `the update agent runs on Linux hosts with systemd (this is ${host.platform}). Install updates with the upgrade command instead.`;
+    }
+    const r = await host.runner.run(["systemctl", "--user", "show-environment"]);
+    if (r.exitCode !== 0) {
+        return `systemd's user manager is not reachable (\`systemctl --user\`: ${r.stderr.trim().slice(0, 200) || `exit ${r.exitCode}`}). Log in to the host as this user directly (not via \`su\`), or install updates with the upgrade command.`;
+    }
+    return null;
+}
+/** `<unitDir>/<name>.service` + `.timer`. */
+export function agentUnitPaths(host, name) {
+    return {
+        service: join(host.unitDir, `${name}.service`),
+        timer: join(host.unitDir, `${name}.timer`),
+    };
+}
+async function systemctl(host, ...args) {
+    const r = await host.runner.run(["systemctl", "--user", ...args]);
+    return r.exitCode === 0
+        ? null
+        : `systemctl --user ${args.join(" ")}: ${r.stderr.trim().slice(0, 300) || `exit ${r.exitCode}`}`;
+}
+/**
+ * Write both units, reload, enable + start the timer, and make sure the
+ * user lingers. Idempotent: re-running rewrites the same files.
+ */
+export async function installAgentUnits(spec, host) {
+    const paths = agentUnitPaths(host, spec.name);
+    try {
+        mkdirSync(host.unitDir, { recursive: true });
+        writeFileSync(paths.service, agentServiceUnit(spec), { mode: 0o644 });
+        writeFileSync(paths.timer, agentTimerUnit(spec), { mode: 0o644 });
+    }
+    catch (e) {
+        return { ok: false, error: `could not write the units: ${e.message}` };
+    }
+    for (const args of [["daemon-reload"], ["enable", "--now", `${spec.name}.timer`]]) {
+        const error = await systemctl(host, ...args);
+        if (error)
+            return { ok: false, error };
+    }
+    const warnings = [];
+    const linger = await ensureLinger(host);
+    if (linger)
+        warnings.push(linger);
+    return { ok: true, warnings };
+}
+/** Lingering on for the user; returns a warning when it could not be. */
+async function ensureLinger(host) {
+    if (!host.user)
+        return "could not tell the user name, so lingering was not checked";
+    const show = await host.runner.run(["loginctl", "show-user", host.user, "--property=Linger"]);
+    if (show.exitCode === 0 && show.stdout.trim() === "Linger=yes")
+        return null;
+    const enable = await host.runner.run(["loginctl", "enable-linger", host.user]);
+    if (enable.exitCode === 0)
+        return null;
+    return `the agent only runs while ${host.user} is logged in: lingering could not be switched on (${enable.stderr.trim().slice(0, 200) || `exit ${enable.exitCode}`}). Have an administrator run \`sudo loginctl enable-linger ${host.user}\` once.`;
+}
+/** The release the installed service runs, or null when it is not installed. */
+export function installedAgentVersion(host, name) {
+    const { service } = agentUnitPaths(host, name);
+    try {
+        return pinnedAgentVersion(readFileSync(service, "utf8"));
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return null;
+        throw e;
+    }
+}
+/**
+ * Re-pin an installed agent to `spec.version` (after an update). Does
+ * nothing when the agent is not installed.
+ */
+export async function repinAgentUnits(spec, host) {
+    const { service } = agentUnitPaths(host, spec.name);
+    try {
+        // "r+" opens only an existing file (ENOENT otherwise), so the check and
+        // the rewrite are one step — no window for the file to change between.
+        const fd = openSync(service, "r+");
+        try {
+            ftruncateSync(fd, 0);
+            writeSync(fd, agentServiceUnit(spec), 0, "utf8");
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch (e) {
+        if (e.code === "ENOENT") {
+            return { ok: true, warnings: [], installed: false };
+        }
+        return { ok: false, error: `could not rewrite ${service}: ${e.message}` };
+    }
+    const error = await systemctl(host, "daemon-reload");
+    return error ? { ok: false, error } : { ok: true, warnings: [], installed: true };
+}
+/** Stop + disable the timer and delete both units. */
+export async function uninstallAgentUnits(host, name) {
+    const warnings = [];
+    const disabled = await systemctl(host, "disable", "--now", `${name}.timer`);
+    if (disabled)
+        warnings.push(disabled);
+    const paths = agentUnitPaths(host, name);
+    rmSync(paths.service, { force: true });
+    rmSync(paths.timer, { force: true });
+    const reload = await systemctl(host, "daemon-reload");
+    if (reload)
+        warnings.push(reload);
+    return { ok: true, warnings };
+}
+/** `systemctl --user status` of both units (text for the terminal). */
+export async function agentUnitStatus(host, name) {
+    const r = await host.runner.run([
+        "systemctl",
+        "--user",
+        "--no-pager",
+        "status",
+        `${name}.timer`,
+        `${name}.service`,
+    ]);
+    // status exits 3 for an inactive oneshot service; the text is what matters.
+    return (r.stdout || r.stderr).trim();
+}
+/** The argv that shows the agent's log (journald). */
+export function agentLogsArgv(name, opts) {
+    return [
+        "journalctl",
+        "--user",
+        "--no-pager",
+        "-u",
+        `${name}.service`,
+        "-n",
+        String(opts.lines),
+        ...(opts.follow ? ["-f"] : []),
+    ];
+}
+//# sourceMappingURL=systemd.js.map

package/dist/agent/systemd.js.map

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

package/dist/agent/units.d.ts

@@ -0,0 +1,44 @@
+/** Everything the units name; all paths absolute. */
+export interface AgentUnitSpec {
+    /** Unit base name (`caelo-agent-<domain>-<hash>`), see {@link agentUnitName}. */
+    readonly name: string;
+    readonly domain: string;
+    /** The provisioning release the service runs. */
+    readonly version: string;
+    /** The `bun` binary (the one that ran `init`). */
+    readonly bunPath: string;
+    /** The install's `.caelo/` directory. */
+    readonly caeloDir: string;
+    /** Where `.caelo/` lives (the service's working directory). */
+    readonly workDir: string;
+    /** PATH for the service: docker, cosign and bun must be on it. */
+    readonly path: string;
+    /** DOCKER_HOST of the installing shell (rootless Docker), when set. */
+    readonly dockerHost?: string;
+    /**
+     * The provenance-verified CLI of {@link version} (agent/cli-provenance.ts)
+     * — what an update re-pins the agent to. Without it the service runs the
+     * release the operator installed with (`bun x`, as they did by hand).
+     */
+    readonly cliPath?: string;
+}
+/** The longest a single run (one full upgrade) may take before systemd stops it. */
+export declare const AGENT_RUN_TIMEOUT_MINUTES = 80;
+/**
+ * `caelo-agent-<domain>-<hash>`: one agent per install, several installs
+ * per host possible. The slug is for people; the hash of the install's
+ * `.caelo/` path keeps two installs apart even when their slugs collide
+ * (`a.b.example.com` vs `a-b.example.com`).
+ */
+export declare function agentUnitName(domain: string, caeloDir: string): string;
+/** The package the service runs, pinned. */
+export declare function agentPackageRef(version: string): string;
+/** The argv of one agent run (also what `agent status` shows). */
+export declare function agentRunArgv(spec: Pick<AgentUnitSpec, "bunPath" | "version" | "cliPath">): string[];
+/** `<name>.service`. */
+export declare function agentServiceUnit(spec: AgentUnitSpec): string;
+/** `<name>.timer`. */
+export declare function agentTimerUnit(spec: Pick<AgentUnitSpec, "name" | "domain">): string;
+/** The release an installed service file runs, or null when it names none. */
+export declare function pinnedAgentVersion(serviceUnit: string): string | null;
+//# sourceMappingURL=units.d.ts.map

package/dist/agent/units.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"units.d.ts","sourceRoot":"","sources":["../../src/agent/units.ts"],"names":[],"mappings":"AA4BA,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,oFAAoF;AACpF,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAStE;AAED,4CAA4C;AAC5C,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKvD;AAmBD,kEAAkE;AAClE,wBAAgB,YAAY,CAC1B,IAAI,EAAE,IAAI,CAAC,aAAa,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC,GAC3D,MAAM,EAAE,CAGV;AAED,wBAAwB;AACxB,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAuB5D;AAED,sBAAsB;AACtB,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,QAAQ,CAAC,GAAG,MAAM,CAoBnF;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMrE"}

package/dist/agent/units.js

@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * The systemd units of `caelo-agent` (#696 Phase 4c), as text. Pure, so the
+ * exact files are unit-tested; agent/systemd.ts installs them.
+ *
+ * Why a systemd --user timer on the host, and not a container: the agent
+ * has to run `docker compose` for the install, and the only way a container
+ * could is the Docker socket — root on the host for anything that gets into
+ * that container (Watchtower, the usual answer, was archived in 2025 and
+ * verifies no signatures). The agent instead runs as the operator who ran
+ * `init`, a member of the `docker` group like that operator already is to
+ * run Compose at all; nothing new gets Docker access, and no unit runs as
+ * root.
+ *
+ * Shape: a oneshot service (one poll: heartbeat, then claim and run at most
+ * one request) started by a timer every {@link PLATFORM_UPDATE_AGENT_POLL_SECONDS}
+ * seconds after the previous run ended — systemd never starts the service
+ * while a run (an upgrade can take many minutes) is still active.
+ *
+ * The service runs the provisioning CLI pinned to an exact release
+ * (`bun x --bun @caelo-cms/provisioning@<version> agent run`); a successful
+ * update re-pins it to the release it installed.
+ */
+import { createHash } from "node:crypto";
+import { PLATFORM_UPDATE_AGENT_POLL_SECONDS } from "@caelo-cms/shared";
+/** The longest a single run (one full upgrade) may take before systemd stops it. */
+export const AGENT_RUN_TIMEOUT_MINUTES = 80;
+/**
+ * `caelo-agent-<domain>-<hash>`: one agent per install, several installs
+ * per host possible. The slug is for people; the hash of the install's
+ * `.caelo/` path keeps two installs apart even when their slugs collide
+ * (`a.b.example.com` vs `a-b.example.com`).
+ */
+export function agentUnitName(domain, caeloDir) {
+    const slug = domain
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60);
+    if (!slug)
+        throw new Error(`cannot name the agent unit after domain ${JSON.stringify(domain)}`);
+    const hash = createHash("sha256").update(caeloDir).digest("hex").slice(0, 8);
+    return `caelo-agent-${slug}-${hash}`;
+}
+/** The package the service runs, pinned. */
+export function agentPackageRef(version) {
+    if (!/^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$/.test(version)) {
+        throw new Error(`not a release version: ${JSON.stringify(version)}`);
+    }
+    return `@caelo-cms/provisioning@${version}`;
+}
+/**
+ * One systemd word: double-quoted, `%` escaped (systemd specifiers). Values
+ * with a quote, backslash or control character are refused rather than
+ * escaped — they are paths and versions, and such a path is a mistake.
+ */
+function word(value) {
+    if (!value || /["\\\p{Cc}]/u.test(value)) {
+        throw new Error(`cannot put ${JSON.stringify(value)} into a systemd unit`);
+    }
+    return `"${value.replace(/%/g, "%%")}"`;
+}
+/** `Environment="KEY=value"`. */
+function environment(key, value) {
+    return `Environment=${word(`${key}=${value}`)}`;
+}
+/** The argv of one agent run (also what `agent status` shows). */
+export function agentRunArgv(spec) {
+    if (spec.cliPath)
+        return [spec.bunPath, spec.cliPath, "agent", "run"];
+    return [spec.bunPath, "x", "--bun", agentPackageRef(spec.version), "agent", "run"];
+}
+/** `<name>.service`. */
+export function agentServiceUnit(spec) {
+    return [
+        "# SPDX-License-Identifier: MPL-2.0",
+        "# Generated by cms-provision (agent install) — do not edit; re-run it instead.",
+        "[Unit]",
+        `Description=Caelo update agent for ${spec.domain}`,
+        "Documentation=https://caelo-cms.com/install-self-hosted",
+        "After=network-online.target",
+        "",
+        "[Service]",
+        "Type=oneshot",
+        `WorkingDirectory=${word(spec.workDir)}`,
+        environment("CAELO_SELF_HOSTED_DIR", spec.caeloDir),
+        environment("PATH", spec.path),
+        ...(spec.dockerHost ? [environment("DOCKER_HOST", spec.dockerHost)] : []),
+        `ExecStart=${agentRunArgv(spec).map(word).join(" ")}`,
+        `TimeoutStartSec=${AGENT_RUN_TIMEOUT_MINUTES}min`,
+        // Backups, config.json and the lock file: the operator's only.
+        "UMask=0077",
+        "NoNewPrivileges=yes",
+        "Nice=5",
+        "",
+    ].join("\n");
+}
+/** `<name>.timer`. */
+export function agentTimerUnit(spec) {
+    return [
+        "# SPDX-License-Identifier: MPL-2.0",
+        "# Generated by cms-provision (agent install) — do not edit; re-run it instead.",
+        "[Unit]",
+        `Description=Poll for Caelo updates for ${spec.domain}`,
+        "",
+        "[Timer]",
+        // The first poll a minute after the timer starts (install, boot);
+        // then a minute after each run ends.
+        "OnActiveSec=1min",
+        "OnBootSec=2min",
+        `OnUnitInactiveSec=${PLATFORM_UPDATE_AGENT_POLL_SECONDS}s`,
+        "AccuracySec=5s",
+        `Unit=${spec.name}.service`,
+        "",
+        "[Install]",
+        "WantedBy=timers.target",
+        "",
+    ].join("\n");
+}
+/** The release an installed service file runs, or null when it names none. */
+export function pinnedAgentVersion(serviceUnit) {
+    const exec = /^ExecStart=.*$/m.exec(serviceUnit)?.[0] ?? "";
+    const m = /@caelo-cms\/provisioning@([0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?)"/.exec(exec) ??
+        /\/caelo-([0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?)\/node_modules\//.exec(exec);
+    return m?.[1] ?? null;
+}
+//# sourceMappingURL=units.js.map

package/dist/agent/units.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"units.js","sourceRoot":"","sources":["../../src/agent/units.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,kCAAkC,EAAE,MAAM,mBAAmB,CAAC;AA2BvE,oFAAoF;AACpF,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,QAAgB;IAC5D,MAAM,IAAI,GAAG,MAAM;SAChB,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAChB,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAChG,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7E,OAAO,eAAe,IAAI,IAAI,IAAI,EAAE,CAAC;AACvC,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,IAAI,CAAC,4CAA4C,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,2BAA2B,OAAO,EAAE,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,SAAS,IAAI,CAAC,KAAa;IACzB,IAAI,CAAC,KAAK,IAAI,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC;AAC1C,CAAC;AAED,iCAAiC;AACjC,SAAS,WAAW,CAAC,GAAW,EAAE,KAAa;IAC7C,OAAO,eAAe,IAAI,CAAC,GAAG,GAAG,IAAI,KAAK,EAAE,CAAC,EAAE,CAAC;AAClD,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,YAAY,CAC1B,IAA4D;IAE5D,IAAI,IAAI,CAAC,OAAO;QAAE,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;IACtE,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;AACrF,CAAC;AAED,wBAAwB;AACxB,MAAM,UAAU,gBAAgB,CAAC,IAAmB;IAClD,OAAO;QACL,oCAAoC;QACpC,gFAAgF;QAChF,QAAQ;QACR,sCAAsC,IAAI,CAAC,MAAM,EAAE;QACnD,yDAAyD;QACzD,6BAA6B;QAC7B,EAAE;QACF,WAAW;QACX,cAAc;QACd,oBAAoB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE;QACxC,WAAW,CAAC,uBAAuB,EAAE,IAAI,CAAC,QAAQ,CAAC;QACnD,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC;QAC9B,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,aAAa,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACzE,aAAa,YAAY,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE;QACrD,mBAAmB,yBAAyB,KAAK;QACjD,+DAA+D;QAC/D,YAAY;QACZ,qBAAqB;QACrB,QAAQ;QACR,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,sBAAsB;AACtB,MAAM,UAAU,cAAc,CAAC,IAA4C;IACzE,OAAO;QACL,oCAAoC;QACpC,gFAAgF;QAChF,QAAQ;QACR,0CAA0C,IAAI,CAAC,MAAM,EAAE;QACvD,EAAE;QACF,SAAS;QACT,kEAAkE;QAClE,qCAAqC;QACrC,kBAAkB;QAClB,gBAAgB;QAChB,qBAAqB,kCAAkC,GAAG;QAC1D,gBAAgB;QAChB,QAAQ,IAAI,CAAC,IAAI,UAAU;QAC3B,EAAE;QACF,WAAW;QACX,wBAAwB;QACxB,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,kBAAkB,CAAC,WAAmB;IACpD,MAAM,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5D,MAAM,CAAC,GACL,wEAAwE,CAAC,IAAI,CAAC,IAAI,CAAC;QACnF,sEAAsE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpF,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AACxB,CAAC"}