@vibesdotdev/tools 0.0.0-stage → 1.0.0-rc.3

package/dist/cli/commands/tools.list.command.impl.js

@@ -0,0 +1,257 @@
+/**
+ * `vibes tools list` implementation.
+ *
+ * Pilots SURFACE-PACKAGE-CONVENTIONS §3 — acquires the canonical
+ * `ToolsClient` via the runtime-client helper, falls back to direct
+ * runtime queries to surface the same `tools/tool` set the registry
+ * exposes today. Emits structured output (table-ish text or JSON).
+ *
+ * Local tools the discovery pass registered from `.vibes/tools` are tagged
+ * `source: 'local'` so end-user developers can tell project tools from system
+ * catalog entries.
+ */
+import * as z from 'zod/v4';
+import { toolEligibleForPurpose } from '@vibesdotdev/tools/kinds/tool';
+import { writeJson } from '@vibesdotdev/cli/output';
+import { systemToolSchemaToJsonSchema } from '@vibesdotdev/tools/schemas/system-tools';
+import { ToolSafetyCategorySchema, ToolSchemasSchema } from '@vibesdotdev/tools/schemas/runtime/descriptors';
+// Feature package public export — tools/cli is a surface over @vibesdotdev/tools.
+import { emitLocalToolsNotices, isLocalToolId, localToolsOf } from '@vibesdotdev/tools/local/node/ensure-local-tools';
+import { openCommandOutput } from "../shared/command-io.js";
+import { parseCommandInput } from "../shared/command-input.js";
+import { parseRequestedToolPurpose } from "./requested-purpose.js";
+import { CatalogToolSchema } from "./resolve-tool.js";
+const COMMAND = 'tools list';
+const ListArgsSchema = z.object({});
+const ListOptionsSchema = z.object({
+    category: z.string().optional(),
+    scope: z.string().optional(),
+    local: z.boolean().optional(),
+    localOnly: z.boolean().optional(),
+    json: z.boolean().optional(),
+    format: z.string().optional(),
+    purpose: z.string().optional()
+});
+/**
+ * Prefer mcpDescription for list surfaces — that is what agents/MCP hosts see.
+ * Exported for unit tests (protects Ex: example strings from being hidden
+ * behind longer generic `description` fields).
+ */
+export function selectToolListDescription(d) {
+    const mcpDescription = d.mcpDescription && d.mcpDescription.length > 0 ? d.mcpDescription : undefined;
+    const description = d.description && d.description.length > 0 ? d.description : undefined;
+    return {
+        description: mcpDescription ?? description,
+        mcpDescription
+    };
+}
+/**
+ * Classify a tools/tool id as project-local when discovery registered it from
+ * `.vibes/tools`. Uses the shared isLocalToolId (same alias rules as MCP
+ * [local] tagging).
+ */
+export function classifyToolListSource(kind, toolId, localToolIds) {
+    if (kind === 'ai/tool')
+        return 'ai/tool';
+    const toolIds = Array.isArray(localToolIds)
+        ? localToolIds
+        : [...localToolIds];
+    if (toolIds.length === 0)
+        return 'tools/tool';
+    return isLocalToolId(toolId, toolIds) ? 'local' : 'tools/tool';
+}
+/**
+ * Exported for unit tests: foreign hosts project live parameters and their
+ * approval policy from these rows, so the input-schema and safety wiring is
+ * contract, not detail.
+ */
+export function pickRow(descriptor, kind, localToolIds) {
+    const d = CatalogToolSchema.parse(descriptor);
+    const { description, mcpDescription } = selectToolListDescription(d);
+    const id = d.id ?? '';
+    const row = {
+        id,
+        name: d.name ?? id,
+        description,
+        mcpDescription,
+        category: d.category,
+        hardware: d.hardware,
+        purpose: d.purpose,
+        tags: d.tags,
+        source: classifyToolListSource(kind, id, localToolIds)
+    };
+    const inputSchema = systemToolSchemaToJsonSchema(d.schemas?.input);
+    if (inputSchema !== undefined)
+        row.inputSchema = inputSchema;
+    if (d.requiresApproval !== undefined)
+        row.requiresApproval = d.requiresApproval;
+    // A row claims safety only when its whole declaration reads: an unreadable
+    // action map withholds the tool-level category too, so a host asks before
+    // any action rather than running every action as the tool's `read`.
+    const declaredActionSafety = d.schemas?.actionSafety;
+    const actionSafety = ToolSchemasSchema.shape.actionSafety.safeParse(declaredActionSafety);
+    if (!actionSafety.success)
+        return row;
+    if (actionSafety.data !== undefined)
+        row.schemas = { actionSafety: actionSafety.data };
+    if (d.safety !== undefined)
+        row.safety = d.safety;
+    return row;
+}
+/**
+ * Every enabled `tools/tool` descriptor this call may see. With no requested
+ * purpose, the host's own eligibility (its declared purpose and hardware)
+ * applies through the query; a requested purpose is evaluated per descriptor
+ * by the kind's rule on the host's hardware, so a purpose-locked tool is
+ * listed exactly when that purpose unlocks it. Exported for unit tests.
+ */
+export function eligibleToolDescriptors(runtime, purpose) {
+    if (!runtime.hasKind('tools/tool'))
+        return [];
+    if (!purpose) {
+        return runtime.query('tools/tool').enabled().descriptors();
+    }
+    const hardware = runtime.scope.hardware;
+    return runtime
+        .assets('tools/tool')
+        .descriptors()
+        .filter((d) => d.enabled !== false && toolEligibleForPurpose(d, purpose, hardware));
+}
+async function gatherTools(runtime, out, localToolIds, purpose) {
+    if (!runtime.hasKind('tools/tool')) {
+        out.errorLine('[vibes tools list] tools/tool kind is not registered in this runtime — ' +
+            'the system tool catalog will be empty. Register @vibesdotdev/tools plugin ' +
+            '(or your app vibes.config tools plugin chain) before treating "No tools" as truth.');
+    }
+    // `tools/tool` — framework-registered system tools (the canonical set
+    // surfaced by `vibes tools list` historically) + auto-loaded local tools.
+    const systemDescs = eligibleToolDescriptors(runtime, purpose);
+    // `ai/tool` — user-defined custom tool wrappers. Best-effort: ToolsClient
+    // reads these via runtime queries, so we go straight to the runtime to
+    // avoid forcing storage manifests to load in environments where they're
+    // not provisioned.
+    const customDescs = runtime.hasKind('ai/tool') ? runtime.query('ai/tool').descriptors() : [];
+    return [
+        ...systemDescs.map((d) => pickRow(d, 'tools/tool', localToolIds)),
+        ...customDescs.map((d) => pickRow(d, 'ai/tool', localToolIds))
+    ];
+}
+export function formatNoToolsMessage(params) {
+    if (params.localOnly) {
+        const localCount = params.allRows.filter((r) => r.source === 'local').length;
+        if (localCount === 0) {
+            return ('No local tools registered from .vibes/tools. ' +
+                'Run: vibes tools init [--example]  then  vibes tools list --local');
+        }
+        // Filters below may still empty the set (category/scope + local).
+    }
+    if (!params.category && !params.scope && !params.localOnly)
+        return 'No tools registered.';
+    if (params.scope) {
+        const scopes = Array.from(new Set(params.allRows.flatMap((row) => row.hardware ?? []))).sort();
+        if (scopes.length === 0) {
+            return `No tools match hardware scope "${params.scope}". No registered tools declare hardware.`;
+        }
+        return `No tools match hardware scope "${params.scope}". Available hardware: ${scopes.join(', ')}.`;
+    }
+    if (params.category) {
+        const categories = Array.from(new Set(params.allRows
+            .map((row) => row.category)
+            .filter((category) => category !== undefined && category.length > 0))).sort();
+        if (categories.length === 0) {
+            return `No tools match category "${params.category}". No registered tools declare a category.`;
+        }
+        return `No tools match category "${params.category}". Available categories: ${categories.join(', ')}.`;
+    }
+    if (params.localOnly) {
+        return 'No local tools match the current filters.';
+    }
+    return 'No tools registered.';
+}
+/**
+ * Filter tools by hardware scope (consumer|cloud). Tools with empty/missing
+ * hardware remain visible (universal). Exported for unit tests.
+ */
+export function filterToolsByScope(rows, scope) {
+    if (!scope)
+        return rows;
+    const normalized = scope.trim().toLowerCase();
+    if (!normalized)
+        return rows;
+    return rows.filter((row) => {
+        if (!row.hardware || row.hardware.length === 0)
+            return true;
+        return row.hardware.some((h) => h.toLowerCase() === normalized);
+    });
+}
+/** Keep only project-local (`.vibes/tools`) rows. */
+export function filterToolsLocalOnly(rows, localOnly) {
+    if (!localOnly)
+        return rows;
+    return rows.filter((row) => row.source === 'local');
+}
+function isJsonOutput(opts) {
+    return opts.json === true || opts.format === 'json';
+}
+function printTable(out, rows, options) {
+    if (rows.length === 0) {
+        out.line(formatNoToolsMessage(options));
+        return;
+    }
+    out.line(`\nAvailable Tools (${rows.length}):\n`);
+    out.line(`${'ID'.padEnd(36)} ${'Category'.padEnd(14)} ${'Source'.padEnd(11)} Name`);
+    out.line('-'.repeat(96));
+    const sorted = [...rows].sort((a, b) => {
+        // Local tools first when mixed — end-user project catalog is the hero.
+        if (a.source === 'local' && b.source !== 'local')
+            return -1;
+        if (b.source === 'local' && a.source !== 'local')
+            return 1;
+        const cat = (a.category ?? 'zz').localeCompare(b.category ?? 'zz');
+        return cat !== 0 ? cat : a.id.localeCompare(b.id);
+    });
+    for (const r of sorted) {
+        out.line(`${r.id.slice(0, 36).padEnd(36)} ${(r.category ?? '-').slice(0, 14).padEnd(14)} ${r.source.padEnd(11)} ${r.name}`);
+    }
+    out.line('');
+}
+export async function execute(rawArgs, rawOptions, context) {
+    parseCommandInput(ListArgsSchema, rawArgs, COMMAND);
+    const opts = parseCommandInput(ListOptionsSchema, rawOptions, COMMAND);
+    const runtime = context.runtime;
+    const out = await openCommandOutput(runtime);
+    const options = {
+        category: opts.category,
+        scope: opts.scope,
+        localOnly: opts.local === true || opts.localOnly === true,
+        json: opts.json === true,
+        format: opts.format
+    };
+    // The requested purpose is this call's argument (`scope-invalid` for an
+    // unknown one); the host's declared scope is never patched.
+    const purpose = parseRequestedToolPurpose(opts.purpose);
+    // The boot's discovery pass registered `.vibes/tools`; this reports it.
+    // Notices are for human mode only.
+    const local = localToolsOf(runtime);
+    if (!isJsonOutput(options))
+        emitLocalToolsNotices(local);
+    // isLocalToolId expands bare ↔ local: aliases (same as MCP [local] tagging).
+    const allRows = await gatherTools(runtime, out, local.toolIds, purpose);
+    let rows = options.category
+        ? allRows.filter((row) => row.category === options.category)
+        : allRows;
+    rows = filterToolsByScope(rows, options.scope);
+    rows = filterToolsLocalOnly(rows, options.localOnly);
+    if (isJsonOutput(options)) {
+        await writeJson(runtime, rows);
+        return;
+    }
+    printTable(out, rows, {
+        category: options.category,
+        scope: options.scope,
+        localOnly: options.localOnly,
+        allRows
+    });
+}
+export default { execute };
+//# sourceMappingURL=tools.list.command.impl.js.map

