ultracode-ai 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UltraCode Team / SIMO GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# ultracode-ai
+
+> Interactive AI code assistant for the terminal — with AI-powered versioning and release planning.
+
+Part of the [UltraCode AI](https://github.com/AndreasSchwan-SIMO/UltraCode) monorepo.
+
+## Installation
+
+```bash
+npm install -g ultracode-ai
+# or run ad hoc
+npx ultracode-ai
+```
+
+Requires Node.js `>=22.13.0`.
+
+## Usage
+
+```bash
+ultracode-ai            # start the interactive assistant
+ultracode-ai --help     # list commands and flags
+```
+
+The CLI bundles the agentic coding assistant (multiple LLM providers, a sandboxed
+tool layer, persistent sessions) together with the UltraCode AI versioning subsystem:
+it derives a SemVer bump from your Git diffs and commits, drafts a changelog and
+checks the configured release quality gates.
+
+## Packages
+
+- [`ultracode-core`](https://www.npmjs.com/package/ultracode-core) — agents, tools, memory, context, providers, config and AI versioning.
+- [`ultracode-shared`](https://www.npmjs.com/package/ultracode-shared) — shared types, contracts, errors and utilities.
+
+## License
+
+[MIT](./LICENSE) © UltraCode AI Team / SIMO GmbH

package/dist/commands/authoring-agents.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `ultracode agents create|evolve|test`
+ *
+ * Agent authoring commands backed by the facade's `authoring` sub-API
+ * (Module B). These extend the existing `agents list` group (registered by
+ * `./list.ts`) with proposal-generating subcommands. Generated agents never
+ * escalate tool permissions; `persist` is gated behind `--yes`.
+ *
+ * Material is supplied via `--file <material.json>` or inline
+ * `--topic`/`--catalog` flags (same convention as `skills create`).
+ */
+import type { Command } from "commander";
+import type { CliContext } from "../context.js";
+/**
+ * Register agent-authoring subcommands. Must be called AFTER
+ * `registerListCommands` so it attaches to the existing `agents` group.
+ */
+export declare function registerAuthoringAgentCommands(program: Command, ctx: CliContext): void;
+//# sourceMappingURL=authoring-agents.d.ts.map

package/dist/commands/authoring-agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authoring-agents.d.ts","sourceRoot":"","sources":["../../src/commands/authoring-agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAqGhD;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,UAAU,GAAG,IAAI,CAqCtF"}

package/dist/commands/authoring-agents.js

@@ -0,0 +1,123 @@
+/**
+ * `ultracode agents create|evolve|test`
+ *
+ * Agent authoring commands backed by the facade's `authoring` sub-API
+ * (Module B). These extend the existing `agents list` group (registered by
+ * `./list.ts`) with proposal-generating subcommands. Generated agents never
+ * escalate tool permissions; `persist` is gated behind `--yes`.
+ *
+ * Material is supplied via `--file <material.json>` or inline
+ * `--topic`/`--catalog` flags (same convention as `skills create`).
+ */
+import path from "node:path";
+import process from "node:process";
+import { promises as fs } from "node:fs";
+import { ValidationError } from "ultracode-shared";
+import { authoringOf, withExtFacade } from "./ext-helpers.js";
+import { formatBlock, formatTestResult } from "./ext-format.js";
+async function loadMaterial(ctx, opts) {
+    if (opts.file !== undefined) {
+        const target = path.resolve(ctx.cwd, opts.file);
+        let raw;
+        try {
+            raw = await fs.readFile(target, "utf8");
+        }
+        catch (cause) {
+            throw new ValidationError(`Cannot read material file: ${target}`, { cause });
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw.replace(/^/, ""));
+        }
+        catch (cause) {
+            throw new ValidationError(`Invalid JSON in material file: ${target}`, { cause });
+        }
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new ValidationError(`Material file must contain a JSON object: ${target}`);
+        }
+        return parsed;
+    }
+    if (opts.topic === undefined || opts.catalog === undefined) {
+        throw new ValidationError("Provide --file <material.json>, or both --topic and --catalog to create agent material inline.");
+    }
+    return {
+        catalog: opts.catalog,
+        topic: opts.topic,
+        summary: opts.summary ?? "",
+        facts: [],
+        codeSnippets: [],
+        sources: [],
+    };
+}
+function writeProposal(ctx, proposal, json) {
+    if (json) {
+        ctx.stdout.write(`${JSON.stringify(proposal)}\n`);
+        return;
+    }
+    ctx.stdout.write(`Proposal (${proposal.kind}): ${proposal.name}\n`);
+    ctx.stdout.write(formatBlock("Rationale", proposal.rationale));
+    if (proposal.diffFromExisting !== undefined) {
+        ctx.stdout.write(formatBlock("Diff", proposal.diffFromExisting));
+    }
+}
+/** Resolve the create/evolve method, failing clearly when core lacks it. */
+function agentMethod(authoring, which) {
+    const fn = which === "create" ? authoring.createAgent : authoring.evolveAgent;
+    if (typeof fn !== "function") {
+        throw new ValidationError(`Agent ${which} is not available in this build of ultracode-core.`);
+    }
+    return fn.bind(authoring);
+}
+async function proposeAgent(ctx, which, opts) {
+    await withExtFacade(ctx, async (facade) => {
+        const authoring = authoringOf(facade);
+        const material = await loadMaterial(ctx, opts);
+        const proposal = await agentMethod(authoring, which)(material);
+        writeProposal(ctx, proposal, opts.json === true);
+        if (opts.yes === true) {
+            await authoring.persist(proposal, { approved: true });
+            if (opts.json !== true)
+                ctx.stdout.write(`✓ agent "${proposal.name}" persisted\n`);
+        }
+        else if (opts.json !== true) {
+            ctx.stdout.write("Run again with --yes to persist this agent.\n");
+        }
+    });
+}
+const materialOptions = (cmd) => cmd
+    .option("--file <path>", "knowledge material JSON file")
+    .option("--topic <topic>", "agent topic (inline material)")
+    .option("--catalog <catalog>", "agent catalog (inline material)")
+    .option("--summary <text>", "agent summary (inline material)");
+/**
+ * Register agent-authoring subcommands. Must be called AFTER
+ * `registerListCommands` so it attaches to the existing `agents` group.
+ */
+export function registerAuthoringAgentCommands(program, ctx) {
+    const agents = program.commands.find((c) => c.name() === "agents") ??
+        program.command("agents").description("inspect and author agents");
+    materialOptions(agents
+        .command("create")
+        .description("create a new agent from knowledge material (proposal only unless --yes)"))
+        .option("--yes", "persist the proposal instead of only printing it")
+        .option("--json", "output as JSON")
+        .action(async (opts) => proposeAgent(ctx, "create", opts));
+    materialOptions(agents
+        .command("evolve")
+        .description("evolve an existing agent from new material (proposal only unless --yes)"))
+        .option("--yes", "persist the proposal instead of only printing it")
+        .option("--json", "output as JSON")
+        .action(async (opts) => proposeAgent(ctx, "evolve", opts));
+    materialOptions(agents.command("test").description("test an agent proposal built from material, without persisting"))
+        .option("--json", "output as JSON")
+        .action(async (opts) => withExtFacade(ctx, async (facade) => {
+        const authoring = authoringOf(facade);
+        const material = await loadMaterial(ctx, opts);
+        const proposal = await agentMethod(authoring, "create")(material);
+        const result = await authoring.test(proposal);
+        ctx.stdout.write(opts.json ? `${JSON.stringify(result)}\n` : formatTestResult(result));
+        if (!result.passed)
+            process.exitCode = 1;
+    }));
+}
+//# sourceMappingURL=authoring-agents.js.map

package/dist/commands/authoring-agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authoring-agents.js","sourceRoot":"","sources":["../../src/commands/authoring-agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,OAAO,MAAM,cAAc,CAAC;AACnC,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AAEzC,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAYhE,KAAK,UAAU,YAAY,CAAC,GAAe,EAAE,IAA0B;IACrE,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAChD,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC1C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,eAAe,CAAC,8BAA8B,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAC/E,CAAC;QACD,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAY,CAAC;QACxD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,eAAe,CAAC,kCAAkC,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QACnF,CAAC;QACD,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3E,MAAM,IAAI,eAAe,CAAC,6CAA6C,MAAM,EAAE,CAAC,CAAC;QACnF,CAAC;QACD,OAAO,MAA2B,CAAC;IACrC,CAAC;IACD,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAC3D,MAAM,IAAI,eAAe,CACvB,gGAAgG,CACjG,CAAC;IACJ,CAAC;IACD,OAAO;QACL,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,EAAE;QAC3B,KAAK,EAAE,EAAE;QACT,YAAY,EAAE,EAAE;QAChB,OAAO,EAAE,EAAE;KACZ,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,GAAe,EAAE,QAA2B,EAAE,IAAa;IAChF,IAAI,IAAI,EAAE,CAAC;QACT,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAClD,OAAO;IACT,CAAC;IACD,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,QAAQ,CAAC,IAAI,MAAM,QAAQ,CAAC,IAAI,IAAI,CAAC,CAAC;IACpE,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,WAAW,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;IAC/D,IAAI,QAAQ,CAAC,gBAAgB,KAAK,SAAS,EAAE,CAAC;QAC5C,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC;IACnE,CAAC;AACH,CAAC;AAED,4EAA4E;AAC5E,SAAS,WAAW,CAClB,SAA0B,EAC1B,KAA0B;IAE1B,MAAM,EAAE,GAAG,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,WAAW,CAAC;IAC9E,IAAI,OAAO,EAAE,KAAK,UAAU,EAAE,CAAC;QAC7B,MAAM,IAAI,eAAe,CACvB,SAAS,KAAK,oDAAoD,CACnE,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAC5B,CAAC;AAED,KAAK,UAAU,YAAY,CACzB,GAAe,EACf,KAA0B,EAC1B,IAA0B;IAE1B,MAAM,aAAa,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;QACxC,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;QACtC,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC/C,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC;QAC/D,aAAa,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;QACjD,IAAI,IAAI,CAAC,GAAG,KAAK,IAAI,EAAE,CAAC;YACtB,MAAM,SAAS,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;YACtD,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI;gBAAE,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,QAAQ,CAAC,IAAI,eAAe,CAAC,CAAC;QACrF,CAAC;aAAM,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YAC9B,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,+CAA+C,CAAC,CAAC;QACpE,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,eAAe,GAAG,CAAC,GAAY,EAAW,EAAE,CAChD,GAAG;KACA,MAAM,CAAC,eAAe,EAAE,8BAA8B,CAAC;KACvD,MAAM,CAAC,iBAAiB,EAAE,+BAA+B,CAAC;KAC1D,MAAM,CAAC,qBAAqB,EAAE,iCAAiC,CAAC;KAChE,MAAM,CAAC,kBAAkB,EAAE,iCAAiC,CAAC,CAAC;AAEnE;;;GAGG;AACH,MAAM,UAAU,8BAA8B,CAAC,OAAgB,EAAE,GAAe;IAC9E,MAAM,MAAM,GACV,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,QAAQ,CAAC;QACnD,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,CAAC,2BAA2B,CAAC,CAAC;IAErE,eAAe,CACb,MAAM;SACH,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,yEAAyE,CAAC,CAC1F;SACE,MAAM,CAAC,OAAO,EAAE,kDAAkD,CAAC;SACnE,MAAM,CAAC,QAAQ,EAAE,gBAAgB,CAAC;SAClC,MAAM,CAAC,KAAK,EAAE,IAA0B,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;IAEnF,eAAe,CACb,MAAM;SACH,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,yEAAyE,CAAC,CAC1F;SACE,MAAM,CAAC,OAAO,EAAE,kDAAkD,CAAC;SACnE,MAAM,CAAC,QAAQ,EAAE,gBAAgB,CAAC;SAClC,MAAM,CAAC,KAAK,EAAE,IAA0B,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;IAEnF,eAAe,CACb,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,WAAW,CAAC,gEAAgE,CAAC,CACrG;SACE,MAAM,CAAC,QAAQ,EAAE,gBAAgB,CAAC;SAClC,MAAM,CAAC,KAAK,EAAE,IAA0B,EAAE,EAAE,CAC3C,aAAa,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;QAClC,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;QACtC,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC/C,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,CAAC;QAClE,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC9C,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC;QACvF,IAAI,CAAC,MAAM,CAAC,MAAM;YAAE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IAC3C,CAAC,CAAC,CACH,CAAC;AACN,CAAC"}

package/dist/commands/budget.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `ultracode budget plan|show|set|status|history`
+ *
+ * Cost-control commands backed by the facade's `budget` sub-API (Module A).
+ * - `budget show` / `budget status` print the current spend snapshot.
+ * - `budget plan` installs/reads a plan (interactive answers via `--cap`/`--threshold`).
+ * - `budget set <file>` loads a plan from a JSON file.
+ * - `budget history [--limit n]` prints the ledger.
+ *
+ * Every subcommand supports `--json` for machine-readable output.
+ */
+import type { Command } from "commander";
+import type { CliContext } from "../context.js";
+/** Register the `budget` command group on `program`. */
+export declare function registerBudgetCommands(program: Command, ctx: CliContext): void;
+//# sourceMappingURL=budget.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../src/commands/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAyBhD,wDAAwD;AACxD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,UAAU,GAAG,IAAI,CA0F9E"}

package/dist/commands/budget.js

@@ -0,0 +1,105 @@
+/**
+ * `ultracode budget plan|show|set|status|history`
+ *
+ * Cost-control commands backed by the facade's `budget` sub-API (Module A).
+ * - `budget show` / `budget status` print the current spend snapshot.
+ * - `budget plan` installs/reads a plan (interactive answers via `--cap`/`--threshold`).
+ * - `budget set <file>` loads a plan from a JSON file.
+ * - `budget history [--limit n]` prints the ledger.
+ *
+ * Every subcommand supports `--json` for machine-readable output.
+ */
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { ValidationError } from "ultracode-shared";
+import { budgetOf, withExtFacade } from "./ext-helpers.js";
+import { formatBudgetStatus, formatLedger } from "./ext-format.js";
+/** Parse a numeric CLI option, throwing {@link ValidationError} when invalid. */
+function parseNumber(raw, label) {
+    const n = Number(raw);
+    if (!Number.isFinite(n))
+        throw new ValidationError(`${label} must be a finite number, got "${raw}"`);
+    return n;
+}
+/** Register the `budget` command group on `program`. */
+export function registerBudgetCommands(program, ctx) {
+    const budget = program.command("budget").description("cost control: plan, status and spend history");
+    const showAction = async (opts) => withExtFacade(ctx, async (facade) => {
+        const status = await budgetOf(facade).status();
+        ctx.stdout.write(opts.json ? `${JSON.stringify(status)}\n` : formatBudgetStatus(status));
+    });
+    budget
+        .command("show")
+        .description("print the current budget status (spend, cap, remaining)")
+        .option("--json", "output as JSON")
+        .action(showAction);
+    budget
+        .command("status")
+        .description("alias of `budget show`")
+        .option("--json", "output as JSON")
+        .action(showAction);
+    budget
+        .command("plan")
+        .description("install or read the budget plan (caps / approval threshold)")
+        .option("--cap <usd>", "monthly USD cap (omit for no cap)")
+        .option("--threshold <usd>", "USD value above which a run requires approval")
+        .option("--json", "output as JSON")
+        .action(async (opts) => withExtFacade(ctx, async (facade) => {
+        const answers = {};
+        if (opts.cap !== undefined)
+            answers["capUsd"] = parseNumber(opts.cap, "--cap");
+        if (opts.threshold !== undefined) {
+            answers["approvalThresholdUsd"] = parseNumber(opts.threshold, "--threshold");
+        }
+        const plan = await budgetOf(facade).plan(Object.keys(answers).length > 0 ? answers : undefined);
+        if (Object.keys(answers).length > 0) {
+            await budgetOf(facade).setPlan(plan);
+        }
+        if (opts.json) {
+            ctx.stdout.write(`${JSON.stringify(plan)}\n`);
+        }
+        else {
+            ctx.stdout.write(`Budget Plan\n  Cap: ${plan.capUsd === null ? "(none)" : `$${plan.capUsd}`}\n`);
+            if (plan.approvalThresholdUsd !== undefined) {
+                ctx.stdout.write(`  Approval threshold: $${plan.approvalThresholdUsd}\n`);
+            }
+        }
+    }));
+    budget
+        .command("set")
+        .description("load and persist a budget plan from a JSON file")
+        .argument("<file>", "JSON file describing a BudgetPlan")
+        .action(async (file) => withExtFacade(ctx, async (facade) => {
+        const target = path.resolve(ctx.cwd, file);
+        let raw;
+        try {
+            raw = await fs.readFile(target, "utf8");
+        }
+        catch (cause) {
+            throw new ValidationError(`Cannot read budget plan file: ${target}`, { cause });
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw.replace(/^/, ""));
+        }
+        catch (cause) {
+            throw new ValidationError(`Invalid JSON in budget plan file: ${target}`, { cause });
+        }
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new ValidationError(`Budget plan file must contain a JSON object: ${target}`);
+        }
+        await budgetOf(facade).setPlan(parsed);
+        ctx.stdout.write(`✓ budget plan loaded from ${target}\n`);
+    }));
+    budget
+        .command("history")
+        .description("print the spend ledger (estimated vs. actual)")
+        .option("--limit <n>", "maximum number of entries to show")
+        .option("--json", "output as JSON")
+        .action(async (opts) => withExtFacade(ctx, async (facade) => {
+        const limit = opts.limit !== undefined ? parseNumber(opts.limit, "--limit") : undefined;
+        const entries = await budgetOf(facade).history(limit);
+        ctx.stdout.write(opts.json ? `${JSON.stringify(entries)}\n` : formatLedger(entries));
+    }));
+}
+//# sourceMappingURL=budget.js.map

