@withandeo/cli 0.19.11 → 0.19.12

package/dist/update-storage.d.ts

@@ -0,0 +1,3 @@
+export declare function atomicJson(path: string, value: unknown): Promise<void>;
+export declare function withUpdateLock<T>(path: string, action: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=update-storage.d.ts.map

package/dist/update-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-storage.d.ts","sourceRoot":"","sources":["../src/update-storage.ts"],"names":[],"mappings":"AAKA,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAO5E;AAID,wBAAsB,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAsB1F"}

package/dist/update-storage.js

@@ -0,0 +1,69 @@
+import { lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+import { CliError } from "./errors.js";
+export async function atomicJson(path, value) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+// A dead process may leave a lock. Reclaim only locks whose recorded process
+// definitely no longer exists, never a live installer or a malformed lock.
+export async function withUpdateLock(path, action) {
+    await mkdir(dirname(path), { recursive: true });
+    try {
+        await mkdir(path);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        const recovery = `${path}.recovery`;
+        try {
+            await mkdir(recovery);
+        }
+        catch {
+            throw busy();
+        }
+        try {
+            const info = await lstat(path);
+            if (info.isSymbolicLink() || !info.isDirectory())
+                throw busy();
+            const pid = Number(await readFile(`${path}/pid`, "utf8").catch(() => ""));
+            if (!Number.isSafeInteger(pid) || pid <= 0)
+                throw busy();
+            try {
+                process.kill(pid, 0);
+                throw busy();
+            }
+            catch (failure) {
+                if (failure.code !== "ESRCH")
+                    throw failure;
+            }
+            await rm(path, { recursive: true });
+            try {
+                await mkdir(path);
+            }
+            catch {
+                throw busy();
+            }
+        }
+        finally {
+            await rm(recovery, { recursive: true, force: true });
+        }
+    }
+    try {
+        await writeFile(`${path}/pid`, String(process.pid), { flag: "wx", mode: 0o600 });
+        return await action();
+    }
+    finally {
+        await rm(path, { recursive: true, force: true });
+    }
+}
+function busy() { return new CliError("update_busy", "Another Andeo update is in progress. Retry after it finishes."); }
+//# sourceMappingURL=update-storage.js.map

package/dist/update-storage.js.map

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

package/dist/updates.d.ts

@@ -0,0 +1,52 @@
+export declare const CLI_PACKAGE_DIRECTORY: string;
+type Manager = "npm" | "pnpm" | "yarn";
+export type UpdateRunner = (command: string, args: string[], cwd: string, environment: NodeJS.ProcessEnv) => Promise<string>;
+export declare const runUpdateCommand: UpdateRunner;
+export interface UpdateRuntime {
+    version: string;
+    homeDirectory: string;
+    cwd: string;
+    environment: NodeJS.ProcessEnv;
+    packageDirectory: string;
+    fetcher: typeof fetch;
+    runner: UpdateRunner;
+    now(): number;
+    notify(message: string): void;
+}
+export declare function defaultUpdateRuntime(version: string): UpdateRuntime;
+export declare function configureAutoUpgrade(action: string, runtime: UpdateRuntime): Promise<{
+    enabled: boolean;
+    cadence: string;
+    automaticRange: string;
+    scope: string;
+    skillSync: string;
+    lastCheck: number | null;
+}>;
+export declare function detectGlobalInstallation(runtime: UpdateRuntime): Promise<{
+    manager: Manager;
+    root: string;
+} | null>;
+interface Release {
+    version: string;
+    engines?: {
+        node?: string;
+    };
+    dist?: {
+        tarball: string;
+        integrity: string;
+    };
+}
+export declare function automaticRelease(current: string, available: Release[]): Release | undefined;
+export declare function upgradeCli(runtime: UpdateRuntime): Promise<{
+    status: string;
+    previousVersion: string;
+    version: string;
+    manager: Manager;
+    message: string;
+} | {
+    status: string;
+    version: string;
+}>;
+export declare function maintainCli(argv: string[], runtime: UpdateRuntime): Promise<void>;
+export {};
+//# sourceMappingURL=updates.d.ts.map

package/dist/updates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updates.d.ts","sourceRoot":"","sources":["../src/updates.ts"],"names":[],"mappings":"AAgBA,eAAO,MAAM,qBAAqB,QAAiD,CAAC;AACpF,KAAK,OAAO,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;AACvC,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,UAAU,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAI7H,eAAO,MAAM,gBAAgB,EAAE,YAM7B,CAAC;AAEH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC,UAAU,CAAC;IAC/B,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,OAAO,KAAK,CAAC;IACtB,MAAM,EAAE,YAAY,CAAC;IACrB,GAAG,IAAI,MAAM,CAAC;IACd,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAInE;AAgBD,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa;;;;;;;GAYhF;AAQD,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAoBzH;AAED,UAAU,OAAO;IAAG,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE;AAmCjH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,OAAO,GAAG,SAAS,CAO3F;AA2DD,wBAAsB,UAAU,CAAC,OAAO,EAAE,aAAa;;;;;;;;;GAStD;AAID,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CA4CvF"}

package/dist/updates.js

@@ -0,0 +1,297 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { lstat, mkdir, mkdtemp, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import semver from "semver";
+import { CliError } from "./errors.js";
+import { syncDocumentation } from "./documentation.js";
+import { atomicJson, withUpdateLock } from "./update-storage.js";
+const PACKAGE = "@withandeo/cli";
+const REGISTRY_ORIGIN = "https://registry.npmjs.org";
+const REGISTRY = `${REGISTRY_ORIGIN}/@withandeo%2fcli`;
+const MAX_ARCHIVE_BYTES = 64 * 1024 * 1024;
+const DAY = 24 * 60 * 60 * 1000;
+export const CLI_PACKAGE_DIRECTORY = fileURLToPath(new URL("../", import.meta.url));
+// No shell, no elevation, bounded output and runtime. Child output never enters
+// CLI stdout or exposes package-manager configuration/credentials on failure.
+export const runUpdateCommand = (command, args, cwd, environment) => new Promise((accept, reject) => {
+    const installing = args[0] === "install" || args[0] === "global" && args[1] === "add";
+    execFile(command, args, { cwd, env: environment, timeout: installing ? 60_000 : 3000, maxBuffer: 1024 * 1024 }, (error, stdout) => {
+        if (error)
+            reject(new CliError("cli_upgrade_failed", "The package-manager command failed or timed out. Retry andeo upgrade, or update using your package manager."));
+        else
+            accept(stdout.trim());
+    });
+});
+export function defaultUpdateRuntime(version) {
+    return { version, homeDirectory: homedir(), cwd: process.cwd(), environment: process.env,
+        packageDirectory: CLI_PACKAGE_DIRECTORY, fetcher: fetch, runner: runUpdateCommand,
+        now: Date.now, notify: message => { process.stderr.write(`${message}\n`); } };
+}
+function directory(runtime) { return resolve(runtime.homeDirectory, ".config/andeo/updates"); }
+async function settings(runtime) {
+    try {
+        const value = JSON.parse(await readFile(join(directory(runtime), "settings.json"), "utf8"));
+        if (value?.schema !== "andeo.updates/v1" || typeof value.autoUpgrade !== "boolean"
+            || value.lastCheck !== undefined && (!Number.isSafeInteger(value.lastCheck) || value.lastCheck < 0))
+            throw new Error();
+        return value;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { schema: "andeo.updates/v1", autoUpgrade: true };
+        throw new CliError("update_config_invalid", "Andeo update settings could not be read. Repair ~/.config/andeo/updates/settings.json before updating.");
+    }
+}
+export async function configureAutoUpgrade(action, runtime) {
+    if (!["on", "off", "status"].includes(action))
+        throw new CliError("argument_invalid", "Use andeo config autoupgrade on|off|status.");
+    return withUpdateLock(join(directory(runtime), ".lock"), async () => {
+        const state = await settings(runtime);
+        if (action !== "status") {
+            state.autoUpgrade = action === "on";
+            delete state.lastCheck;
+            await atomicJson(join(directory(runtime), "settings.json"), state);
+        }
+        return { enabled: state.autoUpgrade, cadence: "daily", automaticRange: semver.major(runtime.version) === 0 ? "current_minor" : "current_major",
+            scope: "verified_global_installs", skillSync: "independent", lastCheck: state.lastCheck ?? null };
+    });
+}
+function ci(environment) {
+    return ["CI", "CONTINUOUS_INTEGRATION", "BUILD_NUMBER", "GITHUB_ACTIONS", "TF_BUILD"].some(key => {
+        const value = environment[key];
+        return !!value && !["0", "false"].includes(value.toLowerCase());
+    });
+}
+export async function detectGlobalInstallation(runtime) {
+    const actual = await realpath(runtime.packageDirectory);
+    // Source checkouts and temporary package-runner caches cannot own a global
+    // install. npm's execution environment alone is not proof of installation.
+    if (!actual.replaceAll("\\", "/").includes("/node_modules/")
+        || /(?:^|[/\\])(?:_npx|_cacache|dlx)(?:[/\\]|$)/u.test(actual))
+        return null;
+    const candidates = [
+        { manager: "pnpm", args: ["root", "-g"] },
+        { manager: "yarn", args: ["global", "dir"] },
+        { manager: "npm", args: ["root", "-g"] },
+    ];
+    for (const { manager, args } of candidates) {
+        try {
+            const output = (await runtime.runner(manager, args, runtime.homeDirectory, runtime.environment)).trim();
+            if (!isAbsolute(output) || output.includes("\n"))
+                continue;
+            const root = manager === "yarn" ? join(output, "node_modules") : output;
+            if (await realpath(join(root, PACKAGE)) === actual)
+                return { manager, root };
+        }
+        catch { /* An unavailable or unrelated manager does not establish ownership. */ }
+    }
+    return null;
+}
+async function releases(runtime) {
+    let response;
+    try {
+        response = await runtime.fetcher(REGISTRY, { redirect: "error", credentials: "omit", signal: AbortSignal.timeout(5000),
+            headers: { accept: "application/vnd.npm.install-v1+json" } });
+    }
+    catch {
+        throw new CliError("cli_update_unavailable", "Could not check Andeo CLI releases; the installed CLI was retained.");
+    }
+    if (!response.ok || !response.body) {
+        await response.body?.cancel();
+        throw new CliError("cli_update_unavailable", "Could not check Andeo CLI releases; the installed CLI was retained.");
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let length = 0;
+    try {
+        while (true) {
+            const item = await reader.read();
+            if (item.done)
+                break;
+            length += item.value.byteLength;
+            if (length > 4 * 1024 * 1024) {
+                await reader.cancel();
+                throw new Error();
+            }
+            chunks.push(item.value);
+        }
+        const value = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        const latestVersion = value?.["dist-tags"]?.latest;
+        if (value.name !== PACKAGE || typeof latestVersion !== "string" || !semver.valid(latestVersion) || semver.prerelease(latestVersion)
+            || !value.versions || typeof value.versions !== "object")
+            throw new Error();
+        const versions = Object.entries(value.versions).flatMap(([version, info]) => {
+            if (!semver.valid(version) || semver.prerelease(version) || !info || typeof info !== "object"
+                || info.version !== version)
+                return [];
+            const engines = info.engines;
+            if (engines?.node !== undefined && (typeof engines.node !== "string" || !semver.validRange(engines.node)))
+                return [];
+            return [{ version, ...(engines ? { engines } : {}), dist: info.dist }];
+        });
+        const latest = versions.find(release => release.version === latestVersion);
+        if (!latest)
+            throw new Error();
+        return { latest, versions };
+    }
+    catch {
+        throw new CliError("cli_update_invalid", "The Andeo release response was invalid; the installed CLI was retained.");
+    }
+}
+export function automaticRelease(current, available) {
+    return available.filter(release => semver.gt(release.version, current)
+        && !semver.prerelease(release.version)
+        && semver.major(release.version) === semver.major(current)
+        && (semver.major(current) !== 0 || semver.minor(release.version) === semver.minor(current))
+        && semver.satisfies(process.versions.node, release.engines?.node ?? "*"))
+        .sort((a, b) => semver.rcompare(a.version, b.version))[0];
+}
+async function installRelease(release, installation, runtime) {
+    if (!semver.satisfies(process.versions.node, release.engines?.node ?? "*"))
+        throw new CliError("cli_node_upgrade_required", `CLI ${release.version} requires Node ${release.engines?.node}; upgrade Node before upgrading the CLI.`);
+    // An older process must not roll back a concurrently upgraded installation.
+    if (await installedVersion(installation.root) !== runtime.version)
+        throw new CliError("cli_installation_changed", "The installed CLI changed while this command was running. Retry with the current CLI.");
+    const archive = await verifiedArchive(release, runtime);
+    const args = installation.manager === "yarn" ? ["global", "add", archive] : ["install", "-g", archive];
+    args.push(`--registry=${REGISTRY_ORIGIN}/`);
+    await runtime.runner(installation.manager, args, runtime.homeDirectory, runtime.environment);
+    if (await installedVersion(installation.root) !== release.version)
+        throw new CliError("cli_upgrade_failed", "The package manager did not install the verified CLI version. Update through your package manager before syncing guidance.");
+    return { status: "updated", previousVersion: runtime.version, version: release.version, manager: installation.manager,
+        message: "The next Andeo invocation uses the updated CLI." };
+}
+async function installedVersion(root) {
+    try {
+        const value = JSON.parse(await readFile(join(root, PACKAGE, "package.json"), "utf8"));
+        return value.name === PACKAGE && typeof value.version === "string" && semver.valid(value.version) ? value.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function verifiedArchive(release, runtime) {
+    // Bind the executable bytes to the metadata we checked, not a second name
+    // resolution through a user's scoped registry, mirror, or package-manager cache.
+    const expectedUrl = `${REGISTRY_ORIGIN}/${PACKAGE}/-/cli-${release.version}.tgz`;
+    if (release.dist?.tarball !== expectedUrl || !/^sha512-[A-Za-z0-9+/]{86}==$/u.test(release.dist?.integrity ?? ""))
+        throw new CliError("cli_update_invalid", "The CLI release is missing a trusted archive URL or SHA-512 integrity. The installed CLI was retained.");
+    let bytes;
+    try {
+        const response = await runtime.fetcher(expectedUrl, { redirect: "error", credentials: "omit", signal: AbortSignal.timeout(30_000) });
+        if (!response.ok || !response.body) {
+            await response.body?.cancel();
+            throw new Error();
+        }
+        const reader = response.body.getReader(), chunks = [];
+        let length = 0;
+        while (true) {
+            const item = await reader.read();
+            if (item.done)
+                break;
+            length += item.value.byteLength;
+            if (length > MAX_ARCHIVE_BYTES) {
+                await reader.cancel();
+                throw new Error();
+            }
+            chunks.push(item.value);
+        }
+        bytes = Buffer.concat(chunks);
+        if (`sha512-${createHash("sha512").update(bytes).digest("base64")}` !== release.dist.integrity)
+            throw new Error();
+    }
+    catch {
+        throw new CliError("cli_update_invalid", "The CLI archive could not be downloaded and verified. The installed CLI was retained.");
+    }
+    const archives = join(directory(runtime), "packages");
+    await mkdir(archives, { recursive: true, mode: 0o700 });
+    const stage = await mkdtemp(join(archives, ".download-"));
+    // pnpm and Yarn record file specs in their global manifest. Keep immutable,
+    // content-addressed archives available for subsequent manager operations.
+    const archive = join(archives, `cli-${release.version}-${createHash("sha256").update(bytes).digest("hex")}.tgz`);
+    try {
+        await writeFile(join(stage, "cli.tgz"), bytes, { mode: 0o600, flag: "wx" });
+        await rename(join(stage, "cli.tgz"), archive);
+    }
+    finally {
+        await rm(stage, { recursive: true, force: true });
+    }
+    return archive;
+}
+export async function upgradeCli(runtime) {
+    if (ci(runtime.environment))
+        throw new CliError("cli_upgrade_skipped", "CI uses its pinned CLI. Update the dependency through your package manager.");
+    return withUpdateLock(join(directory(runtime), ".lock"), async () => {
+        const installation = await detectGlobalInstallation(runtime);
+        if (!installation)
+            throw new CliError("cli_installation_unmanaged", "Only verified global npm, pnpm or Yarn 1 installations can self-upgrade. Update this installation through its package manager.");
+        const { latest } = await releases(runtime);
+        if (!semver.gt(latest.version, runtime.version))
+            return { status: "up_to_date", version: runtime.version };
+        return installRelease(latest, installation, runtime);
+    });
+}
+// Called only by the executable after a successful normal command. Help,
+// version and explicit maintenance commands remain quick and side-effect free.
+export async function maintainCli(argv, runtime) {
+    if (ci(runtime.environment) || !argv.length || ["help", "version", "--version", "--help", "-h", "-v", "upgrade", "config", "skill"].includes(argv[0])
+        || argv.includes("--help") || argv.includes("-h"))
+        return;
+    try {
+        const snapshot = await settings(runtime);
+        if (snapshot.lastCheck !== undefined && runtime.now() - snapshot.lastCheck < DAY)
+            return;
+        const installation = await detectGlobalInstallation(runtime);
+        if (!installation)
+            return;
+        await withUpdateLock(join(directory(runtime), ".lock"), async () => {
+            const state = await settings(runtime);
+            if (state.lastCheck !== undefined && runtime.now() - state.lastCheck < DAY)
+                return;
+            // Record attempted checks too, so outages do not delay every invocation.
+            state.lastCheck = runtime.now();
+            await atomicJson(join(directory(runtime), "settings.json"), state);
+            let installedVersion = runtime.version;
+            try {
+                const { latest, versions } = await releases(runtime);
+                const eligible = automaticRelease(runtime.version, versions.filter(release => semver.lte(release.version, latest.version)));
+                if (state.autoUpgrade && eligible) {
+                    await installRelease(eligible, installation, runtime);
+                    installedVersion = eligible.version;
+                    runtime.notify(`Andeo CLI updated to ${eligible.version}; the next invocation uses it.`);
+                }
+                if (semver.gt(latest.version, installedVersion))
+                    runtime.notify(`Andeo CLI ${latest.version} is available. Run andeo upgrade to update explicitly.`);
+            }
+            catch {
+                runtime.notify("Andeo CLI update check or upgrade failed. Run andeo upgrade to retry; your command result is unchanged.");
+            }
+            for (const agent of [".agents", ".claude"]) {
+                const base = resolve(runtime.homeDirectory, agent, "skills");
+                if (!await lstat(resolve(base, "andeo")).catch(() => null))
+                    continue;
+                try {
+                    const result = await syncDocumentation(base, installedVersion, { fetcher: runtime.fetcher });
+                    if (result.status === "updated")
+                        runtime.notify("Andeo skill updated. Reread SKILL.md and relevant references before continuing in this chat.");
+                    else if (["local_changes", "unmanaged"].includes(result.status))
+                        runtime.notify(`Andeo skill ${result.status}: local files preserved. Run andeo skill status --json to inspect.`);
+                }
+                catch (error) {
+                    runtime.notify(error instanceof CliError && error.code === "skill_cli_upgrade_required"
+                        ? `${error.message} Run andeo upgrade, then andeo skill sync --json.`
+                        : "Andeo skill could not be refreshed; installed guidance retained. Run andeo skill sync --json to retry.");
+                }
+            }
+        });
+    }
+    catch (error) {
+        if (error instanceof CliError && error.code === "update_busy")
+            return;
+        runtime.notify("Andeo automatic maintenance could not complete. Run andeo config autoupgrade status to inspect settings.");
+    }
+}
+//# sourceMappingURL=updates.js.map

package/dist/updates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"updates.js","sourceRoot":"","sources":["../src/updates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpG,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAEjE,MAAM,OAAO,GAAG,gBAAgB,CAAC;AACjC,MAAM,eAAe,GAAG,4BAA4B,CAAC;AACrD,MAAM,QAAQ,GAAG,GAAG,eAAe,mBAAmB,CAAC;AACvD,MAAM,iBAAiB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAC3C,MAAM,GAAG,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAChC,MAAM,CAAC,MAAM,qBAAqB,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,KAAK,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAIpF,gFAAgF;AAChF,8EAA8E;AAC9E,MAAM,CAAC,MAAM,gBAAgB,GAAiB,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE;IAChH,MAAM,UAAU,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC;IACtF,QAAQ,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,GAAG,IAAI,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;QAChI,IAAI,KAAK;YAAE,MAAM,CAAC,IAAI,QAAQ,CAAC,oBAAoB,EAAE,6GAA6G,CAAC,CAAC,CAAC;;YAChK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAcH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,WAAW,EAAE,OAAO,CAAC,GAAG;QACtF,gBAAgB,EAAE,qBAAqB,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB;QACjF,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAClF,CAAC;AAGD,SAAS,SAAS,CAAC,OAAsB,IAAI,OAAO,OAAO,CAAC,OAAO,CAAC,aAAa,EAAE,uBAAuB,CAAC,CAAC,CAAC,CAAC;AAC9G,KAAK,UAAU,QAAQ,CAAC,OAAsB;IAC5C,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QAC5F,IAAI,KAAK,EAAE,MAAM,KAAK,kBAAkB,IAAI,OAAO,KAAK,CAAC,WAAW,KAAK,SAAS;eAC7E,KAAK,CAAC,SAAS,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,EAAE,CAAC;QACzH,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;QACjH,MAAM,IAAI,QAAQ,CAAC,uBAAuB,EAAE,wGAAwG,CAAC,CAAC;IACxJ,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,MAAc,EAAE,OAAsB;IAC/E,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,MAAM,IAAI,QAAQ,CAAC,kBAAkB,EAAE,6CAA6C,CAAC,CAAC;IACrI,OAAO,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,KAAK,IAAI,EAAE;QAClE,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC;QACtC,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;YACxB,KAAK,CAAC,WAAW,GAAG,MAAM,KAAK,IAAI,CAAC;YACpC,OAAO,KAAK,CAAC,SAAS,CAAC;YACvB,MAAM,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC,EAAE,KAAK,CAAC,CAAC;QACrE,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,eAAe;YAC5I,KAAK,EAAE,0BAA0B,EAAE,SAAS,EAAE,aAAa,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI,EAAE,CAAC;IACtG,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,EAAE,CAAC,WAA8B;IACxC,OAAO,CAAC,IAAI,EAAE,wBAAwB,EAAE,cAAc,EAAE,gBAAgB,EAAE,UAAU,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE;QAC/F,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QAAC,OAAO,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;IAClG,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,OAAsB;IACnE,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACxD,2EAA2E;IAC3E,2EAA2E;IAC3E,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,gBAAgB,CAAC;WACvD,8CAA8C,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9E,MAAM,UAAU,GAAgD;QAC9D,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE;QACzC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE;QAC5C,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE;KACzC,CAAC;IACF,KAAK,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,UAAU,EAAE,CAAC;QAC3C,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,aAAa,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YACxG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,SAAS;YAC3D,MAAM,IAAI,GAAG,OAAO,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YACxE,IAAI,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,KAAK,MAAM;gBAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC/E,CAAC;QAAC,MAAM,CAAC,CAAC,uEAAuE,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAGD,KAAK,UAAU,QAAQ,CAAC,OAAsB;IAC5C,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC;YACpH,OAAO,EAAE,EAAE,MAAM,EAAE,qCAAqC,EAAE,EAAE,CAAC,CAAC;IAClE,CAAC;IAAC,MAAM,CAAC;QAAC,MAAM,IAAI,QAAQ,CAAC,wBAAwB,EAAE,qEAAqE,CAAC,CAAC;IAAC,CAAC;IAChI,IAAI,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,IAAI,QAAQ,CAAC,wBAAwB,EAAE,qEAAqE,CAAC,CAAC;IAAC,CAAC;IAC3L,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;IACzC,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,CAAC;QACH,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAAC,IAAI,IAAI,CAAC,IAAI;gBAAE,MAAM;YACvD,MAAM,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC;YAChC,IAAI,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,EAAE,CAAC;gBAAC,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC;gBAAC,MAAM,IAAI,KAAK,EAAE,CAAC;YAAC,CAAC;YAC3E,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QACjE,MAAM,aAAa,GAAG,KAAK,EAAE,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QACnD,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,OAAO,aAAa,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,aAAa,CAAC;eAC9H,CAAC,KAAK,CAAC,QAAQ,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ;YAAE,MAAM,IAAI,KAAK,EAAE,CAAC;QAC9E,MAAM,QAAQ,GAAc,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,EAAE;YACrF,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;mBACvF,IAAgB,CAAC,OAAO,KAAK,OAAO;gBAAE,OAAO,EAAE,CAAC;YACtD,MAAM,OAAO,GAAI,IAAgB,CAAC,OAAO,CAAC;YAC1C,IAAI,OAAO,EAAE,IAAI,KAAK,SAAS,IAAI,CAAC,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBAAE,OAAO,EAAE,CAAC;YACrH,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAG,IAAgB,CAAC,IAAI,EAAE,CAAC,CAAC;QACtF,CAAC,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,OAAO,KAAK,aAAa,CAAC,CAAC;QAC3E,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,EAAE,CAAC;QAC/B,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QAAC,MAAM,IAAI,QAAQ,CAAC,oBAAoB,EAAE,yEAAyE,CAAC,CAAC;IAAC,CAAC;AAClI,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,SAAoB;IACpE,OAAO,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC;WACjE,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC;WACnC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC;WACvD,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;WACxF,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,IAAI,GAAG,CAAC,CAAC;SACxE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED,KAAK,UAAU,cAAc,CAAC,OAAgB,EAAE,YAAgD,EAAE,OAAsB;IACtH,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,IAAI,GAAG,CAAC;QACxE,MAAM,IAAI,QAAQ,CAAC,2BAA2B,EAAE,OAAO,OAAO,CAAC,OAAO,kBAAkB,OAAO,CAAC,OAAO,EAAE,IAAI,0CAA0C,CAAC,CAAC;IAC3J,4EAA4E;IAC5E,IAAI,MAAM,gBAAgB,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,OAAO;QAC/D,MAAM,IAAI,QAAQ,CAAC,0BAA0B,EAAE,uFAAuF,CAAC,CAAC;IAC1I,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACvG,IAAI,CAAC,IAAI,CAAC,cAAc,eAAe,GAAG,CAAC,CAAC;IAC5C,MAAM,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,aAAa,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC7F,IAAI,MAAM,gBAAgB,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,OAAO;QAC/D,MAAM,IAAI,QAAQ,CAAC,oBAAoB,EAAE,4HAA4H,CAAC,CAAC;IACzK,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,eAAe,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,CAAC,OAAO;QACnH,OAAO,EAAE,iDAAiD,EAAE,CAAC;AACjE,CAAC;AAED,KAAK,UAAU,gBAAgB,CAAC,IAAY;IAC1C,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QACtF,OAAO,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3H,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,IAAI,CAAC;IAAC,CAAC;AAC1B,CAAC;AAED,KAAK,UAAU,eAAe,CAAC,OAAgB,EAAE,OAAsB;IACrE,0EAA0E;IAC1E,iFAAiF;IACjF,MAAM,WAAW,GAAG,GAAG,eAAe,IAAI,OAAO,UAAU,OAAO,CAAC,OAAO,MAAM,CAAC;IACjF,IAAI,OAAO,CAAC,IAAI,EAAE,OAAO,KAAK,WAAW,IAAI,CAAC,+BAA+B,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,IAAI,EAAE,CAAC;QAC/G,MAAM,IAAI,QAAQ,CAAC,oBAAoB,EAAE,wGAAwG,CAAC,CAAC;IACrJ,IAAI,KAAa,CAAC;IAClB,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACrI,IAAI,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;YAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;YAAC,MAAM,IAAI,KAAK,EAAE,CAAC;QAAC,CAAC;QACzF,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,MAAM,GAAiB,EAAE,CAAC;QACpE,IAAI,MAAM,GAAG,CAAC,CAAC;QACf,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAAC,IAAI,IAAI,CAAC,IAAI;gBAAE,MAAM;YACvD,MAAM,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC;YAChC,IAAI,MAAM,GAAG,iBAAiB,EAAE,CAAC;gBAAC,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC;gBAAC,MAAM,IAAI,KAAK,EAAE,CAAC;YAAC,CAAC;YAC7E,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;QACD,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC9B,IAAI,UAAU,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,SAAS;YAAE,MAAM,IAAI,KAAK,EAAE,CAAC;IACpH,CAAC;IAAC,MAAM,CAAC;QAAC,MAAM,IAAI,QAAQ,CAAC,oBAAoB,EAAE,uFAAuF,CAAC,CAAC;IAAC,CAAC;IAC9I,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC,CAAC;IACtD,MAAM,KAAK,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACxD,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC;IAC1D,4EAA4E;IAC5E,0EAA0E;IAC1E,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,EAAE,OAAO,OAAO,CAAC,OAAO,IAAI,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACjH,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5E,MAAM,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,CAAC;IAChD,CAAC;YAAS,CAAC;QAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAAC,CAAC;IAChE,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,OAAsB;IACrD,IAAI,EAAE,CAAC,OAAO,CAAC,WAAW,CAAC;QAAE,MAAM,IAAI,QAAQ,CAAC,qBAAqB,EAAE,6EAA6E,CAAC,CAAC;IACtJ,OAAO,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,KAAK,IAAI,EAAE;QAClE,MAAM,YAAY,GAAG,MAAM,wBAAwB,CAAC,OAAO,CAAC,CAAC;QAC7D,IAAI,CAAC,YAAY;YAAE,MAAM,IAAI,QAAQ,CAAC,4BAA4B,EAAE,gIAAgI,CAAC,CAAC;QACtM,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC;YAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3G,OAAO,cAAc,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;IACvD,CAAC,CAAC,CAAC;AACL,CAAC;AAED,yEAAyE;AACzE,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAc,EAAE,OAAsB;IACtE,IAAI,EAAE,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC;WACjJ,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO;IAC5D,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC;QACzC,IAAI,QAAQ,CAAC,SAAS,KAAK,SAAS,IAAI,OAAO,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,SAAS,GAAG,GAAG;YAAE,OAAO;QACzF,MAAM,YAAY,GAAG,MAAM,wBAAwB,CAAC,OAAO,CAAC,CAAC;QAC7D,IAAI,CAAC,YAAY;YAAE,OAAO;QAC1B,MAAM,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,KAAK,IAAI,EAAE;YACjE,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC;YACtC,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS,IAAI,OAAO,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,GAAG,GAAG;gBAAE,OAAO;YACnF,yEAAyE;YACzE,KAAK,CAAC,SAAS,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;YAChC,MAAM,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC,EAAE,KAAK,CAAC,CAAC;YACnE,IAAI,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;YACvC,IAAI,CAAC;gBACH,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC;gBACrD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;gBAC5H,IAAI,KAAK,CAAC,WAAW,IAAI,QAAQ,EAAE,CAAC;oBAClC,MAAM,cAAc,CAAC,QAAQ,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;oBACtD,gBAAgB,GAAG,QAAQ,CAAC,OAAO,CAAC;oBACpC,OAAO,CAAC,MAAM,CAAC,wBAAwB,QAAQ,CAAC,OAAO,gCAAgC,CAAC,CAAC;gBAC3F,CAAC;gBACD,IAAI,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,gBAAgB,CAAC;oBAC7C,OAAO,CAAC,MAAM,CAAC,aAAa,MAAM,CAAC,OAAO,wDAAwD,CAAC,CAAC;YACxG,CAAC;YAAC,MAAM,CAAC;gBAAC,OAAO,CAAC,MAAM,CAAC,yGAAyG,CAAC,CAAC;YAAC,CAAC;YACtI,KAAK,MAAM,KAAK,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC;gBAC3C,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;gBAC7D,IAAI,CAAC,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC;oBAAE,SAAS;gBACrE,IAAI,CAAC;oBACH,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;oBAC7F,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS;wBAAE,OAAO,CAAC,MAAM,CAAC,8FAA8F,CAAC,CAAC;yBAC3I,IAAI,CAAC,eAAe,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;wBAAE,OAAO,CAAC,MAAM,CAAC,eAAe,MAAM,CAAC,MAAM,oEAAoE,CAAC,CAAC;gBACpL,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,OAAO,CAAC,MAAM,CAAC,KAAK,YAAY,QAAQ,IAAI,KAAK,CAAC,IAAI,KAAK,4BAA4B;wBACrF,CAAC,CAAC,GAAG,KAAK,CAAC,OAAO,mDAAmD;wBACrE,CAAC,CAAC,wGAAwG,CAAC,CAAC;gBAChH,CAAC;YACH,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,QAAQ,IAAI,KAAK,CAAC,IAAI,KAAK,aAAa;YAAE,OAAO;QACtE,OAAO,CAAC,MAAM,CAAC,0GAA0G,CAAC,CAAC;IAC7H,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withandeo/cli",
-  "version": "0.19.11",
+  "version": "0.19.12",
   "description": "Developer CLI for Andeo applications",
   "type": "module",
   "license": "UNLICENSED",
@@ -30,6 +30,7 @@
     "@cloudflare/flagship": "0.5.0",
     "@openfeature/server-sdk": "1.23.0",
     "@types/node": "^26.2.0",
+    "@types/semver": "^7.8.0",
     "typescript": "^7.0.2",
     "vitest": "^4.1.11"
   },
@@ -38,6 +39,7 @@
     "esbuild": "0.28.1",
     "jsonc-parser": "3.3.1",
     "miniflare": "5.20260918.0-alpha",
+    "semver": "^7.8.5",
     "smol-toml": "1.8.0"
   },
   "exports": {

package/skill/publication.json

@@ -1,3 +1,3 @@
 {
-  "minimumCliVersion": "0.19.11"
+  "minimumCliVersion": "0.19.12"
 }

package/skill/tender-accounts/SKILL.md

@@ -5,7 +5,15 @@ description: Build, preview, diagnose and operate merchant-owned Andeo apps with
 
 # Andeo applications
 
-Use `npx @withandeo/cli` as the merchant platform interface. Keep merchant behavior in merchant source and provider credentials/customer authorization server-side. Use Andeo in customer-facing copy; retain existing technical identifiers and configuration schemas.
+Use `andeo` as the merchant platform interface. A project-local CLI stays pinned to its dependency; use `npx @withandeo/cli@latest` when an explicitly current temporary CLI is needed. Keep merchant behavior in merchant source and provider credentials/customer authorization server-side. Use Andeo in customer-facing copy; retain existing technical identifiers and configuration schemas.
+
+## Check guidance freshness before each Andeo task
+
+Run `andeo skill sync --agent codex --json` for a Codex installation, or use `--agent claude` for Claude. For a custom installation, pass its parent directory with `--directory PATH`. Sync refreshes an existing, unchanged managed guide without login. After `status=updated`, reread this `SKILL.md` and task-relevant references before continuing; an active chat retains previously loaded instructions.
+
+For `local_changes` or `unmanaged`, preserve local files and report the result; inspect with `andeo skill status --json` using the same destination. Never use `--force` automatically. For `not_installed`, use `skill install` only when asked to install guidance. On an outage, state that freshness is unverified and use current CLI help, bundled `andeo docs`, and live capabilities. If the guide requires a newer CLI, run `andeo upgrade` for a supported global installation; update a project-local dependency through its package manager.
+
+Global installations automatically maintain the CLI and existing default Codex/Claude guides once daily after successful commands. `andeo config autoupgrade off` disables CLI installation while retaining update reminders and independent skill refresh. Detailed guidance remains in the references, CLI help and maintained practice catalog.
 
 ## Discover scope before acting
 

package/skill/tender-accounts/references/skills.md

@@ -1,8 +1,11 @@
 # Authenticated skills
 
 The global Andeo guide is public and updates independently of CLI releases.
-Run `andeo skill install --agent codex --force --json` to refresh its latest
-compatible revision, without login. Check the returned source and revision;
+Run `andeo skill sync --agent codex --json` to refresh its latest
+compatible revision, without login or overwriting local edits. Use `--agent claude`
+for Claude or `--directory PATH` for a custom installation. Check freshness with
+`andeo skill status --json` using the same destination. After an update, reread the
+entrypoint and relevant references in active chats. Check the returned source and revision;
 `--bundled` selects the CLI's offline snapshot. `andeo doctor` checks global
 guidance against the public revision. The private practice skills below still
 require authentication and do not use this public endpoint.