package/dist/cli/commands/tools.list.command.impl.js.map

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

package/dist/cli/commands/tools.run.command.descriptor.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `vibes tools run <toolId>` — execute a tool by ID (surface package ownership).
+ * The feature-prefixed filename keeps runtime discovery unambiguous.
+ */
+export declare const runCommandDescriptor: {
+    readonly kind: "cli/command";
+    readonly id: "tools.run";
+    readonly name: "run";
+    readonly description: "Run a tool by ID with arguments";
+    readonly group: "tools";
+    readonly arguments: [{
+        readonly name: "toolId";
+        readonly description: "Tool ID to run (e.g., workspace-fs, web-search)";
+        readonly required: true;
+    }];
+    readonly options: [{
+        readonly flags: "--metadata <json>";
+        readonly description: "Caller metadata as a JSON object; identity and workspace use their dedicated bindings";
+    }, {
+        readonly flags: "-i, --input <json>";
+        readonly description: "Tool input as JSON string";
+    }, {
+        readonly flags: "-f, --format <format>";
+        readonly description: "Output format (json|yaml|raw)";
+        readonly default: "raw";
+    }, {
+        readonly flags: "--dry-run";
+        readonly description: "Show what would be executed without running";
+    }, {
+        readonly flags: "-s, --session <sessionId>";
+        readonly description: "Explicit session id to bind for this tool call";
+    }, {
+        readonly flags: "-p, --participant <participantId>";
+        readonly description: "Explicit participant id to bind for this tool call";
+    }, {
+        readonly flags: "-a, --agent <agentId>";
+        readonly description: "Explicit agent id to bind for this tool call";
+    }, {
+        readonly flags: "--purpose <purpose>";
+        readonly description: "Invocation purpose (direct|worker|mcp|agent|projection). Locked tools honor it; projection and mcp are one surface.";
+    }];
+    readonly surfaces: ["cli"];
+    readonly hardware: ["consumer", "cloud"];
+    readonly enabled: true;
+    readonly examples: [{
+        readonly command: "vibes tools run example-echo --input '{\"action\":\"echo\",\"message\":\"hi\"}'";
+        readonly description: "Run a local or registered tool with JSON input";
+        readonly expectExit: 0;
+    }];
+};
+export default runCommandDescriptor;
+//# sourceMappingURL=tools.run.command.descriptor.d.ts.map