package/dist/commands/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../src/commands/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AAEzC,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAgBnE,iFAAiF;AACjF,SAAS,WAAW,CAAC,GAAW,EAAE,KAAa;IAC7C,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACtB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,MAAM,IAAI,eAAe,CAAC,GAAG,KAAK,kCAAkC,GAAG,GAAG,CAAC,CAAC;IACrG,OAAO,CAAC,CAAC;AACX,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,sBAAsB,CAAC,OAAgB,EAAE,GAAe;IACtE,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,CAAC,8CAA8C,CAAC,CAAC;IAErG,MAAM,UAAU,GAAG,KAAK,EAAE,IAAgB,EAAiB,EAAE,CAC3D,aAAa,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;QAClC,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC;QAC/C,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3F,CAAC,CAAC,CAAC;IAEL,MAAM;SACH,OAAO,CAAC,MAAM,CAAC;SACf,WAAW,CAAC,yDAAyD,CAAC;SACtE,MAAM,CAAC,QAAQ,EAAE,gBAAgB,CAAC;SAClC,MAAM,CAAC,UAAU,CAAC,CAAC;IAEtB,MAAM;SACH,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,wBAAwB,CAAC;SACrC,MAAM,CAAC,QAAQ,EAAE,gBAAgB,CAAC;SAClC,MAAM,CAAC,UAAU,CAAC,CAAC;IAEtB,MAAM;SACH,OAAO,CAAC,MAAM,CAAC;SACf,WAAW,CAAC,6DAA6D,CAAC;SAC1E,MAAM,CAAC,aAAa,EAAE,mCAAmC,CAAC;SAC1D,MAAM,CAAC,mBAAmB,EAAE,+CAA+C,CAAC;SAC5E,MAAM,CAAC,QAAQ,EAAE,gBAAgB,CAAC;SAClC,MAAM,CAAC,KAAK,EAAE,IAAiB,EAAE,EAAE,CAClC,aAAa,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;QAClC,MAAM,OAAO,GAA4B,EAAE,CAAC;QAC5C,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS;YAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC/E,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YACjC,OAAO,CAAC,sBAAsB,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;QAC/E,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,CACtC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CACtD,CAAC;QACF,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpC,MAAM,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACvC,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChD,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,uBAAuB,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YACjG,IAAI,IAAI,CAAC,oBAAoB,KAAK,SAAS,EAAE,CAAC;gBAC5C,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,0BAA0B,IAAI,CAAC,oBAAoB,IAAI,CAAC,CAAC;YAC5E,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CACH,CAAC;IAEJ,MAAM;SACH,OAAO,CAAC,KAAK,CAAC;SACd,WAAW,CAAC,iDAAiD,CAAC;SAC9D,QAAQ,CAAC,QAAQ,EAAE,mCAAmC,CAAC;SACvD,MAAM,CAAC,KAAK,EAAE,IAAY,EAAE,EAAE,CAC7B,aAAa,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;QAClC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC3C,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC1C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,eAAe,CAAC,iCAAiC,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAClF,CAAC;QACD,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAY,CAAC;QACxD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,eAAe,CAAC,qCAAqC,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QACtF,CAAC;QACD,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3E,MAAM,IAAI,eAAe,CAAC,gDAAgD,MAAM,EAAE,CAAC,CAAC;QACtF,CAAC;QACD,MAAM,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,MAAwB,CAAC,CAAC;QACzD,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,6BAA6B,MAAM,IAAI,CAAC,CAAC;IAC5D,CAAC,CAAC,CACH,CAAC;IAEJ,MAAM;SACH,OAAO,CAAC,SAAS,CAAC;SAClB,WAAW,CAAC,+CAA+C,CAAC;SAC5D,MAAM,CAAC,aAAa,EAAE,mCAAmC,CAAC;SAC1D,MAAM,CAAC,QAAQ,EAAE,gBAAgB,CAAC;SAClC,MAAM,CAAC,KAAK,EAAE,IAAoB,EAAE,EAAE,CACrC,aAAa,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;QAClC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACxF,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACtD,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IACvF,CAAC,CAAC,CACH,CAAC;AACN,CAAC"}

