@cicore/cli 1.0.0

package/dist/lib/ops/core.js

@@ -0,0 +1,322 @@
+/**
+ * CiCore CLI — Core skeleton + environment primitives
+ *
+ * A "core" is one logical SaaS instance inside the multi-core VuCore
+ * stack. Each core lives in its own subdirectory under `cfg.coresHostPath`
+ * with its own `.env`, addons/, storage/, etc. The PHP and Nuxt containers
+ * are shared across cores — runtime routing (nginx $target_core) picks
+ * which core handles a given request.
+ *
+ * This module provides the primitives `vu setup` needs to onboard a new
+ * core:
+ *
+ *   - {@link coreEnsureSkeleton}: server-side mkdir of the standard layout
+ *   - {@link coreEnvGenerate}: build a config object from host + per-core
+ *                              inputs (domain, name, secrets)
+ *   - {@link coreWriteEnv}: serialize the config and write it atomically
+ *                            to `<coresHostPath>/<core>/.env`
+ *
+ * Secrets (DB password, JWT) are generated with `crypto.randomBytes` — 32
+ * bytes hex, suitable for both. The caller can override via options to
+ * support importing an existing core's secrets.
+ */
+import { randomBytes } from 'node:crypto';
+import { log } from '../logger.js';
+import { runRemote, runRemoteScript } from './ssh.js';
+/** Core name validation — same rule as Postgres ident + DB name. */
+const CORE_NAME_RE = /^[a-zA-Z_][a-zA-Z0-9_-]{0,62}$/;
+function assertCoreName(name) {
+    if (!CORE_NAME_RE.test(name)) {
+        throw new Error(`Invalid core name '${name}'. Must match /^[a-zA-Z_][a-zA-Z0-9_-]{0,62}$/.`);
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Skeleton (directory layout on the server)
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * Standard subdirectory layout under `cores/<name>/`. Each entry gets
+ * created with `mkdir -p` so re-running the op is idempotent.
+ *
+ * `storage/` and its children are writable by the PHP container's
+ * www-data (uid 82) — see {@link coreEnsureSkeleton} for the chmod
+ * that establishes that.
+ */
+const SKELETON_DIRS = Object.freeze([
+    'addons',
+    'shared',
+    'vendor',
+    'storage',
+    'storage/cache',
+    'storage/sessions',
+    'storage/logs',
+    'storage/framework/cache',
+]);
+/**
+ * Create `cores/<name>/` and its subdirectories on the server if missing.
+ * Permissions are set so PHP container's www-data (uid 82) can write into
+ * the storage/ tree. Files outside storage/ keep root-owned defaults.
+ *
+ * Idempotent — safe to call repeatedly. Returns success when every dir
+ * exists (whether we created it or it was already there).
+ */
+export async function coreEnsureSkeleton(cfg, coreName) {
+    assertCoreName(coreName);
+    const root = `${cfg.coresHostPath}/${coreName}`;
+    log.info(`[core] ensure skeleton ${root} on ${cfg.brandName}`);
+    // Compose a single script: mkdir -p each dir, then chmod the storage tree,
+    // then chown the whole core tree to the PHP runtime uid so the container can
+    // read/write it regardless of which SSH user the CLI logged in as.
+    // `set -e` aborts on first error; we'd rather know immediately than
+    // leave a half-built skeleton.
+    const mkdirs = SKELETON_DIRS.map(dir => `mkdir -p ${shellQuote(root + '/' + dir)}`).join('\n');
+    // Default brand.json so the core renders its own identity out of the box
+    // (core-loader → useBrand → VBrandLogo + titleTemplate). Written only if
+    // absent — `ci brand reconcile` / the panel overwrite it with richer data
+    // (logo, theme) from the control-plane. Makes a fresh `ci setup` reproducible
+    // without the hand-written brand.json this used to need.
+    const brandJsonPath = root + '/brand.json';
+    const brandJson = JSON.stringify({ brand: coreName, title: humanizeBrand(coreName), logoUrl: null, faviconUrl: null, theme: {} }, null, 2);
+    const script = `set -e\n` +
+        `mkdir -p ${shellQuote(root)}\n` +
+        mkdirs +
+        `\nchmod -R u+rwX,g+rwX,o+rwX ${shellQuote(root + '/storage')}\n` +
+        `if [ ! -f ${shellQuote(brandJsonPath)} ]; then cat > ${shellQuote(brandJsonPath)} <<'__VU_BRAND_EOF__'\n` +
+        brandJson + `\n__VU_BRAND_EOF__\nfi\n` +
+        chownToRuntimeUid(cfg, root);
+    return runRemoteScript(cfg, script, { silent: true });
+}
+/** Humanize a core slug for the default brand.json title. */
+function humanizeBrand(slug) {
+    if (slug === 'cicore')
+        return 'CiCore';
+    if (slug === 'cicore')
+        return 'ciCore';
+    return slug.charAt(0).toUpperCase() + slug.slice(1);
+}
+/**
+ * Shell snippet that chowns `target` (recursively) to the host's PHP runtime
+ * uid:gid. Tries direct chown first (works when the SSH user is root or is
+ * already that uid — a no-op), falling back to `sudo -n` for non-root SSH
+ * users whose uid differs. Decouples file ownership from the SSH login so the
+ * PHP/Nuxt container can always read per-core files (notably the mode-600
+ * `.env`). Returns a trailing-newline-terminated snippet for concatenation.
+ */
+function chownToRuntimeUid(cfg, target) {
+    const owner = `${cfg.phpRuntimeUid}:${cfg.phpRuntimeUid}`;
+    const q = shellQuote(target);
+    return `chown -R ${owner} ${q} 2>/dev/null || sudo -n chown -R ${owner} ${q}\n`;
+}
+/**
+ * Build the full `.env` config object from the host topology and per-core
+ * inputs. Values are simple strings — caller serializes via
+ * {@link coreWriteEnv} when ready.
+ *
+ * Secrets default to fresh 32-byte hex values; pass overrides via
+ * `inputs.dbPassword` / `inputs.jwtSecret` when reusing an existing core's
+ * credentials (e.g. clone, restore).
+ */
+export function coreEnvGenerate(cfg, coreName, inputs) {
+    assertCoreName(coreName);
+    const brand = inputs.brand ?? coreName;
+    return Object.freeze({
+        // Identity
+        CORE_NAME: coreName,
+        DOMAIN: inputs.domain,
+        ADDITIONAL_DOMAINS: inputs.additionalDomains ?? '',
+        // Public Nuxt config (visible to browser)
+        NUXT_PUBLIC_API_BASE: `https://api.${inputs.domain}`,
+        NUXT_PUBLIC_WS_URL: `wss://${inputs.domain}/ws`,
+        NUXT_PUBLIC_HOST: inputs.domain,
+        NUXT_PUBLIC_CORE_CDN_URL: `${cfg.cdnBaseUrl}/CoreUI/latest`,
+        NUXT_PUBLIC_BRAND: brand,
+        // Image source — runtime pull reads these for self-update workflows
+        DOCKER_REGISTRY: cfg.composeImageName.split('/')[0] ?? 'baynis',
+        IMAGE_TAG: 'latest',
+        // Database — connection points to the shared postgres container.
+        // Each core gets its own LOGIN role + database (dbCreateRoleAndDb)
+        // so a leaked .env's blast radius is exactly one core's DB. The
+        // role name defaults to `db_<core>_<8hex>` and the password to a
+        // 24-byte base64url string; setup overrides both when re-running
+        // (idempotency — existing .env wins).
+        DB_HOST: cfg.dbContainerName,
+        DB_PORT: '5432',
+        DB_NAME: `${coreName}_db`,
+        DB_USER: inputs.dbUser ?? `db_${coreName}_${randomHex(4)}`,
+        DB_PASS: inputs.dbPassword ?? randomHex(32),
+        DB_GATEWAY: 'local',
+        // Auth secrets — fresh per core (no cross-core token validity).
+        JWT_SECRET: inputs.jwtSecret ?? randomHex(32),
+        // Misc
+        ADDON_DEBUG: 'true',
+    });
+}
+// ─────────────────────────────────────────────────────────────────────────
+// .env serialization + atomic write
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * Serialize an env config to dotenv format and write atomically to the
+ * server at `cores/<coreName>/.env`.
+ *
+ * Format: `KEY=value` per line, no quoting (values must be free of
+ * newlines and unescaped `"`/`'`). Generated secrets meet this; caller
+ * overrides should too.
+ *
+ * Atomic via temp file + mv inside the same script. If a previous .env
+ * exists, it's backed up to `.env.bak-<timestamp>` so a botched setup is
+ * recoverable. Idempotent: writing the same content twice is a no-op
+ * (transform short-circuits when content matches).
+ */
+export async function coreWriteEnv(cfg, coreName, env) {
+    assertCoreName(coreName);
+    validateEnvValues(env);
+    const path = `${cfg.coresHostPath}/${coreName}/.env`;
+    const content = serializeEnv(env);
+    log.info(`[core] write .env (${Object.keys(env).length} keys) → ${path}`);
+    // Backup-then-replace pattern: timestamp suffix + cmp before overwriting.
+    // The `cmp --silent` short-circuits identical writes (skip backup + mv).
+    const script = `set -e\n` +
+        `tmp="${path}.tmp.$$"\n` +
+        `cat > "$tmp" <<'__VU_ENV_EOF__'\n` +
+        content +
+        `__VU_ENV_EOF__\n` +
+        `chmod 600 "$tmp"\n` +
+        `if [ -f ${shellQuote(path)} ] && cmp --silent ${shellQuote(path)} "$tmp"; then\n` +
+        `  rm -f "$tmp"\n` +
+        `  echo "unchanged"\n` +
+        `  exit 0\n` +
+        `fi\n` +
+        `if [ -f ${shellQuote(path)} ]; then\n` +
+        `  cp -a ${shellQuote(path)} "${path}.bak-$(date -u +%Y%m%d-%H%M%S)"\n` +
+        `fi\n` +
+        `mv "$tmp" ${shellQuote(path)}\n` +
+        // Newly mv'd file is owned by the SSH user; hand it to the PHP runtime uid
+        // so the container can read it (mode 600). Keep 600 — owner is now php-fpm.
+        chownToRuntimeUid(cfg, path) +
+        `echo "written"\n`;
+    return runRemoteScript(cfg, script, { silent: true });
+}
+/**
+ * Parse the existing `.env` on the server into a plain object. Useful for
+ * re-using an existing core's secrets when adding domains or for
+ * inspection. Returns an empty object if the file doesn't exist.
+ *
+ * Best-effort parsing: supports `KEY=value` and `KEY="value"`, skips blank
+ * lines and `#` comments. Doesn't expand `$VAR` references — values are
+ * returned verbatim.
+ */
+export async function coreReadEnv(cfg, coreName) {
+    assertCoreName(coreName);
+    const path = `${cfg.coresHostPath}/${coreName}/.env`;
+    const result = await runRemote(cfg, `cat ${shellQuote(path)} 2>/dev/null || true`, {
+        silent: true,
+    });
+    if (!result.success || result.stdout.trim() === '')
+        return {};
+    const out = {};
+    for (const rawLine of result.stdout.split('\n')) {
+        const line = rawLine.trim();
+        if (line === '' || line.startsWith('#'))
+            continue;
+        const eq = line.indexOf('=');
+        if (eq === -1)
+            continue;
+        const key = line.slice(0, eq).trim();
+        let value = line.slice(eq + 1);
+        // Strip surrounding quotes if present (matched pair only).
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        out[key] = value;
+    }
+    return out;
+}
+/**
+ * Project a brand into `cores/<slug>/brand.json` on the host, idempotently.
+ *
+ * Reads the existing file and compares *semantically* (parsed + key-sorted),
+ * so formatting differences between the PHP and CLI writers never register as
+ * drift — only a real identity change rewrites the file. Returns whether the
+ * file changed so `ci brand reconcile` can report an honest unchanged/written
+ * summary. The freshly-written file is chowned to the PHP runtime uid so the
+ * container can read it.
+ */
+export async function coreReconcileBrandJson(cfg, slug, projection) {
+    assertCoreName(slug);
+    const path = `${cfg.coresHostPath}/${slug}/brand.json`;
+    // Compare against what's already there (semantic, not byte-for-byte).
+    const existing = await runRemote(cfg, `cat ${shellQuote(path)} 2>/dev/null || true`, { silent: true });
+    if (existing.success && existing.stdout.trim() !== '') {
+        try {
+            const current = JSON.parse(existing.stdout);
+            if (stableStringify(current) === stableStringify(projection)) {
+                return { success: true, changed: false, stderr: '' };
+            }
+        }
+        catch {
+            // Unparseable existing file → treat as drift and rewrite.
+        }
+    }
+    const content = JSON.stringify(projection, null, 2) + '\n';
+    log.info(`[core] reconcile brand.json → ${path}`);
+    const script = `set -e\n` +
+        `mkdir -p ${shellQuote(`${cfg.coresHostPath}/${slug}`)}\n` +
+        `tmp="${path}.tmp.$$"\n` +
+        `cat > "$tmp" <<'__VU_BRAND_EOF__'\n` +
+        content +
+        `__VU_BRAND_EOF__\n` +
+        `mv "$tmp" ${shellQuote(path)}\n` +
+        chownToRuntimeUid(cfg, path);
+    const result = await runRemoteScript(cfg, script, { silent: true });
+    return { success: result.success, changed: result.success, stderr: result.stderr };
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * Deterministic JSON string with recursively sorted object keys, so two
+ * structurally-equal documents compare equal regardless of key order or
+ * whitespace. Arrays keep their order (meaningful); scalars pass through.
+ */
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    const obj = value;
+    const body = Object.keys(obj)
+        .sort()
+        .map(k => `${JSON.stringify(k)}:${stableStringify(obj[k])}`)
+        .join(',');
+    return `{${body}}`;
+}
+function serializeEnv(env) {
+    // Stable order makes diffs meaningful between runs.
+    const lines = Object.keys(env)
+        .sort()
+        .map(key => `${key}=${env[key]}`);
+    return lines.join('\n') + '\n';
+}
+/**
+ * Reject env values that would break the serializer: embedded newlines
+ * (would prematurely terminate the line), trailing whitespace (parsed
+ * inconsistently across loaders), or NUL bytes. Caller-provided overrides
+ * sometimes carry these — better to fail loudly than write a broken file.
+ */
+function validateEnvValues(env) {
+    for (const [key, value] of Object.entries(env)) {
+        if (/[\r\n\0]/.test(value)) {
+            throw new Error(`Env value for '${key}' contains a newline or NUL byte; cannot serialize safely.`);
+        }
+        if (value !== value.replace(/[\s]+$/, '')) {
+            throw new Error(`Env value for '${key}' has trailing whitespace; trim before passing.`);
+        }
+    }
+}
+function randomHex(bytes) {
+    return randomBytes(bytes).toString('hex');
+}
+function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+//# sourceMappingURL=core.js.map

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

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

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

@@ -0,0 +1,116 @@
+/**
+ * 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 type { HostConfig } from '../hosts.js';
+import { type ExecResult } from './ssh.js';
+/**
+ * Returns true if a database with the given name exists.
+ * Uses `pg_database` catalog query — works regardless of search_path.
+ */
+export declare function dbExists(cfg: HostConfig, dbName: string): Promise<boolean>;
+/**
+ * Check if a postgres ROLE (login user) already exists.
+ * Used by `dbCreateRoleAndDb` for idempotency.
+ */
+export declare function roleExists(cfg: HostConfig, role: string): Promise<boolean>;
+/**
+ * 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 declare function dbCreateIfMissing(cfg: HostConfig, dbName: string): Promise<ExecResult>;
+/**
+ * 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 declare function dbCreateRoleAndDb(cfg: HostConfig, role: string, password: string, dbName: string): Promise<ExecResult>;
+export interface MigrationApplied {
+    readonly version: string;
+    readonly success: boolean;
+    readonly stderr: string;
+}
+export interface MigrationRunResult {
+    readonly applied: readonly MigrationApplied[];
+    readonly skipped: readonly string[];
+    readonly success: boolean;
+}
+/**
+ * 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 declare function dbRunMigrations(cfg: HostConfig, dbName: string, migrationsDir: string): Promise<MigrationRunResult>;
+/**
+ * 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 declare function dbSelectJson<T = Record<string, unknown>>(cfg: HostConfig, dbName: string, innerSelect: string): Promise<T[]>;
+/**
+ * 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 declare function dbExec(cfg: HostConfig, dbName: string, sql: string): Promise<ExecResult>;
+//# sourceMappingURL=db.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../../src/lib/ops/db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,UAAU,CAAA;AAyB3D;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAKhF;AAMD;;;GAGG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAKhF;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAe5F;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,UAAU,EACf,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,UAAU,CAAC,CAwDrB;AAMD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAA;IAC7C,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,UAAU,EACf,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,kBAAkB,CAAC,CA6D7B;AA+CD;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5D,GAAG,EAAE,UAAU,EACf,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,CAAC,EAAE,CAAC,CAiBd;AAED;;;;;;GAMG;AACH,wBAAsB,MAAM,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAE9F"}