@skillsmith/core 0.12.3 → 0.12.5

package/dist/src/install/fan-out.overwrite.d.ts

@@ -0,0 +1,51 @@
+import type { Stats } from 'node:fs';
+import type { LinkManifest } from './fan-out.manifest.js';
+export { leftoverBackupWarning, listLeftoverBackups, recoverDestination, } from './fan-out.leftovers.js';
+export { withDestinationLock, withFileLock } from './fan-out.locks.js';
+/** Result of looking for `.git` at a directory's root. */
+export type GitAtRoot = {
+    kind: 'absent';
+} | {
+    kind: 'present';
+} | {
+    kind: 'unknown';
+    reason: string;
+};
+/**
+ * Look for a `.git` entry at the root of `p` with `lstat` (never following a
+ * symlink, so a dangling `.git` link still counts). Any error other than
+ * ENOENT/ENOTDIR is `unknown`, which callers must treat as "refuse".
+ */
+export declare function checkGitAtRoot(p: string): Promise<GitAtRoot>;
+/** Refusal text for a git check that isn't `absent`, or `null` when it is. */
+export declare function gitRefusal(p: string, check: GitAtRoot, verb: 'overwrite' | 'delete'): string | null;
+/**
+ * Throw, changing nothing, unless the existing destination may be replaced:
+ * a symlink (always disposable), or a copy recorded in the link manifest that
+ * hasn't become a git working tree.
+ */
+export declare function assertOverwritable(dest: string, existing: Stats, manifest: LinkManifest): Promise<void>;
+/** What {@link replaceDestination} put in place, and what it could not clean up. */
+export interface PlacedDestination {
+    /**
+     * Identity of the entry now at `dest`, or null when this call cannot be
+     * sure what it placed — round 21 (Opus): a published symlink that something
+     * replaced between creating it and reading it back. A null identity means an
+     * undo reports the write instead of deleting anything.
+     */
+    placed: Stats | null;
+    /** Warnings for the caller to surface, e.g. a superseded copy left behind. */
+    warnings: string[];
+}
+/**
+ * Replace (or create) `dest` with what `write` produces. The caller must hold
+ * `withDestinationLock(dest)` and have checked `assertOverwritable`. `write`
+ * receives a staging path; if it throws, the destination is never touched.
+ *
+ * Returns the identity of the entry now at `dest`. Round 15 (Opus): it is
+ * taken from the staged entry before the swap, since a rename keeps device
+ * and inode. Taken after the swap, it could record a folder another program
+ * had put there in between, and an undo would then delete that folder.
+ */
+export declare function replaceDestination(dest: string, write: (stagedPath: string) => Promise<void>): Promise<PlacedDestination>;
+//# sourceMappingURL=fan-out.overwrite.d.ts.map

package/dist/src/install/fan-out.overwrite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fan-out.overwrite.d.ts","sourceRoot":"","sources":["../../../src/install/fan-out.overwrite.ts"],"names":[],"mappings":"AA+CA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAazD,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,wBAAwB,CAAA;AAG/B,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAUtE,0DAA0D;AAC1D,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAEvC;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CASlE;AAED,8EAA8E;AAC9E,wBAAgB,UAAU,CACxB,CAAC,EAAE,MAAM,EACT,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,WAAW,GAAG,QAAQ,GAC3B,MAAM,GAAG,IAAI,CAUf;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,KAAK,EACf,QAAQ,EAAE,YAAY,GACrB,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED,oFAAoF;AACpF,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,MAAM,EAAE,KAAK,GAAG,IAAI,CAAA;IACpB,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAC3C,OAAO,CAAC,iBAAiB,CAAC,CA0B5B"}

package/dist/src/install/fan-out.overwrite.js

