@nifrajs/cli 0.1.0-alpha.1

package/dist/doctor.js

@@ -0,0 +1,291 @@
+/**
+ * `nifra doctor` — catches the Bun-workspace footgun the typed-client lint can't: a package that's
+ * IMPORTED in source but NOT declared in `package.json`. Bun resolves it at runtime (via hoisting or a
+ * workspace), so tests pass and `bun install` reports "no changes" — false confidence — yet `tsc` fails
+ * and a fresh or standalone install can't resolve it. doctor diffs every bare import specifier against
+ * the package's declared dependencies and flags the gap, with a stable `--json` shape for agents/CI.
+ *
+ * Scope is intentionally per-package: it checks the `package.json` at `cwd`, because a dependency must be
+ * declared by the package that imports it (for `tsc` and for that package to install on its own) even
+ * when a monorepo would hoist it. Relative paths, runtime builtins (node core, `node:`/`bun:`, `bun`),
+ * the package's own name, and tsconfig `paths` aliases are excluded — none of them are npm deps.
+ */
+import { builtinModules } from "node:module";
+import { dirname, join } from "node:path";
+import { stripComments, walkSource } from "./check.js";
+// Runtime-provided modules that are never an npm dependency: Node core (bare + `node:` form) and Bun's
+// own `bun` module. `node:`/`bun:`-prefixed specifiers are filtered in packageOf by prefix.
+const BUILTINS = new Set([
+    ...builtinModules,
+    ...builtinModules.map((m) => `node:${m}`),
+    "bun",
+]);
+// The four specifier-bearing forms: static import/re-export with a source, side-effect import, dynamic
+// import, and CJS require. Anchored with `(?<![.\w$])` so `myimport`/`.import`/`foorequire` never match.
+// Comments are stripped before these run (see stripComments) — else a doc-comment usage example would be
+// flagged as a real import.
+const IMPORT_PATTERNS = [
+    /(?<![.\w$])(?:import|export)\b[^'"]*?\bfrom\s*['"]([^'"]+)['"]/g,
+    /(?<![.\w$])import\s+['"]([^'"]+)['"]/g,
+    /(?<![.\w$])import\s*\(\s*['"]([^'"]+)['"]/g,
+    /(?<![.\w$])require\s*\(\s*['"]([^'"]+)['"]/g,
+];
+const NPM_PACKAGE_NAME = /^(?:@[A-Za-z0-9._-]+\/)?[A-Za-z0-9._-]+$/;
+const DEPENDENCY_FIELDS = [
+    "dependencies",
+    "devDependencies",
+    "peerDependencies",
+    "optionalDependencies",
+];
+const isNpmPackageName = (name) => NPM_PACKAGE_NAME.test(name) &&
+    name.split("/").every((part) => part !== "" && part !== "." && part !== "..");
+/**
+ * Resolve an import specifier to the npm package name it would install as, or `undefined` when it isn't
+ * an npm dependency at all (a relative/absolute path, a runtime builtin, or a malformed scope like the
+ * `@/…` path-alias convention). `@scope/name/sub` → `@scope/name`; `name/sub` → `name`.
+ */
+export function packageOf(spec) {
+    if (spec === "" || spec.startsWith(".") || spec.startsWith("/"))
+        return undefined;
+    if (spec.startsWith("node:") || spec.startsWith("bun:"))
+        return undefined;
+    if (spec.startsWith("@")) {
+        const [scope, name] = spec.split("/");
+        if (!scope || scope === "@" || !name)
+            return undefined; // `@/alias`, `@foo` — not a real package
+        const pkg = `${scope}/${name}`;
+        return isNpmPackageName(pkg) ? pkg : undefined;
+    }
+    const name = spec.split("/")[0];
+    if (!isNpmPackageName(name))
+        return undefined;
+    return BUILTINS.has(name) ? undefined : name;
+}
+/** Build a predicate matching tsconfig `paths` aliases (e.g. `@/*`, `~/utils`), which resolve to local
+ * source, not npm packages — so doctor must not flag them. */
+export function aliasMatcher(paths) {
+    const prefixes = Object.keys(paths ?? {})
+        .map((k) => k.replace(/\/?\*$/, ""))
+        .filter((p) => p !== "");
+    return (spec) => prefixes.some((p) => spec === p || spec.startsWith(`${p}/`));
+}
+/**
+ * Scan one file for bare imports whose resolved package is neither `declared` nor a path `alias`. Pure +
+ * line-accurate. Deduped per (package, line): the `snippet` carries the undeclared package name.
+ */
+export function scanUndeclaredImports(file, content, declared, isAlias) {
+    const out = [];
+    const seen = new Set();
+    const code = stripComments(content); // so doc-comment usage examples aren't read as real imports
+    for (const rx of IMPORT_PATTERNS) {
+        rx.lastIndex = 0;
+        for (let m = rx.exec(code); m !== null; m = rx.exec(code)) {
+            const spec = m[1] ?? "";
+            if (isAlias(spec))
+                continue;
+            const pkg = packageOf(spec);
+            if (pkg === undefined || declared.has(pkg))
+                continue;
+            const line = content.slice(0, m.index).split("\n").length;
+            const key = `${pkg}@${line}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push({ file, line, snippet: pkg });
+        }
+    }
+    return out.sort((a, b) => a.line - b.line || a.snippet.localeCompare(b.snippet));
+}
+/** Read + parse a JSON file, or `undefined` if it's missing/unparseable (doctor degrades, never throws). */
+async function readJson(path) {
+    try {
+        const text = await Bun.file(path).text();
+        const parsed = JSON.parse(text);
+        return typeof parsed === "object" && parsed !== null
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const depNames = (pkg, field) => {
+    const deps = pkg[field];
+    return typeof deps === "object" && deps !== null
+        ? Object.keys(deps)
+        : [];
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function depRecord(pkg, field) {
+    const deps = pkg[field];
+    return isRecord(deps) ? deps : undefined;
+}
+function dependencySpec(pkg, name) {
+    for (const field of DEPENDENCY_FIELDS) {
+        const spec = depRecord(pkg, field)?.[name];
+        if (typeof spec === "string" && spec.length > 0)
+            return spec;
+    }
+    return undefined;
+}
+async function ancestorDependencySpec(cwd, name) {
+    for (let dir = dirname(cwd);; dir = dirname(dir)) {
+        const pkg = await readJson(join(dir, "package.json"));
+        if (pkg !== undefined) {
+            const spec = dependencySpec(pkg, name);
+            if (spec !== undefined)
+                return spec;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+    }
+}
+async function installedPackageSpec(cwd, name) {
+    if (!isNpmPackageName(name))
+        return undefined;
+    const parts = name.split("/");
+    for (let dir = cwd;; dir = dirname(dir)) {
+        const meta = await readJson(join(dir, "node_modules", ...parts, "package.json"));
+        if (typeof meta?.version === "string" && meta.version.length > 0) {
+            return `^${meta.version}`;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+    }
+}
+async function inferDependencyFix(cwd, name) {
+    const ancestorSpec = await ancestorDependencySpec(cwd, name);
+    if (ancestorSpec !== undefined) {
+        return { version: ancestorSpec, source: "ancestor-package-json" };
+    }
+    const installedSpec = await installedPackageSpec(cwd, name);
+    return installedSpec === undefined
+        ? undefined
+        : { version: installedSpec, source: "installed-package-json" };
+}
+/** Run doctor against the project at `cwd`: diff source imports vs declared deps. */
+export async function collectDoctorResult(cwd) {
+    const pkg = await readJson(join(cwd, "package.json"));
+    if (pkg === undefined)
+        return { ok: true, ran: false, findings: [] };
+    const declared = new Set();
+    if (typeof pkg.name === "string")
+        declared.add(pkg.name); // a package may import its own name (exports map)
+    for (const field of DEPENDENCY_FIELDS) {
+        for (const name of depNames(pkg, field))
+            declared.add(name);
+    }
+    const tsconfig = await readJson(join(cwd, "tsconfig.json"));
+    const compilerOptions = tsconfig?.compilerOptions;
+    const isAlias = aliasMatcher(compilerOptions?.paths);
+    const findings = [];
+    await walkSource(cwd, (rel, content) => {
+        for (const f of scanUndeclaredImports(rel, content, declared, isAlias)) {
+            findings.push({ file: f.file, line: f.line, package: f.snippet });
+        }
+    });
+    findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+    return { ok: findings.length === 0, ran: true, findings };
+}
+/** Safely add undeclared imports to package.json when the version can be inferred without network I/O. */
+export async function applyDoctorAutoFix(cwd) {
+    const before = await collectDoctorResult(cwd);
+    if (!before.ran || before.findings.length === 0)
+        return before;
+    const pkgPath = join(cwd, "package.json");
+    const pkg = await readJson(pkgPath);
+    if (pkg === undefined)
+        return before;
+    const dependencies = pkg.dependencies;
+    if (dependencies !== undefined && !isRecord(dependencies)) {
+        const skippedFixes = [...new Set(before.findings.map((f) => f.package))].sort().map((name) => ({
+            package: name,
+            reason: "`dependencies` exists but is not an object; refusing to rewrite it automatically",
+            command: ["bun", "add", name],
+        }));
+        return { ...before, skippedFixes };
+    }
+    const deps = (dependencies ?? {});
+    if (dependencies === undefined)
+        pkg.dependencies = deps;
+    const fixed = [];
+    const skippedFixes = [];
+    for (const name of [...new Set(before.findings.map((f) => f.package))].sort()) {
+        if (!isNpmPackageName(name)) {
+            skippedFixes.push({
+                package: name,
+                reason: "package name did not match npm package-name syntax",
+                command: ["bun", "add", name],
+            });
+            continue;
+        }
+        const inferred = await inferDependencyFix(cwd, name);
+        if (inferred === undefined) {
+            skippedFixes.push({
+                package: name,
+                reason: "no declared ancestor version or installed package metadata was found locally",
+                command: ["bun", "add", name],
+            });
+            continue;
+        }
+        deps[name] = inferred.version;
+        fixed.push({ package: name, field: "dependencies", ...inferred });
+    }
+    if (fixed.length > 0)
+        await Bun.write(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+    const after = fixed.length > 0 ? await collectDoctorResult(cwd) : before;
+    return {
+        ...after,
+        ...(fixed.length > 0 ? { fixed } : {}),
+        ...(skippedFixes.length > 0 ? { skippedFixes } : {}),
+    };
+}
+/** Run doctor; print a report (`--json` for machine output) and return whether it passed. */
+export async function runDoctor(cwd, opts = {}) {
+    const result = opts.autoFix ? await applyDoctorAutoFix(cwd) : await collectDoctorResult(cwd);
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return result.ok;
+    }
+    console.log("nifra doctor\n");
+    if (!result.ran) {
+        console.log("• no package.json at this directory — nothing to check");
+        return true;
+    }
+    if (result.fixed && result.fixed.length > 0) {
+        console.log("✓ updated package.json dependencies:");
+        for (const f of result.fixed) {
+            console.log(`  ${f.package}@${f.version} (${f.source})`);
+        }
+        console.log("");
+    }
+    if (result.skippedFixes && result.skippedFixes.length > 0) {
+        console.log("• not auto-fixed:");
+        for (const f of result.skippedFixes) {
+            console.log(`  ${f.package} — ${f.reason}; run \`${f.command.join(" ")}\``);
+        }
+        console.log("");
+    }
+    if (result.ok) {
+        console.log("✓ every imported package is declared in package.json");
+        return true;
+    }
+    // Group by package so the fix ("add X to dependencies") is stated once with its import sites.
+    const byPkg = new Map();
+    for (const f of result.findings) {
+        const list = byPkg.get(f.package) ?? [];
+        list.push(f);
+        byPkg.set(f.package, list);
+    }
+    console.log(`✗ ${byPkg.size} package(s) imported but not declared in package.json:\n`);
+    for (const [pkg, sites] of [...byPkg.entries()].sort()) {
+        console.log(`  ${pkg} — add to dependencies (\`bun add ${pkg}\`)`);
+        for (const s of sites)
+            console.log(`      ${s.file}:${s.line}`);
+    }
+    console.log("\nThese resolve at Bun runtime via hoisting/workspace but break `tsc` and a standalone install.");
+    return false;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/doctor.js.map

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

package/dist/examples.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `nifra_example` — verified, copy-pasteable code examples for agents. The corpus is `examples.json`
+ * (written into this package by `bun run gen:llms`): the same doc snippets `check:docs` typechecks
+ * against the live `@nifrajs/*` API. So every example this returns is GUARANTEED to compile against the
+ * installed version — the antidote to an agent hallucinating a framework API from stale training.
+ *
+ * Keyword-scored over each example's name/topic/slug (curated identifiers, heavily weighted) and its
+ * code body. No query → a grouped index of what's available (the cheap discovery call).
+ */
+export interface Example {
+    readonly name: string;
+    /** The doc page's title, e.g. "Nifra — Auth & sessions". */
+    readonly topic: string;
+    /** The doc page slug, e.g. "auth" — a short, matchable tag. */
+    readonly slug: string;
+    readonly code: string;
+}
+export interface ScoredExample extends Example {
+    readonly score: number;
+}
+/** Score examples against the query: a term in the slug/topic/name (the curated, searchable labels)
+ * is worth far more than a mention in the code body; body hits cap per term so one long snippet can't
+ * outweigh a precisely-tagged one. */
+export declare function searchExamples(examples: readonly Example[], query: string, limit: number): ScoredExample[];
+/** Render the tool result: matched examples as fenced code blocks, or the grouped index when no query. */
+export declare function renderExamplesResult(examples: readonly Example[], query: string | undefined, limit: number): string;
+/** Load the bundled example corpus. Resolves relative to this module so it works from `src/` (repo dev)
+ * and `dist/` (published) alike — `docs/examples.json` sits at the package root next to both. */
+export declare function loadExamplesCorpus(): Promise<Example[] | undefined>;
+//# sourceMappingURL=examples.d.ts.map

package/dist/examples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"examples.d.ts","sourceRoot":"","sources":["../src/examples.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,aAAc,SAAQ,OAAO;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED;;sCAEsC;AACtC,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,aAAa,EAAE,CAejB;AAED,0GAA0G;AAC1G,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,KAAK,EAAE,MAAM,GACZ,MAAM,CAoBR;AAED;iGACiG;AACjG,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC,CAUzE"}

package/dist/examples.js

@@ -0,0 +1,70 @@
+/**
+ * `nifra_example` — verified, copy-pasteable code examples for agents. The corpus is `examples.json`
+ * (written into this package by `bun run gen:llms`): the same doc snippets `check:docs` typechecks
+ * against the live `@nifrajs/*` API. So every example this returns is GUARANTEED to compile against the
+ * installed version — the antidote to an agent hallucinating a framework API from stale training.
+ *
+ * Keyword-scored over each example's name/topic/slug (curated identifiers, heavily weighted) and its
+ * code body. No query → a grouped index of what's available (the cheap discovery call).
+ */
+import { countBodyHits, queryTermGroups, tokenize, tokenSetHas } from "./search-terms.js";
+/** Score examples against the query: a term in the slug/topic/name (the curated, searchable labels)
+ * is worth far more than a mention in the code body; body hits cap per term so one long snippet can't
+ * outweigh a precisely-tagged one. */
+export function searchExamples(examples, query, limit) {
+    const terms = queryTermGroups(query);
+    if (terms.length === 0)
+        return [];
+    const scored = [];
+    for (const ex of examples) {
+        const labelTokens = new Set([...tokenize(ex.slug), ...tokenize(ex.topic), ...tokenize(ex.name)]);
+        const codeLower = ex.code.toLowerCase();
+        let score = 0;
+        for (const term of terms) {
+            if (tokenSetHas(labelTokens, term))
+                score += 8;
+            score += countBodyHits(codeLower, term, 5);
+        }
+        if (score > 0)
+            scored.push({ ...ex, score });
+    }
+    return scored.sort((a, b) => b.score - a.score).slice(0, limit);
+}
+/** Render the tool result: matched examples as fenced code blocks, or the grouped index when no query. */
+export function renderExamplesResult(examples, query, limit) {
+    if (query === undefined || query.trim() === "") {
+        const byTopic = new Map();
+        for (const ex of examples) {
+            const list = byTopic.get(ex.topic) ?? [];
+            list.push(ex.name);
+            byTopic.set(ex.topic, list);
+        }
+        const index = [...byTopic.entries()]
+            .map(([topic, names]) => `- **${topic}**: ${names.join(", ")}`)
+            .join("\n");
+        return `# nifra examples — index (${examples.length} verified snippets; pass \`query\` to fetch code)\n\nEvery snippet is typechecked against the installed nifra version — prefer these over recalling an API.\n\n${index}`;
+    }
+    const matches = searchExamples(examples, query, limit);
+    if (matches.length === 0) {
+        return `No examples matched ${JSON.stringify(query)}. Call without a query for the index, or try a broader term (e.g. "auth", "upload", "isr", "client").`;
+    }
+    return matches
+        .map((m) => `## ${m.name} — ${m.topic}\n\n\`\`\`ts\n${m.code}\n\`\`\``)
+        .join("\n\n---\n\n");
+}
+/** Load the bundled example corpus. Resolves relative to this module so it works from `src/` (repo dev)
+ * and `dist/` (published) alike — `docs/examples.json` sits at the package root next to both. */
+export async function loadExamplesCorpus() {
+    const url = new URL("../docs/examples.json", import.meta.url);
+    try {
+        const text = await Bun.file(url).text();
+        if (text.length === 0)
+            return undefined;
+        const parsed = JSON.parse(text);
+        return Array.isArray(parsed) && parsed.length > 0 ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=examples.js.map

package/dist/examples.js.map

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

package/dist/introspect.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Introspect a loaded nifra project into a Markdown brief — the API routes (`backend.routes()`), the
+ * page routes (`discoverRoutes`), and a conventions summary — for piping into an AI coding agent's
+ * prompt. Used by `nifra context` (stdout) and the `nifra mcp` server (a tool result), so an agent sees
+ * *this* project's actual surface, not just generic docs.
+ */
+import type { Manifest } from "@nifrajs/web";
+import type { LoadedApp } from "./load.js";
+/** Structural view of a `@nifrajs/core` route descriptor — declared locally so the CLI needs no type
+ * dependency on core. `app.routes()` returns these. */
+interface RouteDesc {
+    readonly method: string;
+    readonly path: string;
+    readonly schema?: unknown;
+}
+/**
+ * Render a JSON Schema as a compact TypeScript-like type (`{ id: string, name?: string }`) — the
+ * shape agents already think in, at a fraction of the raw JSON Schema's tokens (~70-80% smaller).
+ * Anything the renderer doesn't model falls back to the raw JSON for that subtree, so the output
+ * is always faithful, just not always minimal.
+ */
+export declare function tsTypeOf(schema: unknown, depth?: number): string;
+/**
+ * The typed-client call form for a route — the exact `client<typeof app>` proxy chain an agent should
+ * write, derived from the same convention `@nifrajs/client` implements (so it never has to read the
+ * client tests to learn it): a static segment is a property (`.users`), a path param/wildcard is a call
+ * that appends the value (`({ id })`), the root path is `.index`, and the HTTP verb is the terminal call.
+ * Body verbs (POST/PUT/PATCH) take the body first then call-options; other verbs take call-options first —
+ * so the `{ query }` argument lands in the right slot for each.
+ */
+export declare function clientCall(method: string, path: string, schema: unknown): string;
+/** Markdown section listing the backend's API routes with their request + response field shapes. */
+export declare function apiRoutesSection(routes: readonly RouteDesc[]): string;
+/** Markdown section listing the file-routed pages (URL pattern → source file). */
+export declare function pageRoutesSection(manifest: Manifest | undefined): string;
+/** Optional narrowing for {@link describeProject} — a path prefix and/or one section. A filtered
+ * brief omits the conventions block (the agent already has it from its first full call), so
+ * follow-up calls cost a fraction of the tokens. */
+export interface ContextFilter {
+    readonly path?: string;
+    readonly kind?: "api" | "pages";
+}
+/** Build the project brief (API routes + page routes + conventions) as Markdown — optionally
+ * narrowed by {@link ContextFilter} for cheap follow-up calls. */
+export declare function describeProject(app: LoadedApp, filter?: ContextFilter): string;
+/** One API route as structured JSON: method, path, the exact typed-client call form, and compact
+ * TS-shaped request/response contracts (present only when the route declares the schema). */
+export interface RouteJson {
+    readonly method: string;
+    readonly path: string;
+    readonly call: string;
+    readonly body?: string;
+    readonly query?: string;
+    readonly response?: string;
+}
+/**
+ * The backend's API routes as structured JSON — what the `nifra_routes` MCP tool returns, so an agent
+ * consumes the contract programmatically (`list_routes` / `get_route_schema`) instead of parsing the
+ * Markdown brief. Optionally filtered to routes whose path starts with `pathPrefix`. Reuses the exact
+ * same `call` form and TS-shaped contracts the Markdown brief shows.
+ */
+export declare function routesToJson(app: LoadedApp, pathPrefix?: string): RouteJson[];
+export {};
+//# sourceMappingURL=introspect.d.ts.map

package/dist/introspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspect.d.ts","sourceRoot":"","sources":["../src/introspect.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAE5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAE1C;uDACuD;AACvD,UAAU,SAAS;IACjB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAC1B;AAoCD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,SAAI,GAAG,MAAM,CAsC3D;AAuBD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAwBhF;AAED,oGAAoG;AACpG,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,MAAM,CAYrE;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAQxE;AAmBD;;oDAEoD;AACpD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,GAAG,OAAO,CAAA;CAChC;AAED;kEACkE;AAClE,wBAAgB,eAAe,CAAC,GAAG,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,MAAM,CA8B9E;AAED;6FAC6F;AAC7F,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,SAAS,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE,CA2B7E"}