@opensip-cli/fitness 0.1.0

package/dist/tool.js

@@ -0,0 +1,260 @@
+/**
+ * fitnessTool — fitness as a Tool plugin.
+ *
+ * Owns the `fit`, `fit-list`, `fit-recipes`, and `fit-baseline-export`
+ * subcommands. Since release 2.11.0 (Phase 4) the Commander wiring is no longer
+ * hand-rolled: the tool exports declarative {@link CommandSpec}s
+ * (`commandSpecs`) and the host's `mountCommandSpec` mounts them
+ * (name/description/aliases, the ADR-0021 common flags, each command's options)
+ * and owns the parse→handler→error→exit pipeline. This file owns only the
+ * fitness command-spec assembly + the live-view renderer wiring; the spec
+ * modules under `cli/fit/` own the option declarations and handler bodies. (The
+ * standalone `report` subcommand is owned by the CLI, which composes it from
+ * every tool's contributed data — see
+ * packages/cli/src/commands/host-command-specs.ts — and migrates with the host
+ * commands in Phase 6.)
+ *
+ * Two-key registration invariant
+ * ------------------------------
+ * Fitness contributes TWO distinct identifiers to the CLI's registries
+ * and the mismatch is intentional — do not collapse them:
+ *
+ *   - `metadata.id = 'fitness'` is the package-wide tool identifier
+ *     (conflict-detection key in the CLI-managed tool registry).
+ *
+ *   - `FIT_LIVE_VIEW_KEY = 'fit'` is the live-view key. Used to call
+ *     `cli.registerLiveView('fit', renderer)` and consumed by
+ *     `cli.renderLive('fit', args)` in `runLiveMode`. The key matches
+ *     the `fit` subcommand name so the dispatcher's `renderLive(key)`
+ *     reads naturally next to the command that triggers it.
+ *
+ * Layer 5 Phase 3 (closes audit 2026-05-23 F3): fitness now ships its
+ * own Ink/React renderer (`renderFitLive` in `cli/fit-runner.tsx`)
+ * and registers it directly via `cli.registerLiveView`. The prior
+ * `cli.builtinLiveViews` self-lookup handshake is gone.
+ *
+ * In the spec-mounted world there is no `register()` mount hook, so the live-view
+ * renderer is registered lazily on the host context (via {@link setUpFitLiveView})
+ * the first time a live `fit` run needs it. `registerLiveView` is an idempotent
+ * map write, so doing this once per run — only on the interactive path that needs
+ * it — is equivalent to the old mount-time registration.
+ *
+ * Module layout
+ * -------------
+ * - This file owns the command-spec assembly + the tool descriptor.
+ * - `cli/fit/fit-command-spec.ts` owns the primary `fit` command spec + handler.
+ * - `cli/fit/fit-aux-command-specs.ts` owns the aux command specs.
+ * - `cli/fit-modes.ts` owns the dispatch branches (gate/list/recipes/json/live).
+ */
+import { readPackageVersion } from '@opensip-cli/core';
+import { fitnessFingerprintStrategy } from './baseline-strategy.js';
+import { fitBaselineExportCommandSpec, fitListCommandSpec, fitRecipesCommandSpec, } from './cli/fit/fit-aux-command-specs.js';
+import { buildFitCommandSpec, FIT_LIVE_VIEW_KEY } from './cli/fit/fit-command-spec.js';
+import { renderFitLive } from './cli/fit-runner.js';
+import { fitRunWorkerCommandSpec } from './cli/fit-worker.js';
+import { collectFitnessReportData } from './cli/report-data.js';
+import { fitnessConfigDeclaration } from './config/fitness-config-schema.js';
+import { createCheckRegistry, createFitnessLoadState, createRecipeRegistry, currentCheckRegistry, currentRecipeRegistry, } from './framework/scope-registry.js';
+import { fitReplayFromSession } from './persistence/session-replay.js';
+import { FIT_PLUGIN_LAYOUT } from './plugins/loader.js';
+import { fitScaffoldConfigBlock } from './scaffold/config-block.js';
+import { fitScaffoldExamples, fitStableExampleIds } from './scaffold/examples.js';
+// Side-effect import: ensures the RunScope.fitness augmentation is loaded so
+// `scope.fitness` is the correctly-typed slot here.
+import './scope-augmentation.js';
+// =============================================================================
+// COMMAND DESCRIPTORS — used by --help listings and conflict detection.
+// =============================================================================
+const FIT = {
+    name: 'fit',
+    description: 'Run fitness checks',
+};
+const FIT_LIST = {
+    name: 'fit-list',
+    description: 'List available fitness checks',
+};
+const FIT_RECIPES = {
+    name: 'fit-recipes',
+    description: 'List available fitness recipes',
+};
+const FIT_BASELINE_EXPORT = {
+    name: 'fit-baseline-export',
+    description: 'Export the fit gate baseline (SARIF) from the datastore to a file',
+};
+const FIT_RUN_WORKER = {
+    name: 'fit-run-worker',
+    description: '[internal] Run fit headless and stream progress + result over IPC (forked by the live view)',
+};
+// =============================================================================
+// LIVE-VIEW SETUP + COMMAND-SPEC ASSEMBLY
+// =============================================================================
+/**
+ * Set fitness's live view (Layer 5 Phase 3) up on the host context — a
+ * synchronous, void-returning map write (named with the `setUp` prefix to signal
+ * that; `register*` would trip the `detached-promises` dogfood heuristic). Its
+ * effectful egress (cloud + `--report-to`) lives at the composition root:
+ * renderFitLive returns the run's envelope and this callback delivers it once
+ * the Ink app exits.
+ *
+ * In the spec-mounted world there is no `register()` mount hook, so the `fit`
+ * handler sets the renderer up lazily on the interactive path (before any
+ * `cli.renderLive` lookup). `registerLiveView` is an idempotent map write, so
+ * doing this once per run — only on the live path that needs it — is equivalent
+ * to the old mount-time registration.
+ */
+function setUpFitLiveView(cli) {
+    cli.registerLiveView(FIT_LIVE_VIEW_KEY, async (args, liveContext) => {
+        const fitArgs = args;
+        // The host always supplies the LiveViewContext (carrying the run timer for
+        // the summary provider). The renderer returns a ToolRunCompletion; the HOST
+        // persists its `session` after this resolves (host-owned-run-timing Phase 2).
+        const completion = await renderFitLive(fitArgs, liveContext, {
+            setExitCode: cli.setExitCode,
+        });
+        // Effectful egress lives at the composition root (ADR-0011 / ADR-0008):
+        // best-effort cloud sync + `--report-to` (which owns exit 4). Delivered
+        // ONCE, after the interactive Ink view exits. A content failure
+        // (critical/high signals) dominates a `--report-to` upload failure so a
+        // real failure is never masked by exit 4.
+        if (completion.envelope !== undefined) {
+            // ADR-0035: the host derives the findings exit from envelope.verdict.passed
+            // inside deliverSignals — no runFailed override on a normal run.
+            await cli.deliverSignals(completion.envelope, {
+                cwd: fitArgs.cwd,
+                reportTo: fitArgs.reportTo,
+                apiKey: fitArgs.apiKey,
+            });
+        }
+        // Return the completion so the host completes the lifecycle + persists the
+        // session contribution (the renderer no longer writes the session).
+        return completion;
+    });
+}
+/**
+ * Fitness's declarative command surface (release 2.11.0 Phase 4). The host
+ * mounts each spec via `mountCommandSpec`; fitness no longer touches Commander.
+ * The primary `fit` spec is built with `setUpFitLiveView` so the renderer wiring
+ * stays next to the `renderFitLive` import in this module.
+ */
+const fitCommandSpecs = [
+    buildFitCommandSpec(setUpFitLiveView),
+    fitListCommandSpec,
+    fitRecipesCommandSpec,
+    fitBaselineExportCommandSpec,
+    fitRunWorkerCommandSpec,
+];
+/**
+ * The fitness tool's REAL registrar for its `fit-pack` capability domain
+ * (§5.3 / Phase 4). The host registers the domain from fitness's manifest with
+ * a deferred placeholder, then swaps in this registrar once fitness's module
+ * loads. A routed contribution (already shape-checked against the domain's
+ * `requiredKeys: ['slug']` schema by the host) is registered into THIS run's
+ * scope-owned check registry — fitness owns the registration semantics.
+ */
+const registerFitCheck = (contribution) => {
+    currentCheckRegistry().register(contribution);
+};
+/**
+ * The fitness tool's registrar for its `fit-recipe` capability domain (§5.3
+ * separate-domains fold). A check pack's co-located `recipes` export is routed
+ * here by the SAME discovery walk that loads its checks. The host has already
+ * shape-checked each contribution against `requiredKeys: ['id', 'name']`; this
+ * silently skips a recipe whose id/name is already registered (mirroring the
+ * shared `registerRecipesFromMod` dedupe), so re-discovery is idempotent.
+ */
+const registerFitRecipe = (contribution) => {
+    const recipe = contribution;
+    const registry = currentRecipeRegistry();
+    if (registry.has(recipe.id) || registry.has(recipe.name))
+        return;
+    registry.register(recipe, { allowOverwrite: false });
+};
+/**
+ * Per-run subscope contribution (D7). Called by the CLI's pre-action-hook
+ * after constructing the scope and before entering it; the kernel installs
+ * the returned `fitness` slot. Fresh check + recipe registries (and an empty
+ * `ensureChecksLoaded` lifecycle slot) per run so concurrent scopes carry
+ * independent fitness state.
+ */
+function contributeScope() {
+    return {
+        fitness: {
+            checks: createCheckRegistry(),
+            recipes: createRecipeRegistry(),
+            load: createFitnessLoadState(),
+        },
+    };
+}
+// =============================================================================
+// Per-tool contract version (ADR-0047)
+// =============================================================================
+/**
+ * Per-tool contract version for the fitness-specific surface
+ * (defineCheck, analysis modes, check packs, recipes, etc.).
+ * Independent of the core TOOL_CONTRACT_VERSION (the generic Tool bus).
+ * Bumped only on actual changes to this surface; value = major.minor of the
+ * CLI release shipping the change (see ADR-0047).
+ */
+export const FITNESS_CONTRACT_VERSION = '1.0.0';
+// =============================================================================
+// EXPORT
+// =============================================================================
+export const FITNESS_STABLE_ID = 'afd68bd3-ff3c-4935-a5b6-76d8fc7a5224';
+export const fitnessTool = {
+    metadata: {
+        id: FITNESS_STABLE_ID, // stable UUID (per ADR-0048; matches Checks `id` naming)
+        name: 'fitness', // human key (previously the value in `id`)
+        version: readPackageVersion(import.meta.url),
+        description: 'Run fitness checks against a codebase',
+    },
+    commands: [FIT, FIT_LIST, FIT_RECIPES, FIT_BASELINE_EXPORT, FIT_RUN_WORKER],
+    pluginLayout: FIT_PLUGIN_LAYOUT,
+    // Release 2.11.0 Phase 4: fitness declares its command surface; the host
+    // mounts each spec via mountCommandSpec. The deprecated `register()` fallback
+    // is gone — fitness no longer touches Commander.
+    commandSpecs: fitCommandSpecs,
+    contributeScope,
+    collectReportData: collectFitnessReportData,
+    sessionReplay: {
+        tool: 'fit',
+        replaySession: fitReplayFromSession,
+    },
+    // ADR-0023 Phase 4: fitness contributes its namespaced `fitness:` Zod schema
+    // (gate thresholds, disabledChecks, recipe) so the host composes +
+    // strict-validates the whole config document before dispatch. Shared
+    // targeting (targets/globalExcludes/checkOverrides) stays with
+    // SignalersConfigSchema because the fit hot path consumes target registries
+    // through that loader.
+    config: fitnessConfigDeclaration,
+    // §5.3 Phase 4: fitness owns the `fit-pack` capability domain (declared in
+    // its manifest). It supplies the REAL registrar so the host can replace the
+    // manifest-time deferred placeholder once fitness's module loads.
+    capabilityRegistrars: { 'fit-pack': registerFitCheck, 'fit-recipe': registerFitRecipe },
+    // ADR-0036: fitness's message-hash baseline identity (sha256(filePath\nruleId\n
+    // message)), read by the host baseline/ratchet seams when fit stamps its gate
+    // envelope. Excludes line/col so unrelated line-shifts don't flap the ratchet.
+    fingerprintStrategy: fitnessFingerprintStrategy,
+    // ADR-0038: fitness owns its `init` example bytes + the pinned check-id universe.
+    // The host writes each returned file under userPluginDir('fit', file.kind).
+    scaffoldExamples: fitScaffoldExamples,
+    stableExampleIds: fitStableExampleIds,
+    // ADR-0038 Decision 2: fitness owns its `fitness:` config block (inline guidance
+    // comments the bare ToolConfigDeclaration.defaults can't express → the hook route).
+    scaffoldConfigBlock: fitScaffoldConfigBlock,
+    initialize: async () => {
+        // ensureChecksLoaded() is called inside the executeFit / listChecks
+        // / listRecipes paths, so a separate initialize() pass is not
+        // strictly needed today. Left as a no-op so fitness has somewhere
+        // to hang future tool-startup work (eager check-pack discovery,
+        // catalog warming, etc.) without requiring a contract change.
+    },
+    // ADR-0047: per-tool contract version for the fitness-specific surface
+    // (defineCheck, analysis modes, check packs, recipes, etc.). This is
+    // independent of the core TOOL_CONTRACT_VERSION (the generic Tool bus).
+    // Declared here so agent-catalog, compatibility logic, and external
+    // fitness pack authors can see the exact surface this tool was written against.
+    extensionPoints: {
+        fitnessContractVersion: FITNESS_CONTRACT_VERSION,
+    },
+};
+//# sourceMappingURL=tool.js.map