package/dist/commands/config.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `ultracode config show|get|set|validate|export|import`
+ *
+ * Configuration inspection and modification through the UltraCode facade.
+ * Mutating subcommands (`set`, `import`) require the optional `configManager`
+ * exposed by the facade (ConfigManager semantics: `set(path, value)` +
+ * `save("user")`); without it they fail with a clear {@link ConfigError}.
+ * `show` prefers core's redacted view and falls back to a local key-masking
+ * redaction so secrets are never printed.
+ */
+import type { Command } from "commander";
+import type { CliContext } from "../context.js";
+/** Register the `config` command group on `program`. */
+export declare function registerConfigCommand(program: Command, ctx: CliContext): void;
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/commands/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,UAAU,EAAmB,MAAM,eAAe,CAAC;AAsCjE,wDAAwD;AACxD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,UAAU,GAAG,IAAI,CAwH7E"}

package/dist/commands/config.js

@@ -0,0 +1,147 @@
+/**
+ * `ultracode config show|get|set|validate|export|import`
+ *
+ * Configuration inspection and modification through the UltraCode facade.
+ * Mutating subcommands (`set`, `import`) require the optional `configManager`
+ * exposed by the facade (ConfigManager semantics: `set(path, value)` +
+ * `save("user")`); without it they fail with a clear {@link ConfigError}.
+ * `show` prefers core's redacted view and falls back to a local key-masking
+ * redaction so secrets are never printed.
+ */
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { ConfigError, isPlainObject } from "ultracode-shared";
+import { safeDispose } from "../context.js";
+import { flattenLeaves, getAtPath, parseCliValue, redactConfig } from "../utils/text.js";
+/** Run `fn` against a fresh facade, always disposing it afterwards. */
+async function withFacade(ctx, fn) {
+    const facade = await ctx.createFacade({ cwd: ctx.cwd });
+    try {
+        return await fn(facade);
+    }
+    finally {
+        await safeDispose(facade);
+    }
+}
+function requireManager(facade) {
+    const manager = facade.configManager;
+    if (!manager || typeof manager.set !== "function" || typeof manager.save !== "function") {
+        throw new ConfigError("Modifying configuration requires the ConfigManager, which this build of ultracode-core does not expose. " +
+            "Edit ~/.ultracode/config.toml manually instead.");
+    }
+    return manager;
+}
+function redactedView(facade) {
+    const manager = facade.configManager;
+    if (manager && typeof manager.redacted === "function")
+        return manager.redacted();
+    return redactConfig(facade.config);
+}
+/** Register the `config` command group on `program`. */
+export function registerConfigCommand(program, ctx) {
+    const config = program.command("config").description("inspect and modify the configuration");
+    config
+        .command("show")
+        .description("print the resolved configuration (secrets masked)")
+        .option("--json", "output as JSON")
+        .action(async (opts) => withFacade(ctx, async (facade) => {
+        const view = redactedView(facade);
+        if (opts.json) {
+            ctx.stdout.write(`${JSON.stringify(view)}\n`);
+            return;
+        }
+        const flat = isPlainObject(view)
+            ? flattenLeaves(view)
+            : [["config", view]];
+        for (const [key, value] of flat) {
+            ctx.stdout.write(`${key} = ${JSON.stringify(value)}\n`);
+        }
+    }));
+    config
+        .command("get")
+        .description("print a single configuration value by dotted path")
+        .argument("<path>", 'dotted config path, e.g. "core.activeModel"')
+        .option("--json", "output as JSON ({ path, value })")
+        .action(async (dotted, opts) => withFacade(ctx, async (facade) => {
+        const manager = facade.configManager;
+        const value = manager && typeof manager.get === "function"
+            ? manager.get(dotted)
+            : getAtPath(facade.config, dotted);
+        if (value === undefined) {
+            throw new ConfigError(`Unknown config path: "${dotted}"`);
+        }
+        if (opts.json) {
+            ctx.stdout.write(`${JSON.stringify({ path: dotted, value })}\n`);
+        }
+        else {
+            ctx.stdout.write(`${typeof value === "string" ? value : JSON.stringify(value)}\n`);
+        }
+    }));
+    config
+        .command("set")
+        .description("set a configuration value and persist it to the user layer")
+        .argument("<path>", 'dotted config path, e.g. "ui.theme"')
+        .argument("<value>", "new value (JSON literals are parsed, otherwise string)")
+        .action(async (dotted, raw) => withFacade(ctx, async (facade) => {
+        const manager = requireManager(facade);
+        const value = parseCliValue(raw);
+        manager.set(dotted, value);
+        await manager.save("user");
+        ctx.stdout.write(`✓ ${dotted} = ${JSON.stringify(value)} (saved to user config)\n`);
+    }));
+    config
+        .command("validate")
+        .description("validate the resolved configuration")
+        .action(async () => withFacade(ctx, async (facade) => {
+        const manager = facade.configManager;
+        if (manager && typeof manager.validate === "function")
+            manager.validate();
+        ctx.stdout.write("✓ configuration is valid\n");
+    }));
+    config
+        .command("export")
+        .description("export the resolved configuration as JSON (stdout or file)")
+        .argument("[file]", "target file; prints to stdout when omitted")
+        .action(async (file) => withFacade(ctx, async (facade) => {
+        const json = JSON.stringify(facade.config, null, 2);
+        if (file === undefined) {
+            ctx.stdout.write(`${json}\n`);
+            return;
+        }
+        const target = path.resolve(ctx.cwd, file);
+        await fs.writeFile(target, `${json}\n`, "utf8");
+        ctx.stdout.write(`✓ configuration exported to ${target}\n`);
+    }));
+    config
+        .command("import")
+        .description("import configuration overrides from a JSON file into the user layer")
+        .argument("<file>", "JSON file produced by `config export` (or compatible)")
+        .action(async (file) => withFacade(ctx, async (facade) => {
+        const manager = requireManager(facade);
+        const target = path.resolve(ctx.cwd, file);
+        let raw;
+        try {
+            raw = await fs.readFile(target, "utf8");
+        }
+        catch (cause) {
+            throw new ConfigError(`Cannot read config file: ${target}`, { cause });
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw.replace(/^\uFEFF/, ""));
+        }
+        catch (cause) {
+            throw new ConfigError(`Invalid JSON in config file: ${target}`, { cause });
+        }
+        if (!isPlainObject(parsed)) {
+            throw new ConfigError(`Config file must contain a JSON object: ${target}`);
+        }
+        const leaves = flattenLeaves(parsed);
+        for (const [key, value] of leaves) {
+            manager.set(key, value);
+        }
+        await manager.save("user");
+        ctx.stdout.write(`✓ imported ${leaves.length} value(s) from ${target} (saved to user config)\n`);
+    }));
+}
+//# sourceMappingURL=config.js.map

