opensip-cli 0.1.0

package/dist/commands/init.d.ts

@@ -0,0 +1,95 @@
+/**
+ * init command — scaffold the project layout.
+ *
+ * Registry-driven (ADR-0038): `init` scaffolds one directory tree per
+ * REGISTERED tool, never a hardcoded fit/sim pair. Each tool owns its own
+ * example bytes + config block; the host owns only the directory layout
+ * (`pluginLayout`), the document header, and `targets:`. With the bundled
+ * fitness + simulation tools registered, a TypeScript project gets:
+ *   <cwd>/opensip-cli.config.yml                                    (TRACKED)
+ *   <cwd>/opensip-cli/fit/checks/example-check.mjs                  (TRACKED)
+ *   <cwd>/opensip-cli/fit/recipes/example-recipe.mjs                (TRACKED)
+ *   <cwd>/opensip-cli/sim/scenarios/example-scenario.mjs            (TRACKED)
+ *   <cwd>/opensip-cli/sim/recipes/example-recipe.mjs                (TRACKED)
+ * A tool with no `pluginLayout` (e.g. `graph`) contributes no directory.
+ *
+ * Consequence — the scaffolded set equals the REGISTERED set:
+ *   - A tool installed AFTER `init` scaffolds on the next `init --keep`.
+ *   - Back-compat behavior shift: if a bundled tool fails to load, init
+ *     now scaffolds FEWER dirs (vs the old always-fit/sim). A bundled tool
+ *     that's expected but absent is surfaced loudly via the
+ *     `cli.tool.expected_bundled_absent` diagnostic (bootstrap) so a silent
+ *     under-scaffold is observable; a genuinely uninstalled third-party
+ *     tool stays silent (correct).
+ *
+ * Appends `opensip-cli/.runtime/` to <cwd>/.gitignore so the
+ * tool-generated state (sessions, logs, dashboards, baselines, plugin
+ * installs) stays untracked.
+ *
+ * Promotion path: when a customer's pack outgrows a handful of .mjs
+ * files (shared helpers, tests, more than a dozen checks/scenarios),
+ * `opensip-cli/<domain>/` can graduate to a real workspace npm
+ * package — `package.json` with `opensipTools.kind: "fit-pack"` or
+ * `"sim-pack"`, `tsconfig.json`, `index.ts` re-exporting checks/recipes.
+ * Marker-based discovery picks up the workspace package automatically
+ * regardless of npm scope. The init scaffold stays loose-`.mjs` to
+ * preserve the fast first-touch experience; graduation is a manual
+ * step the customer takes when their coverage becomes substantial.
+ * See docs/public/50-extend/01-plugin-authoring.md.
+ *
+ * Language selection drives:
+ *   - which `targets:` entry shape goes into the YAML config
+ *   - the `scope.languages` field on the example check
+ *
+ * `--language <list>` (comma-separated) overrides detection.
+ * Detection inspects filesystem markers (Cargo.toml, pyproject.toml,
+ * go.mod, pom.xml/build.gradle, CMakeLists.txt, package.json+tsconfig).
+ * When detection is ambiguous AND --language is missing, init exits
+ * 2 with a helpful prompt — no partial scaffolding.
+ *
+ * Partial-state handling:
+ *
+ * After language resolution, init classifies the working directory
+ * into one of four states based on the presence of the config file
+ * and the `opensip-cli/` directory:
+ *
+ *   - 'pristine'             — neither present; scaffold everything.
+ *   - 'fully-initialized'    — both present; refuse without a flag.
+ *   - 'partial-config-only'  — config XOR dir; refuse without a flag.
+ *   - 'partial-dir-only'     — config XOR dir; refuse without a flag.
+ *
+ * Two flags express explicit user intent for the non-pristine states:
+ *
+ *   - `--keep`   — re-scaffold examples; preserve custom files.
+ *   - `--remove` — delete `opensip-cli/` entirely; scaffold fresh.
+ *
+ * The two flags are mutually exclusive. The legacy `--force` flag is
+ * gone; users who scripted it should migrate to `--remove`, the
+ * closest semantic match.
+ *
+ * Implementation is split across `./init/` siblings:
+ *   - language-detection.ts — marker scanning + `--language` parsing
+ *   - config-templates.ts   — host-owned YAML document skeleton (header +
+ *                             targets); per-tool config blocks come from
+ *                             each tool's `scaffoldConfigBlock()`
+ *   - file-classifier.ts    — scaffolded / stale / custom tagging
+ *   - state-machine.ts      — working-dir state + refusal messages
+ *   - scaffold-writer.ts    — disk writes + gitignore patching
+ *
+ * This file is the orchestrator: argument validation → language
+ * resolution → state classification → file classification → scaffold
+ * (or refuse).
+ */
+import { type ProjectContext } from '@opensip-cli/core';
+import type { ToolScaffold } from './shared.js';
+import type { InitOptions, InitResult } from '@opensip-cli/contracts';
+/**
+ * Run init for the given args. Returns an InitResult — the caller
+ * (CLI render layer) prints it.
+ */
+export declare function executeInit(args: InitOptions & {
+    projectContext?: ProjectContext;
+    cwdExplicit?: boolean;
+    toolScaffolds: readonly ToolScaffold[];
+}): InitResult;
+//# sourceMappingURL=init.d.ts.map