package/dist/tool.js.map

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

package/dist/types/findings.d.ts

@@ -0,0 +1,113 @@
+/**
+ * @fileoverview Core finding and result types for fitness checks
+ *
+ * CheckResult carries Signal[]. Factory functions
+ * (createResultWithSignals, createErrorResult) provide
+ * the standard way to construct check results.
+ */
+import type { DirectiveEntry } from '../framework/directive-inventory.js';
+import type { Signal } from '@opensip-cli/core';
+/**
+ * Severity level for findings and violations.
+ */
+export type FindingSeverity = 'error' | 'warning';
+/**
+ * Alias for FindingSeverity — used by simplified check.ts types.
+ */
+export type Severity = FindingSeverity;
+/**
+ * A single finding from a fitness check (output format).
+ */
+export interface Finding {
+    readonly message: string;
+    readonly severity: Severity;
+    readonly filePath?: string;
+    readonly line?: number;
+    readonly column?: number;
+    readonly suggestion?: string;
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * Output from a tool-based check.
+ */
+export interface ToolOutput {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+}
+/**
+ * Check info for display.
+ */
+export interface CheckInfo {
+    /** Summary label (e.g., "142/150 files compliant") */
+    readonly label: string;
+}
+/**
+ * Metadata about a check run.
+ */
+export interface CheckResultMetadata {
+    /** Total items scanned */
+    readonly totalItems: number;
+    /** Signals (same reference as top-level) */
+    readonly signals: readonly Signal[];
+    /** Duration in milliseconds */
+    readonly durationMs?: number;
+    /** Number of files scanned from filesystem */
+    readonly filesScanned?: number;
+    /** Item type (e.g., 'files', 'modules') */
+    readonly itemType?: string;
+    /** Extra metadata */
+    readonly extra?: Record<string, unknown>;
+}
+/**
+ * Result of running a fitness check.
+ * Now carries universal Signal[] instead of domain-specific violations.
+ */
+export interface CheckResult {
+    /** Whether the check passed (no errors) */
+    readonly passed: boolean;
+    /** Number of error-level signals */
+    readonly errors: number;
+    /** Number of warning-level signals */
+    readonly warnings: number;
+    /** All signals */
+    readonly signals: readonly Signal[];
+    /** Display info */
+    readonly info: CheckInfo;
+    /** Run metadata */
+    readonly metadata: CheckResultMetadata;
+    /** Count of violations ignored via directives */
+    readonly ignoredCount?: number;
+    /** Directives that actually suppressed signals during this check's execution */
+    readonly appliedDirectives?: readonly DirectiveEntry[];
+}
+/**
+ * Item types for check info display.
+ */
+export type ItemType = 'files' | 'modules' | 'packages' | 'functions' | 'classes' | 'components' | 'tests' | 'endpoints' | 'dependencies' | 'issues' | 'violations' | 'rules' | 'recipes' | 'checks';
+/**
+ * Get a human-readable label for an item type.
+ */
+export declare function getItemTypeLabel(type: ItemType, count: number): string;
+/**
+ * Factory for creating CheckInfo objects.
+ */
+export declare const CheckInfoFactory: Readonly<{
+    compliance(compliantItems: number, totalItems: number, unit: string): CheckInfo;
+    violations(count: number, unit: string): CheckInfo;
+}>;
+/**
+ * Create a result with signals.
+ */
+export declare function createResultWithSignals(info: CheckInfo, signals: readonly Signal[], totalItems: number, options?: {
+    ignoredCount?: number;
+    durationMs?: number;
+    filesScanned?: number;
+    itemType?: string;
+    extra?: Record<string, unknown>;
+}): CheckResult;
+/**
+ * Create an error result (for check failures).
+ */
+export declare function createErrorResult(message: string, error?: Error): CheckResult;
+//# sourceMappingURL=findings.d.ts.map

package/dist/types/findings.d.ts.map

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

package/dist/types/findings.js

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview Core finding and result types for fitness checks
+ *
+ * CheckResult carries Signal[]. Factory functions
+ * (createResultWithSignals, createErrorResult) provide
+ * the standard way to construct check results.
+ */
+import { countErrors, countWarnings } from './severity.js';
+const ITEM_TYPE_SINGULAR = {
+    files: 'file',
+    modules: 'module',
+    packages: 'package',
+    functions: 'function',
+    classes: 'class',
+    components: 'component',
+    tests: 'test',
+    endpoints: 'endpoint',
+    dependencies: 'dependency',
+    issues: 'issue',
+    violations: 'violation',
+    rules: 'rule',
+    recipes: 'recipe',
+    checks: 'check',
+};
+/**
+ * Get a human-readable label for an item type.
+ */
+export function getItemTypeLabel(type, count) {
+    return count === 1 ? ITEM_TYPE_SINGULAR[type] : type;
+}
+// =============================================================================
+// FACTORY FUNCTIONS
+// =============================================================================
+/**
+ * Factory for creating CheckInfo objects.
+ */
+export const CheckInfoFactory = Object.freeze({
+    compliance(compliantItems, totalItems, unit) {
+        return { label: `${compliantItems}/${totalItems} ${unit} compliant` };
+    },
+    violations(count, unit) {
+        return { label: count === 0 ? `No ${unit}` : `${count} ${unit}` };
+    },
+});
+/**
+ * Create a result with signals.
+ */
+export function createResultWithSignals(info, signals, totalItems, options) {
+    const errors = countErrors(signals);
+    const warnings = countWarnings(signals);
+    return {
+        passed: errors === 0,
+        errors,
+        warnings,
+        signals,
+        info,
+        metadata: {
+            totalItems,
+            signals,
+            durationMs: options?.durationMs,
+            filesScanned: options?.filesScanned,
+            itemType: options?.itemType,
+            extra: options?.extra,
+        },
+        ...(options?.ignoredCount !== undefined && options.ignoredCount > 0
+            ? { ignoredCount: options.ignoredCount }
+            : {}),
+    };
+}
+/**
+ * Create an error result (for check failures).
+ */
+export function createErrorResult(message, error) {
+    return {
+        passed: false,
+        errors: 1,
+        warnings: 0,
+        signals: [],
+        info: { label: `Error: ${message}` },
+        metadata: {
+            totalItems: 0,
+            signals: [],
+            extra: error
+                ? { originalError: error.message, ...(error.stack ? { stack: error.stack } : {}) }
+                : undefined,
+        },
+    };
+}
+//# sourceMappingURL=findings.js.map

package/dist/types/findings.js.map

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

package/dist/types/severity.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Shared severity classification helpers
+ *
+ * Centralizes severity-based signal filtering and counting logic
+ * used across types, framework, and recipes modules.
+ */
+/** Count error-level signals in an array */
+export declare function countErrors(signals: readonly {
+    severity: string;
+}[]): number;
+/** Count warning-level signals in an array */
+export declare function countWarnings(signals: readonly {
+    severity: string;
+}[]): number;
+//# sourceMappingURL=severity.d.ts.map

package/dist/types/severity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"severity.d.ts","sourceRoot":"","sources":["../../src/types/severity.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AAWH,4CAA4C;AAC5C,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,MAAM,CAM5E;AAED,8CAA8C;AAC9C,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,MAAM,CAM9E"}

package/dist/types/severity.js

@@ -0,0 +1,33 @@
+// @fitness-ignore-file batch-operation-limits -- iterates bounded collections (config entries, registry items, or small analysis results)
+// @fitness-ignore-file clean-code-naming-quality -- short names used in severity mapping utilities
+// @fitness-ignore-file project-readme-existence -- internal module, not a package root
+/**
+ * @fileoverview Shared severity classification helpers
+ *
+ * Centralizes severity-based signal filtering and counting logic
+ * used across types, framework, and recipes modules.
+ */
+import { isErrorSeverity } from '@opensip-cli/core';
+/** Returns true for 'medium' severity signals (warning-level) */
+function isWarningSeverity(severity) {
+    return severity === 'medium';
+}
+/** Count error-level signals in an array */
+export function countErrors(signals) {
+    let count = 0;
+    for (const s of signals) {
+        if (isErrorSeverity(s.severity))
+            count++;
+    }
+    return count;
+}
+/** Count warning-level signals in an array */
+export function countWarnings(signals) {
+    let count = 0;
+    for (const s of signals) {
+        if (isWarningSeverity(s.severity))
+            count++;
+    }
+    return count;
+}
+//# sourceMappingURL=severity.js.map

package/dist/types/severity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"severity.js","sourceRoot":"","sources":["../../src/types/severity.ts"],"names":[],"mappings":"AAAA,0IAA0I;AAC1I,mGAAmG;AACnG,uFAAuF;AACvF;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAIpD,iEAAiE;AACjE,SAAS,iBAAiB,CAAC,QAAwB;IACjD,OAAO,QAAQ,KAAK,QAAQ,CAAC;AAC/B,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,WAAW,CAAC,OAAwC;IAClE,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,IAAI,eAAe,CAAC,CAAC,CAAC,QAA0B,CAAC;YAAE,KAAK,EAAE,CAAC;IAC7D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,aAAa,CAAC,OAAwC;IACpE,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,IAAI,iBAAiB,CAAC,CAAC,CAAC,QAA0B,CAAC;YAAE,KAAK,EAAE,CAAC;IAC/D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}