harnery 0.7.0 → 0.8.0

package/README.md

@@ -23,7 +23,7 @@
 - **Standalone web UI:** `harn web up` boots a local Next.js dashboard for the coord layer, councils, per-project state, and a local coding-agent status view (Claude Code / Codex / Cursor usage, backed by `harn devtools`). Ships with the git clone, not the npm package (see [Install](#install)).
 - **Backup + sync:** `harn backup` snapshots `.harnery/` via [restic](https://restic.net/); `harn sync` keeps a curated subset live across machines via [rclone](https://rclone.org/) (Google Drive or any rclone remote).
 
-The CLI also ships batteries: portable utility commands (`tokens`, `eml`, `env`, `grep`, `docs`, `browse`, `fetch`, `read`, `devtools`, and more) plus the library toolkit they're built from. Useful, cross-platform, dependency-light — and deliberately not the headline. Coordination is why harnery exists; the toolkit exists because the CLI needed it (see [Public surface tiers](#public-surface-tiers)).
+The CLI also ships batteries: portable utility commands (`tokens`, `eml`, `env`, `grep` — parallel, ripgrep-accelerated monorepo search — `docs`, `browse`, `fetch`, `read`, `devtools`, and more) plus the library toolkit they're built from. Useful, cross-platform, dependency-light — and deliberately not the headline. Coordination is why harnery exists; the toolkit exists because the CLI needed it (see [Public surface tiers](#public-surface-tiers)).
 
 ## Install
 

package/dist/commander.d.ts

@@ -78,6 +78,15 @@ export interface HarneryProgramContext {
      * carrying provider-specific checks. harn standalone ships none.
      */
     envSections?: Record<string, EnvSection>;
+    /**
+     * Extra directory names for `grep` to exclude by default — host-generated
+     * mirrors, vendored trees, and similar directories that only ever produce
+     * duplicate or noisy matches. Names match at any depth (same semantics as
+     * grep's `--exclude-dir`). Applied alongside the built-in skip list and
+     * disabled together with it by `--no-default-excludes`. harn standalone
+     * ships none.
+     */
+    grepExcludeDirs?: readonly string[];
     /**
      * Optional callback that returns extra HTTP headers to attach to outbound
      * `fetch` calls based on the target URL. Useful for consumers that need

package/dist/commander.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commander.d.ts","sourceRoot":"","sources":["../src/commander.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAiCpC,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAEhC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IAEnB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,8CAA8C;AAC9C,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;CAC7C;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;AAEnD,MAAM,WAAW,qBAAqB;IACpC,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACzC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvD;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE;QACvB,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,KAAK,MAAM,GAAG,SAAS,CAAC;IACzB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACvE;;;;;OAKG;IACH,yBAAyB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CACjE;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,IAAI,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACxC,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC;IAC5C,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC3D,KAAK,CAAC,GAAG,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,KAAK,GAAG,OAAO,GAAG,IAAI,CAAC;IACrF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IACpE,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,eAAO,MAAM,WAAW,EAAE,WAkCzB,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,kBAAuB,GAAG,OAAO,CA6C3E"}
+{"version":3,"file":"commander.d.ts","sourceRoot":"","sources":["../src/commander.ts"],"names":[],"mappings":"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"}

package/dist/commands/callers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"callers.d.ts","sourceRoot":"","sources":["../../src/commands/callers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAuE1E,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA6BN"}
+{"version":3,"file":"callers.d.ts","sourceRoot":"","sources":["../../src/commands/callers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AA0E1E,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA6BN"}

package/dist/commands/callers.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { resolveSearchEngine } from "../lib/tools/ripgrep.js";
 const DEFAULT_EXCLUDE_DIRS = [
     ".git",
     ".cache",
@@ -62,20 +63,29 @@ async function runCallers(symbol, opts, context) {
         throw new Error(`symbol must be a valid identifier (got: ${symbol})`);
     }
     const started = Date.now();
+    const { engine, rgBin } = await resolveSearchEngine("callers");
     const repos = resolveRepos(opts, context);
     const limit = opts.limit ? Number.parseInt(opts.limit, 10) : 500;
+    // Search every repo concurrently, each capped at the global limit, then
+    // apply the global budget in repo order so truncation stays deterministic.
+    // In --all-repos mode the parent scan prunes submodule dirs (each submodule
+    // is scanned on its own), so a match is attributed to exactly one repo.
+    const perRepo = await Promise.all(repos.map((repo) => {
+        const pruneDirs = opts.allRepos && repo.name === "parent" ? (context?.submodules ?? []) : [];
+        return searchInRepo(symbol, opts, repo, limit, engine, rgBin, pruneDirs);
+    }));
     const allCallers = [];
     let truncated = false;
-    for (const repo of repos) {
-        if (allCallers.length >= limit) {
-            truncated = true;
-            break;
-        }
-        const remaining = limit - allCallers.length;
-        const found = await grepInRepo(symbol, opts, repo, remaining);
+    let budget = limit;
+    for (let i = 0; i < repos.length; i++) {
+        const found = perRepo[i] ?? { callers: [], truncated: false };
         if (found.truncated)
             truncated = true;
-        allCallers.push(...found.callers);
+        const take = Math.min(found.callers.length, Math.max(0, budget));
+        if (found.callers.length > take)
+            truncated = true;
+        allCallers.push(...found.callers.slice(0, take));
+        budget -= take;
     }
     const by_kind = {};
     for (const c of allCallers) {
@@ -121,22 +131,61 @@ function resolveRepos(opts, context) {
     }
     return [{ name: "cwd", cwd: process.cwd() }];
 }
-function grepInRepo(symbol, opts, repo, limit) {
-    const args = ["-rnw", "--color=never", "-I", "-E"];
-    for (const d of DEFAULT_EXCLUDE_DIRS)
-        args.push(`--exclude-dir=${d}`);
-    for (const f of DEFAULT_EXCLUDE_FILES)
-        args.push(`--exclude=${f}`);
+function resolveLangGlobs(opts) {
     const langGlobs = opts.lang ? LANG_GLOBS[opts.lang] : undefined;
     if (opts.lang && !langGlobs) {
         throw new Error(`unknown --lang "${opts.lang}". Valid: ${Object.keys(LANG_GLOBS).join(", ")}`);
     }
+    return langGlobs;
+}
+function buildCallersGrepArgs(symbol, opts, extraExcludeDirs) {
+    const args = ["-rnw", "-H", "--color=never", "-I", "-E"];
+    for (const d of DEFAULT_EXCLUDE_DIRS)
+        args.push(`--exclude-dir=${d}`);
+    for (const f of DEFAULT_EXCLUDE_FILES)
+        args.push(`--exclude=${f}`);
+    for (const d of extraExcludeDirs)
+        args.push(`--exclude-dir=${d}`);
+    const langGlobs = resolveLangGlobs(opts);
     if (langGlobs)
         for (const g of langGlobs)
             args.push(`--include=${g}`);
     args.push("--", symbol, ".");
+    return args;
+}
+function buildCallersRgArgs(symbol, opts, extraExcludeDirs) {
+    // --hidden --no-ignore --no-config: match grep semantics (dotdirs searched,
+    // .gitignore ignored, user rg config can't skew results). -w = whole word.
+    // Lang globs (positives) go before dir excludes (negatives) since rg globs
+    // are last-match-wins.
+    const args = [
+        "-nw",
+        "--no-heading",
+        "--with-filename",
+        "--color=never",
+        "--no-config",
+        "--hidden",
+        "--no-ignore",
+    ];
+    const langGlobs = resolveLangGlobs(opts);
+    if (langGlobs)
+        for (const g of langGlobs)
+            args.push(`--glob=${g}`);
+    for (const d of DEFAULT_EXCLUDE_DIRS)
+        args.push(`--glob=!${d}`);
+    for (const f of DEFAULT_EXCLUDE_FILES)
+        args.push(`--glob=!${f}`);
+    for (const d of extraExcludeDirs)
+        args.push(`--glob=!${d}`);
+    args.push("--", symbol, ".");
+    return args;
+}
+function searchInRepo(symbol, opts, repo, limit, engine, rgBin, extraExcludeDirs) {
+    const [bin, args] = engine === "rg"
+        ? [rgBin, buildCallersRgArgs(symbol, opts, extraExcludeDirs)]
+        : ["grep", buildCallersGrepArgs(symbol, opts, extraExcludeDirs)];
     return new Promise((resolveP, reject) => {
-        const proc = spawn("grep", args, { cwd: repo.cwd, stdio: ["ignore", "pipe", "pipe"] });
+        const proc = spawn(bin, args, { cwd: repo.cwd, stdio: ["ignore", "pipe", "pipe"] });
         const callers = [];
         let buffer = "";
         let stderr = "";
@@ -174,8 +223,11 @@ function grepInRepo(symbol, opts, repo, limit) {
                 if (parsed)
                     callers.push(parsed);
             }
-            if (code !== null && code !== 0 && code !== 1 && !truncated) {
-                reject(new Error(`grep exited ${code}: ${stderr.trim() || "(no stderr)"}`));
+            // Exit 1 = no matches (both engines): normal. Exit 2 with nothing
+            // collected = a real failure; with matches, a partial walk error we
+            // tolerate (surface what was found).
+            if (code !== null && code !== 0 && code !== 1 && !truncated && callers.length === 0) {
+                reject(new Error(`${bin} exited ${code}: ${stderr.trim() || "(no stderr)"}`));
                 return;
             }
             resolveP({ callers, truncated });

package/dist/commands/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAInD,KAAK,QAAQ,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC,UAAU,KAAK;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAMD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAwC/E;AAED,wBAAgB,SAAS,IAAI,KAAK,EAAE,CAYnC"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAKnD,KAAK,QAAQ,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC,UAAU,KAAK;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAOD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAmD/E;AAED,wBAAgB,SAAS,IAAI,KAAK,EAAE,CAanC"}

package/dist/commands/doctor.js

@@ -14,15 +14,25 @@ import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { resolveBinName } from "../core/config.js";
+import { resolveBinName, ripgrepAutoInstall } from "../core/config.js";
 import { loadHarnessWiring } from "../core/hooks/harness/wiring.js";
+import { findRg, installRg, managedRgPath, rgInstallSupported } from "../lib/tools/ripgrep.js";
 export function registerDoctorCommand(program, emit) {
     program
         .command("doctor")
         .description("Verify the runtime + optional deps harnery commands expect. Exits 0 " +
         "unless a required dep (Node, git) is missing.")
         .option("--json", "Machine-readable JSON output")
-        .action((opts) => {
+        .option("--fix", "Install missing managed tools (currently: ripgrep, pinned + checksum-verified)")
+        .action(async (opts) => {
+        if (opts.fix && !findRg() && rgInstallSupported()) {
+            try {
+                await installRg((line) => emit.text(`${line}\n`));
+            }
+            catch (err) {
+                emit.text(`ripgrep install failed: ${err.message}\n`);
+            }
+        }
         const checks = runChecks();
         const requiredFailed = checks.some((c) => c.severity === "fail");
         if (opts.json) {
@@ -56,6 +66,7 @@ export function runChecks() {
         checkNode(),
         checkGit(),
         checkBun(),
+        checkRipgrep(),
         checkHarneryDir(),
         checkHarnessHooks(),
         checkRestic(),
@@ -64,6 +75,39 @@ export function runChecks() {
         checkPython(),
     ];
 }
+function checkRipgrep() {
+    const found = findRg();
+    if (found) {
+        const r = whichVersion(found);
+        const managed = found === managedRgPath() ? ", managed" : "";
+        return {
+            name: "ripgrep",
+            severity: "ok",
+            detail: `${r.out.replace(/^ripgrep\s*/, "")} (${found === "rg" ? "PATH" : found}${managed})`,
+        };
+    }
+    if (!rgInstallSupported()) {
+        return {
+            name: "ripgrep",
+            severity: "warn",
+            detail: "missing (grep fallback; no pinned artifact for this OS/arch)",
+            hint: "https://github.com/BurntSushi/ripgrep#installation",
+        };
+    }
+    if (ripgrepAutoInstall()) {
+        return {
+            name: "ripgrep",
+            severity: "warn",
+            detail: "missing (autoInstall on: will self-provision on first grep)",
+        };
+    }
+    return {
+        name: "ripgrep",
+        severity: "warn",
+        detail: "missing (grep fallback works, just slower)",
+        hint: `${resolveBinName()} doctor --fix  (pinned + checksum-verified, installs to the harnery tools dir)`,
+    };
+}
 function whichVersion(bin, args = ["--version"]) {
     const r = spawnSync(bin, args, { encoding: "utf-8" });
     if (r.status !== 0)

package/dist/commands/grep.d.ts

@@ -1,4 +1,48 @@
 import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.js";
+import { type SearchEngine } from "../lib/tools/ripgrep.js";
+export type GrepEngine = SearchEngine;
+export interface GrepOpts {
+    repo?: string;
+    allRepos?: boolean;
+    lang?: string;
+    ignoreCase?: boolean;
+    wholeWord?: boolean;
+    literal?: boolean;
+    filesOnly?: boolean;
+    files?: boolean;
+    count?: boolean;
+    context?: string;
+    maxCount?: string;
+    limit?: string;
+    include?: string[];
+    exclude?: string[];
+    noDefaultExcludes?: boolean;
+    json?: boolean;
+}
+interface Match {
+    repo: string;
+    file: string;
+    line: number;
+    text: string;
+}
 export declare function registerGrepCommand(program: Command, emit: EmitContext, context?: HarneryProgramContext): void;
+export interface GrepResult {
+    pattern: string;
+    mode: "regex" | "literal" | "files";
+    engine: GrepEngine;
+    repos: {
+        name: string;
+        cwd: string;
+        matches: Match[];
+        truncated: boolean;
+    }[];
+    total_matches: number;
+    total_files: number;
+    truncated: boolean;
+    elapsed_ms: number;
+}
+/** Exported for tests (not part of the package exports map). */
+export declare function runGrep(pattern: string, paths: string[], opts: GrepOpts, context: HarneryProgramContext | undefined): Promise<GrepResult>;
+export {};
 //# sourceMappingURL=grep.d.ts.map

package/dist/commands/grep.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grep.d.ts","sourceRoot":"","sources":["../../src/commands/grep.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AA4E1E,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAoCN"}
+{"version":3,"file":"grep.d.ts","sourceRoot":"","sources":["../../src/commands/grep.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAgEjF,MAAM,MAAM,UAAU,GAAG,YAAY,CAAC;AAEtC,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,UAAU,KAAK;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA0CN;AAMD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;IACpC,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,KAAK,EAAE,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;IAC7E,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,gEAAgE;AAChE,wBAAsB,OAAO,CAC3B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EAAE,EACf,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,qBAAqB,GAAG,SAAS,GACzC,OAAO,CAAC,UAAU,CAAC,CA4FrB"}