@nac3/forge-cli 0.2.0-alpha.1

package/dist/chat/tools/lifecycle.js

@@ -0,0 +1,295 @@
+/**
+ * App lifecycle tools (V1.13 of HITO 1).
+ *
+ * Three tools:
+ *   - forge.run_app(repo_dir?, command?, wait_for_url_ms?)
+ *   - forge.stop_app(pid?)
+ *   - forge.restart_app(repo_dir?, command?)
+ *
+ * Single-process model: at most one app runs per chat session.
+ * Multi-app concurrency is a v0.4+ slice.
+ *
+ * Spawn detection (when no explicit command is given):
+ *   1. Read package.json scripts.
+ *   2. Prefer `dev`, then `start`, then `serve`. Refuse loudly
+ *      when none exist.
+ *   3. Run via the matching package manager
+ *      (pnpm-lock.yaml -> pnpm, yarn.lock -> yarn, default
+ *      npm).
+ *
+ * URL detection is best-effort: monitor stdout for up to
+ * wait_for_url_ms (default 5000) looking for the typical
+ * "http://localhost:<port>" pattern. When found, return it;
+ * else return null with a note in the result.
+ *
+ * Loud failures per ROADMAP sec 12.2.
+ *
+ * ASCII-only.
+ */
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+const DEFAULT_WAIT_MS = 5000;
+const MAX_WAIT_MS = 30_000;
+/** Process registry. Single-entry. */
+let active = null;
+/* ============================================================
+ * Specs
+ * ============================================================ */
+export const RUN_APP_SPEC = {
+    name: 'forge.run_app',
+    description: 'Launch the project dev server. Auto-detects the package manager (npm / yarn / pnpm) and the script (dev / start / serve). Returns pid + best-effort URL.',
+    input_schema: {
+        type: 'object',
+        properties: {
+            repo_dir: { type: 'string', description: 'Path to the project root. Default: projectRoot.' },
+            command: { type: 'string', description: 'Explicit script name (e.g. "dev", "build:watch"). When omitted, autoselected.' },
+            wait_for_url_ms: { type: 'number', description: 'How long to monitor stdout for a URL (default 5000, max 30000).' },
+        },
+        required: [],
+    },
+    requires_approval: true,
+};
+export const STOP_APP_SPEC = {
+    name: 'forge.stop_app',
+    description: 'Stop the running app spawned by forge.run_app. Returns the final logs tail.',
+    input_schema: {
+        type: 'object',
+        properties: {
+            pid: { type: 'number', description: 'PID to stop. Default: the active one.' },
+        },
+        required: [],
+    },
+    requires_approval: true,
+};
+export const RESTART_APP_SPEC = {
+    name: 'forge.restart_app',
+    description: 'Stop the running app + relaunch with the same (or new) options.',
+    input_schema: {
+        type: 'object',
+        properties: {
+            repo_dir: { type: 'string', description: 'Path. Default: previous app dir, then projectRoot.' },
+            command: { type: 'string', description: 'Script. Default: previous.' },
+            wait_for_url_ms: { type: 'number' },
+        },
+        required: [],
+    },
+    requires_approval: true,
+};
+/* ============================================================
+ * Implementations
+ * ============================================================ */
+function defaultReadFile(p) {
+    return fs.readFile(p, 'utf-8');
+}
+async function defaultExists(p) {
+    try {
+        await fs.stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function defaultSpawner(cmd, args, cwd) {
+    const proc = spawn(cmd, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], shell: process.platform === 'win32' });
+    return proc;
+}
+const URL_PATTERN = /\bhttps?:\/\/(?:localhost|127\.0\.0\.1)(?::\d+)?(?:\/[^\s]*)?/;
+async function detectCommand(repoDir, scriptOverride, deps) {
+    const exists = deps.fileExists ?? defaultExists;
+    const readFile = deps.readFile ?? defaultReadFile;
+    const pkgPath = path.join(repoDir, 'package.json');
+    if (!(await exists(pkgPath))) {
+        return { error: 'no package.json in ' + repoDir };
+    }
+    let pkg;
+    try {
+        pkg = JSON.parse(await readFile(pkgPath));
+    }
+    catch (err) {
+        return { error: 'invalid package.json: ' + (err instanceof Error ? err.message : String(err)) };
+    }
+    const scripts = pkg.scripts ?? {};
+    let script = scriptOverride;
+    if (!script) {
+        for (const candidate of ['dev', 'start', 'serve']) {
+            if (typeof scripts[candidate] === 'string') {
+                script = candidate;
+                break;
+            }
+        }
+        if (!script) {
+            return { error: 'no dev/start/serve script in package.json -- pass an explicit command' };
+        }
+    }
+    else if (typeof scripts[script] !== 'string') {
+        return { error: 'script "' + script + '" not found in package.json scripts' };
+    }
+    /* Package manager detection. */
+    let pm = 'npm';
+    if (await exists(path.join(repoDir, 'pnpm-lock.yaml')))
+        pm = 'pnpm';
+    else if (await exists(path.join(repoDir, 'yarn.lock')))
+        pm = 'yarn';
+    return {
+        cmd: pm,
+        args: pm === 'npm' ? ['run', script] : pm === 'yarn' ? ['run', script] : [script],
+        script,
+    };
+}
+export async function runApp(args, ctx, deps = {}) {
+    if (active) {
+        return {
+            tool: RUN_APP_SPEC.name,
+            result: { error: 'an app is already running (pid ' + active.app.pid + '). Call forge.stop_app first.' },
+            is_error: true,
+            display: 'already running',
+        };
+    }
+    const repoDir = args.repo_dir
+        ? (path.isAbsolute(args.repo_dir) ? args.repo_dir : path.join(ctx.projectRoot, args.repo_dir))
+        : ctx.projectRoot;
+    const stat = await fs.stat(repoDir).catch(() => null);
+    if (!stat || !stat.isDirectory()) {
+        return { tool: RUN_APP_SPEC.name, result: { error: 'repo_dir does not exist or is not a directory: ' + repoDir }, is_error: true, display: 'bad repo_dir' };
+    }
+    const det = await detectCommand(repoDir, args.command, deps);
+    if ('error' in det) {
+        return { tool: RUN_APP_SPEC.name, result: { error: det.error }, is_error: true, display: 'spawn detect failed' };
+    }
+    const spawner = deps.spawner ?? defaultSpawner;
+    const proc = spawner(det.cmd, det.args, repoDir);
+    if (typeof proc.pid !== 'number') {
+        return { tool: RUN_APP_SPEC.name, result: { error: 'failed to spawn ' + det.cmd + ' ' + det.args.join(' ') }, is_error: true, display: 'spawn failed' };
+    }
+    const app = {
+        pid: proc.pid,
+        repo_dir: repoDir,
+        command: [det.cmd, ...det.args],
+        started_at: new Date().toISOString(),
+        url: null,
+        recent_logs: '',
+    };
+    active = { proc: proc, app };
+    /* Bound the captured logs. */
+    function appendLog(s) {
+        app.recent_logs = (app.recent_logs + s).slice(-16384);
+    }
+    /* URL detection: monitor stdout + stderr up to wait_for_url_ms. */
+    const waitMs = Math.min(Math.max(args.wait_for_url_ms ?? DEFAULT_WAIT_MS, 0), MAX_WAIT_MS);
+    const urlFound = new Promise((resolve) => {
+        let resolved = false;
+        const timer = setTimeout(() => {
+            if (!resolved) {
+                resolved = true;
+                resolve(null);
+            }
+        }, waitMs);
+        const onChunk = (chunk) => {
+            const s = String(chunk);
+            appendLog(s);
+            const m = s.match(URL_PATTERN);
+            if (m && !resolved) {
+                resolved = true;
+                clearTimeout(timer);
+                resolve(m[0]);
+            }
+        };
+        if (proc.stdout)
+            proc.stdout.on('data', onChunk);
+        if (proc.stderr)
+            proc.stderr.on('data', onChunk);
+    });
+    /* Wire close so we clear active on graceful exit. */
+    proc.on('close', (code) => {
+        appendLog('\n[process exited with code ' + code + ']\n');
+        if (active && active.proc === proc) {
+            active = null;
+        }
+    });
+    proc.on('error', (err) => {
+        appendLog('\n[process error: ' + (err && err.message ? err.message : String(err)) + ']\n');
+    });
+    const url = await urlFound;
+    app.url = url;
+    return {
+        tool: RUN_APP_SPEC.name,
+        result: {
+            pid: app.pid,
+            repo_dir: app.repo_dir,
+            command: app.command,
+            started_at: app.started_at,
+            url,
+            url_detected: url !== null,
+            recent_logs_tail: app.recent_logs.slice(-2048),
+        },
+        display: url
+            ? 'app running pid ' + app.pid + ' at ' + url
+            : 'app spawned pid ' + app.pid + ' -- URL not detected in ' + waitMs + 'ms (check logs)',
+    };
+}
+export async function stopApp(args, _ctx, _deps = {}) {
+    if (!active) {
+        return {
+            tool: STOP_APP_SPEC.name,
+            result: { error: 'no app is running' },
+            is_error: true,
+            display: 'nothing to stop',
+        };
+    }
+    if (args.pid !== undefined && args.pid !== active.app.pid) {
+        return {
+            tool: STOP_APP_SPEC.name,
+            result: { error: 'pid mismatch: requested ' + args.pid + ', active is ' + active.app.pid },
+            is_error: true,
+            display: 'pid mismatch',
+        };
+    }
+    const app = active.app;
+    const proc = active.proc;
+    active = null;
+    /* SIGTERM first; many dev servers handle it gracefully. */
+    try {
+        proc.kill('SIGTERM');
+    }
+    catch (err) {
+        return {
+            tool: STOP_APP_SPEC.name,
+            result: { error: 'kill failed: ' + (err instanceof Error ? err.message : String(err)) },
+            is_error: true,
+            display: 'kill failed',
+        };
+    }
+    return {
+        tool: STOP_APP_SPEC.name,
+        result: {
+            pid: app.pid,
+            repo_dir: app.repo_dir,
+            command: app.command,
+            stopped_at: new Date().toISOString(),
+            recent_logs_tail: app.recent_logs.slice(-2048),
+        },
+        display: 'stopped pid ' + app.pid,
+    };
+}
+export async function restartApp(args, ctx, deps = {}) {
+    const prev = active;
+    if (prev) {
+        await stopApp({}, ctx, deps);
+    }
+    /* Inherit the previous repo_dir / command if the caller did
+       not supply new ones. */
+    const repoDir = args.repo_dir ?? (prev ? prev.app.repo_dir : undefined);
+    const command = args.command ?? (prev ? prev.app.command[2] : undefined); /* pm script slot */
+    return runApp({
+        ...(repoDir ? { repo_dir: repoDir } : {}),
+        ...(command ? { command } : {}),
+        ...(args.wait_for_url_ms !== undefined ? { wait_for_url_ms: args.wait_for_url_ms } : {}),
+    }, ctx, deps);
+}
+/** Test seam: reset the singleton between test cases. */
+export function _resetLifecycleForTests() {
+    active = null;
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/chat/tools/lifecycle.js.map

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

package/dist/chat/tools/manual.d.ts

@@ -0,0 +1,26 @@
+/**
+ * forge.manual.open chat tool (Fase F.7 of HITO 1 extension).
+ *
+ * Resolves the user's chosen language (or the explicitly
+ * requested one) to the HTML manual under docs/manuals/, opens
+ * it through the existing reader pipeline (V1.19 HTML parser),
+ * and surfaces the reader session so subsequent next_block /
+ * search / bookmark calls operate on the manual just like any
+ * other document.
+ *
+ * The actual document parsing reuses the existing reader; this
+ * tool just resolves the manual path by language and delegates.
+ *
+ * ASCII-only.
+ */
+import type { ToolContext, ToolResult, ToolSpec } from '../tools.js';
+import { type SupportedLanguage } from '../../i18n/index.js';
+export declare const MANUAL_OPEN_SPEC: ToolSpec;
+export declare function runManualOpen(args: {
+    lang?: string;
+} | undefined, ctx: ToolContext): Promise<ToolResult>;
+/** List which manuals are present on disk -- handy for yf
+ *  doctor + for the panel's language selector to surface
+ *  installation gaps. */
+export declare function listAvailableManuals(packageDir?: string): Promise<SupportedLanguage[]>;
+//# sourceMappingURL=manual.d.ts.map

package/dist/chat/tools/manual.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manual.d.ts","sourceRoot":"","sources":["../../../src/chat/tools/manual.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAIrE,OAAO,EAGL,KAAK,iBAAiB,EAEvB,MAAM,qBAAqB,CAAC;AAgC7B,eAAO,MAAM,gBAAgB,EAAE,QAe9B,CAAC;AA4CF,wBAAsB,aAAa,CACjC,IAAI,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,EACnC,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,UAAU,CAAC,CAyCrB;AAED;;yBAEyB;AACzB,wBAAsB,oBAAoB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAkB5F"}

package/dist/chat/tools/manual.js

@@ -0,0 +1,164 @@
+/**
+ * forge.manual.open chat tool (Fase F.7 of HITO 1 extension).
+ *
+ * Resolves the user's chosen language (or the explicitly
+ * requested one) to the HTML manual under docs/manuals/, opens
+ * it through the existing reader pipeline (V1.19 HTML parser),
+ * and surfaces the reader session so subsequent next_block /
+ * search / bookmark calls operate on the manual just like any
+ * other document.
+ *
+ * The actual document parsing reuses the existing reader; this
+ * tool just resolves the manual path by language and delegates.
+ *
+ * ASCII-only.
+ */
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { runReaderOpen, } from './reader.js';
+import { normaliseLanguageTag, SUPPORTED_LANGUAGES, currentLanguage, } from '../../i18n/index.js';
+/** Resolve the manual base directory relative to THIS module
+ *  (independent of process.cwd()). Tries, in order:
+ *
+ *   1. Installed package layout: when this file is at
+ *      <pkg>/dist/chat/tools/manual.js, the manuals are at
+ *      <pkg>/docs/manuals/. The `files` glob in package.json
+ *      ships docs/manuals/ inside the tarball.
+ *   2. Dev (tsx) layout: when this file is at
+ *      <repo>/src/chat/tools/manual.ts, the manuals are at
+ *      <repo>/docs/manuals/.
+ *   3. cwd-relative (last-resort dev fallback). */
+function manualBaseDirs() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    /* dist/chat/tools/manual.js  -> ../../../docs/manuals/  (installed)
+       src/chat/tools/manual.ts   -> ../../../docs/manuals/  (dev via tsx)
+       Same relative depth -- the parent layout is identical. */
+    const moduleRelative = path.resolve(here, '..', '..', '..', 'docs', 'manuals');
+    return [
+        moduleRelative,
+        /* Last-resort fallback when someone invokes the tool from
+           a tree that contains a docs/manuals/ at the cwd root. */
+        path.join(process.cwd(), 'docs', 'manuals'),
+    ];
+}
+const MANUAL_PATH_CANDIDATES = (lang) => {
+    const fname = 'manual.' + lang + '.html';
+    return manualBaseDirs().map((dir) => path.join(dir, fname));
+};
+export const MANUAL_OPEN_SPEC = {
+    name: 'forge.manual.open',
+    description: 'Open the Yujin Forge user manual in the requested language (default: current user language). Resolves to docs/manuals/manual.<lang>.html and opens it through the reader pipeline so the user can navigate by voice. Available languages: es, en, pt, fr, ja, zh, hi, ar, de, it.',
+    input_schema: {
+        type: 'object',
+        properties: {
+            lang: {
+                type: 'string',
+                description: 'Language code (es, en, pt, fr, ja, zh, hi, ar, de, it). Optional; defaults to the current panel language.',
+                enum: ['es', 'en', 'pt', 'fr', 'ja', 'zh', 'hi', 'ar', 'de', 'it'],
+            },
+        },
+        required: [],
+    },
+    requires_approval: false,
+};
+/** Resolve which language to serve. Priority:
+ *  1. Explicit args.lang (normalised).
+ *  2. The panel's current language.
+ *  3. Spanish (default).
+ *
+ *  Then verify the HTML file actually exists on disk; fall
+ *  back to Spanish if the user-requested locale is missing.
+ *  If even Spanish is missing, throw -- the install is broken. */
+async function resolveManualPath(reqLang, packageDir) {
+    const requested = reqLang
+        ? normaliseLanguageTag(reqLang)
+        : currentLanguage();
+    const order = [requested];
+    if (requested !== 'es')
+        order.push('es');
+    for (const lang of order) {
+        const candidates = MANUAL_PATH_CANDIDATES(lang);
+        if (packageDir) {
+            candidates.push(path.join(packageDir, 'docs', 'manuals', 'manual.' + lang + '.html'));
+        }
+        for (const candidate of candidates) {
+            try {
+                await fs.access(candidate);
+                return {
+                    path: candidate,
+                    lang,
+                    fellBack: lang !== requested,
+                };
+            }
+            catch {
+                /* try next candidate */
+            }
+        }
+    }
+    throw new Error('manual.open: no manual HTML found for any language. Tried: '
+        + order.join(', ') + '. Reinstall the package or check the docs/manuals/ directory.');
+}
+export async function runManualOpen(args, ctx) {
+    /* Resolve absolute path; ToolContext does not carry an
+       install dir today, so we fall through to cwd + a probed
+       parent in MANUAL_PATH_CANDIDATES. */
+    let resolved;
+    try {
+        resolved = await resolveManualPath(args?.lang, undefined);
+    }
+    catch (err) {
+        return {
+            tool: MANUAL_OPEN_SPEC.name,
+            result: { error: err instanceof Error ? err.message : String(err) },
+            is_error: true,
+            display: 'manual not found',
+        };
+    }
+    /* Reuse runReaderOpen so the manual goes through the same
+       session machinery -- the user can then say "siguiente" /
+       "buscar X" / "marcame aca" on the manual just like any
+       other document. The path passed in is absolute. */
+    const readerResult = await runReaderOpen({ path: resolved.path }, ctx);
+    if (readerResult.is_error)
+        return readerResult;
+    /* Decorate the result with manual-specific metadata so the
+       panel + the chat can surface which language was served and
+       whether we fell back. */
+    const enriched = {
+        ...readerResult.result,
+        manual_lang: resolved.lang,
+        manual_fell_back: resolved.fellBack,
+        manual_path: resolved.path,
+    };
+    return {
+        tool: MANUAL_OPEN_SPEC.name,
+        result: enriched,
+        display: 'manual opened: ' + resolved.lang
+            + (resolved.fellBack ? ' (fell back from ' + (args?.lang || 'unknown') + ')' : ''),
+    };
+}
+/** List which manuals are present on disk -- handy for yf
+ *  doctor + for the panel's language selector to surface
+ *  installation gaps. */
+export async function listAvailableManuals(packageDir) {
+    const present = [];
+    for (const lang of SUPPORTED_LANGUAGES) {
+        const candidates = MANUAL_PATH_CANDIDATES(lang);
+        if (packageDir) {
+            candidates.push(path.join(packageDir, 'docs', 'manuals', 'manual.' + lang + '.html'));
+        }
+        for (const candidate of candidates) {
+            try {
+                await fs.access(candidate);
+                present.push(lang);
+                break;
+            }
+            catch {
+                /* try next */
+            }
+        }
+    }
+    return present;
+}
+//# sourceMappingURL=manual.js.map