package/dist/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AAIH,OAAO,EAAuB,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAW7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEtE;;;GAGG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,WAAW,GAAG;IAClB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,SAAS,YAAY,EAAE,CAAC;CACxC,GACA,UAAU,CAsIZ"}

package/dist/commands/init.js

@@ -0,0 +1,209 @@
+/**
+ * init command — scaffold the project layout.
+ *
+ * Registry-driven (ADR-0038): `init` scaffolds one directory tree per
+ * REGISTERED tool, never a hardcoded fit/sim pair. Each tool owns its own
+ * example bytes + config block; the host owns only the directory layout
+ * (`pluginLayout`), the document header, and `targets:`. With the bundled
+ * fitness + simulation tools registered, a TypeScript project gets:
+ *   <cwd>/opensip-cli.config.yml                                    (TRACKED)
+ *   <cwd>/opensip-cli/fit/checks/example-check.mjs                  (TRACKED)
+ *   <cwd>/opensip-cli/fit/recipes/example-recipe.mjs                (TRACKED)
+ *   <cwd>/opensip-cli/sim/scenarios/example-scenario.mjs            (TRACKED)
+ *   <cwd>/opensip-cli/sim/recipes/example-recipe.mjs                (TRACKED)
+ * A tool with no `pluginLayout` (e.g. `graph`) contributes no directory.
+ *
+ * Consequence — the scaffolded set equals the REGISTERED set:
+ *   - A tool installed AFTER `init` scaffolds on the next `init --keep`.
+ *   - Back-compat behavior shift: if a bundled tool fails to load, init
+ *     now scaffolds FEWER dirs (vs the old always-fit/sim). A bundled tool
+ *     that's expected but absent is surfaced loudly via the
+ *     `cli.tool.expected_bundled_absent` diagnostic (bootstrap) so a silent
+ *     under-scaffold is observable; a genuinely uninstalled third-party
+ *     tool stays silent (correct).
+ *
+ * Appends `opensip-cli/.runtime/` to <cwd>/.gitignore so the
+ * tool-generated state (sessions, logs, dashboards, baselines, plugin
+ * installs) stays untracked.
+ *
+ * Promotion path: when a customer's pack outgrows a handful of .mjs
+ * files (shared helpers, tests, more than a dozen checks/scenarios),
+ * `opensip-cli/<domain>/` can graduate to a real workspace npm
+ * package — `package.json` with `opensipTools.kind: "fit-pack"` or
+ * `"sim-pack"`, `tsconfig.json`, `index.ts` re-exporting checks/recipes.
+ * Marker-based discovery picks up the workspace package automatically
+ * regardless of npm scope. The init scaffold stays loose-`.mjs` to
+ * preserve the fast first-touch experience; graduation is a manual
+ * step the customer takes when their coverage becomes substantial.
+ * See docs/public/50-extend/01-plugin-authoring.md.
+ *
+ * Language selection drives:
+ *   - which `targets:` entry shape goes into the YAML config
+ *   - the `scope.languages` field on the example check
+ *
+ * `--language <list>` (comma-separated) overrides detection.
+ * Detection inspects filesystem markers (Cargo.toml, pyproject.toml,
+ * go.mod, pom.xml/build.gradle, CMakeLists.txt, package.json+tsconfig).
+ * When detection is ambiguous AND --language is missing, init exits
+ * 2 with a helpful prompt — no partial scaffolding.
+ *
+ * Partial-state handling:
+ *
+ * After language resolution, init classifies the working directory
+ * into one of four states based on the presence of the config file
+ * and the `opensip-cli/` directory:
+ *
+ *   - 'pristine'             — neither present; scaffold everything.
+ *   - 'fully-initialized'    — both present; refuse without a flag.
+ *   - 'partial-config-only'  — config XOR dir; refuse without a flag.
+ *   - 'partial-dir-only'     — config XOR dir; refuse without a flag.
+ *
+ * Two flags express explicit user intent for the non-pristine states:
+ *
+ *   - `--keep`   — re-scaffold examples; preserve custom files.
+ *   - `--remove` — delete `opensip-cli/` entirely; scaffold fresh.
+ *
+ * The two flags are mutually exclusive. The legacy `--force` flag is
+ * gone; users who scripted it should migrate to `--remove`, the
+ * closest semantic match.
+ *
+ * Implementation is split across `./init/` siblings:
+ *   - language-detection.ts — marker scanning + `--language` parsing
+ *   - config-templates.ts   — host-owned YAML document skeleton (header +
+ *                             targets); per-tool config blocks come from
+ *                             each tool's `scaffoldConfigBlock()`
+ *   - file-classifier.ts    — scaffolded / stale / custom tagging
+ *   - state-machine.ts      — working-dir state + refusal messages
+ *   - scaffold-writer.ts    — disk writes + gitignore patching
+ *
+ * This file is the orchestrator: argument validation → language
+ * resolution → state classification → file classification → scaffold
+ * (or refuse).
+ */
+import { existsSync } from 'node:fs';
+import { resolveProjectPaths } from '@opensip-cli/core';
+import { classifyFiles } from './init/file-classifier.js';
+import { resolveLanguages } from './init/language-detection.js';
+import { runScaffold } from './init/scaffold-writer.js';
+import { buildPartialStateMessage, classifyWorkingDir, formatInsideExistingProjectMessage, } from './init/state-machine.js';
+/**
+ * Run init for the given args. Returns an InitResult — the caller
+ * (CLI render layer) prints it.
+ */
+export function executeInit(args) {
+    const cwd = args.cwd;
+    const keep = args.keep === true;
+    const remove = args.remove === true;
+    const paths = resolveProjectPaths(cwd);
+    const baseResult = {
+        type: 'init',
+        path: paths.configFile,
+        cwd,
+        configFilename: 'opensip-cli.config.yml',
+    };
+    // Discovery-aware refusal: if cwd sits inside an existing project and
+    // the user did NOT pass --cwd explicitly, offer the three corrective
+    // actions instead of silently scaffolding a phantom nested project.
+    const project = args.projectContext;
+    const cwdExplicit = args.cwdExplicit === true;
+    if (project?.scope === 'project' && project.projectRoot !== cwd && !cwdExplicit) {
+        const message = formatInsideExistingProjectMessage(project.projectRoot);
+        return {
+            ...baseResult,
+            path: '', // no scaffold target — we refused
+            created: false,
+            insideExistingProject: {
+                discoveredRoot: project.projectRoot,
+                message,
+            },
+        };
+    }
+    // Mutex: --keep and --remove are mutually exclusive.
+    if (keep && remove) {
+        return {
+            ...baseResult,
+            created: false,
+            partialStateError: {
+                state: 'fully-initialized',
+                preExistingFiles: [],
+                message: '--keep and --remove are mutually exclusive. Pick one.',
+            },
+        };
+    }
+    if (!existsSync(cwd)) {
+        // A non-existent target directory is a user error, not a "pristine
+        // success". Surface it through `ambiguousLanguageError` (which the
+        // register-init layer already maps to CONFIGURATION_ERROR / exit 2)
+        // so `opensip init --cwd /nonexistent` returns a nonzero exit
+        // code with a clear message instead of silently exiting 0.
+        return {
+            ...baseResult,
+            created: false,
+            ambiguousLanguageError: {
+                detected: [],
+                message: `Target directory does not exist: ${cwd}`,
+            },
+        };
+    }
+    const resolution = resolveLanguages(cwd, args.language);
+    if (!resolution.ok) {
+        return { ...baseResult, created: false, ambiguousLanguageError: resolution.error };
+    }
+    const { languages } = resolution;
+    const state = classifyWorkingDir(paths);
+    const preExistingFiles = state === 'pristine' ? [] : classifyFiles(paths, languages, args.toolScaffolds);
+    // Pristine: scaffold and exit. No flag interaction needed.
+    if (state === 'pristine') {
+        return runScaffold({
+            paths,
+            languages,
+            cwd,
+            state,
+            preExistingFiles: [],
+            removeFirst: false,
+            keepCustom: false,
+            toolScaffolds: args.toolScaffolds,
+        }, baseResult);
+    }
+    // Non-pristine without an explicit flag: refuse with partial-state
+    // error.
+    if (!keep && !remove) {
+        return {
+            ...baseResult,
+            created: false,
+            state,
+            languages,
+            preExistingFiles,
+            partialStateError: {
+                state,
+                preExistingFiles,
+                message: buildPartialStateMessage(state, preExistingFiles, cwd),
+            },
+        };
+    }
+    // --remove: blow away the dir, then scaffold from zero.
+    if (remove) {
+        return runScaffold({
+            paths,
+            languages,
+            cwd,
+            state,
+            preExistingFiles,
+            removeFirst: true,
+            keepCustom: false,
+            toolScaffolds: args.toolScaffolds,
+        }, baseResult);
+    }
+    // --keep: re-scaffold examples; preserve custom + stale-scaffolded files.
+    return runScaffold({
+        paths,
+        languages,
+        cwd,
+        state,
+        preExistingFiles,
+        removeFirst: false,
+        keepCustom: true,
+        toolScaffolds: args.toolScaffolds,
+    }, baseResult);
+}
+//# sourceMappingURL=init.js.map

