@nac3/forge-cli 0.2.0-alpha.8 → 0.2.1-alpha.60

package/dist/nac3/backend_tools.js

@@ -0,0 +1,271 @@
+/**
+ * NAC-3 v3.x backend tools (task #23 -- design in
+ * docs/NAC3_SPEC_V3_BACKEND_TOOLS.md).
+ *
+ * Slice 1: parse the `nac3_backend.tools[]` section from
+ * yujin.forge.json + expose the parsed catalogue. Dispatcher
+ * routing + auth header + audit log ship in slice 2.
+ *
+ * Surface principle: like the F101 MCP bridge invariants, the
+ * backend-tool verbs only appear in the LLM-visible stub when
+ * the adopter app declares them. No declaration -> identical
+ * prompt to v3.0.
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+const VALID_METHODS = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']);
+const VALID_POLICIES = ['unrestricted', 'confirm', 'approval-required', 'destructive'];
+const VALID_SIDE_EFFECTS = ['none', 'external-api', 'filesystem', 'network'];
+const VALID_AUTH_KINDS = ['none', 'bearer', 'header_key', 'basic', 'oauth2_token'];
+function asString(v) {
+    return typeof v === 'string' && v.length > 0 ? v : null;
+}
+function parseEndpoint(raw, ctx, errors) {
+    if (!raw || typeof raw !== 'object') {
+        errors.push(ctx + '.endpoint: missing or not an object');
+        return null;
+    }
+    const r = raw;
+    const m = typeof r.method === 'string' ? r.method.toUpperCase() : '';
+    const p = typeof r.path === 'string' ? r.path : '';
+    if (!VALID_METHODS.has(m)) {
+        errors.push(ctx + '.endpoint.method: must be one of ' + Array.from(VALID_METHODS).join('|') + ' (got "' + r.method + '")');
+        return null;
+    }
+    if (!p.startsWith('/')) {
+        errors.push(ctx + '.endpoint.path: must start with / (got "' + r.path + '")');
+        return null;
+    }
+    return { method: m, path: p };
+}
+function parseSchema(raw, ctx, errors) {
+    if (!raw || typeof raw !== 'object') {
+        errors.push(ctx + '.params_schema: missing or not an object');
+        return null;
+    }
+    const r = raw;
+    if (r.type !== 'object') {
+        errors.push(ctx + '.params_schema.type: must be "object"');
+        return null;
+    }
+    const props = (r.properties && typeof r.properties === 'object') ? r.properties : {};
+    const required = Array.isArray(r.required) ? r.required.filter((x) => typeof x === 'string') : [];
+    /* We do not deep-validate the property shapes here; the dispatcher
+     * validates at invoke time. */
+    return {
+        type: 'object',
+        properties: props,
+        required,
+    };
+}
+function parseAuth(raw, errors) {
+    if (!raw || typeof raw !== 'object') {
+        return { kind: 'none' };
+    }
+    const r = raw;
+    const kind = typeof r.kind === 'string' ? r.kind : 'none';
+    if (!VALID_AUTH_KINDS.includes(kind)) {
+        errors.push('nac3_backend.auth.kind: invalid value "' + kind + '" (must be one of ' + VALID_AUTH_KINDS.join('|') + ')');
+        return { kind: 'none' };
+    }
+    const out = { kind: kind };
+    const slot = asString(r.vault_slot);
+    if (slot)
+        out.vault_slot = slot;
+    const su = asString(r.vault_slot_user);
+    if (su)
+        out.vault_slot_user = su;
+    const sp = asString(r.vault_slot_pass);
+    if (sp)
+        out.vault_slot_pass = sp;
+    const hn = asString(r.header_name);
+    if (hn)
+        out.header_name = hn;
+    return out;
+}
+function parseTool(raw, idx, errors) {
+    if (!raw || typeof raw !== 'object') {
+        errors.push('nac3_backend.tools[' + idx + ']: not an object');
+        return null;
+    }
+    const r = raw;
+    const id = asString(r.id);
+    if (!id || !/^[a-z][a-z0-9_-]{0,79}$/.test(id)) {
+        errors.push('nac3_backend.tools[' + idx + '].id: missing or invalid (must match /^[a-z][a-z0-9_-]{0,79}$/, got "' + r.id + '")');
+        return null;
+    }
+    const label = asString(r.label) || id;
+    const description = asString(r.description) || '';
+    const ctx = 'nac3_backend.tools[' + idx + '/' + id + ']';
+    const endpoint = parseEndpoint(r.endpoint, ctx, errors);
+    if (!endpoint)
+        return null;
+    const schema = parseSchema(r.params_schema, ctx, errors);
+    if (!schema)
+        return null;
+    const policy = (typeof r.policy === 'string' && VALID_POLICIES.includes(r.policy))
+        ? r.policy
+        : 'unrestricted';
+    const seRaw = Array.isArray(r.side_effects) ? r.side_effects : [];
+    const sideEffects = [];
+    for (const s of seRaw) {
+        if (typeof s === 'string' && VALID_SIDE_EFFECTS.includes(s)) {
+            sideEffects.push(s);
+        }
+    }
+    if (sideEffects.length === 0)
+        sideEffects.push('external-api');
+    return {
+        id,
+        label,
+        description,
+        endpoint,
+        policy,
+        side_effects: sideEffects,
+        params_schema: schema,
+        result_shape: (r.result_shape && typeof r.result_shape === 'object')
+            ? r.result_shape
+            : undefined,
+    };
+}
+/** Parse a yujin.forge.json content + extract the nac3_backend
+ *  catalogue. Returns null when the manifest does not declare the
+ *  section (the v3.0 default; no behaviour change). Returns a
+ *  catalogue + errors[] when the section is malformed. */
+export function parseBackendCatalogue(manifest) {
+    const errors = [];
+    const warnings = [];
+    if (!manifest || typeof manifest !== 'object') {
+        return { catalogue: null, errors, warnings };
+    }
+    const m = manifest;
+    const nac3 = m.nac3_backend;
+    if (!nac3 || typeof nac3 !== 'object') {
+        return { catalogue: null, errors, warnings };
+    }
+    const n = nac3;
+    const baseUrl = asString(n.base_url);
+    if (!baseUrl) {
+        errors.push('nac3_backend.base_url: missing or empty');
+        return { catalogue: null, errors, warnings };
+    }
+    if (!/^https?:\/\//.test(baseUrl)) {
+        errors.push('nac3_backend.base_url: must start with http:// or https:// (got "' + baseUrl + '")');
+        return { catalogue: null, errors, warnings };
+    }
+    const auth = parseAuth(n.auth, errors);
+    const rawTools = Array.isArray(n.tools) ? n.tools : [];
+    if (rawTools.length === 0) {
+        warnings.push('nac3_backend.tools: empty -- section is declared but no tools available');
+    }
+    const tools = [];
+    const seenIds = new Set();
+    for (let i = 0; i < rawTools.length; i++) {
+        const t = parseTool(rawTools[i], i, errors);
+        if (!t)
+            continue;
+        if (seenIds.has(t.id)) {
+            errors.push('nac3_backend.tools[' + i + '/' + t.id + ']: duplicate id');
+            continue;
+        }
+        seenIds.add(t.id);
+        tools.push(t);
+    }
+    return {
+        catalogue: {
+            base_url: baseUrl,
+            auth,
+            tools,
+        },
+        errors,
+        warnings,
+    };
+}
+/** Read yujin.forge.json from the project root and parse its
+ *  nac3_backend section. Returns null catalogue when the file is
+ *  missing OR no nac3_backend declared OR malformed. */
+export async function loadBackendCatalogue(projectRoot) {
+    const p = path.join(projectRoot, 'yujin.forge.json');
+    let raw;
+    try {
+        raw = await fs.readFile(p, 'utf-8');
+    }
+    catch {
+        return { catalogue: null, errors: [], warnings: [] };
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(raw);
+    }
+    catch (e) {
+        return {
+            catalogue: null,
+            errors: ['yujin.forge.json parse error: ' + (e instanceof Error ? e.message : String(e))],
+            warnings: [],
+        };
+    }
+    return parseBackendCatalogue(manifest);
+}
+/* ====================================================================
+ * Stub line builder
+ *
+ * Each backend tool surfaces as one synthetic NAC-3 verb in the
+ * LLM-visible stub. Format mirrors the native verb stub from
+ * manifest_lazy.ts:
+ *
+ *   app.<id> [<policy><side_effects>] <label> args:{required,[optional]}
+ *
+ * Plus, before the list, a header line announces the section.
+ * ================================================================== */
+function shortPolicyTag(p) {
+    switch (p) {
+        case 'unrestricted': return 'u';
+        case 'confirm': return 'c';
+        case 'approval-required': return 'A';
+        case 'destructive': return 'D';
+    }
+}
+function shortSideEffectTag(s) {
+    switch (s) {
+        case 'none': return '';
+        case 'external-api': return 'x';
+        case 'filesystem': return 'f';
+        case 'network': return 'n';
+    }
+}
+function buildArgsHint(schema) {
+    const required = schema.required;
+    const allKeys = Object.keys(schema.properties);
+    const optional = allKeys.filter((k) => !required.includes(k));
+    if (required.length === 0 && optional.length === 0)
+        return '{}';
+    const parts = [];
+    for (const r of required)
+        parts.push(r);
+    for (const o of optional)
+        parts.push('[' + o + ']');
+    return '{' + parts.join(',') + '}';
+}
+export function buildBackendToolStub(tool) {
+    const pol = shortPolicyTag(tool.policy);
+    const se = tool.side_effects.map(shortSideEffectTag).filter((s) => s !== '').join('');
+    const tags = '[' + pol + (se ? se : '') + ']';
+    const hint = buildArgsHint(tool.params_schema);
+    return 'app.' + tool.id + ' ' + tags + ' ' + tool.label + ' args:' + hint;
+}
+export function buildBackendToolsSection(catalogue) {
+    if (catalogue.tools.length === 0)
+        return '';
+    const lines = [];
+    lines.push('');
+    lines.push('NAC-3 v3.x BACKEND TOOLS (' + catalogue.tools.length + ' app.* verbs)');
+    lines.push('Base URL: ' + catalogue.base_url + '  Auth: ' + catalogue.auth.kind);
+    lines.push('Each app.<id> verb dispatches to ' + catalogue.base_url + '<endpoint.path>.');
+    lines.push('');
+    for (const t of catalogue.tools)
+        lines.push(buildBackendToolStub(t));
+    return lines.join('\n');
+}
+//# sourceMappingURL=backend_tools.js.map

