@cat-factory/cli 0.8.5 → 0.9.0

package/dist/supervise-runtime.js

@@ -0,0 +1,400 @@
+/**
+ * Effects half of `cat-factory supervise`: the health probe, the optional container dependency,
+ * the port reaper, the supervised child, and the loop that drives them from the pure decisions in
+ * `supervise.ts`.
+ *
+ * Everything the loop touches is behind a seam so `runSupervisor` can be driven by fakes — the
+ * same discipline `host-shell.ts` sets out for the k3s flow. Shell-outs go through {@link HostShell}
+ * rather than `node:child_process` directly; the one exception is the supervised child itself,
+ * which needs inherited stdio and a live handle, so it gets its own {@link ChildLauncher} seam.
+ */
+import { spawn } from 'node:child_process';
+import http from 'node:http';
+import net from 'node:net';
+import { COMMAND_NOT_FOUND } from './host-shell.js';
+import { initialState, stateAfterStart, step } from './supervise.js';
+/**
+ * Thrown by a dependency that cannot be repaired without a human. The loop prints the message ONCE
+ * and stops treating the step as retryable noise — the alternative is a watchdog that repeats a
+ * hopeless action forever, which is the exact pathology (a restart loop that reads as progress)
+ * this supervisor exists to end.
+ */
+export class OperatorActionRequiredError extends Error {
+}
+/**
+ * NOTE the deliberately un-`unref`'d timers throughout this module. An `unref`'d timer does not keep
+ * the event loop alive, and while a spawned child DOES hold it open, that reference vanishes the
+ * moment the child dies — which is precisely when the supervisor must keep running. With `unref` the
+ * poll timer was then the only thing left, so Node exited 0 the instant its child was killed: a
+ * watchdog that died with its patient, silently and with a success code.
+ */
+export const systemClock = {
+    now: () => Date.now(),
+    sleep: (ms, signal) => new Promise((resolve) => {
+        if (signal?.aborted === true) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        // Without this a Ctrl-C would sit out the remainder of the poll interval before the loop
+        // noticed, so the shutdown that is supposed to reap the child takes up to `--poll` seconds.
+        function onAbort() {
+            clearTimeout(timer);
+            resolve();
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+    }),
+};
+const PROBE_CONNECT_TIMEOUT_MS = 2_000;
+const PROBE_HTTP_TIMEOUT_MS = 3_000;
+/**
+ * The real probe. "Serving" requires BOTH signals, because the two failure modes differ: a parked
+ * `node --watch` leaves nothing bound to the port, while a server that booted but wedged (or lost
+ * its DB pool) still holds the socket and only fails the HTTP check.
+ *
+ * Both address families are tried — a Node server on `0.0.0.0` answers on 127.0.0.1, but some dev
+ * servers bind IPv6 `::1` only, and probing one family would report a false outage.
+ */
+export function createHealthProbe(opts) {
+    const hosts = ['127.0.0.1', '::1'];
+    const connect = (host) => new Promise((resolve) => {
+        const socket = net.connect({ host, port: opts.port, timeout: PROBE_CONNECT_TIMEOUT_MS });
+        const done = (result) => {
+            socket.destroy();
+            resolve(result);
+        };
+        socket.once('connect', () => done(true));
+        socket.once('error', () => done(false));
+        socket.once('timeout', () => done(false));
+    });
+    const healthy = (host) => new Promise((resolve) => {
+        const req = http.get({ host, port: opts.port, path: opts.healthPath, timeout: PROBE_HTTP_TIMEOUT_MS }, (res) => {
+            res.resume(); // drain, so the socket can close
+            resolve(res.statusCode === 200);
+        });
+        req.once('error', () => resolve(false));
+        req.once('timeout', () => {
+            req.destroy();
+            resolve(false);
+        });
+    });
+    return {
+        async serving() {
+            const listening = await Promise.all(hosts.map(connect));
+            if (!listening.some(Boolean))
+                return false;
+            const answers = await Promise.all(hosts.map(healthy));
+            return answers.some(Boolean);
+        },
+    };
+}
+const COMPOSE_READY_TIMEOUT_MS = 90_000;
+const COMPOSE_POLL_MS = 2_000;
+/**
+ * A `docker compose` service the supervised process needs. This is the piece that makes recovery
+ * work after the container engine itself restarted: the example compose files set no restart
+ * policy on Postgres, so anything that stops the engine leaves the DB down, and relaunching the
+ * server against a missing (or still-initialising) database just crashes it again in `migrate`.
+ */
+export function createComposeDependency(shell, opts) {
+    const readyTimeoutMs = opts.readyTimeoutMs ?? COMPOSE_READY_TIMEOUT_MS;
+    const readyPollMs = opts.readyPollMs ?? COMPOSE_POLL_MS;
+    const inspectReady = async (id) => {
+        const format = '{{.State.Status}}|{{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}}';
+        const result = await shell.run('docker', ['inspect', id, '--format', format], { cwd: opts.dir });
+        if (result.code !== 0)
+            return false;
+        const [status, health] = result.stdout.trim().split('|');
+        // A service with no healthcheck configured can only be judged by `running`.
+        return status === 'running' && (health === 'healthy' || health === 'none');
+    };
+    return {
+        label: `${opts.service} (docker compose)`,
+        async ensure() {
+            const up = await shell.run('docker', ['compose', 'up', '-d', opts.service], {
+                timeoutMs: 60_000,
+                cwd: opts.dir,
+            });
+            if (up.code !== 0)
+                return false;
+            const deadline = Date.now() + readyTimeoutMs;
+            while (Date.now() < deadline) {
+                const ps = await shell.run('docker', ['compose', 'ps', '-q', opts.service], {
+                    cwd: opts.dir,
+                });
+                const id = ps.stdout.trim().split(/\r?\n/).filter(Boolean)[0];
+                if (id && (await inspectReady(id)))
+                    return true;
+                await new Promise((resolve) => {
+                    setTimeout(resolve, readyPollMs);
+                });
+            }
+            return false;
+        },
+    };
+}
+/**
+ * Frees the port before a restart. Killing the child tree usually suffices, but not always: a
+ * package-manager wrapper that is killed without its subtree leaves the real `node` orphaned and
+ * still holding the socket, and the relaunch then dies with `EADDRINUSE` — turning one outage into
+ * a restart loop. Reaping by PORT is the only check that covers an orphan we never had a handle on.
+ *
+ * It is also, unavoidably, the bluntest thing this supervisor does: reaping by port means SIGKILLing
+ * a process we were never handed. If `--port` names a port some unrelated service owns, that service
+ * is what dies. There is no portable way to prove descent from our own child, so the mitigation is
+ * disclosure rather than detection — every kill NAMES the pid and, where the platform will tell us,
+ * the command behind it, and `reap()` reports what it killed so the caller can log it. Callers only
+ * ever reap AFTER their own child is confirmed dead, so a healthy stack is never a candidate.
+ */
+export function createPortReaper(shell, port, opts = {}) {
+    const isWindows = (opts.platform ?? process.platform) === 'win32';
+    const log = opts.log ?? (() => { });
+    /** Best-effort "what IS this pid", so a surprising kill is at least explicable after the fact. */
+    const describe = async (pid) => {
+        const result = isWindows
+            ? await shell.run('tasklist', ['/FI', `PID eq ${pid}`, '/NH', '/FO', 'CSV'])
+            : await shell.run('ps', ['-p', pid, '-o', 'command=']);
+        if (result.code !== 0)
+            return `pid ${pid}`;
+        const text = result.stdout.trim().split(/\r?\n/)[0]?.trim();
+        return text ? `pid ${pid} (${text})` : `pid ${pid}`;
+    };
+    const listenerPids = async () => {
+        if (isWindows) {
+            // Plain `netstat -ano` (not `-p tcp`, which is IPv4-only) so an IPv6-only listener is seen.
+            const result = await shell.run('netstat', ['-ano']);
+            if (result.code !== 0) {
+                log(`⚠ cannot check port ${port}: netstat failed — an orphaned listener will not be reaped`);
+                return [];
+            }
+            const pids = new Set();
+            for (const line of result.stdout.split(/\r?\n/)) {
+                const match = line.match(/^\s*TCP\s+\S+:(\d+)\s+\S+\s+LISTENING\s+(\d+)/i);
+                if (match && Number(match[1]) === port)
+                    pids.add(match[2]);
+            }
+            return [...pids];
+        }
+        const result = await shell.run('lsof', ['-ti', `tcp:${port}`, '-sTCP:LISTEN']);
+        // `lsof` exits 1 for "nothing matched", which is the common case and not worth a word. A MISSING
+        // lsof is different: it is not installed by default on many Linux images, so the reaper silently
+        // becomes a no-op and the EADDRINUSE restart loop it exists to prevent comes back unexplained.
+        if (result.code === COMMAND_NOT_FOUND) {
+            log(`⚠ cannot check port ${port}: lsof is not installed — an orphaned listener holding the ` +
+                'port will not be reaped, so a restart may fail with EADDRINUSE');
+            return [];
+        }
+        if (result.code !== 0)
+            return [];
+        return [...new Set(result.stdout.split(/\s+/).filter(Boolean))];
+    };
+    return {
+        async reap() {
+            const killed = [];
+            for (const pid of await listenerPids()) {
+                log(`↯ port ${port} is still held by ${await describe(pid)} — killing it`);
+                // `/T` (Windows) kills the descendants too; elsewhere the group is signalled by the caller.
+                if (isWindows)
+                    await shell.run('taskkill', ['/PID', pid, '/F', '/T']);
+                else
+                    await shell.run('kill', ['-9', pid]);
+                killed.push(pid);
+            }
+            return killed;
+        },
+    };
+}
+/**
+ * Launches the supervised command through a shell, with stdio inherited so its logs stay visible —
+ * the supervisor is meant to be a transparent wrapper, not a log proxy.
+ *
+ * The command is passed as ONE string with `shell: true` (rather than a command plus an args array,
+ * which trips Node's DEP0190) so a package-manager entry point resolves through its Windows `.cmd`
+ * shim. On POSIX the child gets its own process group, so killing it takes the whole tree.
+ */
+export function createChildLauncher(opts) {
+    const isWindows = process.platform === 'win32';
+    return {
+        start() {
+            const child = spawn(opts.command, {
+                cwd: opts.cwd,
+                stdio: 'inherit',
+                shell: true,
+                detached: !isWindows,
+            });
+            const exited = new Promise((resolve) => {
+                child.once('exit', (code, signal) => resolve({ code, signal }));
+                child.once('error', () => resolve({ code: null, signal: null }));
+            });
+            return {
+                pid: child.pid,
+                exited,
+                async kill() {
+                    if (child.pid === undefined || child.exitCode !== null)
+                        return;
+                    try {
+                        if (isWindows) {
+                            // No POSIX process groups on Windows; `taskkill /T` is what reaches the subtree.
+                            spawn('taskkill', ['/PID', String(child.pid), '/F', '/T'], {
+                                stdio: 'ignore',
+                            }).unref();
+                        }
+                        else {
+                            process.kill(-child.pid, 'SIGKILL');
+                        }
+                    }
+                    catch (err) {
+                        // silent-catch-ok: the child had already exited between the guard above and the signal
+                        // (ESRCH/EPERM). That is the outcome kill() is asking for, so there is nothing to report.
+                        void err;
+                    }
+                    await Promise.race([
+                        exited,
+                        new Promise((resolve) => {
+                            setTimeout(resolve, 2_000);
+                        }),
+                    ]);
+                },
+            };
+        },
+    };
+}
+/**
+ * Run every dependency's `ensure`, logging each outcome. Returns the labels of any that need
+ * operator action, whose guidance is printed only the first time so a long run doesn't bury it in
+ * repeats. A blocked dependency does NOT abort the ladder: the supervised process is often still
+ * worth restarting (a dead cluster breaks environment provisioning, not the whole backend).
+ */
+async function ensureDependencies(dependencies, log, warned) {
+    const blocked = [];
+    for (const dependency of dependencies) {
+        try {
+            const ready = await dependency.ensure();
+            log(ready
+                ? `✔ ${dependency.label} is ready`
+                : `✖ ${dependency.label} is not ready — will retry next cycle`);
+        }
+        catch (err) {
+            if (!(err instanceof OperatorActionRequiredError))
+                throw err;
+            blocked.push(dependency.label);
+            if (!warned.has(dependency.label)) {
+                warned.add(dependency.label);
+                log(`✖ ${dependency.label} NEEDS YOU: ${err.message}`);
+            }
+        }
+    }
+    return blocked;
+}
+const RESTART_SETTLE_MS = 1_500;
+/**
+ * Run the supervision loop: start the child, then probe on an interval and repair when the
+ * decisions in `supervise.ts` say so. Returns when `stopSignal` aborts, when the crash-loop budget
+ * is spent, or when `maxTicks` is reached (tests) — in production, otherwise never.
+ */
+export async function runSupervisor(deps) {
+    const clock = deps.clock ?? systemClock;
+    const log = deps.log ?? ((message) => process.stdout.write(`${message}\n`));
+    const { config, stopSignal } = deps;
+    let repairs = 0;
+    let ticks = 0;
+    let blocked = [];
+    let gaveUp;
+    const warned = new Set();
+    // A child that has exited is a fact the probe can only infer, slowly. Tracked per generation so a
+    // dead PREDECESSOR's late `exited` can never be read as the current child having died.
+    let generation = 0;
+    let childExited = false;
+    const startChild = () => {
+        const mine = ++generation;
+        childExited = false;
+        const started = deps.launcher.start();
+        void started.exited.then(() => {
+            if (mine === generation)
+                childExited = true;
+        });
+        return started;
+    };
+    let child = startChild();
+    let state = initialState(clock.now(), config);
+    // Restarts that have not yet produced a serving stack. Reset by any successful probe, so this
+    // counts a genuine crash loop rather than a long-lived stack that has been repaired often.
+    let failedStarts = 0;
+    const restart = async () => {
+        await child.kill();
+        await clock.sleep(RESTART_SETTLE_MS);
+        // Reap AFTER killing the tree: this only catches an orphan the tree kill could not reach. Our
+        // own child is dead by now, so anything still on the port is by definition not it.
+        if (deps.reaper)
+            await deps.reaper.reap();
+        child = startChild();
+        state = stateAfterStart(clock.now(), config);
+    };
+    // Read through a function, not inline: `signal.aborted` flips underneath us, and a direct
+    // comparison in the loop condition would let the compiler narrow it to `false` for the body.
+    const stopRequested = () => stopSignal?.aborted === true;
+    while (!stopRequested() &&
+        gaveUp === undefined &&
+        (deps.maxTicks === undefined || ticks < deps.maxTicks)) {
+        await clock.sleep(config.pollMs, stopSignal);
+        if (stopRequested())
+            break;
+        ticks += 1;
+        // Sampled BEFORE the probe: the probe can take seconds against a filtered port, and folding
+        // that into the drift would read as a suspend (see `clockJumpMs`).
+        const now = clock.now();
+        const serving = await deps.probe.serving();
+        if (serving)
+            failedStarts = 0;
+        const next = step(state, { now, serving, childExited }, config);
+        state = next.state;
+        const { action } = next;
+        switch (action.kind) {
+            case 'serving':
+            case 'grace':
+                break;
+            case 'resumed':
+                log(`✔ resumed after ${Math.round(action.driftMs / 1000)}s — the stack is still serving`);
+                break;
+            case 'recovered':
+                log(`✔ serving again (after ${action.afterFailures} failed probe(s))`);
+                break;
+            case 'counting':
+                log(`• health probe failed (${action.failures}/${action.threshold})`);
+                break;
+            case 'repair': {
+                repairs += 1;
+                failedStarts += 1;
+                log(`⚠ not serving — ${action.reason}; repair #${repairs}`);
+                if (failedStarts > config.maxFailedStarts) {
+                    // Reported, not retried — the same rule the wedged-cgroup path follows. A command that has
+                    // never once served is not going to start serving because we killed it again.
+                    gaveUp =
+                        `the supervised command has failed to serve ${failedStarts} starts in a row. ` +
+                            'Restarting cannot fix a command that is broken — run it directly to see why ' +
+                            '(in deploy/local: `pnpm dev:raw`).';
+                    log(`✖ GIVING UP: ${gaveUp}`);
+                    break;
+                }
+                if (deps.dependencies?.length) {
+                    blocked = await ensureDependencies(deps.dependencies, log, warned);
+                }
+                await restart();
+                log('↻ restarted the supervised command');
+                break;
+            }
+        }
+    }
+    // Shutdown is the loop's job because the loop owns the child handle.
+    await child.kill();
+    if (deps.reaper) {
+        const killed = await deps.reaper.reap();
+        if (killed.length > 0)
+            log(`↯ reaped ${killed.length} orphaned listener(s) on shutdown`);
+    }
+    return { ticks, repairs, blocked, gaveUp };
+}
+//# sourceMappingURL=supervise-runtime.js.map

package/dist/supervise-runtime.js.map

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

package/dist/supervise.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Decision core for `cat-factory supervise` — the self-healing local-dev supervisor.
+ *
+ * WHY THIS EXISTS. Every local deployment runs its server under `node --watch`, and
+ * `node --watch` PARKS on crash: it restarts the entry only on a FILE CHANGE, never on a process
+ * exit. A sleeping laptop is the common trigger — on resume the Postgres/Docker connection is
+ * gone, the server dies in `migrate`, and the watcher settles at "Waiting for file changes before
+ * restarting". The result is the worst kind of failure: the wrapper PID is still alive and the
+ * ready banner has already scrolled past, so the stack LOOKS running while nothing is bound to
+ * the port, and the SPA reports only a generic "can't reach backend". It never self-heals, and it
+ * stays that way until someone notices and restarts by hand.
+ *
+ * This module is the JUDGEMENT half of the fix, kept pure — no sockets, no processes, no ambient
+ * clock — so every transition is unit-testable from a table of observations (`supervise.test.ts`).
+ * `supervise-runtime.ts` owns the effects and feeds observations in. That split is the same one
+ * `scripts/silent-catch.mjs` documents for itself: a guard whose judgement nothing tests is a
+ * guard that is trusted without evidence.
+ */
+/** Tuning for the supervisor loop. Resolve partial input with {@link resolveSuperviseConfig}. */
+export interface SuperviseConfig {
+    /** How often the health probe runs. */
+    pollMs: number;
+    /**
+     * Grace window after a (re)start during which a failed probe does NOT count against the child.
+     * A cold boot builds the workspace dependency and runs migrations first, so the port legitimately
+     * stays unbound for a while.
+     */
+    bootGraceMs: number;
+    /** Grace window after a detected resume, so a still-waking Docker/Postgres isn't blamed. */
+    resumeGraceMs: number;
+    /**
+     * A tick arriving this much later than `pollMs` means time jumped — the host slept (or stalled
+     * hard). Timers do not fire while suspended, so lateness is the signal.
+     *
+     * The measurement is deliberately taken tick-START to tick-START (see {@link step}): sampling it
+     * after the probe would fold the probe's own duration into the drift, and a probe that times out
+     * on a filtered port takes seconds — enough to read as a suspend on a short `--poll` and so to
+     * bypass `failureThreshold` entirely.
+     */
+    clockJumpMs: number;
+    /** Consecutive failed probes required before a repair (outside any grace window). */
+    failureThreshold: number;
+    /**
+     * How many restarts in a row may fail to produce a SERVING stack before the supervisor reports
+     * and gives up. A command that is simply broken (a syntax error, a missing binary, a port already
+     * owned by something else) can never be fixed by restarting it, and looping forever on it is the
+     * exact pathology this supervisor exists to end — the motivating incident was a container that
+     * restarted 518 times, exiting 0 each time, while `docker ps` showed healthy motion.
+     */
+    maxFailedStarts: number;
+}
+/** Defaults chosen for a laptop-dev loop: notice within ~30s, never fight a cold boot. */
+export declare const SUPERVISE_DEFAULTS: {
+    readonly pollMs: 10000;
+    readonly bootGraceMs: 60000;
+    readonly resumeGraceMs: 25000;
+    readonly failureThreshold: 3;
+    readonly maxFailedStarts: 5;
+};
+/**
+ * Fill in defaults and derive `clockJumpMs` from the poll interval. A tick 3 intervals late is
+ * well outside normal scheduler jitter but still catches a short suspend.
+ */
+export declare function resolveSuperviseConfig(partial?: Partial<SuperviseConfig>): SuperviseConfig;
+/** Loop state carried between ticks. Treated as immutable: {@link step} returns the next one. */
+export interface SuperviseState {
+    /** Consecutive failed probes so far, reset by any success or repair. */
+    failures: number;
+    /** No failed probe counts against the child until this timestamp (boot/resume grace). */
+    quietUntil: number;
+    /** When the previous tick ran — the basis for clock-jump (sleep) detection. */
+    lastTickAt: number;
+}
+/** What the runtime should do about this tick. Every branch of {@link step} names one. */
+export type SuperviseAction = 
+/** Serving, and it was serving before too — nothing to say. */
+{
+    kind: 'serving';
+}
+/** Serving again after one or more failed probes, without needing a repair. */
+ | {
+    kind: 'recovered';
+    afterFailures: number;
+}
+/** Not serving, but inside a boot/resume grace window — wait it out. */
+ | {
+    kind: 'grace';
+    msLeft: number;
+}
+/** Not serving; failure counted but still below the threshold. */
+ | {
+    kind: 'counting';
+    failures: number;
+    threshold: number;
+}
+/** Run the recovery ladder: re-check dependencies, then restart the child. */
+ | {
+    kind: 'repair';
+    reason: string;
+}
+/** The host resumed from sleep and the stack is still serving. */
+ | {
+    kind: 'resumed';
+    driftMs: number;
+};
+/** State for a freshly started child: clean counters and a full boot grace window. */
+export declare function initialState(now: number, config: SuperviseConfig): SuperviseState;
+/**
+ * State to adopt right after (re)spawning a child mid-run — a fresh boot grace, counters clear.
+ *
+ * `lastTickAt` is re-based on `now` (the moment the new child started), NOT carried over from the
+ * previous tick, because a repair is not instantaneous: it runs the whole dependency ladder first,
+ * and those budgets are 90s (compose readiness) and 120s (apiserver readiness) against a default
+ * `clockJumpMs` of 30s. Carrying the old timestamp forward makes the very next tick measure the
+ * repair's own duration as drift, read a slow-but-successful recovery as a host suspend, and — since
+ * resume detection deliberately outranks the boot-grace window — immediately kill the child it just
+ * started. Re-basing means the clock-jump signal only ever measures time we were genuinely idle.
+ */
+export declare function stateAfterStart(now: number, config: SuperviseConfig): SuperviseState;
+/**
+ * One tick of the supervisor: current state + what we just observed -> next state + the action to
+ * take. Pure; the caller supplies `now` and the probe result.
+ *
+ * `now` must be sampled at the START of the tick, before the probe runs — see `clockJumpMs`.
+ *
+ * Order matters:
+ *  1. The clock-jump check runs FIRST and outranks the grace windows, because a resume is precisely
+ *     when the stack is most likely already dead — deferring it to the normal threshold path would
+ *     idle for another `failureThreshold * pollMs` before repairing something we can already tell
+ *     is broken.
+ *  2. A confirmed-serving stack short-circuits everything below it.
+ *  3. A child that has EXITED then repairs immediately, ahead of the grace window and the failure
+ *     counter, because neither can tell us anything a dead process handle hasn't already: counting
+ *     three more probes against a process that does not exist just adds `failureThreshold * pollMs`
+ *     of downtime. This is checked only once the stack is known not to be serving, so a wrapper that
+ *     exits while its grandchild keeps serving (a shell that `exec`s away, say) is left alone
+ *     rather than having a healthy server restarted out from under it.
+ */
+export declare function step(state: SuperviseState, observation: {
+    now: number;
+    serving: boolean;
+    childExited?: boolean;
+}, config: SuperviseConfig): {
+    state: SuperviseState;
+    action: SuperviseAction;
+};
+//# sourceMappingURL=supervise.d.ts.map

package/dist/supervise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervise.d.ts","sourceRoot":"","sources":["../src/supervise.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,iGAAiG;AACjG,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB,4FAA4F;IAC5F,aAAa,EAAE,MAAM,CAAA;IACrB;;;;;;;;OAQG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB,qFAAqF;IACrF,gBAAgB,EAAE,MAAM,CAAA;IACxB;;;;;;OAMG;IACH,eAAe,EAAE,MAAM,CAAA;CACxB;AAED,0FAA0F;AAC1F,eAAO,MAAM,kBAAkB;aAC7B,MAAM,EAAE,KAAM;aACd,WAAW,EAAE,KAAM;aACnB,aAAa,EAAE,KAAM;aACrB,gBAAgB,EAAE,CAAC;aACnB,eAAe,EAAE,CAAC;CACV,CAAA;AAEV;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,OAAO,CAAC,eAAe,CAAM,GAAG,eAAe,CAU9F;AAED,iGAAiG;AACjG,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAA;IAChB,yFAAyF;IACzF,UAAU,EAAE,MAAM,CAAA;IAClB,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,0FAA0F;AAC1F,MAAM,MAAM,eAAe;AACzB,+DAA+D;AAC7D;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE;AACrB,+EAA+E;GAC7E;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE;AAC9C,wEAAwE;GACtE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACnC,kEAAkE;GAChE;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE;AAC3D,8EAA8E;GAC5E;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACpC,kEAAkE;GAChE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAExC,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,cAAc,CAEjF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,cAAc,CAEpF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,IAAI,CAClB,KAAK,EAAE,cAAc,EACrB,WAAW,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,EACrE,MAAM,EAAE,eAAe,GACtB;IAAE,KAAK,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,CAwDpD"}