@cuna_labs/cli 0.1.0

package/dist/cli/help.js

@@ -0,0 +1,256 @@
+import { exitCodeHelpSection } from "../core/exit-codes.js";
+import { brandedEnvironmentNames } from "../core/namespace.js";
+import { API_KEYS_URL } from "../core/product-web.js";
+import { CLI_ROUTE_REGISTRY } from "./parser.js";
+// Help is the only place most users learn a variable name, so it is derived
+// from the same authority the resolver reads. A hand-written name here would go
+// stale exactly when the accepted set changes, which is the one moment it must
+// not.
+const API_KEY_NAMES = brandedEnvironmentNames("API_KEY").join(" or ");
+// Same reason, one layer up: the exit code is the entire contract for a caller
+// that is not a human, so the list below is projected from `EXIT_CODES` rather
+// than typed out beside it. A hand-written copy here would have kept printing
+// `7` for an unserved operation after that case moved to `8`.
+const EXIT_CODES_SECTION = exitCodeHelpSection();
+/**
+ * What a newcomer sees from bare `cuna` and from `cuna --help`.
+ *
+ * WHY THIS EXISTS. The full surface below is 105 lines, 23 of them an exit-code
+ * table, and the first usable command appears on line 9. Measured on the same
+ * build: the whole of `cuna --help` contained ZERO `http(s)://` matches, so a
+ * user who needs browser sign-in still needs a safe browser-link next
+ * step rather than a platform-specific promise.
+ *
+ * NOTHING WAS DELETED. Every line that used to be here is still in `FULL_HELP`,
+ * reachable as `cuna help --all`, and `cuna <command> --help` is untouched.
+ *
+ * THE UNAVAILABILITY CLAIMS BELOW ARE MEASURED FROM THIS TREE, not guessed, and
+ * they are deliberately stated as properties of the BUILD rather than of a
+ * platform:
+ *
+ *   - interactive commands use the pure-JavaScript encrypted browser-link
+ *     session store. Alternative credential backends are deliberately absent
+ *     from the distributable package, rather than present as an inactive fallback.
+ *   - the automatic journey and exact foreground attach are composed by
+ *     `runCli` before the generic command dispatcher. Their local
+ *     implementation is present, while each invocation still fails closed
+ *     unless the live producer proves the required capabilities and state.
+ *
+ * What is NOT claimed here: that browser sign-in is currently enabled by every
+ * configured deployment. `cuna doctor` measures local encrypted storage, and
+ * its opt-in remote probe measures the browser-login bootstrap separately.
+ */
+const PROVIDER_LABELS = Object.freeze({
+    claude: "Open Claude Code in a machine",
+    codex: "Open Codex in a machine",
+    opencode: "Open OpenCode in a machine",
+});
+const CURRENT_PROVIDER_COMMANDS = Object.freeze(CLI_ROUTE_REGISTRY
+    .map((route) => route.key)
+    .filter((key) => Object.hasOwn(PROVIDER_LABELS, key)));
+/** Commands printed by first-run help, ending in the guided root journey. */
+export const FIRST_RUN_TRANSCRIPT = Object.freeze([
+    Object.freeze(["login"]),
+    Object.freeze([]),
+]);
+/**
+ * Render primary discovery as the intersection of this build's provider routes
+ * and the caller's set.
+ *
+ * WHAT THE DEFAULT MEANS. Help is rendered offline, before any credential or
+ * capability request, so the only authority available to it is this build's
+ * route registry. The default therefore lists every ROUTED provider and makes
+ * no claim at all about what the server currently serves. It is not a
+ * capability filter, and the earlier comment here claimed it was one: it said
+ * this call "keeps OpenCode hidden until both halves actually exist" while
+ * production's only call site is `renderShortHelp()` with no argument, whose
+ * default is derived from the same registry it filters — a tautology that
+ * could never hide anything.
+ *
+ * The parameter is still real, and narrower than the default: a caller holding
+ * a live capability snapshot may pass the subset it proves. Nothing in this
+ * package does that today.
+ */
+export function renderShortHelp(routedProviderCommands = CURRENT_PROVIDER_COMMANDS) {
+    const routed = new Set(routedProviderCommands);
+    const providerLines = CURRENT_PROVIDER_COMMANDS
+        .filter((command) => routed.has(command))
+        .map((command) => `  cuna ${command} [PATH]${" ".repeat(Math.max(1, 18 - command.length))}${PROVIDER_LABELS[command]}`)
+        .join("\n");
+    return `Cuna CLI
+
+Open a machine, pick an agent, keep working.
+
+Start here:
+  cuna                    Choose a machine, agent, and session
+  cuna machines           Browse machines and the sessions inside them
+${providerLines}
+
+First run:
+  1. Run \`cuna login\`, approve in the browser, and paste the displayed login code
+  2. Run \`cuna\` to enter an attached provider terminal
+
+Diagnose this installation:
+  cuna doctor                Report platform, runtime, and encrypted local session-store state
+  cuna version               Show the CLI version, build digest, and protocol range
+  cuna config get            Show effective, redacted configuration
+  cuna self-test --offline   Verify the installed CLI without network access
+
+Advanced and automation:
+  cuna help --all          Every command, option, and exit code
+  cuna <command> --help    Help for one command
+`;
+}
+export const SHORT_HELP = renderShortHelp();
+/**
+ * The marker legend, printed immediately above the reference.
+ *
+ * Without it the bracketed word reads as a status, and a status is exactly what
+ * this CLI cannot know before it asks. Naming the authority in the same breath
+ * is the whole repair.
+ */
+export const COMMAND_REFERENCE_LEGEND = `  [routed]   this build dispatches the command
+  [reserved] this build accepts the name and refuses
+  Neither marker is a server answer. Run \`cuna capabilities\` for what the
+  server currently proves for your account, machine, or AgentSession.
+`;
+/** One generated line per semantic parser route; tests parse these markers. */
+export const COMPLETE_COMMAND_REFERENCE = CLI_ROUTE_REGISTRY
+    .map((route) => `  [${route.dispatch}] ${route.key} :: cuna ${route.syntax}\n      ${route.summary}`)
+    .join("\n");
+export const FULL_HELP = `Cuna CLI
+
+Run cloud development agents from your local command line through public Cuna contracts.
+
+Usage:
+  cuna <command> [options]
+
+Available now:
+  signup                               Create a waitlist-only Cuna account in the browser
+  login                                Sign in through the browser and paste the durable login code
+  whoami                               Show account context; reuse the encrypted session
+  access status                        Print the same line whoami prints, as record access.status
+  logout                               Revoke the login-code family server-first;
+                                       reuse the encrypted session automatically
+  capabilities                         Inspect current server capability truth
+  machines                             Browse machines and their AgentSessions
+  machines list                        List owned Cuna machines
+  machines create [options]            Create a machine when server-advertised
+  machines start|pause|resume|stop ID  Change lifecycle when server-advertised
+  machines update-supervisor ID        Update a stopped OpenCode terminal supervisor
+  machines live-update-supervisor ID   Update a running terminal supervisor in place;
+                                       reports one custody line per AgentSession
+  machines live-update-status ID       Read what one in-place update did; sends nothing
+  machines delete ID                   Delete when server-advertised
+  records list                         List redacted account activity records
+  account show                         Show the public account identity
+  observe --project PROJECT_ID         Observe an authorized shared session read-only
+  share --project PROJECT_ID           Grant or revoke a member's read-only view, and start or stop live sharing
+  workspace show                       Show assignment or waitlist state
+  usage show                           Show authoritative workspace estimates
+  authorizations list --machine ID     List active credential injection rules
+  api-keys create --name NAME --yes    Create an API key and print its secret once
+  api-keys list                        List API-key metadata without secret values
+  api-keys revoke ID --yes             Revoke one API key when server-advertised
+  agent-sessions list --machine ID     List child agent processes
+  agent-sessions create --machine ID --workspace-binding-id ID --workspace-generation N
+                                       Create a workspace-bound child when server-advertised
+  agent-sessions get ID                Read one child process
+  agent-sessions rename ID --name NAME Rename one child process
+  agent-sessions terminate ID          Terminate when server-advertised
+  config get                           Show effective, redacted configuration
+  self-test --offline                  Verify the installed CLI without network access
+  doctor                               Report platform, runtime, and encrypted local session-store state
+
+Foreground terminal attach (the server must grant terminal_connections.create):
+  connect SESSION_ID [SESSION_ID...]   Attach 1-4 exact cloud sessions in this terminal
+  agent-sessions attach SESSION_ID     Attach one exact cloud session in this terminal
+  agent logout --agent-session ID      Sign Claude Code or Codex out of one exact AgentSession
+  claude --agent-session SESSION_ID    Attach one exact Claude Code child
+  codex --agent-session SESSION_ID     Attach one exact Codex child
+  opencode --agent-session SESSION_ID  Attach one exact OpenCode child
+  These routes exist in this build. That is the whole of what the [routed]
+  marker in the complete reference below claims about them.
+  Each invocation still re-reads an AgentSession-scoped capability snapshot and
+  refuses, changing nothing, when the server does not grant
+  terminal_connections.create for that exact session. \`cuna capabilities --scope
+  agent_session --resource-id ID\` shows the same answer before you attach.
+  JSON and redirected output fail closed. Nested SSH/tmux and TERM=dumb use a
+  one-session byte-preserving plain fallback with no appbar; set
+  CUNA_TERMINAL_MODE=plain for accessibility or diagnosis.
+  Ctrl+C detaches locally in one press. Use Ctrl+] c to send Ctrl+C to the agent.
+  Background daemon and local companion behavior are absent from this build.
+
+Automatic local-to-cloud journey:
+  claude [PATH] [--machine NAME | --new] [--no-sync] [--new-session]
+         [--auth-mode interactive_login|credential_binding]
+         [--credential-binding ID]
+  codex [PATH] [--machine NAME | --new] [--no-sync] [--new-session]
+        [--auth-mode interactive_login|credential_binding]
+        [--credential-binding ID]
+  opencode [PATH] [--machine NAME | --new] [--no-sync] [--new-session]
+           [--auth-mode interactive_login]
+  Cuna validates the complete command before effects, selects only from fresh
+  machine capability evidence, reconciles creation by a caller-known request ID,
+  binds and synchronizes the exact workspace generation, selects or creates one
+  exact AgentSession, waits for child readiness, and then attaches this terminal.
+  Ambiguous, stale, cancelled, or unknown outcomes fail closed without silently
+  choosing a target or retrying with a second identity.
+  --credential-binding ID is required exactly when --auth-mode is credential_binding.
+  OpenCode is interactive-only: after Cuna attaches its remote terminal, use
+  /connect to choose and sign in to a provider, then /models to choose a model.
+  Cuna does not broker an OpenCode device-sign-in page. Provider credentials remain
+  in that AgentSession and are never copied from Codex or another provider store.
+  Use --agent-session SESSION_ID to bypass reconciliation and attach one exact child;
+  it cannot be combined with PATH, --machine, --new, --new-session, --no-sync,
+  --auth-mode, or --credential-binding.
+
+Reserved and fail-closed in this build:
+  shell, background daemon, local companion
+
+Complete command reference:
+${COMMAND_REFERENCE_LEGEND}
+${COMPLETE_COMMAND_REFERENCE}
+
+Compatibility aliases (advanced only):
+  cuna --help             Alias for primary help
+  cuna --help --all       Alias for complete help
+  cuna --version          Alias for cuna version
+
+Global options:
+  --json              Emit versioned JSON records
+  --profile NAME      Select one user profile
+  --base-url URL      Override the API origin (custom origins require a development profile)
+  --config-file PATH  Select the user configuration file
+  --timeout-ms N      Bound each API request (100..120000)
+  --no-color          Disable color (output is color-independent by default)
+  --help              Show help (add it after any command for that command's help)
+  --version           Show the CLI version
+
+Exit codes:
+${EXIT_CODES_SECTION}
+  This is the complete set this build can return. One reachable path per code is
+  documented under "Exit codes" in the README.
+
+Authentication:
+  Create an automation credential at ${API_KEYS_URL}.
+  Use cuna signup for waitlist-only enrollment. It never assigns compute or starts billing.
+  Use cuna login for a browser-assisted interactive session. The CLI opens the
+  browser flow, then exchanges the pasted code immediately; it does not open a local callback listener. Paste the exact high-entropy
+  cuna_login_ code shown once by the page. Cuna stores it using AES-256-GCM with
+  a separate user-only key file and exchanges it for short-lived access in each
+  process. Compromise of the same OS account can read both files and defeats this layer.
+  ${API_KEY_NAMES} selects explicit automation mode and never falls
+  back to browser login. Both spellings are accepted and both admit every key brand the
+  service has issued; the first one that is SET wins, even when its value is unusable.
+
+Canonical install:
+  npm install --global ./cuna_labs-cli-0.1.0.tgz
+`;
+/**
+ * The root topic. Bare \`cuna\` and \`cuna --help\` answer with the short
+ * orientation; \`cuna help --all\` and \`cuna --help --all\` answer with the
+ * complete surface. Per-command help is unaffected.
+ */
+export const ROOT_HELP = SHORT_HELP;
+//# sourceMappingURL=help.js.map