package/dist/nac3/backend_tools.js.map

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

package/dist/nac3/dispatch_log.d.ts

@@ -0,0 +1,35 @@
+export type DispatchLogKind = 'invoke' | 'manifest-fetch' | 'verb-not-found' | 'policy-deny' | 'deprecated-alias' | 'schema-fail' | 'panel-handler-error';
+export interface DispatchLogEntry {
+    ts: string;
+    kind: DispatchLogKind;
+    trace_id: string;
+    verb_id?: string;
+    alias_used?: string;
+    closest_verbs?: string[];
+    args_sample?: Record<string, unknown>;
+    policy?: string;
+    side_effects_declared?: string[];
+    side_effects_actual?: string[];
+    result_ok?: boolean;
+    result_error?: string;
+    duration_ms?: number;
+    panel_session_id?: string;
+    forge_version?: string;
+    llm_turn_id?: string;
+    user_text_hash?: string;
+    manifest_version?: string;
+}
+/** Generate a short trace id for correlating a single LLM turn
+ *  across manifest-fetch -> invoke -> result. */
+export declare function newTraceId(): string;
+/** Hash a user message for log correlation without exposing the
+ *  plaintext. Truncated sha256 -- collision resistance is not
+ *  the goal, dedup-friendly correlation is. */
+export declare function hashUserText(text: string): string;
+/** Recursively redact + truncate an args object for safe logging. */
+export declare function redactArgs(args: unknown, depth?: number): unknown;
+/** Append a JSONL row. Never throws. */
+export declare function logDispatch(entry: DispatchLogEntry): Promise<void>;
+/** Return the resolved log path. Exposed so tests can clean up. */
+export declare function logPath(): string;
+//# sourceMappingURL=dispatch_log.d.ts.map