package/dist/commands/config.js.map

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

package/dist/commands/doctor.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `ultracode doctor [--json]`
+ *
+ * Fully offline environment check: Node version, git availability, config
+ * directory writability, config validity, API-key presence (masked — the key
+ * value is never printed) and terminal capabilities. Critical failures set
+ * exit code 1.
+ */
+import type { Command } from "commander";
+import type { CliContext } from "../context.js";
+/** Result of a single doctor check. */
+export interface DoctorCheck {
+    /** Stable check identifier. */
+    name: string;
+    /** Whether the check passed. */
+    ok: boolean;
+    /** Whether a failure of this check is fatal (drives the exit code). */
+    critical: boolean;
+    /** Human-readable detail (secrets always masked). */
+    detail: string;
+}
+/** Aggregated doctor report. `ok` is false iff a *critical* check failed. */
+export interface DoctorReport {
+    ok: boolean;
+    checks: DoctorCheck[];
+}
+/** Injectable dependencies for {@link collectDoctorReport} (offline by design). */
+export interface DoctorDeps {
+    /** Node.js version string, e.g. `"20.11.1"`. */
+    nodeVersion: string;
+    /** Environment snapshot for API-key/colour checks. */
+    env: NodeJS.ProcessEnv;
+    /** Whether stdout is an interactive terminal. */
+    isTTY: boolean;
+    /** Resolve `git --version`, `null` when git is missing. */
+    gitVersion(): Promise<string | null>;
+    /** Resolved user config directory. */
+    configDir: string;
+    /** Probe write access; resolves `true` or an error description. */
+    checkWritable(dir: string): Promise<true | string>;
+    /** Load + validate the configuration (throws on failure). */
+    loadConfig(): Promise<void>;
+}
+/** Environment variables checked for API-key presence. */
+export declare const API_KEY_VARS: readonly ["MISTRAL_API_KEY", "ANTHROPIC_API_KEY", "OPENAI_API_KEY", "ULTRACODE_API_KEY"];
+/** Minimum supported Node.js major version. */
+export declare const MIN_NODE_MAJOR = 22;
+/**
+ * Minimum supported Node.js minor version *within* {@link MIN_NODE_MAJOR}.
+ * A newer major satisfies the requirement regardless of its minor; only the
+ * boundary major is gated on this minor. Mirrors the `engines.node`
+ * (`>=22.13.0`) declared by every workspace package.
+ */
+export declare const MIN_NODE_MINOR = 13;
+/** Default writability probe: mkdir -p, then create + delete a marker file. */
+export declare function defaultCheckWritable(dir: string): Promise<true | string>;
+/** Build the production {@link DoctorDeps} from a {@link CliContext}. */
+export declare function makeDefaultDoctorDeps(ctx: CliContext): DoctorDeps;
+/** Run all doctor checks. Never throws — failures become `ok: false` checks. */
+export declare function collectDoctorReport(deps: DoctorDeps): Promise<DoctorReport>;
+/** Render a {@link DoctorReport} as a ✓/✗ checklist. */
+export declare function renderDoctorReport(report: DoctorReport): string;
+/** Register the `doctor` command on `program`. */
+export declare function registerDoctorCommand(program: Command, ctx: CliContext): void;
+//# sourceMappingURL=doctor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAKhD,uCAAuC;AACvC,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,uEAAuE;IACvE,QAAQ,EAAE,OAAO,CAAC;IAClB,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAED,mFAAmF;AACnF,MAAM,WAAW,UAAU;IACzB,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,iDAAiD;IACjD,KAAK,EAAE,OAAO,CAAC;IACf,2DAA2D;IAC3D,UAAU,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACrC,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,MAAM,CAAC,CAAC;IACnD,6DAA6D;IAC7D,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED,0DAA0D;AAC1D,eAAO,MAAM,YAAY,0FAKf,CAAC;AAEX,+CAA+C;AAC/C,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC,+EAA+E;AAC/E,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,MAAM,CAAC,CAU9E;AAED,yEAAyE;AACzE,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,UAAU,GAAG,UAAU,CAajE;AAED,gFAAgF;AAChF,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC,CAuGjF;AAED,wDAAwD;AACxD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAO/D;AAED,kDAAkD;AAClD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,UAAU,GAAG,IAAI,CAc7E"}