package/dist/commands/init.js.map

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

package/dist/commands/mount-command-spec.d.ts

@@ -0,0 +1,106 @@
+/**
+ * mount-command-spec — the host-owned layer that turns a declarative
+ * {@link CommandSpec} (core, Phase 0) into a wired Commander command.
+ *
+ * Generalizes {@link mountResultCommand}: it mounts ANY command (tool or host)
+ * from its typed spec — translating each `OptionSpec`/`ArgSpec` into Commander
+ * wiring, applying the shared common flags (ADR-0021), and owning the uniform
+ * `parse → handler → dispatch output → map error → exit` pipeline. Tools never
+ * touch Commander; they export specs and the host mounts them (north-star §5.4).
+ *
+ * The single output-dispatch seam — {@link dispatchOutput} — wraps every machine
+ * output in a `CommandOutcome` serialized through the one `renderOutcome` seam.
+ * The wrap lives in the host emit seams this delegates to (`emitCommandResult`,
+ * `ctx.emitEnvelope`), so the handler contract stayed byte-identical (§5.5).
+ */
+import { type CliProgram, type CommandResult } from '@opensip-cli/contracts';
+import { type LiveViewContext, type ToolRunCompletion, type CommandSpec, type ToolCliContext } from '@opensip-cli/core';
+/**
+ * A {@link CommandSpec} whose handler receives the concrete host
+ * {@link ToolCliContext} (render/envelope/live-view emitters), not the kernel's
+ * unconstrained {@link CommandContext} marker. The host mounts THIS shape — the
+ * mounter is the only place that knows the real context type, so it pins it
+ * here. Tools author specs with `defineCommand<TOpts, ToolCliContext>(...)`.
+ */
+export type HostCommandSpec<TOpts = Record<string, unknown>> = CommandSpec<TOpts, ToolCliContext>;
+/**
+ * The minimal context surface {@link mountCommandSpec} / {@link dispatchOutput}
+ * actually touch — the mount layer's structural dependency, decoupled from the
+ * full handler-facing context.
+ *
+ * `render` + `setExitCode` are used by EVERY command (the `command-result`
+ * dispatch arm and the thrown-`ToolError` exit-code path). `emitEnvelope` /
+ * `renderLive` are used ONLY by the `signal-envelope` / `live-view` arms, so
+ * they are optional here: a context that mounts only `command-result` /
+ * `raw-stream` commands (the CLI-owned HOST commands) need not provide them.
+ * `dispatchOutput` guards those arms and throws if the mode is requested without
+ * the corresponding emitter — a mis-declared host spec fails loudly rather than
+ * silently no-op'ing.
+ *
+ * `ToolCliContext` (which provides all four as required members) is structurally
+ * assignable to this — so the existing tool-mount call sites pass unchanged. The
+ * generic `mountCommandSpec` lets host commands mount with a leaner context
+ * (`CliCommandsContext`) through the SAME plane, satisfying the launch "one
+ * command surface" invariant (no two-tier privilege).
+ */
+export interface CommandMountContext {
+    readonly render: (result: CommandResult) => Promise<void>;
+    readonly setExitCode: (code: number) => void;
+    readonly emitEnvelope?: (envelope: unknown) => void;
+    /**
+     * Optional live view dispatch. When the command declares output:'live-view',
+     * the host calls this with an optional third argument carrying the LiveViewContext
+     * (with the host runSession). The impl (registry) forwards it as the second
+     * arg to the registered renderer fn.
+     */
+    readonly renderLive?: (key: string, args: unknown, liveContext?: LiveViewContext) => Promise<ToolRunCompletion | void>;
+}
+/**
+ * Mount a declarative {@link CommandSpec} onto `program` as a fully wired
+ * Commander command.
+ *
+ * Steps (mirroring each tool's former hand-rolled `register()` body, now
+ * host-owned and uniform):
+ *   1. `program.command(name)` + description + aliases.
+ *   2. `applyCommonFlags(cmd, spec.commonFlags)` — the ADR-0021 registry flags.
+ *      `cwd` (the only computed default) is seeded with `process.cwd()`.
+ *   3. Each {@link OptionSpec} → a Commander `Option` (value vs boolean,
+ *      `negatable` `--no-` form, `default` / `arrayDefault`, `choices`,
+ *      `parse` argParser, `variadic`, `required` mandatory).
+ *   4. Each {@link ArgSpec} → `cmd.argument(...)` (variadic / optional bracketing).
+ *   5. `cmd.action(...)` → run `spec.handler(opts, ctx)` → {@link dispatchOutput}
+ *      → on a thrown {@link ToolError}, `mapToolErrorToExitCode` → `ctx.setExitCode`.
+ *
+ * @param program The root Commander program (the entry layer's `CliProgram`).
+ * @param spec    The declarative command surface the tool/host exported.
+ * @param ctx     The per-invocation host context (render/envelope/live-view
+ *                emitters, exit-code setter) — today's `ToolCliContext`.
+ */
+export declare function mountCommandSpec<TCtx extends CommandMountContext>(program: CliProgram, spec: CommandSpec<unknown, TCtx>, ctx: TCtx): void;
+/**
+ * The SINGLE output-dispatch seam. The launch `CommandOutcome` wrap is LANDED:
+ * the host emit seams this delegates to (`emitCommandResult`, `ctx.emitEnvelope`)
+ * now build a `CommandOutcome` and serialize it through the one `renderOutcome`
+ * seam. The handler contract and the mounter above stayed byte-identical — all
+ * the outer-shape change landed in those seams (north-star §5.5), so the handler
+ * keeps returning its pure-domain `CommandResult` / `SignalEnvelope`.
+ *
+ * Routes the handler's return value by the command's declared
+ * {@link CommandSpec.output} mode:
+ *   - `command-result`  — the existing `emitCommandResult` seam (json
+ *                         short-circuit / `ctx.render`), shared verbatim with
+ *                         {@link mountResultCommand}.
+ *   - `signal-envelope` — the run-envelope machine-output path: `--json` emits
+ *                         through `ctx.emitEnvelope` (the shared ADR-0011
+ *                         formatter), otherwise `ctx.render`.
+ *   - `raw-stream`      — explicit raw output (no Ink): the handler already
+ *                         wrote its file + line; the host renders nothing.
+ *   - `live-view`       — the interactive Ink path: `ctx.renderLive(key, args)`
+ *                         against the tool's registered renderer.
+ *
+ * @throws {Error} When a command declares `signal-envelope` / `live-view` output
+ *   but the mount context provides no `emitEnvelope` / `renderLive` emitter — a
+ *   mis-declared host spec fails loudly here rather than silently no-op'ing.
+ */
+export declare function dispatchOutput<TCtx extends CommandMountContext>(result: unknown, spec: CommandSpec<unknown, TCtx>, opts: Record<string, unknown>, positionals: readonly unknown[], ctx: TCtx): Promise<void>;
+//# sourceMappingURL=mount-command-spec.d.ts.map

package/dist/commands/mount-command-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-command-spec.d.ts","sourceRoot":"","sources":["../../src/commands/mount-command-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAGL,KAAK,UAAU,EACf,KAAK,aAAa,EACnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EAGtB,KAAK,WAAW,EAEhB,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAO3B;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,WAAW,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC;AAElG;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;IACpD;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CACpB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,OAAO,EACb,WAAW,CAAC,EAAE,eAAe,KAC1B,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,SAAS,mBAAmB,EAC/D,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,EAChC,GAAG,EAAE,IAAI,GACR,IAAI,CA+DN;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,cAAc,CAAC,IAAI,SAAS,mBAAmB,EACnE,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,EAChC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,WAAW,EAAE,SAAS,OAAO,EAAE,EAC/B,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,IAAI,CAAC,CAyDf"}