package/dist/cli/help.js.map

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

package/dist/cli/output.d.ts

@@ -0,0 +1,28 @@
+import type { Writable } from "node:stream";
+import type { CunaError } from "../core/errors.js";
+export interface CliStreams {
+    readonly stdout: Writable;
+    readonly stderr: Writable;
+    readonly stdoutIsTTY: boolean;
+    readonly stdinIsTTY: boolean;
+    /** Optional because injected test streams predate the preview link gate. */
+    readonly stderrIsTTY?: boolean;
+}
+export interface OutputWriter {
+    readonly structured: boolean;
+    success(command: string, data: unknown, human: string): void;
+    error(command: string, error: CunaError): void;
+    text(value: string): void;
+}
+/**
+ * Human terminal output is a trust boundary. Preserve only the two layout
+ * controls emitted deliberately by Cuna; render every other C0/C1/Unicode
+ * format control visibly so API data and error text cannot execute ANSI/OSC,
+ * alter the title/clipboard, or spoof text direction.
+ */
+export declare function sanitizeHumanTerminalOutput(value: string): string;
+export declare function createOutputWriter(input: {
+    readonly streams: CliStreams;
+    readonly json: boolean;
+}): OutputWriter;
+//# sourceMappingURL=output.d.ts.map

package/dist/cli/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/cli/output.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,KAAK,EAAE,SAAS,EAAmB,MAAM,mBAAmB,CAAC;AAIpE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IAC/C,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAMD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAqBjE;AAwBD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB,GAAG,YAAY,CA8Cf"}