package/dist/nac3/dispatch_log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch_log.d.ts","sourceRoot":"","sources":["../../src/nac3/dispatch_log.ts"],"names":[],"mappings":"AAiDA,MAAM,MAAM,eAAe,GACvB,QAAQ,GACR,gBAAgB,GAChB,gBAAgB,GAChB,aAAa,GACb,kBAAkB,GAClB,aAAa,GACb,qBAAqB,CAAC;AAE1B,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,eAAe,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;iDACiD;AACjD,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED;;+CAE+C;AAC/C,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIjD;AAED,qEAAqE;AACrE,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,SAAI,GAAG,OAAO,CAuB5D;AAsBD,wCAAwC;AACxC,wBAAsB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CASxE;AAED,mEAAmE;AACnE,wBAAgB,OAAO,IAAI,MAAM,CAEhC"}

package/dist/nac3/dispatch_log.js

@@ -0,0 +1,126 @@
+/**
+ * NAC3 dispatch log -- append-only JSONL at
+ * ~/.yujin-forge/nac3_log.jsonl
+ *
+ * Goal: post-hoc analysis of disambiguation. Every nac3_invoke,
+ * every manifest fetch, every verb-not-found event lands as one
+ * JSON line. Pablo can grep/jq the file to see when the LLM is
+ * reaching for verbs that should exist (-> add them) or
+ * calling deprecated aliases (-> hurry the migration).
+ *
+ * Privacy:
+ *   - User text is hashed (sha256), never plaintext.
+ *   - Arg values are redacted on common secret-bearing keys
+ *     (key, token, secret, password, api_key, bearer, cookie)
+ *     and truncated past 200 chars.
+ *   - The log file is local. Never uploaded.
+ *
+ * Bounded growth:
+ *   - Rotates when the active file exceeds 10 MB into
+ *     `nac3_log.YYYYMMDD-HHMMSS.jsonl`.
+ *   - Sumi expects to run a sweep job later (or never -- disk
+ *     is cheap and this is dev-time data).
+ *
+ * Failure mode:
+ *   - The logger never throws. If the filesystem refuses (read-
+ *     only, disk full, permission denied), the write is dropped
+ *     and we continue. The dispatch path must not depend on log
+ *     durability.
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+const LOG_DIR_OVERRIDE = process.env.YF_CONFIG_DIR;
+const LOG_DIR = LOG_DIR_OVERRIDE
+    ? LOG_DIR_OVERRIDE
+    : path.join(os.homedir(), '.yujin-forge');
+const ACTIVE_FILE = path.join(LOG_DIR, 'nac3_log.jsonl');
+const MAX_BYTES = 10 * 1024 * 1024;
+const REDACT_KEYS = new Set([
+    'key', 'token', 'secret', 'password', 'api_key',
+    'bearer', 'cookie', 'authorization', 'value',
+]);
+/** Generate a short trace id for correlating a single LLM turn
+ *  across manifest-fetch -> invoke -> result. */
+export function newTraceId() {
+    return 'trc_' + Date.now().toString(36) + '_' + crypto.randomBytes(3).toString('hex');
+}
+/** Hash a user message for log correlation without exposing the
+ *  plaintext. Truncated sha256 -- collision resistance is not
+ *  the goal, dedup-friendly correlation is. */
+export function hashUserText(text) {
+    if (typeof text !== 'string' || text.length === 0)
+        return '';
+    const h = crypto.createHash('sha256').update(text, 'utf-8').digest('hex');
+    return 'sha256:' + h.slice(0, 16);
+}
+/** Recursively redact + truncate an args object for safe logging. */
+export function redactArgs(args, depth = 0) {
+    if (depth > 4)
+        return '<deep>';
+    if (args === null || args === undefined)
+        return args;
+    if (typeof args === 'string') {
+        return args.length > 200 ? args.slice(0, 200) + '...' : args;
+    }
+    if (typeof args === 'number' || typeof args === 'boolean')
+        return args;
+    if (Array.isArray(args)) {
+        return args.slice(0, 20).map((v) => redactArgs(v, depth + 1));
+    }
+    if (typeof args === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(args)) {
+            if (REDACT_KEYS.has(k.toLowerCase())) {
+                const s = typeof v === 'string' ? v : String(v ?? '');
+                out[k] = '<redacted:' + s.length + '>';
+            }
+            else {
+                out[k] = redactArgs(v, depth + 1);
+            }
+        }
+        return out;
+    }
+    return String(args);
+}
+async function ensureDir() {
+    try {
+        await fs.mkdir(LOG_DIR, { recursive: true });
+    }
+    catch {
+        /* permission denied / fs error -- we'll fail-safe in append. */
+    }
+}
+async function rotateIfNeeded() {
+    try {
+        const stat = await fs.stat(ACTIVE_FILE);
+        if (stat.size < MAX_BYTES)
+            return;
+        const ts = new Date().toISOString().replace(/[-:T.]/g, '').slice(0, 15);
+        const rotated = path.join(LOG_DIR, 'nac3_log.' + ts + '.jsonl');
+        await fs.rename(ACTIVE_FILE, rotated);
+    }
+    catch {
+        /* missing file is fine; other errors swallowed by design. */
+    }
+}
+/** Append a JSONL row. Never throws. */
+export async function logDispatch(entry) {
+    try {
+        await ensureDir();
+        await rotateIfNeeded();
+        const line = JSON.stringify(entry) + '\n';
+        await fs.appendFile(ACTIVE_FILE, line, { encoding: 'utf-8' });
+    }
+    catch {
+        /* swallow -- dispatch path must not depend on log durability. */
+    }
+}
+/** Return the resolved log path. Exposed so tests can clean up. */
+export function logPath() {
+    return ACTIVE_FILE;
+}
+//# sourceMappingURL=dispatch_log.js.map

