charness 3.0.0 → 3.2.0

package/dist/legacyMigration.js

@@ -0,0 +1,338 @@
+"use strict";
+/**
+ * @description The automatic, idempotent move from the pre-rename names to the
+ * Charness ones, run at a COLD start of the bot: the global config dir
+ * (`~/.config/telegramcode`, older `~/.config/telegram-code` → `~/.config/charness`)
+ * and the default data dir (`~/.telegramCode` → `~/.charness`). Each moved dir
+ * leaves a relative SYMLINK at its old path, so a tmux / json-stream agent that
+ * still holds an old absolute path, an external script and an older mirror keep
+ * working. `legacyNames.ts` stays the read-fallback for whatever this does not
+ * (or could not) move.
+ *
+ * WHEN it runs — and the rules that keep it safe:
+ *  - cold start only: the plain `charness` start and the hot SUPERVISOR's start.
+ *    A hot WORKER reload never migrates (its supervisor, possibly the pre-rename
+ *    code, still holds paths in the data dir — the caller passes nothing and
+ *    this module is never reached from the worker).
+ *  - under the instance lock, before the state is loaded (the caller acquires
+ *    it; {@link migrateLegacyNamesUnderLock} takes it itself for the supervisor).
+ *  - never for an isolated instance (`ENV_FILE`): it reads only its own file and
+ *    its own dirs, and the shared config and default data dir belong to another
+ *    bot. Never for an explicit `DATA_DIR`, whatever it names.
+ *  - idempotent: a target that exists, or an old path that is already a symlink
+ *    (ours, or the operator's own), skips the step; nothing is ever deleted; a
+ *    failed step is logged and leaves BOTH sides usable (a failed symlink rolls
+ *    the move back).
+ *  - `TELEGRAMCODE_*` keys are renamed to `CHARNESS_*` only in the global config
+ *    file this migration moved (a `.bak` copy first). `ENV_FILE` and `$PWD/.env`
+ *    are never rewritten: the first is the operator's own, possibly read-only
+ *    and mounted into a container; the second belongs to whatever project the
+ *    bot was launched from.
+ *
+ * One log line per action taken. A step that is skipped because there is nothing
+ * to do is silent, so a second start prints nothing.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasPendingLegacyMigration = hasPendingLegacyMigration;
+exports.migrateLegacyNames = migrateLegacyNames;
+exports.migrateLegacyNamesUnderLock = migrateLegacyNamesUnderLock;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const legacyNames_1 = require("./legacyNames");
+const instanceLock_1 = require("./instanceLock");
+/** The pre-rename key prefix in a config file, and what it becomes. */
+const legacyEnvKeyPrefix = 'TELEGRAMCODE_';
+const currentEnvKeyPrefix = 'CHARNESS_';
+const envFileName = '.env';
+const envBackupSuffix = '.bak';
+function resolveOptions(options) {
+    return {
+        homeDir: options.homeDir ?? os.homedir(),
+        env: options.env ?? process.env,
+        log: options.log ?? ((line) => process.stderr.write(`${line}\n`)),
+        warn: options.warn ?? ((line) => process.stderr.write(`${line}\n`)),
+        fsOps: options.fsOps ?? fs,
+    };
+}
+function getPathKind(fsOps, target) {
+    try {
+        const stat = fsOps.lstatSync(target);
+        if (stat.isSymbolicLink())
+            return 'symlink';
+        return stat.isDirectory() ? 'directory' : 'other';
+    }
+    catch (error) {
+        return error.code === 'ENOENT' ? 'missing' : 'other';
+    }
+}
+function describePath(homeDir, target) {
+    return target.startsWith(`${homeDir}${path.sep}`) ? `~${target.slice(homeDir.length)}` : target;
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** The pre-rename keys a config file still carries that can be renamed (no `CHARNESS_` twin yet). */
+function findRenamableEnvKeys(content) {
+    const definedKeys = new Set();
+    for (const match of content.matchAll(/^[ \t]*(?:export[ \t]+)?([A-Za-z_][A-Za-z0-9_]*)[ \t]*=/gm)) {
+        definedKeys.add(match[1]);
+    }
+    const renamable = [];
+    for (const key of definedKeys) {
+        if (!key.startsWith(legacyEnvKeyPrefix) || key.length === legacyEnvKeyPrefix.length)
+            continue;
+        if (!definedKeys.has(`${currentEnvKeyPrefix}${key.slice(legacyEnvKeyPrefix.length)}`))
+            renamable.push(key);
+    }
+    return renamable;
+}
+function readEnvFileIfPresent(fsOps, filePath) {
+    try {
+        return String(fsOps.readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * @description What a migration would do right now, in order. Reads the file
+ * system only. An isolated instance (`ENV_FILE`) plans nothing.
+ */
+function planMigration(options) {
+    const { homeDir, env, fsOps } = options;
+    if (env.ENV_FILE)
+        return [];
+    const steps = [];
+    const configRoot = path.join(homeDir, '.config');
+    const canonicalConfigDir = path.join(configRoot, legacyNames_1.configDirName);
+    const canonicalConfigKind = getPathKind(fsOps, canonicalConfigDir);
+    const legacyConfigDirs = legacyNames_1.legacyConfigDirNames.map((name) => path.join(configRoot, name));
+    const movableConfigDir = canonicalConfigKind === 'missing'
+        ? legacyConfigDirs.find((dir) => getPathKind(fsOps, dir) === 'directory')
+        : undefined;
+    if (movableConfigDir !== undefined) {
+        steps.push({ kind: 'move-dir', area: 'config', from: movableConfigDir, to: canonicalConfigDir });
+        steps.push({ kind: 'rename-env-keys', envFile: path.join(canonicalConfigDir, envFileName), legacyDir: movableConfigDir });
+    }
+    else if (canonicalConfigKind === 'directory') {
+        // A move of an earlier start whose key rename failed: the old path is our symlink to the canonical dir.
+        const envFile = path.join(canonicalConfigDir, envFileName);
+        const linkedLegacyDir = legacyConfigDirs.find((dir) => isSymlinkTo(fsOps, dir, canonicalConfigDir));
+        const content = linkedLegacyDir === undefined ? null : readEnvFileIfPresent(fsOps, envFile);
+        if (linkedLegacyDir !== undefined && content !== null && findRenamableEnvKeys(content).length > 0) {
+            steps.push({ kind: 'rename-env-keys', envFile, legacyDir: linkedLegacyDir });
+        }
+    }
+    // An explicit DATA_DIR is the operator's, whatever it names.
+    if (!env.DATA_DIR) {
+        const legacyDataDir = path.join(homeDir, legacyNames_1.legacyDefaultDataDirName);
+        const canonicalDataDir = path.join(homeDir, legacyNames_1.defaultDataDirName);
+        if (getPathKind(fsOps, legacyDataDir) === 'directory' && getPathKind(fsOps, canonicalDataDir) === 'missing') {
+            steps.push({ kind: 'move-dir', area: 'data', from: legacyDataDir, to: canonicalDataDir });
+        }
+    }
+    return steps;
+}
+function isSymlinkTo(fsOps, linkPath, targetDir) {
+    if (getPathKind(fsOps, linkPath) !== 'symlink')
+        return false;
+    try {
+        return fsOps.realpathSync(linkPath) === fsOps.realpathSync(targetDir);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * @description Whether a start has anything to migrate — cheap, so the hot
+ * supervisor takes the instance lock only when it will use it.
+ */
+function hasPendingLegacyMigration(options = {}) {
+    return planMigration(resolveOptions(options)).length > 0;
+}
+/**
+ * Rename the dir and leave a relative symlink at the old path. If the symlink
+ * cannot be made the move is undone, so the old path never ends up missing.
+ */
+function moveDirLeavingSymlink(fsOps, from, to, warn) {
+    fsOps.renameSync(from, to);
+    try {
+        fsOps.symlinkSync(path.basename(to), from);
+    }
+    catch (symlinkError) {
+        try {
+            fsOps.renameSync(to, from);
+        }
+        catch (rollbackError) {
+            warn(`[migrate] ${from} was moved to ${to} and the symlink back failed (${describeError(symlinkError)}), ` +
+                `and so did undoing the move (${describeError(rollbackError)}): link ${from} to ${to} by hand`);
+        }
+        throw symlinkError;
+    }
+}
+function findFreeBackupPath(fsOps, envFile) {
+    const firstChoice = `${envFile}${envBackupSuffix}`;
+    return fsOps.existsSync(firstChoice) ? `${firstChoice}.${Date.now()}` : firstChoice;
+}
+/**
+ * Rename `TELEGRAMCODE_*` keys to `CHARNESS_*` in one file, after a backup copy.
+ * The file's mode and a symlinked file's link are kept (the real file is
+ * rewritten in place by rename). Returns the keys renamed.
+ */
+function renameEnvFileKeys(fsOps, envFile) {
+    let realFile;
+    try {
+        realFile = fsOps.realpathSync(envFile);
+    }
+    catch (error) {
+        // A config dir without a `.env` has no keys to rename.
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    const content = String(fsOps.readFileSync(realFile, 'utf8'));
+    const keys = findRenamableEnvKeys(content);
+    if (keys.length === 0)
+        return null;
+    const renamedKeys = new Set(keys);
+    const rewritten = content.replace(/^([ \t]*(?:export[ \t]+)?)(TELEGRAMCODE_[A-Za-z0-9_]+)(?=[ \t]*=)/gm, (whole, prefix, key) => renamedKeys.has(key) ? `${prefix}${currentEnvKeyPrefix}${key.slice(legacyEnvKeyPrefix.length)}` : whole);
+    if (rewritten === content)
+        return null;
+    const mode = fsOps.lstatSync(realFile).mode & 0o777;
+    const backupPath = findFreeBackupPath(fsOps, realFile);
+    fsOps.copyFileSync(realFile, backupPath, fs.constants.COPYFILE_EXCL);
+    const tempPath = `${realFile}.tmp-${process.pid}`;
+    try {
+        fsOps.writeFileSync(tempPath, rewritten, { mode });
+        fsOps.chmodSync(tempPath, mode);
+        fsOps.renameSync(tempPath, realFile);
+    }
+    catch (error) {
+        try {
+            fsOps.unlinkSync(tempPath);
+        }
+        catch {
+            // never written
+        }
+        throw error;
+    }
+    return { keys, backupPath };
+}
+/**
+ * @description Run the migration. The CALLER holds the instance lock. Safe to
+ * call on every cold start: with nothing to do it does nothing and says nothing.
+ */
+function migrateLegacyNames(options = {}) {
+    const resolved = resolveOptions(options);
+    const { homeDir, fsOps } = resolved;
+    const result = { actions: [], failures: [] };
+    const logAction = (line) => {
+        result.actions.push(line);
+        resolved.log(line);
+    };
+    const logFailure = (line) => {
+        result.failures.push(line);
+        resolved.warn(line);
+    };
+    const failedMoves = new Set();
+    for (const step of planMigration(resolved)) {
+        if (step.kind === 'move-dir') {
+            const fromLabel = describePath(homeDir, step.from);
+            const toLabel = describePath(homeDir, step.to);
+            try {
+                moveDirLeavingSymlink(fsOps, step.from, step.to, resolved.warn);
+                logAction(`[migrate] moved ${fromLabel} to ${toLabel}; ${fromLabel} is now a symlink to it`);
+                if (step.area === 'data')
+                    (0, legacyNames_1.redecideDefaultDataDir)(homeDir);
+            }
+            catch (error) {
+                failedMoves.add(step.from);
+                logFailure(`[migrate] could not move ${fromLabel} to ${toLabel} (${describeError(error)}): it stays where it is and ` +
+                    `is still used; move it by hand with the bot stopped (see ${legacyNames_1.renameMigrationDoc})`);
+            }
+            continue;
+        }
+        if (failedMoves.has(step.legacyDir))
+            continue;
+        const envLabel = describePath(homeDir, step.envFile);
+        try {
+            const renamed = renameEnvFileKeys(fsOps, step.envFile);
+            if (renamed === null)
+                continue;
+            logAction(`[migrate] renamed ${renamed.keys.length} key(s) ${legacyEnvKeyPrefix}* to ${currentEnvKeyPrefix}* in ` +
+                `${envLabel} (${renamed.keys.join(', ')}); the old file is kept as ${describePath(homeDir, renamed.backupPath)}`);
+        }
+        catch (error) {
+            logFailure(`[migrate] could not rename the ${legacyEnvKeyPrefix}* keys in ${envLabel} (${describeError(error)}): ` +
+                `rename them by hand (see ${legacyNames_1.renameMigrationDoc})`);
+        }
+    }
+    return result;
+}
+/**
+ * @description The hot SUPERVISOR's cold start: take the instance lock for the
+ * length of the migration. A lock held by a live instance (or any failure to
+ * take it) skips the migration and says why; the next start tries again.
+ */
+function migrateLegacyNamesUnderLock(options = {}) {
+    const resolved = resolveOptions(options);
+    const empty = { actions: [], failures: [] };
+    if (!hasPendingLegacyMigration(options))
+        return empty;
+    let lock;
+    try {
+        lock = (0, instanceLock_1.tryAcquireLock)();
+    }
+    catch (error) {
+        const line = `[migrate] skipped: the instance lock could not be taken (${describeError(error)})`;
+        resolved.warn(line);
+        return { actions: [], failures: [line] };
+    }
+    if (!lock.ok) {
+        const line = `[migrate] skipped: another instance holds the lock on this data dir (${lock.reason}); ` +
+            `the old names keep working and the next cold start tries again`;
+        resolved.warn(line);
+        return { actions: [], failures: [line] };
+    }
+    try {
+        return migrateLegacyNames(options);
+    }
+    finally {
+        (0, instanceLock_1.releaseLock)();
+    }
+}
+//# sourceMappingURL=legacyMigration.js.map

package/dist/legacyMigration.js.map

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

package/dist/legacyNames.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @description The names the project had before it was renamed from TelegramCode
+ * to Charness, and the one place that knows how a running instance falls back to
+ * them.
+ *
+ * WHY a fallback exists: instances hot-reload `main`, so for a while old and new
+ * code meet — the hot SUPERVISOR keeps running the code it was started with (and
+ * keeps setting the old env var names for each new worker), other hosts' mirrors
+ * pull the rename without moving their data dir, and a running agent keeps the
+ * MCP header its launch config named. Every renamed name is therefore read as
+ * `new ?? old`, the old one only as a fallback, and each use of a fallback is
+ * announced ONCE per process, naming the migration doc.
+ *
+ * Nothing here moves a user's file: the fallback only decides which existing path
+ * is read. Moving them is `legacyMigration.ts`'s job, at a cold start.
+ */
+/** The document an operator or an agent finds the old → new table and the steps in. */
+export declare const renameMigrationDoc = "MIGRATION_RENAME_TO_CHARNESS.md";
+/** Default `DATA_DIR` under the home dir, and the one the pre-rename releases used. */
+export declare const defaultDataDirName = ".charness";
+export declare const legacyDefaultDataDirName = ".telegramCode";
+/**
+ * Per-user config dir under `~/.config`, and the ones earlier releases used,
+ * newest first: `telegramcode` before the rename, `telegram-code` before that.
+ */
+export declare const configDirName = "charness";
+export declare const legacyConfigDirNames: readonly string[];
+/** A renamed environment variable: the current name and the one earlier releases used. */
+export interface RenamedEnvName {
+    current: string;
+    legacy: string;
+}
+/**
+ * The supervisor → worker handshake of hot mode (`charness hot`). An operator
+ * never sets these: the supervisor does, so a legacy one reaching a worker means
+ * the supervisor still runs pre-rename code.
+ */
+export declare const hotReloadEnvName: RenamedEnvName;
+export declare const openCodeProcessFileEnvName: RenamedEnvName;
+/**
+ * @description The value of a renamed variable: the current name wins, the legacy
+ * one is the fallback. An empty value counts as unset, as everywhere the bot
+ * reads these.
+ */
+export declare function readRenamedEnv(env: NodeJS.ProcessEnv, name: RenamedEnvName): string | undefined;
+/**
+ * @description The default `DATA_DIR` (no explicit `DATA_DIR`): `~/.charness`,
+ * except that an existing `~/.telegramCode` is kept while `~/.charness` does not
+ * exist — an install made before the rename keeps its state where it is. A
+ * `~/.charness` that holds no `state.json` while `~/.telegramCode` does (made by
+ * hand, or as the parent of another instance's explicit `DATA_DIR`) does not
+ * take over either: the bot would start with none of its bindings. Never creates
+ * or moves anything.
+ *
+ * Decided ONCE per process and home dir: several modules resolve their paths at
+ * load and others at every call, and a `~/.charness` that appears while the
+ * process runs (the console tee creates it on a fresh install; an operator may
+ * `mkdir` it) must not make the two halves disagree until the next restart.
+ */
+export declare function resolveDefaultDataDir(homeDir?: string): string;
+/**
+ * @description Decide the default `DATA_DIR` again, forgetting the earlier
+ * decision — for the one place that moves the dir (`legacyMigration.ts`), so the
+ * rest of the process sees the new path from then on.
+ */
+export declare function redecideDefaultDataDir(homeDir?: string): string;
+/** @description `~/.config/<dirName>/.env` under `homeDir`. */
+export declare function buildGlobalConfigEnvPath(dirName: string, homeDir?: string): string;
+/**
+ * @description The per-user global config file: `~/.config/charness/.env`, else
+ * the first existing of the earlier releases' dirs. When none exists the
+ * canonical path is returned — the location a fresh install should use. Nothing
+ * is moved.
+ */
+export declare function resolveGlobalConfigEnvPath(homeDir?: string): string;
+/** @description The deprecation line every fallback prints: what to rename, to what, and where it is written down. */
+export declare function formatDeprecation(legacyName: string, currentName: string): string;
+type WriteLine = (text: string) => void;
+/**
+ * @description Print one deprecation line, once per process per `key`. Returns
+ * whether it printed. The default sink is `process.stderr` (read at call time, so
+ * the console tee sees it).
+ */
+export declare function warnLegacyNameOnce(key: string, message: string, write?: WriteLine): boolean;
+/** Forget what was announced and decided — for tests, which assert the once-only rules per case. */
+export declare function resetLegacyNameState(): void;
+/** One fallback in use at boot. */
+export interface LegacyNameUse {
+    key: string;
+    message: string;
+}
+/**
+ * @description Every legacy name the environment and the home dir make the
+ * process fall back to right now: a legacy supervisor variable with no current
+ * one, the global config dir when it is a pre-rename one, and the default data
+ * dir when it is the pre-rename one. (The MCP header and the plugin file are
+ * announced where they are seen.)
+ */
+export declare function findLegacyNameUses(env?: NodeJS.ProcessEnv, homeDir?: string): LegacyNameUse[];
+/**
+ * @description The boot-time announcement: print each fallback in use, once per
+ * process. Called by the plain start (after the console tee, so it reaches the
+ * bot log) and by the hot supervisor.
+ */
+export declare function warnLegacyNamesAtBoot(env?: NodeJS.ProcessEnv, homeDir?: string, write?: WriteLine): void;
+export {};
+//# sourceMappingURL=legacyNames.d.ts.map

package/dist/legacyNames.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacyNames.d.ts","sourceRoot":"","sources":["../src/legacyNames.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,uFAAuF;AACvF,eAAO,MAAM,kBAAkB,oCAAoC,CAAC;AAEpE,uFAAuF;AACvF,eAAO,MAAM,kBAAkB,cAAc,CAAC;AAC9C,eAAO,MAAM,wBAAwB,kBAAkB,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,aAAa,aAAa,CAAC;AACxC,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAAsC,CAAC;AAEzF,0FAA0F;AAC1F,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,cAG9B,CAAC;AACF,eAAO,MAAM,0BAA0B,EAAE,cAGxC,CAAC;AAGF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAE/F;AAOD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,MAAqB,GAAG,MAAM,CAY5E;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,MAAqB,GAAG,MAAM,CAG7E;AAED,+DAA+D;AAC/D,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAqB,GAAG,MAAM,CAEhG;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,MAAqB,GAAG,MAAM,CAQjF;AAED,sHAAsH;AACtH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED,KAAK,SAAS,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAQxC;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,SAAyB,GAAG,OAAO,CAK1G;AAED,oGAAoG;AACpG,wBAAgB,oBAAoB,IAAI,IAAI,CAG3C;AAED,mCAAmC;AACnC,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAqB,GAC7B,aAAa,EAAE,CA+BjB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,MAAqB,EAC9B,KAAK,GAAE,SAAyB,GAC/B,IAAI,CAEN"}