package/dist/cli/output.js

@@ -0,0 +1,95 @@
+import { containsCredentialValue } from "../core/namespace.js";
+import { OUTPUT_SCHEMA_VERSION } from "../version.js";
+function writeLine(stream, value) {
+    stream.write(value.endsWith("\n") ? value : `${value}\n`);
+}
+/**
+ * Human terminal output is a trust boundary. Preserve only the two layout
+ * controls emitted deliberately by Cuna; render every other C0/C1/Unicode
+ * format control visibly so API data and error text cannot execute ANSI/OSC,
+ * alter the title/clipboard, or spoof text direction.
+ */
+export function sanitizeHumanTerminalOutput(value) {
+    let result = "";
+    for (const character of value) {
+        if (character === "\n" || character === "\t") {
+            result += character;
+            continue;
+        }
+        const codePoint = character.codePointAt(0) ?? 0;
+        if (codePoint <= 0x1f ||
+            (codePoint >= 0x7f && codePoint <= 0x9f) ||
+            /\p{Cf}/u.test(character)) {
+            result += codePoint <= 0xff
+                ? `\\x${codePoint.toString(16).padStart(2, "0")}`
+                : `\\u{${codePoint.toString(16)}}`;
+            continue;
+        }
+        result += character;
+    }
+    return result;
+}
+function sanitizeSingleLineHumanOutput(value) {
+    return sanitizeHumanTerminalOutput(value).replaceAll("\n", "\\n").replaceAll("\t", "\\t");
+}
+/**
+ * Render one `details` entry for a human terminal.
+ *
+ * `details` distinguishes failures that otherwise print identically: thirteen
+ * distinct configuration faults share one message, and an HTTP 403 carries the
+ * `request_id` support asks for. JSON mode has always emitted it; human mode
+ * dropped it entirely, so the operator saw the same unactionable sentence.
+ *
+ * Values here originate partly from the service, so this is a print sink for
+ * service-controlled bytes and is held to the same rule as every other one.
+ */
+function renderErrorDetail(value) {
+    const rendered = Array.isArray(value)
+        ? value.map((item) => String(item)).join(", ")
+        : String(value);
+    return containsCredentialValue(rendered) ? "[redacted credential]" : rendered;
+}
+export function createOutputWriter(input) {
+    const structured = input.json || !input.streams.stdoutIsTTY;
+    const writer = {
+        structured,
+        success(command, data, human) {
+            if (structured) {
+                writeLine(input.streams.stdout, JSON.stringify({ schema_version: OUTPUT_SCHEMA_VERSION, type: "result", command, data }));
+            }
+            else {
+                writeLine(input.streams.stdout, sanitizeHumanTerminalOutput(human));
+            }
+        },
+        error(command, error) {
+            if (structured) {
+                writeLine(input.streams.stderr, JSON.stringify({
+                    schema_version: OUTPUT_SCHEMA_VERSION,
+                    type: "error",
+                    command,
+                    error: {
+                        code: error.code,
+                        message: error.message,
+                        retryable: error.retryable,
+                        ...(error.hint === undefined ? {} : { hint: error.hint }),
+                        ...(error.details === undefined ? {} : { details: error.details }),
+                    },
+                }));
+            }
+            else {
+                writeLine(input.streams.stderr, sanitizeSingleLineHumanOutput(`Error [${error.code}]: ${error.message}`));
+                for (const [key, value] of Object.entries(error.details ?? {})) {
+                    writeLine(input.streams.stderr, sanitizeSingleLineHumanOutput(`  ${key}: ${renderErrorDetail(value)}`));
+                }
+                if (error.hint !== undefined) {
+                    writeLine(input.streams.stderr, sanitizeSingleLineHumanOutput(`Next: ${error.hint}`));
+                }
+            }
+        },
+        text(value) {
+            writeLine(input.streams.stdout, sanitizeHumanTerminalOutput(value));
+        },
+    };
+    return Object.freeze(writer);
+}
+//# sourceMappingURL=output.js.map

