@vibe-agent-toolkit/utils 0.1.41 → 0.1.42

package/dist/path-core.js

@@ -0,0 +1,251 @@
+/**
+ * Pure path-string helpers.
+ *
+ * **This module's only import is `node:path`.** Nothing here touches the
+ * filesystem, the OS, or URLs — that is the whole point: the `./path` and
+ * `./glob` subpath entries re-export from here so importing them can never
+ * pull `node:fs`, `node:os`, or `node:url` into a consumer's graph.
+ *
+ * Filesystem-touching path helpers (`normalizePath`, `normalizedTmpdir`,
+ * `mkdirSyncReal`, `resolveFromImportMeta`, `dynamicImportPath`) live in
+ * `./path-utils.ts` and are exposed via the `./fs` entry.
+ */
+import path from 'node:path';
+/**
+ * Check if a path is absolute
+ *
+ * Cross-platform detection of absolute paths:
+ * - Unix: /path/to/file
+ * - Windows: C:\path\to\file or C:/path/to/file
+ *
+ * @param p - Path to check
+ * @returns True if path is absolute
+ *
+ * @example
+ * isAbsolutePath('/path/to/file')  // true
+ * isAbsolutePath('./relative')      // false
+ * isAbsolutePath('C:/Windows')      // true (Windows)
+ */
+export function isAbsolutePath(p) {
+    return path.isAbsolute(p);
+}
+/**
+ * True if `p` is absolute on ANY platform — a POSIX root path (`/etc`), a
+ * Windows drive-letter path (`C:\…` or `C:/…`), or a UNC path (`\\host\share`).
+ *
+ * Unlike {@link isAbsolutePath} (host-platform only), this is host-independent,
+ * so config-containment checks reject Windows-absolute paths even when run on
+ * POSIX CI, and vice versa. Used to keep config-supplied relative paths (skill
+ * `files:` dest) from escaping their anchor directory (zip-slip class).
+ *
+ * @example
+ * isAbsoluteAnyPlatform('/etc/passwd')   // true (POSIX)
+ * isAbsoluteAnyPlatform('C:\\Users')      // true (Windows drive)
+ * isAbsoluteAnyPlatform('scripts/cli')    // false (relative)
+ */
+export function isAbsoluteAnyPlatform(p) {
+    return path.posix.isAbsolute(p) || path.win32.isAbsolute(p);
+}
+/**
+ * True if `p` contains a `..` parent-directory traversal segment.
+ *
+ * Forward-slash-normalized, then inspects each `/`-delimited segment — so a
+ * `..` is caught regardless of the original OS separator. A containment guard
+ * for config-supplied relative paths (skill `files:` dest values, glob magic
+ * remainders) that must never climb above their anchor directory.
+ *
+ * @example
+ * hasParentTraversalSegment('a/../b')      // true
+ * hasParentTraversalSegment('a/b/c')       // false
+ * hasParentTraversalSegment('..\\evil')     // true (backslash normalized)
+ * hasParentTraversalSegment('a..b/c')      // false (".." must be a whole segment)
+ */
+export function hasParentTraversalSegment(p) {
+    return toForwardSlash(p).split('/').includes('..');
+}
+/**
+ * Compute a `ValidationIssue.location`: an absolute source file path made
+ * relative to the scan/project root, forward-slashed.
+ *
+ * This is the ONE relativizer every VAT validation lane uses. `location` is
+ * contractually project-relative (see `ValidationIssue` in
+ * `@vibe-agent-toolkit/agent-schema`), so producers must route through here
+ * rather than emitting `skillPath` directly — absolute locations leak the
+ * developer's home directory into CI logs and make `validation.allow` globs,
+ * which match against `location`, unwritable.
+ *
+ * `projectRoot` is required precisely because "relative to what?" has no safe
+ * default: a caller with no root must decide one (the skill directory, the
+ * scan root) rather than silently falling back to an absolute path.
+ *
+ * @param sourceFilePath - Absolute path to the file the issue was found in.
+ * @param projectRoot - Root the location is expressed relative to.
+ * @returns Forward-slashed relative location.
+ *
+ * @example
+ * issueLocation('/repo/skills/foo/SKILL.md', '/repo')  // 'skills/foo/SKILL.md'
+ */
+export function issueLocation(sourceFilePath, projectRoot) {
+    return toForwardSlash(path.relative(projectRoot, sourceFilePath));
+}
+/**
+ * Convert a relative path to absolute
+ *
+ * If path is already absolute, returns it normalized.
+ * Otherwise resolves relative to baseDir.
+ *
+ * @param p - Path to convert
+ * @param baseDir - Base directory for resolution
+ * @returns Absolute path with **forward slashes** (cross-platform safe)
+ *
+ * @example
+ * toAbsolutePath('./docs/README.md', '/project')
+ * // Returns: '/project/docs/README.md'
+ *
+ * toAbsolutePath('/absolute/path.md', '/project')
+ * // Returns: '/absolute/path.md'
+ */
+export function toAbsolutePath(p, baseDir) {
+    if (path.isAbsolute(p)) {
+        return toForwardSlash(path.normalize(p));
+    }
+    return toForwardSlash(path.resolve(baseDir, p));
+}
+/**
+ * Get the relative path from one file to another
+ *
+ * Useful for generating relative links between markdown files.
+ *
+ * @param from - Source file path (absolute)
+ * @param to - Target file path (absolute)
+ * @returns Relative path from source to target with **forward slashes** (cross-platform safe)
+ *
+ * @example
+ * getRelativePath('/project/docs/guide.md', '/project/README.md')
+ * // Returns: '../README.md'
+ *
+ * getRelativePath('/project/README.md', '/project/docs/api.md')
+ * // Returns: 'docs/api.md'
+ */
+export function getRelativePath(from, to) {
+    // Get directory of source file (not the file itself)
+    const fromDir = path.dirname(from);
+    // Calculate relative path from source directory to target file
+    return toForwardSlash(path.relative(fromDir, to));
+}
+/**
+ * Convert a path to forward slashes
+ *
+ * Windows accepts both forward slashes and backslashes as path separators.
+ * This function normalizes all paths to use forward slashes for consistency.
+ * Useful for glob pattern matching, cross-platform comparisons, and string operations.
+ *
+ * @param p - Path to convert
+ * @returns Path with forward slashes
+ *
+ * @example
+ * toForwardSlash('C:\\Users\\docs\\README.md')
+ * // Returns: 'C:/Users/docs/README.md'
+ *
+ * toForwardSlash('/project/docs/README.md')
+ * // Returns: '/project/docs/README.md' (unchanged)
+ */
+export function toForwardSlash(p) {
+    return p.replaceAll('\\', '/');
+}
+/**
+ * Cross-platform safe path operations.
+ *
+ * Wraps Node's `path.join()`, `path.resolve()`, and `path.relative()` to always
+ * return forward-slash paths. On Windows, the native `path.*` functions return
+ * backslashes, which causes bugs when paths are used as Map keys, compared as
+ * strings, or matched with glob patterns.
+ *
+ * **Use these instead of importing from `node:path` directly.**
+ * ESLint rules enforce this — see `no-path-join`, `no-path-resolve`, `no-path-relative`.
+ *
+ * @example
+ * ```typescript
+ * import { safePath } from '@vibe-agent-toolkit/utils';
+ *
+ * // Always forward slashes, even on Windows
+ * safePath.join('C:\\Users', 'docs', 'file.md')          // → 'C:/Users/docs/file.md'
+ * safePath.resolve('/project', './docs')                   // → '/project/docs'
+ * safePath.relative('/project/docs', '/project')           // → '..'
+ * safePath.joinUnderRoot('/harness', 'skill-abc')          // → '/harness/skill-abc'
+ * safePath.joinUnderRoot('/harness', '../escape')          // throws Error
+ * ```
+ */
+export const safePath = {
+    /** Like `path.join()` but always returns forward slashes. */
+    join(...paths) {
+        return toForwardSlash(path.join(...paths));
+    },
+    /** Like `path.resolve()` but always returns forward slashes. */
+    resolve(...paths) {
+        return toForwardSlash(path.resolve(...paths));
+    },
+    /** Like `path.relative()` but always returns forward slashes. */
+    relative(from, to) {
+        return toForwardSlash(path.relative(from, to));
+    },
+    /**
+     * Join path segments under a security root, throwing if the result would escape.
+     *
+     * Resolves `root + segments` and verifies the result is strictly inside `root`
+     * (or equal to it). Throws when any segment would cause the result to escape:
+     *
+     * - A `..` traversal that climbs above root
+     * - An absolute POSIX path segment (e.g. `/etc/passwd`)
+     * - A Windows drive-letter segment (e.g. `C:\Users\evil`)
+     *
+     * On success returns a forward-slash-normalized absolute path (consistent with
+     * the other `safePath` helpers).
+     *
+     * **Use this instead of `safePath.join(root, segment)` whenever `segment` may
+     * contain caller-controlled input** — this is the bug class that the original
+     * skill-test staging code was vulnerable to on Windows.
+     *
+     * @returns Forward-slash absolute path guaranteed to be inside `root`.
+     * @throws {Error} If the resolved path would escape `root`.
+     *
+     * @example
+     * ```typescript
+     * // ✅ Safe — throws if caller passes '../../../etc'
+     * const dest = safePath.joinUnderRoot(harnessRoot, stagedDirName(item.name));
+     *
+     * // ❌ Unsafe — silently escapes on Windows with absolute segment
+     * const dest = safePath.join(harnessRoot, item.name);
+     * ```
+     */
+    joinUnderRoot(root, ...segments) {
+        // Eagerly reject any segment that is absolute (POSIX or Windows drive-letter)
+        // BEFORE resolving, so the error message can name the offending segment.
+        for (const seg of segments) {
+            if (path.isAbsolute(seg)) {
+                throw new Error(`safePath.joinUnderRoot: segment "${seg}" is absolute and escapes root "${root}".`);
+            }
+            // Windows drive-letter check for POSIX hosts (path.isAbsolute won't catch
+            // 'C:\...' on POSIX, but node's path.win32.isAbsolute does).
+            if (path.win32.isAbsolute(seg)) {
+                throw new Error(`safePath.joinUnderRoot: segment "${seg}" contains a Windows drive letter and escapes root "${root}".`);
+            }
+        }
+        const resolvedRoot = path.resolve(root);
+        const resolvedResult = segments.length > 0
+            ? path.resolve(resolvedRoot, ...segments)
+            : resolvedRoot;
+        // Containment check: normalize both to forward slashes so the comparison
+        // is platform-independent and no path.sep is needed in string operations.
+        const fwdRoot = toForwardSlash(resolvedRoot);
+        const fwdResult = toForwardSlash(resolvedResult);
+        // Result must equal root or start with root + '/' (not just startsWith(root)
+        // which would match '/rootEvil' when root is '/root').
+        const rootPrefix = fwdRoot.endsWith('/') ? fwdRoot : `${fwdRoot}/`;
+        if (fwdResult !== fwdRoot && !fwdResult.startsWith(rootPrefix)) {
+            throw new Error(`safePath.joinUnderRoot: result "${fwdResult}" escapes root "${fwdRoot}".`);
+        }
+        return fwdResult;
+    },
+};
+//# sourceMappingURL=path-core.js.map