@@ -0,0 +1,343 @@
+/**
+ * SMI-6529: safe replacement of a fan-out destination, split out of
+ * fan-out.ts to stay under the 500-line gate.
+ *
+ * Every write to a destination happens under a per-destination lock, and a
+ * refresh never writes into the destination in place:
+ *
+ *  1. The new copy (or symlink) is written into a hidden staging folder next
+ *     to the destination.
+ *  2. The old destination is renamed aside into a hidden backup folder.
+ *  3. The staged copy is renamed into place, and the backup is dropped.
+ *
+ * If step 3 fails, the old destination is renamed back. Nothing at the
+ * destination is ever deleted to make room, and a half-written copy is never
+ * visible there.
+ *
+ * Review history:
+ *  - Round 5 (R2/R3): the first version used a fixed backup name it
+ *    `rm -rf`'d first, and never restored a backup stranded by a crash.
+ *  - Round 6: two concurrent force-refreshes of one destination could lose
+ *    the original. Call B's recovery "restored" call A's in-flight backup,
+ *    then A's failure path deleted it. The per-destination lock serializes
+ *    recovery, write and swap; staging removes A's delete entirely. Round 6
+ *    also found that a stranded `original` was restored whatever it was (a
+ *    symlink to /etc included), that an EACCES on the `.git` check was
+ *    reported as "contains a .git directory", and that the name prefix could
+ *    match a sibling skill's folders.
+ *  - Round 13 (cross-model review): the destination lock keeps other
+ *    Skillsmith calls out, not other programs. So a staging or backup folder
+ *    is deleted only while it is still the folder we made (same device and
+ *    inode). Round 14: a crashed write's staging folder is never deleted
+ *    (neither its name nor its contents proves who owns it), only reported,
+ *    and a folder left in place is named with the reason. Round 15: each
+ *    delete parks the folder under a random name and checks it there
+ *    (`removeIfSame`), closing the gap between the check and the delete,
+ *    and `replaceDestination` returns the new entry's identity, taken before
+ *    it became visible at the destination.
+ *  - Round 8: a lock released mid-attempt was reported as corrupt, so
+ *    contending callers failed at once; waiting on an orphaned reclaim lock
+ *    still blocked the event loop; a reinstall after an uninstall restored a
+ *    stale backup; and an empty backup folder from a crash was reported
+ *    forever.
+ *
+ * @module @skillsmith/core/install/fan-out.overwrite
+ */
+import * as path from 'node:path';
+import * as fsp from 'node:fs/promises';
+import { removeIfSame } from './remove-if-same.js';
+import { BACKUP_TAG, STAGING_TAG, isRecordedCopy, lstatOrNull, siblingPrefix, } from './fan-out.leftovers.js';
+// Round 16: the leftover-reporting half of this module moved to
+// fan-out.leftovers.ts to stay under the 500-line gate. Re-exported here so
+// existing importers keep one entry point.
+export { leftoverBackupWarning, listLeftoverBackups, recoverDestination, } from './fan-out.leftovers.js';
+// Round 27: the locking half moved to fan-out.locks.ts for the same 500-line
+// reason. Re-exported here so existing importers keep one entry point.
+export { withDestinationLock, withFileLock } from './fan-out.locks.js';
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function errorCode(err) {
+    return err?.code ?? errorMessage(err);
+}
+/**
+ * Look for a `.git` entry at the root of `p` with `lstat` (never following a
+ * symlink, so a dangling `.git` link still counts). Any error other than
+ * ENOENT/ENOTDIR is `unknown`, which callers must treat as "refuse".
+ */
+export async function checkGitAtRoot(p) {
+    try {
+        await fsp.lstat(path.join(p, '.git'));
+        return { kind: 'present' };
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return { kind: 'absent' };
+        return { kind: 'unknown', reason: code ?? errorMessage(err) };
+    }
+}
+/** Refusal text for a git check that isn't `absent`, or `null` when it is. */
+export function gitRefusal(p, check, verb) {
+    if (check.kind === 'absent')
+        return null;
+    if (check.kind === 'present') {
+        return (`${p} is a recorded Skillsmith fan-out copy but now contains a .git directory ` +
+            `(looks like a real git working tree) — refusing to ${verb} it. Remove it yourself, ` +
+            `then retry.`);
+    }
+    return `could not check ${p} for a .git directory (${check.reason}) — refusing to ${verb} it.`;
+}
+/**
+ * Throw, changing nothing, unless the existing destination may be replaced:
+ * a symlink (always disposable), or a copy recorded in the link manifest that
+ * hasn't become a git working tree.
+ */
+export async function assertOverwritable(dest, existing, manifest) {
+    if (existing.isSymbolicLink())
+        return;
+    if (!isRecordedCopy(dest, manifest)) {
+        // Round 23 (Opus): the non-force refusal sends the user here, so this one
+        // explains the same state — an empty directory is most likely a claim an
+        // interrupted install left, and Skillsmith will not remove it for them.
+        const empty = existing.isDirectory() && (await fsp.readdir(dest).catch(() => ['?'])).length === 0;
+        throw new Error(`addLink: ${dest} already exists and is not a fan-out destination Skillsmith recorded ` +
+            `(no matching entry in the link manifest); remove it yourself, then retry with force.` +
+            (empty
+                ? ` It is an empty directory: an interrupted install may have left it, and Skillsmith ` +
+                    `does not remove it for you, since an empty directory you made looks the same.`
+                : ''));
+    }
+    const refusal = gitRefusal(dest, await checkGitAtRoot(dest), 'overwrite');
+    if (refusal)
+        throw new Error(`addLink: ${refusal}`);
+}
+/**
+ * Replace (or create) `dest` with what `write` produces. The caller must hold
+ * `withDestinationLock(dest)` and have checked `assertOverwritable`. `write`
+ * receives a staging path; if it throws, the destination is never touched.
+ *
+ * Returns the identity of the entry now at `dest`. Round 15 (Opus): it is
+ * taken from the staged entry before the swap, since a rename keeps device
+ * and inode. Taken after the swap, it could record a folder another program
+ * had put there in between, and an undo would then delete that folder.
+ */
+export async function replaceDestination(dest, write) {
+    const parent = path.dirname(dest);
+    const stagingFolder = await fsp.mkdtemp(path.join(parent, siblingPrefix(dest, STAGING_TAG)));
+    const made = await fsp.lstat(stagingFolder);
+    const staged = path.join(stagingFolder, 'content');
+    let placed;
+    let warnings;
+    try {
+        await write(staged);
+        const staging = await fsp.lstat(staged);
+        ({ placed, warnings } = await swapIntoPlace(dest, staged, staging));
+    }
+    catch (err) {
+        // A partial copy made from the source skill: remove it, but only while
+        // the folder is still the one we made (round 13), and say why when that
+        // didn't happen (round 14).
+        const removal = await removeIfSame(stagingFolder, made);
+        if (removal.removed)
+            throw err;
+        throw new Error(`${errorMessage(err)}; the staging folder ${stagingFolder} ${removal.reason}`, {
+            cause: err,
+        });
+    }
+    // Empty after a successful swap, so a non-recursive rmdir can't delete
+    // anything else. If it fails, the folder stays, and listLeftoverBackups,
+    // which the caller runs next, reports it.
+    await fsp.rmdir(stagingFolder).catch(() => { });
+    return { placed, warnings };
+}
+/**
+ * Put `staged` at `dest` without replacing anything that holds content. Round
+ * 20 (cross-model review): `rename` replaces its destination, so publishing
+ * with it could destroy an entry another program created after the destination
+ * was checked. A directory is published by claiming the name with `mkdir`,
+ * which fails with EEXIST rather than replacing, and then renaming the staged
+ * copy over that empty claim; a symlink is published with `symlink()`, which
+ * refuses an occupied path the same way.
+ *
+ * Round 24: the bound this holds, and the one it does not. The rename can
+ * still replace an EMPTY directory, if another program removes this call's own
+ * claim and substitutes one inside the two-syscall window — the accepted
+ * residual described below (SMI-6559). It can never replace anything holding
+ * content: POSIX `rename` refuses a non-empty directory (ENOTEMPTY) and a
+ * non-directory (ENOTDIR).
+ *
+ * Returns the identity of what is now at `dest`: a rename keeps the staged
+ * directory's, while a published symlink is a new entry.
+ */
+async function publish(staged, dest, staging) {
+    if (staging.isSymbolicLink()) {
+        const target = await fsp.readlink(staged);
+        await fsp.symlink(target, dest);
+        await fsp.unlink(staged).catch(() => { });
+        // Round 21 (Opus): `symlink` creates a NEW entry, so unlike the rename
+        // below there is no pre-image to report. Read it back and accept it only
+        // while it is still the link just written — anything else means another
+        // program replaced it in that window, and reporting that identity would
+        // let an undo delete their entry. Fail closed: no identity. (`link` is not
+        // an option: on Linux it links the symlink, on macOS it follows it.)
+        const now = await lstatOrNull(dest);
+        if (now === null || !now.isSymbolicLink())
+            return null;
+        const linked = await fsp.readlink(dest).catch(() => null);
+        return linked === target ? now : null;
+    }
+    // Round 22 (cross-model review; accepted residual, user decision
+    // 2026-09-12, tracked as SMI-6559): the claim and the rename below are two
+    // syscalls, and that CANNOT be made atomic here — Node exposes no
+    // no-replace rename (Linux's renameat2(RENAME_NOREPLACE) and macOS's
+    // renamex_np have no binding in node:fs). What the remaining window
+    // requires is narrow: another program must remove THIS call's own empty
+    // claim and put its own entry at the path in between — and even then the
+    // rename can only ever replace an EMPTY directory, because POSIX `rename`
+    // refuses a non-empty directory (ENOTEMPTY) and a non-directory (ENOTDIR).
+    // Measured across six interleavings on macOS and Linux, three of which
+    // removed the claim first: nothing holding content was ever replaced. The alternative —
+    // filling the claimed directory in place — removes the window but makes a
+    // half-copied skill visible at the destination, which staging exists to
+    // prevent (round 6).
+    await fsp.mkdir(dest);
+    try {
+        await fsp.rename(staged, dest);
+    }
+    catch (err) {
+        // Round 25 (cross-model review): the empty directory this call claimed is
+        // left in place and reported, never removed. Round 24 removed it after an
+        // identity check, and that check cannot hold: `mkdir` and the `lstat` that
+        // takes the identity are two syscalls, so what it records may already be
+        // another program's directory; the check and the `rmdir` are two more, so a
+        // substitution between them can reuse the freed inode and match. Node
+        // exposes no pathname operation that verifies identity and removes in one
+        // step, so the only choices are to remove something we cannot prove is
+        // ours, or to leave it and say so. This module's rule decides it: delete
+        // only what you can identify. The cost is an empty directory at the
+        // destination, which the next install refuses and explains.
+        throw new Error(`${errorMessage(err)}; the empty directory this call claimed at ${dest} was left in ` +
+            `place, since nothing can prove it is still the one this call made. Remove it ` +
+            `yourself if you do not want it.`, { cause: err });
+    }
+    return staging;
+}
+/** Swaps `staged` into `dest`, returning what it placed and what it could not clean up. */
+async function swapIntoPlace(dest, staged, staging) {
+    const existing = await lstatOrNull(dest);
+    if (existing === null) {
+        return { placed: await publish(staged, dest, staging), warnings: [] };
+    }
+    if (existing.isSymbolicLink()) {
+        // Round 19 (Opus): this used to `unlink` the destination two syscalls
+        // after the `lstat` that said "symlink", so a file another program put at
+        // the path in between was deleted. `removeIfSame` removes only the entry
+        // it checked.
+        const removal = await removeIfSame(dest, existing);
+        if (!removal.removed)
+            throw new Error(`addLink: ${dest} ${removal.reason}.`);
+        return { placed: await publish(staged, dest, staging), warnings: [] };
+    }
+    const backupFolder = await fsp.mkdtemp(path.join(path.dirname(dest), siblingPrefix(dest, BACKUP_TAG)));
+    const backupMade = await fsp.lstat(backupFolder);
+    const original = path.join(backupFolder, 'original');
+    // Round 20 (cross-model review): move aside only the entry that was checked.
+    // A rename moves whatever is at the path, so without this an entry another
+    // program had just put there would be carried into this call's backup folder.
+    // The same accepted residual as the claim above (SMI-6559): this check and
+    // the rename that follows are two syscalls. If another program replaces the
+    // destination in between, its entry is moved into this call's backup folder
+    // rather than deleted, and `listLeftoverBackups` reports it.
+    // Round 27 (cross-model review): a failed look used to fall into the
+    // refusal below, which told the user the destination "was replaced by
+    // something else" — a diagnosis this call never made. Refuse the same way,
+    // fail closed the same way, but say what actually happened.
+    let stillThere;
+    try {
+        stillThere = await lstatOrNull(dest);
+    }
+    catch (err) {
+        await fsp.rmdir(backupFolder).catch(() => { });
+        throw new Error(`addLink: ${dest} could not be checked (${errorCode(err)}) before this refresh could move ` +
+            `it aside; nothing was changed.`, { cause: err });
+    }
+    if (stillThere === null || stillThere.dev !== existing.dev || stillThere.ino !== existing.ino) {
+        await fsp.rmdir(backupFolder).catch(() => { });
+        throw new Error(`addLink: ${dest} was replaced by something else before this refresh could move it ` +
+            `aside; nothing was changed.`);
+    }
+    try {
+        await fsp.rename(dest, original);
+    }
+    catch (err) {
+        await fsp.rmdir(backupFolder).catch(() => { });
+        throw err;
+    }
+    let placed;
+    try {
+        placed = await publish(staged, dest, staging);
+    }
+    catch (err) {
+        // Round 19 (Opus): put the original back only while the path is still
+        // free — a rename would otherwise replace whatever took it, and the
+        // original is safe where it is, in a backup folder listLeftoverBackups
+        // reports. A path that can't be checked counts as taken.
+        let free;
+        try {
+            free = (await lstatOrNull(dest)) === null;
+        }
+        catch {
+            free = false;
+        }
+        if (!free) {
+            throw new Error(`addLink: ${errorMessage(err)}; something else is at ${dest} now, so the original was ` +
+                `left at ${original}`, { cause: err });
+        }
+        try {
+            await fsp.rename(original, dest);
+        }
+        catch (restoreErr) {
+            throw new Error(`addLink: ${errorMessage(err)}; the original could not be put back and is preserved ` +
+                `at ${original} (${errorMessage(restoreErr)})`, { cause: err });
+        }
+        await fsp.rmdir(backupFolder).catch(() => { });
+        throw err;
+    }
+    // The swap succeeded, so the superseded copy is no longer needed. Drop it
+    // only while the backup folder and the copy in it are still what we put
+    // there (round 13). A folder left for any reason (not ours, or the removal
+    // failed) stays, and listLeftoverBackups, which the caller runs next,
+    // reports it.
+    // Round 16 (cross-model review): say why a superseded copy was left, rather
+    // than dropping the reason and leaving a later sweep to call it "an earlier
+    // copy" with no explanation.
+    let originalNow;
+    try {
+        originalNow = await lstatOrNull(original);
+    }
+    catch (err) {
+        return {
+            placed,
+            warnings: [
+                `the copy this refresh replaced could not be checked (${errorCode(err)}), so ` +
+                    `${backupFolder} was left in place; check it, then delete it yourself if you don't ` +
+                    `need it.`,
+            ],
+        };
+    }
+    if (originalNow === null ||
+        originalNow.dev !== existing.dev ||
+        originalNow.ino !== existing.ino) {
+        // Not what we put there. listLeftoverBackups reports it.
+        return { placed, warnings: [] };
+    }
+    const removal = await removeIfSame(backupFolder, backupMade);
+    return {
+        placed,
+        warnings: removal.removed
+            ? []
+            : [`the copy this refresh replaced was kept: ${backupFolder} ${removal.reason}.`],
+    };
+}
+//# sourceMappingURL=fan-out.overwrite.js.map