package/dist/cli/commands/tools.run.command.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.run.command.descriptor.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/tools.run.command.descriptor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwD/B,CAAC;AAEH,eAAe,oBAAoB,CAAC"}

package/dist/cli/commands/tools.run.command.descriptor.js

@@ -0,0 +1,63 @@
+/**
+ * `vibes tools run <toolId>` — execute a tool by ID (surface package ownership).
+ * The feature-prefixed filename keeps runtime discovery unambiguous.
+ */
+import { createRuntimeAsset } from '@vibesdotdev/kernel';
+export const runCommandDescriptor = createRuntimeAsset({
+    kind: 'cli/command',
+    id: 'tools.run',
+    name: 'run',
+    description: 'Run a tool by ID with arguments',
+    group: 'tools',
+    arguments: [
+        {
+            name: 'toolId',
+            description: 'Tool ID to run (e.g., workspace-fs, web-search)',
+            required: true
+        }
+    ],
+    options: [
+        { flags: '--metadata <json>', description: 'Caller metadata as a JSON object; identity and workspace use their dedicated bindings' },
+        {
+            flags: '-i, --input <json>',
+            description: 'Tool input as JSON string'
+        },
+        {
+            flags: '-f, --format <format>',
+            description: 'Output format (json|yaml|raw)',
+            default: 'raw'
+        },
+        {
+            flags: '--dry-run',
+            description: 'Show what would be executed without running'
+        },
+        {
+            flags: '-s, --session <sessionId>',
+            description: 'Explicit session id to bind for this tool call'
+        },
+        {
+            flags: '-p, --participant <participantId>',
+            description: 'Explicit participant id to bind for this tool call'
+        },
+        {
+            flags: '-a, --agent <agentId>',
+            description: 'Explicit agent id to bind for this tool call'
+        },
+        {
+            flags: '--purpose <purpose>',
+            description: 'Invocation purpose (direct|worker|mcp|agent|projection). Locked tools honor it; projection and mcp are one surface.'
+        }
+    ],
+    surfaces: ['cli'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true,
+    examples: [
+        {
+            command: 'vibes tools run example-echo --input \'{"action":"echo","message":"hi"}\'',
+            description: 'Run a local or registered tool with JSON input',
+            expectExit: 0
+        }
+    ]
+});
+export default runCommandDescriptor;
+//# sourceMappingURL=tools.run.command.descriptor.js.map

package/dist/cli/commands/tools.run.command.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.run.command.descriptor.js","sourceRoot":"","sources":["../../../src/cli/commands/tools.run.command.descriptor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,CAAC,MAAM,oBAAoB,GAAG,kBAAkB,CAAC;IACtD,IAAI,EAAE,aAAa;IACnB,EAAE,EAAE,WAAW;IACf,IAAI,EAAE,KAAK;IACX,WAAW,EAAE,iCAAiC;IAC9C,KAAK,EAAE,OAAO;IACd,SAAS,EAAE;QACV;YACC,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,iDAAiD;YAC9D,QAAQ,EAAE,IAAI;SACd;KACD;IACD,OAAO,EAAE;QACR,EAAE,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,uFAAuF,EAAE;QACpI;YACC,KAAK,EAAE,oBAAoB;YAC3B,WAAW,EAAE,2BAA2B;SACxC;QACD;YACC,KAAK,EAAE,uBAAuB;YAC9B,WAAW,EAAE,+BAA+B;YAC5C,OAAO,EAAE,KAAK;SACd;QACD;YACC,KAAK,EAAE,WAAW;YAClB,WAAW,EAAE,6CAA6C;SAC1D;QACD;YACC,KAAK,EAAE,2BAA2B;YAClC,WAAW,EAAE,gDAAgD;SAC7D;QACD;YACC,KAAK,EAAE,mCAAmC;YAC1C,WAAW,EAAE,oDAAoD;SACjE;QACD;YACC,KAAK,EAAE,uBAAuB;YAC9B,WAAW,EAAE,8CAA8C;SAC3D;QACD;YACC,KAAK,EAAE,qBAAqB;YAC5B,WAAW,EACV,qHAAqH;SACtH;KACD;IACD,QAAQ,EAAE,CAAC,KAAK,CAAC;IACjB,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;IACb,QAAQ,EAAE;QACT;YACC,OAAO,EAAE,2EAA2E;YACpF,WAAW,EAAE,gDAAgD;YAC7D,UAAU,EAAE,CAAC;SACb;KACD;CACD,CAAC,CAAC;AAEH,eAAe,oBAAoB,CAAC"}

package/dist/cli/commands/tools.run.command.impl.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `vibes tools run` implementation — surface over @vibesdotdev/tools.
+ * The feature-prefixed filename pairs with its globally unique descriptor stem.
+ * Project-local `.vibes/tools` come from the boot's discovery pass (reported by
+ * localToolsOf).
+ * Resolves tool ids the same way as inspect (local: aliases, query+assets).
+ */
+import { type CaughtFailure, type RuntimePurpose, type VibesRuntime } from '@vibesdotdev/kernel';
+import type { CommandContext } from '@vibesdotdev/cli';
+import { type LocalToolsReport } from '@vibesdotdev/tools/local/node/ensure-local-tools';
+import { extractExExampleFromMcpDescription } from '@vibesdotdev/tools/local/extract-ex-example';
+import { type CatalogTool } from './resolve-tool.ts';
+import { type RunArgs, type RunOptions } from './schemas/tools-run.ts';
+import { callerFromRuntimeScope } from '@vibesdotdev/tools/execution';
+export { extractExExampleFromMcpDescription };
+export type { RunArgs, RunOptions } from './schemas/tools-run.ts';
+/** The caller a run is made as; the tools execution package owns it (`@vibesdotdev/tools/execution`). */
+export { callerFromRuntimeScope };
+/**
+ * stderr lines when `--purpose` and a purpose-locked tool disagree; null when
+ * the tool may run. The CLI declares the purpose `tools run --purpose` names
+ * at boot (rc02-rc03 C7), so on the CLI the two agree; a host that declared
+ * another purpose (an embedding host that calls this command) is refused
+ * rather than re-declared. Pure for unit tests.
+ */
+export declare function toolPurposeRefusal(toolId: string, descriptor: {
+    purpose?: readonly string[];
+    restrictPurpose?: boolean;
+}, requested: RuntimePurpose, hostPurpose: RuntimePurpose): string[] | null;
+/**
+ * stderr lines when a tool ID is not registered. Project-local tools are
+ * whatever the boot's discovery pass registered from `.vibes/tools`; a
+ * discovery failure already failed the boot, so there is none to report here.
+ */
+export declare function toolNotFoundMessages(toolId: string, opts?: {
+    local?: Pick<LocalToolsReport, 'status' | 'toolIds'>;
+    /** Registered + local catalog for "did you mean" (end-user DX). */
+    catalogIds?: readonly string[];
+}): string[];
+/**
+ * Human-facing stderr lines for a failed tools run.
+ * Validation failures list issues + inspect/dry-run recovery (end-user DX).
+ * Pure for unit tests — no process.exit.
+ */
+export declare function formatToolRunFailureMessages(failure: CaughtFailure, opts: {
+    toolId: string;
+}): string[];
+/**
+ * What a failed run prints on stdout for a machine reader: with `--format json`, the refusal's
+ * typed facts as the runtime's CapabilityError envelope (an untyped failure as its value-free
+ * INTERNAL form), so a caller in another process keeps its reason and details; otherwise nothing.
+ */
+export declare function toolRunRefusalDocument(failure: CaughtFailure, format: RunOptions['format']): string | undefined;
+/**
+ * When the user omitted --input and the descriptor schema rejects `{}`,
+ * emit a pre-flight message before invoke (clearer than a raw validation dump).
+ * Pure — returns null when empty input is valid or no schema is declared.
+ * Ex: examples come from shared extractExExampleFromMcpDescription (feature package).
+ */
+export declare function formatEmptyInputPreflightMessages(opts: {
+    /** The handed runtime the validator logs on. */
+    runtime: VibesRuntime;
+    toolId: string;
+    descriptor: CatalogTool;
+}): string[] | null;
+declare const _default: {
+    execute(rawArgs: RunArgs, rawOptions: RunOptions, context: CommandContext): Promise<void>;
+};
+export default _default;
+//# sourceMappingURL=tools.run.command.impl.d.ts.map

