@cicore/cli 1.0.0

package/dist/lib/ops/db.js

@@ -0,0 +1,351 @@
+/**
+ * CiCore CLI — PostgreSQL primitives
+ *
+ * Host-aware database operations that run psql inside the postgres
+ * container on the remote host (`docker exec -i <dbContainerName> psql`).
+ * The container exposes psql to localhost only; routing through `docker
+ * exec` keeps us from needing inbound 5432 on the server.
+ *
+ * Authentication uses `cfg.dbAdminUser` + `cfg.dbAdminPassword`. The
+ * password is passed via PGPASSWORD env to avoid `-W` interactive prompts
+ * and to keep it out of `ps` output (PGPASSWORD is read by libpq and
+ * doesn't appear in argv).
+ *
+ * Idempotency:
+ *   - `dbCreateIfMissing`: checks pg_database before CREATE
+ *   - `dbRunMigrations`: uses a `schema_migrations` ledger table inside
+ *     each database, only applying versions not already recorded
+ *
+ * Migration files: `*.sql` in a local directory, sorted by filename.
+ * Convention `NNN_description.sql` (e.g. `001_create_greetings.sql`).
+ * The version key = filename without `.sql`.
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { join as joinPath } from 'node:path';
+import { log } from '../logger.js';
+import { runRemoteScript } from './ssh.js';
+// ─────────────────────────────────────────────────────────────────────────
+// Identifier validation — defense in depth against SQL injection through
+// caller-provided database/user names. CREATE DATABASE doesn't accept
+// parameterized identifiers; only literal interpolation works, so the
+// name MUST be validated before substitution.
+// ─────────────────────────────────────────────────────────────────────────
+/** Postgres identifier rules: alpha/underscore, then alpha/digit/underscore, ≤63 chars. */
+const IDENT_RE = /^[a-zA-Z_][a-zA-Z0-9_]{0,62}$/;
+function assertIdent(value, kind) {
+    if (!IDENT_RE.test(value)) {
+        throw new Error(`Invalid ${kind} identifier '${value}'. ` +
+            `Must match /^[a-zA-Z_][a-zA-Z0-9_]{0,62}$/ (Postgres unquoted identifier rules).`);
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Existence checks
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * Returns true if a database with the given name exists.
+ * Uses `pg_database` catalog query — works regardless of search_path.
+ */
+export async function dbExists(cfg, dbName) {
+    assertIdent(dbName, 'database');
+    const result = await execSql(cfg, 'postgres', `SELECT 1 FROM pg_database WHERE datname='${dbName}';`);
+    if (!result.success)
+        return false;
+    return result.stdout.includes('(1 row)');
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Role & Database lifecycle
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * Check if a postgres ROLE (login user) already exists.
+ * Used by `dbCreateRoleAndDb` for idempotency.
+ */
+export async function roleExists(cfg, role) {
+    assertIdent(role, 'role');
+    const result = await execSql(cfg, 'postgres', `SELECT 1 FROM pg_roles WHERE rolname='${role}';`);
+    if (!result.success)
+        return false;
+    return result.stdout.includes('(1 row)');
+}
+/**
+ * Create the database if missing (idempotent). On creation, grants the
+ * admin user full privileges — postgres makes the creating role the owner
+ * automatically, but the GRANT is belt-and-suspenders against permission
+ * drift from later role changes.
+ */
+export async function dbCreateIfMissing(cfg, dbName) {
+    assertIdent(dbName, 'database');
+    if (await dbExists(cfg, dbName)) {
+        log.info(`[db] '${dbName}' already exists on ${cfg.brandName} — skip create`);
+        return Object.freeze({ stdout: '', stderr: '', exitCode: 0, success: true });
+    }
+    log.info(`[db] CREATE DATABASE ${dbName} on ${cfg.brandName}`);
+    // CREATE DATABASE can't run inside a transaction block; psql autocommits
+    // single statements when no BEGIN is present, so this works as-is.
+    const sql = `CREATE DATABASE ${dbName} OWNER ${cfg.dbAdminUser};\n` +
+        `GRANT ALL PRIVILEGES ON DATABASE ${dbName} TO ${cfg.dbAdminUser};`;
+    return execSql(cfg, 'postgres', sql);
+}
+/**
+ * Per-core role + database provisioning (replaces the shared admin
+ * pattern). Each core gets its own postgres LOGIN role with a random
+ * password, owning its own database — defense in depth: if one core's
+ * .env leaks, the blast radius is one database, not the whole instance.
+ *
+ * Idempotency:
+ *   - If the role already exists, its password is updated (ALTER ROLE)
+ *     so a fresh .env re-write stays in sync with the server.
+ *   - If the database already exists, ownership is reassigned to the
+ *     role (REASSIGN OWNED is overkill for first-run; a simpler
+ *     ALTER DATABASE ... OWNER TO covers it).
+ *
+ * Both statements run under the admin connection (`cfg.dbAdminUser`)
+ * because CREATE ROLE / CREATE DATABASE require it. The single quotes
+ * in the password are escaped before substitution; identifiers go
+ * through `assertIdent` to forbid SQL-meta characters entirely.
+ *
+ * Caller responsibility: pass a strong password (≥24 random base64url
+ * chars) and a globally-unique role name. The setup orchestrator
+ * generates both via Node `crypto.randomBytes`.
+ */
+export async function dbCreateRoleAndDb(cfg, role, password, dbName) {
+    assertIdent(role, 'role');
+    assertIdent(dbName, 'database');
+    if (!password || password.length < 16) {
+        throw new Error(`Password too short (got ${password?.length ?? 0} chars, need ≥16)`);
+    }
+    // Postgres string literal escape: double up single quotes. The role
+    // name itself is already validated as a plain identifier, so it's
+    // interpolated raw.
+    const pwEscaped = password.replace(/'/g, "''");
+    log.info(`[db] ensure role+db '${role}'/'${dbName}' on ${cfg.brandName}`);
+    // Step 1: ROLE — create with password, or update password if exists.
+    // CREATE ROLE inside a DO block lets us branch on existence atomically.
+    // CREATEDB: the per-core role must be able to create its own database —
+    // the app's installer (POST /setup/install → SetupService::createDatabase)
+    // connects AS this role and issues CREATE DATABASE. Without it the install
+    // fails "permission denied to create database". Scoped to DB creation only
+    // (not superuser), so per-core isolation holds. (Bug surfaced 2026-05-24.)
+    const roleSql = `DO $$\n` +
+        `BEGIN\n` +
+        `  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '${role}') THEN\n` +
+        `    ALTER ROLE ${role} WITH LOGIN CREATEDB PASSWORD '${pwEscaped}';\n` +
+        `  ELSE\n` +
+        `    CREATE ROLE ${role} WITH LOGIN CREATEDB PASSWORD '${pwEscaped}';\n` +
+        `  END IF;\n` +
+        `END $$;`;
+    const roleResult = await execSql(cfg, 'postgres', roleSql);
+    if (!roleResult.success) {
+        return Object.freeze({
+            stdout: roleResult.stdout,
+            stderr: `role create/update failed: ${roleResult.stderr}`,
+            exitCode: roleResult.exitCode,
+            success: false,
+        });
+    }
+    // Step 2: DATABASE — create owned by role, or reassign ownership if
+    // it already exists. CREATE DATABASE can't run in a DO block (not
+    // allowed in transactions), so check + branch in two statements.
+    if (await dbExists(cfg, dbName)) {
+        log.info(`[db] '${dbName}' exists — reassigning owner to '${role}'`);
+        const alterSql = `ALTER DATABASE ${dbName} OWNER TO ${role};\n` +
+            `GRANT ALL PRIVILEGES ON DATABASE ${dbName} TO ${role};`;
+        return execSql(cfg, 'postgres', alterSql);
+    }
+    log.info(`[db] CREATE DATABASE ${dbName} OWNER ${role}`);
+    const createSql = `CREATE DATABASE ${dbName} OWNER ${role};\n` +
+        `GRANT ALL PRIVILEGES ON DATABASE ${dbName} TO ${role};`;
+    return execSql(cfg, 'postgres', createSql);
+}
+/**
+ * Apply every `*.sql` file under `migrationsDir` that hasn't already run
+ * against `dbName`. Files are applied in filename-sorted order so that the
+ * `NNN_description.sql` convention controls ordering.
+ *
+ * Each migration runs inside an explicit transaction:
+ *
+ *   BEGIN;
+ *   <file contents>
+ *   INSERT INTO schema_migrations(version) VALUES ('<version>');
+ *   COMMIT;
+ *
+ * On failure the transaction rolls back atomically — partial migrations
+ * never leave the schema in a half-applied state. Subsequent migrations
+ * are skipped, and {@link MigrationRunResult.success} is false.
+ *
+ * The ledger table is created on first call (idempotent). Existing rows
+ * dictate which versions are skipped on subsequent runs.
+ */
+export async function dbRunMigrations(cfg, dbName, migrationsDir) {
+    assertIdent(dbName, 'database');
+    const files = await listMigrationFiles(migrationsDir);
+    if (files.length === 0) {
+        log.debug(`[db] no migration files in ${migrationsDir}`);
+        return Object.freeze({ applied: [], skipped: [], success: true });
+    }
+    const ledgerSetup = await ensureMigrationsLedger(cfg, dbName);
+    if (!ledgerSetup.success) {
+        return Object.freeze({
+            applied: [],
+            skipped: [],
+            success: false,
+        });
+    }
+    const alreadyApplied = await listAppliedMigrations(cfg, dbName);
+    const appliedSet = new Set(alreadyApplied);
+    const applied = [];
+    const skipped = [];
+    for (const file of files) {
+        const version = file.version;
+        if (appliedSet.has(version)) {
+            skipped.push(version);
+            log.debug(`[db] migration ${version} already applied — skip`);
+            continue;
+        }
+        log.info(`[db] apply migration ${version} → ${dbName}`);
+        const body = await readFile(file.path, 'utf8');
+        // Compose a single transactional script: file body + ledger insert.
+        // We use dollar-quoted string for the version to avoid escaping issues
+        // when the version itself contains single quotes (it won't, but defense).
+        const tx = `BEGIN;\n${body}\nINSERT INTO schema_migrations(version) VALUES ($mv$${version}$mv$);\nCOMMIT;\n`;
+        const result = await execSql(cfg, dbName, tx);
+        applied.push(Object.freeze({
+            version,
+            success: result.success,
+            stderr: result.stderr,
+        }));
+        if (!result.success) {
+            // Stop the chain — earlier migrations may depend on this one.
+            return Object.freeze({
+                applied: Object.freeze(applied),
+                skipped: Object.freeze(skipped),
+                success: false,
+            });
+        }
+    }
+    return Object.freeze({
+        applied: Object.freeze(applied),
+        skipped: Object.freeze(skipped),
+        success: true,
+    });
+}
+/** List `<dir>/*.sql` sorted by filename, paired with the version key. */
+async function listMigrationFiles(dir) {
+    const entries = await readdir(dir).catch(() => []);
+    const sqlFiles = entries
+        .filter(name => name.endsWith('.sql') && !name.startsWith('.'))
+        .sort();
+    return Object.freeze(sqlFiles.map(name => Object.freeze({
+        version: name.slice(0, -'.sql'.length),
+        path: joinPath(dir, name),
+    })));
+}
+/** Ensure `schema_migrations` ledger table exists (CREATE IF NOT EXISTS). */
+async function ensureMigrationsLedger(cfg, dbName) {
+    const sql = `CREATE TABLE IF NOT EXISTS schema_migrations (\n` +
+        `  version TEXT PRIMARY KEY,\n` +
+        `  applied_at TIMESTAMPTZ NOT NULL DEFAULT now()\n` +
+        `);`;
+    return execSql(cfg, dbName, sql);
+}
+/** Return the list of already-applied migration versions, sorted. */
+async function listAppliedMigrations(cfg, dbName) {
+    // -A unaligned, -t tuples-only — strips headers and separators for clean parsing.
+    const result = await execSql(cfg, dbName, 'SELECT version FROM schema_migrations ORDER BY version;', {
+        psqlFlags: ['-A', '-t'],
+    });
+    if (!result.success)
+        return [];
+    return result.stdout
+        .split('\n')
+        .map(line => line.trim())
+        .filter(line => line.length > 0);
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Read-only query (control-plane reconcile, status reads)
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * Run a read-only SELECT against `dbName` and return rows as parsed objects.
+ *
+ * The caller's inner query is wrapped in `json_agg` so every row round-trips
+ * as one JSON document — jsonb columns (themes), embedded commas, quotes and
+ * escapes all survive losslessly, with none of the fragile CSV/line parsing
+ * the migration ledger reader can get away with for a single text column.
+ *
+ * Returns `[]` on an empty result set or a failed/unparseable query (the
+ * failure is logged). `innerSelect` must be a bare SELECT with no trailing
+ * semicolon (it's interpolated as a subquery).
+ */
+export async function dbSelectJson(cfg, dbName, innerSelect) {
+    const sql = `SELECT COALESCE(json_agg(t), '[]'::json) FROM (${innerSelect}) t;`;
+    // Read-only: dry-run planının gerçek veriyi okuyabilmesi için global dry-run'da
+    // bile koştur (Part A). Aksi halde validate/inventory boş döner → "not found".
+    const result = await execSql(cfg, dbName, sql, { psqlFlags: ['-A', '-t'], silent: true, allowInDryRun: true });
+    if (!result.success) {
+        log.error(`[db] query on ${dbName} failed: ${result.stderr.trim() || result.stdout.trim()}`);
+        return [];
+    }
+    const text = result.stdout.trim();
+    if (text === '')
+        return [];
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        log.error(`[db] could not parse query result: ${err instanceof Error ? err.message : String(err)}`);
+        return [];
+    }
+}
+/**
+ * Run a write statement (UPDATE/INSERT) against `dbName`. Thin wrapper over
+ * the internal executor for callers outside this module (e.g. reconcile
+ * writing achieved DNS state back to the control-plane). The caller is
+ * responsible for validating any interpolated values — there is no parameter
+ * binding here; pass only validated identifiers / enum literals.
+ */
+export async function dbExec(cfg, dbName, sql) {
+    return execSql(cfg, dbName, sql, { silent: true });
+}
+/**
+ * Execute a SQL script inside the postgres container via `docker exec -i`.
+ *
+ * The script is piped through stdin (not -c) so multi-statement migrations
+ * including BEGIN/COMMIT work as expected. PGPASSWORD is exported in the
+ * remote shell before invoking docker exec so libpq picks it up — never
+ * appears in argv.
+ */
+async function execSql(cfg, dbName, sql, opts = {}) {
+    assertIdent(dbName, 'database');
+    // Build psql argv. ON_ERROR_STOP=1 makes psql exit non-zero on the first
+    // SQL error inside a script — without it, psql continues and reports
+    // success even though individual statements failed.
+    const psqlArgs = [
+        '-v',
+        'ON_ERROR_STOP=1',
+        '-U',
+        cfg.dbAdminUser,
+        '-d',
+        dbName,
+        ...(opts.psqlFlags ?? []),
+    ];
+    const psqlArgline = psqlArgs.map(quoteShellArg).join(' ');
+    // The remote shell sees: docker exec -i -e PGPASSWORD=… <container> psql <args>
+    // Heredoc carries the SQL. -i keeps stdin attached. -e injects the password
+    // into the container env (not just the outer shell), so libpq can read it.
+    const script = `docker exec -i -e PGPASSWORD="$PGPASSWORD" ${quoteShellArg(cfg.dbContainerName)} ` +
+        `psql ${psqlArgline} <<'__VU_SQL_EOF__'\n` +
+        sql +
+        `\n__VU_SQL_EOF__\n`;
+    return runRemoteScript(cfg, script, {
+        env: { PGPASSWORD: cfg.dbAdminPassword },
+        silent: opts.silent,
+        allowInDryRun: opts.allowInDryRun,
+    });
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────
+/** Single-quote wrap for safe shell interpolation. */
+function quoteShellArg(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+//# sourceMappingURL=db.js.map

package/dist/lib/ops/db.js.map

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

package/dist/lib/ops/dns.d.ts

@@ -0,0 +1,111 @@
+/**
+ * CiCore CLI — DNS / TLS provider abstraction
+ *
+ * Vendor-neutral {@link DnsProvider} interface + a Cloudflare implementation.
+ * The interface exists so a second vendor (Route53, …) can slot in later
+ * without touching callers (see brand-layer plan §K2 / §8). For now the only
+ * implementation is {@link CloudflareDnsProvider}.
+ *
+ * Two routing modes — both first-class, both modelled by the control plane
+ * (`cp_domains.dns_mode`):
+ *
+ *   - `owned_zone` — the hostname lives in a zone *we* manage (e.g.
+ *     `lab.multinodex.com`). We upsert a proxied CNAME → our origin target;
+ *     TLS is covered by the zone's Universal / Advanced certificate. The
+ *     zone id is resolved from the hostname at call time (a single host can
+ *     serve several owned zones — mkt fronts both multinodex.com and
+ *     randevu360.net — so we can't rely on `cfg.cfZoneId` alone).
+ *
+ *   - `custom_hostname` (PRIMARY) — a domain the *customer* owns (BYO domain,
+ *     Shopify/Webflow model). We register it as a Cloudflare for SaaS custom
+ *     hostname in our SaaS zone (`cfg.cfZoneId`); DV TLS is issued + renewed
+ *     automatically, and the customer points a CNAME at our fallback origin.
+ *     This retires the per-host tunnel-ingress + `api-lab` SSL-depth hack:
+ *     deep subdomains (`api.lab.x`) that Universal SSL's single-level wildcard
+ *     can't cover get their own per-hostname cert for free.
+ *
+ * All calls use the host's scoped token `cfg.cfApiToken` (Bearer) — NOT the
+ * stored-config token that `lib/cloudflare.ts` reads. Keep new DNS work here,
+ * on the host-aware path. Every mutation honours `--dry-run`.
+ */
+import type { HostConfig } from '../hosts.js';
+/** How a hostname is routed + secured. Mirrors `cp_domains.dns_mode`. */
+export type DnsMode = 'owned_zone' | 'custom_hostname';
+/** Routing status, aligned with `cp_domains.routing_status` / `ssl_status`. */
+export type DnsStatus = 'active' | 'pending' | 'error';
+export interface DnsHostRequest {
+    /** Fully-qualified hostname to provision (e.g. `lab.multinodex.com`). */
+    readonly hostname: string;
+    /** Routing mode. Defaults to auto-detection via {@link DnsProvider.detectMode}. */
+    readonly mode: DnsMode;
+    /**
+     * Where traffic should land:
+     *   - owned_zone: CNAME content (e.g. the host's proxied A-record name or
+     *     a tunnel CNAME target) the proxied record points at.
+     *   - custom_hostname: the fallback-origin hostname customers CNAME to;
+     *     used to surface the CNAME target back to the caller. The custom
+     *     hostname itself is registered against `cfg.cfZoneId`.
+     */
+    readonly originTarget: string;
+}
+/** Resolved state of a provisioned hostname — enough to persist in `cp_domains`. */
+export interface DnsHostState {
+    readonly success: boolean;
+    readonly hostname: string;
+    readonly mode: DnsMode;
+    /** Routing reachability. */
+    readonly routingStatus: DnsStatus;
+    /** TLS issuance/validation status. */
+    readonly sslStatus: DnsStatus;
+    /** custom_hostname only: CF object id → persist as `cf_custom_hostname_id`. */
+    readonly customHostnameId?: string;
+    /** Zone the record/hostname lives in → persist as `cf_zone_id`. */
+    readonly cfZoneId?: string;
+    /** owned_zone: CNAME content. custom_hostname: target the customer must CNAME to. */
+    readonly cnameTarget?: string;
+    /**
+     * custom_hostname only: ownership + DV validation records the customer (or
+     * we, for owned validation) must publish → persist as `verification_record`.
+     */
+    readonly verification?: unknown;
+    readonly errorMessage: string;
+}
+/** Minimal mutation result for teardown / bootstrap ops. */
+export interface DnsResult {
+    readonly success: boolean;
+    readonly errorMessage: string;
+}
+/**
+ * Vendor-neutral DNS/TLS provisioning surface. A `CloudflareDnsProvider`
+ * implements it today; the brand provisioning flow + `ci setup` depend only
+ * on this interface.
+ */
+export interface DnsProvider {
+    /**
+     * Decide whether `hostname` falls under a zone we manage (`owned_zone`) or
+     * belongs to a customer (`custom_hostname`). Lets callers omit an explicit
+     * mode and "do the right thing" for both our subdomains and BYO domains.
+     */
+    detectMode(hostname: string): Promise<DnsMode>;
+    /**
+     * Make `hostname` reachable + TLS-valid, routing to our origin. Idempotent.
+     * For `custom_hostname`, TLS is issued asynchronously by Cloudflare — the
+     * returned `sslStatus` may be `pending`; poll {@link getHostState} until it
+     * flips to `active` before marking the domain live.
+     */
+    ensureHost(req: DnsHostRequest): Promise<DnsHostState>;
+    /** Current routing + TLS state. Use to poll a `pending` custom hostname. */
+    getHostState(hostname: string, mode: DnsMode): Promise<DnsHostState>;
+    /** Remove routing + cert for `hostname` (rollback / brand teardown). Idempotent. */
+    removeHost(hostname: string, mode: DnsMode): Promise<DnsResult>;
+    /**
+     * One-time per-zone bootstrap (custom_hostname mode): designate
+     * `originHostname` — a *proxied* record that already exists in the SaaS zone
+     * — as the Cloudflare for SaaS fallback origin. Required before any custom
+     * hostname can be served. Idempotent.
+     */
+    ensureFallbackOrigin(originHostname: string): Promise<DnsResult>;
+}
+/** Construct the configured provider for a host. Cloudflare-only today. */
+export declare function createDnsProvider(cfg: HostConfig): DnsProvider;
+//# sourceMappingURL=dns.d.ts.map

package/dist/lib/ops/dns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dns.d.ts","sourceRoot":"","sources":["../../../src/lib/ops/dns.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAQ7C,yEAAyE;AACzE,MAAM,MAAM,OAAO,GAAG,YAAY,GAAG,iBAAiB,CAAA;AAEtD,+EAA+E;AAC/E,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAA;AAEtD,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAC9B;AAED,oFAAoF;AACpF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,4BAA4B;IAC5B,QAAQ,CAAC,aAAa,EAAE,SAAS,CAAA;IACjC,sCAAsC;IACtC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAClC,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,qFAAqF;IACrF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAC9B;AAED,4DAA4D;AAC5D,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAC9B;AAID;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAE9C;;;;;OAKG;IACH,UAAU,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IAEtD,4EAA4E;IAC5E,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IAEpE,oFAAoF;IACpF,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;IAE/D;;;;;OAKG;IACH,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;CACjE;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,UAAU,GAAG,WAAW,CAE9D"}