package/dist/nac3/dispatch_log.js.map

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

package/dist/nac3/internal_manifest.d.ts

@@ -0,0 +1,62 @@
+export type Nac3Policy = 'unrestricted' | 'confirm' | 'approval-required' | 'destructive' | 'byok-required' | 'project-root-gated';
+export type Nac3SideEffect = 'none' | 'dom' | 'filesystem' | 'network' | 'process' | 'external-api' | 'git';
+export type Nac3Role = 'button' | 'link' | 'dialog' | 'action' | 'query' | 'navigation' | 'control' | 'region' | 'form-field';
+export interface Nac3JsonSchema {
+    type: 'object';
+    properties: Record<string, {
+        type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+        description?: string;
+        enum?: readonly string[];
+        minLength?: number;
+        maxLength?: number;
+        pattern?: string;
+    }>;
+    required: readonly string[];
+}
+export interface Nac3Verb {
+    id: string;
+    role: Nac3Role;
+    action: string;
+    label: string;
+    description?: string;
+    schema: Nac3JsonSchema;
+    policy: Nac3Policy;
+    side_effects: Nac3SideEffect[];
+    visible: boolean;
+    /** Where the handler runs. 'panel' = client-side DOM action,
+     *  dispatched via the panel intercept of tool_rounds.
+     *  'server' = handler runs inside nac3_invoke server-side via
+     *  the legacy alias. */
+    handler_side: 'panel' | 'server';
+    /** When true AND handler_side='server', the server runs the
+     *  legacy handler first (to perform the side effect, e.g. read
+     *  a file from disk), then wraps the result as a panel-dispatch
+     *  envelope so the panel materialises a UI update with the
+     *  server-provided payload. Used by verbs like
+     *  yujin.pizarron.open-file where the server reads disk and
+     *  the panel renders the tab. */
+    panel_consume?: boolean;
+    precondition?: string;
+    deprecated_aliases?: string[];
+}
+export interface Nac3Manifest {
+    version: string;
+    built_at: string;
+    forge_version: string;
+    verbs: Nac3Verb[];
+}
+export declare function manifest(): Nac3Manifest;
+export declare function findVerb(verb_id: string): Nac3Verb | null;
+/** Resolve a deprecated alias (legacy `forge_*` tool name) to
+ *  its current verb. Returns null when the alias is unknown. */
+export declare function findVerbByAlias(alias: string): Nac3Verb | null;
+/** Validate args against the verb's schema. Returns null when
+ *  ok, or a short error string when not. Subset of JSON Schema --
+ *  enough to catch the LLM's typical mistakes (missing required,
+ *  wrong type, value out of enum, string too long). */
+export declare function validateArgs(verb: Nac3Verb, args: Record<string, unknown>): string | null;
+/** Compute up to N verb ids closest to the queried id by
+ *  Levenshtein distance. Used by the dispatcher when a verb is
+ *  not found to give the LLM (and the log) actionable suggestions. */
+export declare function suggestVerbs(queried: string, top?: number): string[];
+//# sourceMappingURL=internal_manifest.d.ts.map