package/dist/chat/tools/manual.js.map

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

package/dist/chat/tools/reader.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Reader chat tools (V1.28 of HITO 1).
+ *
+ * Exposes the reader subsystem (V1.14+) to the chat catalog.
+ * Single shared session map at module scope so the user can
+ * open a doc in one chat turn and continue navigating it in
+ * the next.
+ *
+ * Tools:
+ *   forge.reader.open(path)
+ *   forge.reader.list_documents()
+ *   forge.reader.read_section(doc_id, index?)
+ *   forge.reader.next_block(doc_id)
+ *   forge.reader.search(doc_id, query, max?)
+ *   forge.reader.bookmark_set(doc_id, name)
+ *   forge.reader.bookmark_jump(doc_id, name)
+ *   forge.reader.recap(doc_id, window?)
+ *
+ * All read-only (requires_approval=false). The reader does
+ * not write to the project; it parses + remembers state +
+ * answers queries.
+ *
+ * Loud failures per ROADMAP sec 12.2.
+ *
+ * ASCII-only.
+ */
+import type { ToolContext, ToolResult, ToolSpec } from '../tools.js';
+/** V1.26b -- Claude-backed recap summariser. Optional DI seam.
+ *  When the chat server boots with a Claude client, it calls
+ *  setRecapSummarizer() to install the summariser; otherwise
+ *  mode='summary' calls return a loud error pointing the
+ *  caller at the env flag + config.
+ *
+ *  Gated by env var YF_ENABLE_CLAUDE_RECAP=1 so even an
+ *  installed summariser will NOT fire by accident -- the
+ *  user has to opt in once per machine. */
+export type RecapSummarizer = (blocks: string[], options: {
+    language?: string;
+}) => Promise<string>;
+export declare function setRecapSummarizer(impl: RecapSummarizer | null): void;
+/** Test seam. */
+export declare function _resetReaderForTests(): void;
+export declare const READER_OPEN_SPEC: ToolSpec;
+export declare const READER_LIST_DOCS_SPEC: ToolSpec;
+export declare const READER_READ_SECTION_SPEC: ToolSpec;
+export declare const READER_NEXT_BLOCK_SPEC: ToolSpec;
+export declare const READER_SEARCH_SPEC: ToolSpec;
+export declare const READER_BOOKMARK_SET_SPEC: ToolSpec;
+export declare const READER_BOOKMARK_JUMP_SPEC: ToolSpec;
+export declare const READER_RECAP_SPEC: ToolSpec;
+export declare function runReaderOpen(args: {
+    path: string;
+}, ctx: ToolContext): Promise<ToolResult>;
+export declare function runReaderListDocuments(): Promise<ToolResult>;
+export declare function runReaderReadSection(args: {
+    doc_id: string;
+    index?: number;
+}): Promise<ToolResult>;
+export declare function runReaderNextBlock(args: {
+    doc_id: string;
+}): Promise<ToolResult>;
+export declare function runReaderSearch(args: {
+    doc_id: string;
+    query: string;
+    max?: number;
+}): Promise<ToolResult>;
+export declare function runReaderBookmarkSet(args: {
+    doc_id: string;
+    name: string;
+}): Promise<ToolResult>;
+export declare function runReaderBookmarkJump(args: {
+    doc_id: string;
+    name: string;
+}): Promise<ToolResult>;
+export declare function runReaderRecap(args: {
+    doc_id: string;
+    window?: number;
+    mode?: 'literal' | 'summary';
+}): Promise<ToolResult>;
+//# sourceMappingURL=reader.d.ts.map

package/dist/chat/tools/reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../../src/chat/tools/reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAkBrE;;;;;;;;2CAQ2C;AAC3C,MAAM,MAAM,eAAe,GAAG,CAC5B,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,KAC3B,OAAO,CAAC,MAAM,CAAC,CAAC;AAErB,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI,CAErE;AAED,iBAAiB;AACjB,wBAAgB,oBAAoB,IAAI,IAAI,CAG3C;AAMD,eAAO,MAAM,gBAAgB,EAAE,QAW9B,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,QAKnC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,QAYtC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,QAWpC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,QAahC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,QAYtC,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,QAYvC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,QAa/B,CAAC;AAYF,wBAAsB,aAAa,CACjC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EACtB,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,UAAU,CAAC,CA0CrB;AAED,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,UAAU,CAAC,CAelE;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAmCxG;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAwCtF;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAehH;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAgBtG;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAevG;AAoBD,wBAAsB,cAAc,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;CAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CA4FjI"}