package/dist/cli/output.js.map

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

package/dist/cli/parser.d.ts

@@ -0,0 +1,65 @@
+export type OptionValue = string | boolean;
+export interface ParsedInvocation {
+    readonly command: string | undefined;
+    readonly operands: readonly string[];
+    readonly options: Readonly<Record<string, OptionValue>>;
+}
+/**
+ * What THIS BUILD does with a command name. Never what the server allows.
+ *
+ * `routed`   — the preflight switch in `commands/commands.ts` dispatches this
+ *              leaf in this build.
+ * `reserved` — the name is accepted for compatibility and refuses.
+ *
+ * This vocabulary is deliberately DISJOINT from `CapabilityAvailability` in
+ * `src/api/contracts.ts` (`supported | unsupported | temporarily_unavailable |
+ * unknown`). That enum is the server's answer about one capability at one
+ * moment. This field is a compile-time constant computed with no network call,
+ * so it cannot know that answer.
+ *
+ * The two were spelled the same word until 2026-08-29, and `cuna help --all`
+ * consequently stamped `[supported]` on `machines.start`, every
+ * `agent-sessions` action, every terminal path, `usage`, `workspace`,
+ * `authorizations` and `api_keys.list` — while a live `cuna capabilities`
+ * listed none of them. One word, two authorities, and the offline one won on
+ * screen. `test/progressive-command-disclosure.test.mjs` now fails if the two
+ * vocabularies ever intersect again.
+ */
+export type CliRouteDispatch = "routed" | "reserved";
+/**
+ * One semantic leaf accepted by the CLI preflight/dispatch boundary.
+ *
+ * The tokenizer deliberately remains generic: it must parse an invocation
+ * before the command layer can return a precise usage error. Discovery still
+ * needs a closed world, however, so help and its tests consume this registry
+ * rather than maintaining a second handwritten command census.
+ */
+export interface CliRouteDefinition {
+    readonly key: string;
+    readonly command: string;
+    readonly action?: string;
+    readonly operandMode: "exact" | "free";
+    readonly syntax: string;
+    readonly argv: readonly string[];
+    readonly summary: string;
+    readonly dispatch: CliRouteDispatch;
+}
+/** The closed discovery projection of the command preflight switch. */
+export declare const CLI_ROUTE_REGISTRY: readonly CliRouteDefinition[];
+/**
+ * Resolve an invocation to one admitted semantic leaf.
+ *
+ * Exact command leaves accept no positional operand. Action leaves consume
+ * their registered first operand and leave IDs/names to the command-specific
+ * validator. Only provider PATH journeys and `connect` intentionally admit
+ * free positional operands. Consequently, adding a switch branch cannot make
+ * a new command or subaction executable until it is registered here.
+ */
+export declare function resolveCliRoute(parsed: ParsedInvocation): CliRouteDefinition | undefined;
+/** Fail closed before the command preflight switch can admit an unregistered leaf. */
+export declare function assertRegisteredCliRoute(parsed: ParsedInvocation): CliRouteDefinition;
+export declare function parseArgv(argv: readonly string[]): ParsedInvocation;
+export declare function stringOption(parsed: ParsedInvocation, name: string): string | undefined;
+export declare function booleanOption(parsed: ParsedInvocation, name: string): boolean;
+export declare function rejectUnknownOptions(parsed: ParsedInvocation, allowed: readonly string[]): void;
+//# sourceMappingURL=parser.d.ts.map

package/dist/cli/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/cli/parser.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,CAAC;AAC3C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;CACzD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,UAAU,CAAC;AAErD;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,OAAO,GAAG,MAAM,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;CACrC;AA8BD,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,EAAE,SAAS,kBAAkB,EAmD1D,CAAC;AAEH;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,gBAAgB,GAAG,kBAAkB,GAAG,SAAS,CAYxF;AAwBD,sFAAsF;AACtF,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,gBAAgB,GAAG,kBAAkB,CAwBrF;AAqFD,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,gBAAgB,CAsCnE;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKvF;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAK7E;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAI/F"}