package/dist/nac3/internal_manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal_manifest.d.ts","sourceRoot":"","sources":["../../src/nac3/internal_manifest.ts"],"names":[],"mappings":"AAiBA,MAAM,MAAM,UAAU,GAClB,cAAc,GACd,SAAS,GACT,mBAAmB,GACnB,aAAa,GACb,eAAe,GACf,oBAAoB,CAAC;AAEzB,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,KAAK,GACL,YAAY,GACZ,SAAS,GACT,SAAS,GACT,cAAc,GACd,KAAK,CAAC;AAEV,MAAM,MAAM,QAAQ,GAChB,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,YAAY,GACZ,SAAS,GACT,QAAQ,GACR,YAAY,CAAC;AAEjB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;QACzB,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;QAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QACzB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,UAAU,CAAC;IACnB,YAAY,EAAE,cAAc,EAAE,CAAC;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB;;;4BAGwB;IACxB,YAAY,EAAE,OAAO,GAAG,QAAQ,CAAC;IACjC;;;;;;qCAMiC;IACjC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AA66ED,wBAAgB,QAAQ,IAAI,YAAY,CAOvC;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAGzD;AAED;gEACgE;AAChE,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAO9D;AAED;;;uDAGuD;AACvD,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI,CAgCzF;AAED;;sEAEsE;AACtE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,SAAI,GAAG,MAAM,EAAE,CAO/D"}