package/dist/cli/commands/tools.run.command.impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.run.command.impl.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/tools.run.command.impl.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAGN,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAOvD,OAAO,EAGN,KAAK,gBAAgB,EACrB,MAAM,kDAAkD,CAAC;AAC1D,OAAO,EAAE,kCAAkC,EAAE,MAAM,6CAA6C,CAAC;AAKjG,OAAO,EAIN,KAAK,WAAW,EAChB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAmC,KAAK,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACxG,OAAO,EAAE,sBAAsB,EAAsB,MAAM,8BAA8B,CAAC;AAG1F,OAAO,EAAE,kCAAkC,EAAE,CAAC;AAI9C,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAuBlE,yGAAyG;AACzG,OAAO,EAAE,sBAAsB,EAAE,CAAC;AAElC;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CACjC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE;IAAE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,eAAe,CAAC,EAAE,OAAO,CAAA;CAAE,EACtE,SAAS,EAAE,cAAc,EACzB,WAAW,EAAE,cAAc,GACzB,MAAM,EAAE,GAAG,IAAI,CAcjB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CACnC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE;IACL,KAAK,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,QAAQ,GAAG,SAAS,CAAC,CAAC;IACrD,mEAAmE;IACnE,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B,GACJ,MAAM,EAAE,CAeV;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,EAAE,CAmCvG;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,GAAG,MAAM,GAAG,SAAS,CAE/G;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,IAAI,EAAE;IACvD,gDAAgD;IAChD,OAAO,EAAE,YAAY,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,WAAW,CAAC;CACxB,GAAG,MAAM,EAAE,GAAG,IAAI,CAelB;;qBAGuB,OAAO,cAAc,UAAU,WAAW,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;;AADhG,wBA6GE"}