package/dist/src/install/fan-out.overwrite.js.map

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

package/dist/src/install/remove-if-same.d.ts

@@ -0,0 +1,58 @@
+/** Tag in a parked entry's name: `.<name>.skillsmith-removing-<32 hex>`. */
+export declare const PARK_TAG = ".skillsmith-removing-";
+/** An entry's device and inode, to tell it apart from anything later put at its path. */
+export interface EntryIdentity {
+    dev: number;
+    ino: number;
+}
+/**
+ * Result of {@link removeIfSame}. `reason` reads after the path, e.g.
+ * `${target} ${reason}`.
+ */
+export type CheckedRemoval = {
+    removed: true;
+} | {
+    removed: false;
+    reason: string;
+};
+/** What a parked-leftover scan found, and whether it could look at all. */
+export interface ParkedScan {
+    /** Entries a crashed or failed removal left parked beside the target. */
+    parked: string[];
+    /** Set when the folder holding them could not be listed. */
+    unreadable?: string;
+}
+/** Matches exactly the names {@link removeIfSame} parks `target` under. */
+export declare function parkedPattern(target: string): RegExp;
+/**
+ * Entries a crashed or failed removal left parked next to `target`, so a
+ * caller can report them. Round 16 (both reviewers): away from a fan-out
+ * destination nothing swept these, so a failed removal's leftover was named
+ * once, in one error, and never again.
+ */
+export declare function listParkedLeftovers(target: string): Promise<ParkedScan>;
+/**
+ * User-facing warning for what {@link listParkedLeftovers} found. Round 18
+ * (cross-model review): who owns a parked entry is not known. It is whatever
+ * was at the path when a removal moved it aside, which in a race can belong
+ * to another program, so the wording says that instead of calling it ours.
+ */
+export declare function parkedLeftoverWarning(parked: string): string;
+/**
+ * Remove `target` (a folder recursively, anything else with `unlink`) only if
+ * it is still the entry `expected` describes. An entry that is already gone
+ * counts as removed. Anything else is left alone, and whatever this call
+ * moved aside is reported with its exact path.
+ *
+ * Round 17 (cross-model review): nothing is ever renamed back. `rename`
+ * replaces what is at the destination — measured on macOS and Linux, a
+ * directory replaces an empty directory and a file or symlink replaces a file
+ * or symlink — so putting an entry back could destroy something created at
+ * that path in the meantime, and a check first only narrows that window
+ * rather than closing it. The two failure modes are not equal: a put-back can
+ * destroy an entry, while leaving one parked merely moves it, recoverably,
+ * and says where it went. The identity is also checked once BEFORE the entry
+ * is parked, so the ordinary mismatch moves nothing at all.
+ */
+export declare function removeIfSame(target: string, expected: EntryIdentity): Promise<CheckedRemoval>;
+//# sourceMappingURL=remove-if-same.d.ts.map

package/dist/src/install/remove-if-same.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remove-if-same.d.ts","sourceRoot":"","sources":["../../../src/install/remove-if-same.ts"],"names":[],"mappings":"AA0BA,4EAA4E;AAC5E,eAAO,MAAM,QAAQ,0BAA0B,CAAA;AAE/C,yFAAyF;AACzF,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;CACZ;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAOnF,2EAA2E;AAC3E,MAAM,WAAW,UAAU;IACzB,yEAAyE;IACzE,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAcD,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAoB7E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAM5D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,aAAa,GACtB,OAAO,CAAC,cAAc,CAAC,CAuFzB"}