package/dist/path-core.js.map

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

package/dist/path-utils.d.ts

@@ -1,4 +1,16 @@
 import { mkdirSync } from 'node:fs';
+/**
+ * Re-export every pure path helper so the package barrel keeps exposing the
+ * exact same surface it always has. The pure definitions themselves live in
+ * `./path-core.ts`, which imports nothing but `node:path` — see that file's
+ * header for why the split exists.
+ *
+ * This preserves the BARREL only. `@vibe-agent-toolkit/utils/fs` no longer
+ * re-exports the pure helpers — they moved to `@vibe-agent-toolkit/utils/path`,
+ * which is a breaking change for `./fs` consumers (see CHANGELOG and
+ * `test/path-fs-subpaths.test.ts`).
+ */
+export * from './path-core.js';
 /**
  * Normalize any path (resolve short names on Windows)
  *
@@ -90,189 +102,6 @@ export declare function normalizedTmpdir(): string;
  * ```
  */
 export declare function mkdirSyncReal(dirPath: string, options?: Parameters<typeof mkdirSync>[1]): string;
-/**
- * Check if a path is absolute
- *
- * Cross-platform detection of absolute paths:
- * - Unix: /path/to/file
- * - Windows: C:\path\to\file or C:/path/to/file
- *
- * @param p - Path to check
- * @returns True if path is absolute
- *
- * @example
- * isAbsolutePath('/path/to/file')  // true
- * isAbsolutePath('./relative')      // false
- * isAbsolutePath('C:/Windows')      // true (Windows)
- */
-export declare function isAbsolutePath(p: string): boolean;
-/**
- * True if `p` is absolute on ANY platform — a POSIX root path (`/etc`), a
- * Windows drive-letter path (`C:\…` or `C:/…`), or a UNC path (`\\host\share`).
- *
- * Unlike {@link isAbsolutePath} (host-platform only), this is host-independent,
- * so config-containment checks reject Windows-absolute paths even when run on
- * POSIX CI, and vice versa. Used to keep config-supplied relative paths (skill
- * `files:` dest) from escaping their anchor directory (zip-slip class).
- *
- * @example
- * isAbsoluteAnyPlatform('/etc/passwd')   // true (POSIX)
- * isAbsoluteAnyPlatform('C:\\Users')      // true (Windows drive)
- * isAbsoluteAnyPlatform('scripts/cli')    // false (relative)
- */
-export declare function isAbsoluteAnyPlatform(p: string): boolean;
-/**
- * True if `p` contains a `..` parent-directory traversal segment.
- *
- * Forward-slash-normalized, then inspects each `/`-delimited segment — so a
- * `..` is caught regardless of the original OS separator. A containment guard
- * for config-supplied relative paths (skill `files:` dest values, glob magic
- * remainders) that must never climb above their anchor directory.
- *
- * @example
- * hasParentTraversalSegment('a/../b')      // true
- * hasParentTraversalSegment('a/b/c')       // false
- * hasParentTraversalSegment('..\\evil')     // true (backslash normalized)
- * hasParentTraversalSegment('a..b/c')      // false (".." must be a whole segment)
- */
-export declare function hasParentTraversalSegment(p: string): boolean;
-/**
- * Compute a `ValidationIssue.location`: an absolute source file path made
- * relative to the scan/project root, forward-slashed.
- *
- * This is the ONE relativizer every VAT validation lane uses. `location` is
- * contractually project-relative (see `ValidationIssue` in
- * `@vibe-agent-toolkit/agent-schema`), so producers must route through here
- * rather than emitting `skillPath` directly — absolute locations leak the
- * developer's home directory into CI logs and make `validation.allow` globs,
- * which match against `location`, unwritable.
- *
- * `projectRoot` is required precisely because "relative to what?" has no safe
- * default: a caller with no root must decide one (the skill directory, the
- * scan root) rather than silently falling back to an absolute path.
- *
- * @param sourceFilePath - Absolute path to the file the issue was found in.
- * @param projectRoot - Root the location is expressed relative to.
- * @returns Forward-slashed relative location.
- *
- * @example
- * issueLocation('/repo/skills/foo/SKILL.md', '/repo')  // 'skills/foo/SKILL.md'
- */
-export declare function issueLocation(sourceFilePath: string, projectRoot: string): string;
-/**
- * Convert a relative path to absolute
- *
- * If path is already absolute, returns it normalized.
- * Otherwise resolves relative to baseDir.
- *
- * @param p - Path to convert
- * @param baseDir - Base directory for resolution
- * @returns Absolute path with **forward slashes** (cross-platform safe)
- *
- * @example
- * toAbsolutePath('./docs/README.md', '/project')
- * // Returns: '/project/docs/README.md'
- *
- * toAbsolutePath('/absolute/path.md', '/project')
- * // Returns: '/absolute/path.md'
- */
-export declare function toAbsolutePath(p: string, baseDir: string): string;
-/**
- * Get the relative path from one file to another
- *
- * Useful for generating relative links between markdown files.
- *
- * @param from - Source file path (absolute)
- * @param to - Target file path (absolute)
- * @returns Relative path from source to target with **forward slashes** (cross-platform safe)
- *
- * @example
- * getRelativePath('/project/docs/guide.md', '/project/README.md')
- * // Returns: '../README.md'
- *
- * getRelativePath('/project/README.md', '/project/docs/api.md')
- * // Returns: 'docs/api.md'
- */
-export declare function getRelativePath(from: string, to: string): string;
-/**
- * Convert a path to forward slashes
- *
- * Windows accepts both forward slashes and backslashes as path separators.
- * This function normalizes all paths to use forward slashes for consistency.
- * Useful for glob pattern matching, cross-platform comparisons, and string operations.
- *
- * @param p - Path to convert
- * @returns Path with forward slashes
- *
- * @example
- * toForwardSlash('C:\\Users\\docs\\README.md')
- * // Returns: 'C:/Users/docs/README.md'
- *
- * toForwardSlash('/project/docs/README.md')
- * // Returns: '/project/docs/README.md' (unchanged)
- */
-export declare function toForwardSlash(p: string): string;
-/**
- * Cross-platform safe path operations.
- *
- * Wraps Node's `path.join()`, `path.resolve()`, and `path.relative()` to always
- * return forward-slash paths. On Windows, the native `path.*` functions return
- * backslashes, which causes bugs when paths are used as Map keys, compared as
- * strings, or matched with glob patterns.
- *
- * **Use these instead of importing from `node:path` directly.**
- * ESLint rules enforce this — see `no-path-join`, `no-path-resolve`, `no-path-relative`.
- *
- * @example
- * ```typescript
- * import { safePath } from '@vibe-agent-toolkit/utils';
- *
- * // Always forward slashes, even on Windows
- * safePath.join('C:\\Users', 'docs', 'file.md')          // → 'C:/Users/docs/file.md'
- * safePath.resolve('/project', './docs')                   // → '/project/docs'
- * safePath.relative('/project/docs', '/project')           // → '..'
- * safePath.joinUnderRoot('/harness', 'skill-abc')          // → '/harness/skill-abc'
- * safePath.joinUnderRoot('/harness', '../escape')          // throws Error
- * ```
- */
-export declare const safePath: {
-    /** Like `path.join()` but always returns forward slashes. */
-    readonly join: (...paths: string[]) => string;
-    /** Like `path.resolve()` but always returns forward slashes. */
-    readonly resolve: (...paths: string[]) => string;
-    /** Like `path.relative()` but always returns forward slashes. */
-    readonly relative: (from: string, to: string) => string;
-    /**
-     * Join path segments under a security root, throwing if the result would escape.
-     *
-     * Resolves `root + segments` and verifies the result is strictly inside `root`
-     * (or equal to it). Throws when any segment would cause the result to escape:
-     *
-     * - A `..` traversal that climbs above root
-     * - An absolute POSIX path segment (e.g. `/etc/passwd`)
-     * - A Windows drive-letter segment (e.g. `C:\Users\evil`)
-     *
-     * On success returns a forward-slash-normalized absolute path (consistent with
-     * the other `safePath` helpers).
-     *
-     * **Use this instead of `safePath.join(root, segment)` whenever `segment` may
-     * contain caller-controlled input** — this is the bug class that the original
-     * skill-test staging code was vulnerable to on Windows.
-     *
-     * @returns Forward-slash absolute path guaranteed to be inside `root`.
-     * @throws {Error} If the resolved path would escape `root`.
-     *
-     * @example
-     * ```typescript
-     * // ✅ Safe — throws if caller passes '../../../etc'
-     * const dest = safePath.joinUnderRoot(harnessRoot, stagedDirName(item.name));
-     *
-     * // ❌ Unsafe — silently escapes on Windows with absolute segment
-     * const dest = safePath.join(harnessRoot, item.name);
-     * ```
-     */
-    readonly joinUnderRoot: (root: string, ...segments: string[]) => string;
-};
 /**
  * Resolve an OS-native absolute path from an ESM module's `import.meta.url` and
  * optional relative path segments.

package/dist/path-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path-utils.d.ts","sourceRoot":"","sources":["../src/path-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAgB,MAAM,SAAS,CAAC;AAKlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,aAAa,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CA+BxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAezC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,GACxC,MAAM,CAiBR;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,cAAc,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAKjE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAMhE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,QAAQ;IACnB,6DAA6D;8BAC9C,MAAM,EAAE,KAAG,MAAM;IAIhC,gEAAgE;iCAC9C,MAAM,EAAE,KAAG,MAAM;IAInC,iEAAiE;8BAClD,MAAM,MAAM,MAAM,KAAG,MAAM;IAI1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;mCACiB,MAAM,eAAe,MAAM,EAAE,KAAG,MAAM;CAuClD,CAAC;AAEX;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAQ1F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAGhF"}
+{"version":3,"file":"path-utils.d.ts","sourceRoot":"","sources":["../src/path-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAgB,MAAM,SAAS,CAAC;AAOlD;;;;;;;;;;GAUG;AACH,cAAc,gBAAgB,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,aAAa,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CA+BxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAezC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,GACxC,MAAM,CAiBR;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAQ1F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAGhF"}