gamealgo-cli 0.3.6 → 0.3.8

package/dist/client.js

@@ -58,10 +58,11 @@ export class GameAlgoAdminClient {
     async archiveExperimentV2Strategy(strategyKey, archived) {
         return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/strategies-v2/${encodeURIComponent(strategyKey)}/archive`, { archived });
     }
-    async rollbackExperimentV2Strategy(strategyKey, versionId, message) {
+    async rollbackExperimentV2Strategy(strategyKey, versionId, message, platform) {
         return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/strategies-v2/${encodeURIComponent(strategyKey)}/rollback`, {
             versionId,
             message,
+            ...(platform ? { platform } : {}),
         });
     }
     async createExperimentV2Run(strategyKey, body) {
@@ -133,17 +134,39 @@ export class GameAlgoAdminClient {
     async getScriptVersion(name, versionId) {
         return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/scripts/${encodeURIComponent(name)}/versions/${encodeURIComponent(versionId)}`);
     }
+    async listDynamicConfigs() {
+        return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/dynamic-configs`);
+    }
+    async getDynamicConfig(key) {
+        return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/dynamic-configs/${encodeURIComponent(key)}`);
+    }
+    async putDynamicConfig(key, body) {
+        return await this.put(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/dynamic-configs/${encodeURIComponent(key)}`, body);
+    }
+    async queueDynamicConfigRun(key) {
+        return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/dynamic-configs/${encodeURIComponent(key)}/run`, {});
+    }
+    async listDynamicConfigRuns(key, limit = 50) {
+        return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/dynamic-configs/${encodeURIComponent(key)}/runs?limit=${encodeURIComponent(String(limit))}`);
+    }
     async getReportPack() {
         return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/report-pack`);
     }
-    async previewReportPack(content) {
-        return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/report-pack/preview`, { content });
+    async previewReportPack(content, options = {}) {
+        return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/report-pack/preview`, {
+            content,
+            ...(options.responseMode ? { responseMode: options.responseMode } : {}),
+        });
     }
     async putReportPack(content) {
         return await this.put(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/report-pack`, { content });
     }
-    async reportManifest() {
-        return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/reports/manifest`);
+    async reportManifest(options = {}) {
+        const params = new URLSearchParams();
+        if (options.responseMode)
+            params.set("responseMode", options.responseMode);
+        const query = params.size ? `?${params.toString()}` : "";
+        return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/reports/manifest${query}`);
     }
     async queryReportDashboard(body, options = {}) {
         return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/reports/query`, body, options);
@@ -173,6 +196,15 @@ export class GameAlgoAdminClient {
     async deprecateEventCatalog(eventType) {
         return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/events/catalog/${encodeURIComponent(eventType)}/deprecate`, {});
     }
+    async blockEventCatalog(eventType, reason) {
+        return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/events/catalog/${encodeURIComponent(eventType)}/block`, { reason });
+    }
+    async activateEventCatalog(eventType, reason, confirmEventType) {
+        return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/events/catalog/${encodeURIComponent(eventType)}/activate`, {
+            reason,
+            confirmEventType,
+        });
+    }
     async getIntegrationPlan(environment, platform) {
         const params = new URLSearchParams({ environment, platform });
         return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/integration/plan?${params.toString()}`);

package/dist/commands/dynamic-config.js

@@ -0,0 +1,71 @@
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { parseFlags } from "../args.js";
+import { printResult } from "../output.js";
+import { contentTypeForFileName, objectValue, readJsonFile, sanitizeRemoteFileName } from "../resources.js";
+import { announceTargetGame } from "../target.js";
+import { optionalString } from "../utils.js";
+export async function handleDynamicConfig(client, args, global) {
+    const sub = args.shift();
+    if (sub === "list") {
+        parseFlags(args);
+        await printResult(await client.listDynamicConfigs(), global);
+        return;
+    }
+    if (sub === "get") {
+        const key = args.shift();
+        if (!key)
+            throw new Error("usage: gamealgo dynamic-config get <key>");
+        parseFlags(args);
+        await printResult(await client.getDynamicConfig(key), global);
+        return;
+    }
+    if (sub === "runs") {
+        const key = args.shift();
+        if (!key)
+            throw new Error("usage: gamealgo dynamic-config runs <key> [--limit 50]");
+        const flags = parseFlags(args);
+        await printResult(await client.listDynamicConfigRuns(key, Number(flags.limit || 50)), global);
+        return;
+    }
+    if (sub === "run") {
+        const key = args.shift();
+        if (!key)
+            throw new Error("usage: gamealgo dynamic-config run <key>");
+        parseFlags(args);
+        await announceTargetGame(client);
+        await printResult(await client.queueDynamicConfigRun(key), global);
+        return;
+    }
+    if (sub === "publish") {
+        const definitionPath = args.shift();
+        if (!definitionPath) {
+            throw new Error("usage: gamealgo dynamic-config publish <definition.json> [--script transform.js] [--message text]");
+        }
+        const flags = parseFlags(args);
+        const definition = objectValue(await readJsonFile(definitionPath));
+        if (!definition)
+            throw new Error("dynamic config definition must be a JSON object");
+        const key = optionalString(definition.key);
+        if (!key)
+            throw new Error("dynamic config definition.key is required");
+        const body = { ...definition };
+        delete body.key;
+        const scriptPath = optionalString(flags.script);
+        await announceTargetGame(client);
+        if (scriptPath) {
+            const scriptName = sanitizeRemoteFileName(optionalString(definition.scriptName) || basename(scriptPath));
+            const content = await readFile(scriptPath, "utf8");
+            const created = await client.createScriptVersion(scriptName, content, contentTypeForFileName(scriptName), optionalString(flags.message));
+            body.scriptVersionId = created.scriptVersion.versionId;
+        }
+        delete body.scriptName;
+        if (!optionalString(body.scriptVersionId)) {
+            throw new Error("definition.scriptVersionId or --script is required");
+        }
+        const response = await client.putDynamicConfig(key, body);
+        await printResult({ ok: true, ...response }, global);
+        return;
+    }
+    throw new Error("usage: gamealgo dynamic-config <list|get|publish|run|runs>");
+}

package/dist/commands/events.js

@@ -1,12 +1,22 @@
 import YAML from "yaml";
 import { parseFlags } from "../args.js";
+import { diffReportPackEventCatalog } from "../event-catalog-diff.js";
 import { confirm, formatDuration, printResult, reportTimeoutMs, startProgress, withCliMeta } from "../output.js";
-import { readObjectFile, writeTextFile } from "../resources.js";
+import { readJsonFile, readObjectFile, writeTextFile } from "../resources.js";
 import { announceTargetGame } from "../target.js";
 import { optionalString } from "../utils.js";
 export async function handleEvents(client, args, global) {
     const sub = args.shift();
     const flags = parseFlags(args);
+    if (sub === "diff") {
+        const filePath = optionalString(flags.pack) || args.shift();
+        if (!filePath || args.length)
+            throw new Error("usage: gamealgo events diff --pack <report-pack.json>");
+        const reportPack = await readJsonFile(filePath);
+        const catalog = await client.listEventCatalog(30, false);
+        await printResult(diffReportPackEventCatalog(reportPack, catalog), global);
+        return;
+    }
     if (sub === "list") {
         if (args.length)
             throw new Error("usage: gamealgo events list [--days 30] [--no-diagnostics]");
@@ -41,8 +51,32 @@ export async function handleEvents(client, args, global) {
         await writeEventCatalogOutput(await client.deprecateEventCatalog(eventType), flags, global);
         return;
     }
+    if (sub === "block") {
+        const eventType = args.shift();
+        const reason = optionalString(flags.reason);
+        if (!eventType || args.length || !reason)
+            throw new Error("usage: gamealgo events block <eventType> --reason <reason> [--yes]");
+        if (!flags.yes && !(await confirm(`Block event ${eventType}? New occurrences will be dropped before Kafka.`)))
+            throw new Error("Cancelled");
+        await announceTargetGame(client);
+        await writeEventCatalogOutput(await client.blockEventCatalog(eventType, reason), flags, global);
+        return;
+    }
+    if (sub === "activate") {
+        const eventType = args.shift();
+        const reason = optionalString(flags.reason);
+        const confirmation = optionalString(flags.confirm);
+        if (!eventType || args.length || !reason || !confirmation) {
+            throw new Error("usage: gamealgo events activate <eventType> --reason <reason> --confirm <eventType>");
+        }
+        if (confirmation !== eventType)
+            throw new Error("--confirm must exactly match eventType");
+        await announceTargetGame(client);
+        await writeEventCatalogOutput(await client.activateEventCatalog(eventType, reason, confirmation), flags, global);
+        return;
+    }
     if (sub !== "count")
-        throw new Error("usage: gamealgo events <list|get|apply|deprecate|count>");
+        throw new Error("usage: gamealgo events <list|get|diff|apply|deprecate|block|activate|count>");
     const timeoutMs = reportTimeoutMs(flags);
     const startedAt = Date.now();
     const stopProgress = startProgress("Querying event counts", timeoutMs);

package/dist/commands/experiment.js

@@ -2,7 +2,7 @@ import YAML from "yaml";
 import { parseFlags } from "../args.js";
 import { confirm, isInteractive, optionalNonNegativeInteger, positiveInteger, printResult } from "../output.js";
 import { objectValue, printExperimentRunVariantScripts, readObjectFile, validateExperimentRunVariantScripts, writeTextFile } from "../resources.js";
-import { optionalString } from "../utils.js";
+import { experimentPlatform, optionalString } from "../utils.js";
 export async function handleExperiment(client, args, global) {
     const sub = args.shift();
     if (sub === "strategies" || sub === "list") {
@@ -126,12 +126,13 @@ export async function handleExperimentStrategy(client, args, global) {
         const flags = parseFlags(args);
         const strategyKey = optionalString(flags.strategy || flags.key) || optionalString(args.shift());
         const versionId = optionalString(flags.version || flags["version-id"]);
+        const platform = flags.platform === undefined ? undefined : experimentPlatform(flags.platform);
         const message = requiredMessage(flags, "experiment strategy rollback");
         if (!strategyKey || !versionId) {
-            throw new Error("usage: gamealgo experiment strategy rollback <strategyKey> --version-id <versionId> --message <reason> --yes");
+            throw new Error("usage: gamealgo experiment strategy rollback <strategyKey> --version-id <versionId> [--platform ios|android|rest] --message <reason> --yes");
         }
         await requireYes(flags, global, "experiment strategy rollback");
-        await printResult(await client.rollbackExperimentV2Strategy(strategyKey, versionId, message), global);
+        await printResult(await client.rollbackExperimentV2Strategy(strategyKey, versionId, message, platform), global);
         return;
     }
     throw new Error("usage: gamealgo experiment strategy <show|publish|default|archive|restore|rollback>");
@@ -219,11 +220,14 @@ export async function handleExperimentRun(client, args, global) {
         const run = response.run;
         if (!run)
             throw new Error(`experiment run not found: ${runId}`);
+        const reportConfig = objectValue(run.reportConfig);
+        const managedConfig = objectValue(reportConfig?.managed);
         await printResult({
             run: {
                 id: run.id,
                 strategyKey: run.strategyKey,
                 displayName: run.displayName,
+                platform: optionalString(reportConfig?.platform) ?? optionalString(managedConfig?.platform) ?? null,
                 type: run.type,
                 status: run.status,
                 objective: run.objective,

package/dist/commands/report.js

@@ -1,5 +1,8 @@
+import { extname, join } from "node:path";
 import { parseFlags, parseSelectorFlags } from "../args.js";
-import { formatDuration, printResult, reportTimeoutMs, startProgress, withCliMeta } from "../output.js";
+import { formatDuration, markCommandFailed, printResult, reportTimeoutMs, startProgress, withCliMeta } from "../output.js";
+import { reportDashboardCsv, reportDashboardCsvExports } from "../report-csv.js";
+import { normalizeReportSampleRows, summarizeReportDashboard, summarizeReportManifest, summarizeReportValidation, } from "../report-summary.js";
 import { objectValue, readJsonFile, writeTextFile } from "../resources.js";
 import { announceTargetGame } from "../target.js";
 import { optionalString } from "../utils.js";
@@ -16,9 +19,15 @@ export async function handleReport(client, args, global) {
     if (sub === "validate") {
         const filePath = args.shift();
         if (!filePath)
-            throw new Error("usage: gamealgo report validate <report-pack.json>");
+            throw new Error("usage: gamealgo report validate <report-pack.json> [--full]");
+        const flags = parseFlags(args);
+        const full = reportFullOutput(flags);
         const content = await readJsonFile(filePath);
-        await printResult(await client.previewReportPack(content), global);
+        const response = await client.previewReportPack(content, { responseMode: full ? "full" : "summary" });
+        const summary = summarizeReportValidation(response);
+        await printResult(full ? response : summary, global);
+        if (!summary.ok)
+            markCommandFailed();
         return;
     }
     if (sub === "publish") {
@@ -33,8 +42,10 @@ export async function handleReport(client, args, global) {
         return;
     }
     if (sub === "manifest" || sub === "list") {
-        parseFlags(args);
-        await printResult(await client.reportManifest(), global);
+        const flags = parseFlags(args);
+        const full = reportFullOutput(flags);
+        const response = await client.reportManifest({ responseMode: full ? "full" : "summary" });
+        await printResult(full ? response : summarizeReportManifest(response), global);
         return;
     }
     if (sub === "result") {
@@ -43,8 +54,12 @@ export async function handleReport(client, args, global) {
         const startDate = String(flags.from || flags.start || flags.startDate || "");
         const endDate = String(flags.to || flags.end || flags.endDate || "");
         if (!startDate || !endDate)
-            throw new Error("usage: gamealgo report result --from YYYY-MM-DD --to YYYY-MM-DD [--platform ios|android|rest] [--tab name] [--group name] [--chart name] [--selector k=v]");
+            throw new Error("usage: gamealgo report result --from YYYY-MM-DD --to YYYY-MM-DD [--platform ios|android|rest] [--tab name] [--group name] [--chart name] [--selector k=v] [--sample-rows 0..20] [--full] [--format json|csv] [--out file-or-directory]");
+        requireReportQueryScope(flags, "report result");
         const timeoutMs = reportTimeoutMs(flags);
+        const format = reportOutputFormat(flags.format);
+        const full = reportFullOutput(flags) || format === "csv";
+        const sampleRows = reportSampleRows(flags, full);
         const platform = await resolveCliReportPlatform(client, flags.platform, selectors.platform, startDate, endDate);
         const startedAt = Date.now();
         const stopProgress = startProgress("Querying report results", timeoutMs);
@@ -62,25 +77,19 @@ export async function handleReport(client, args, global) {
                 platform,
                 selectors,
                 refresh: Boolean(flags.refresh),
+                responseMode: full ? "full" : "summary",
+                sampleRows,
             }, { timeoutMs });
         }
         finally {
             stopProgress();
         }
         const elapsedMs = Date.now() - startedAt;
-        const outputValue = withCliMeta(response, { elapsedMs, timeoutMs });
+        const rawOutputValue = withCliMeta(response, { elapsedMs, timeoutMs });
+        const statusSummary = summarizeReportDashboard(rawOutputValue, { command: "report.result", sampleRows });
+        const outputValue = full ? rawOutputValue : statusSummary;
         process.stderr.write(`Report query finished in ${formatDuration(elapsedMs)}.\n`);
-        if (flags.out) {
-            await writeTextFile(String(flags.out), JSON.stringify(outputValue, null, 2) + "\n");
-            await printResult({
-                ok: true,
-                out: String(flags.out),
-                results: Array.isArray(outputValue.results) ? outputValue.results.length : 0,
-                elapsedMs,
-            }, global);
-            return;
-        }
-        await printResult(outputValue, global);
+        await writeReportQueryOutput(outputValue, flags, global, elapsedMs, statusSummary.ok);
         return;
     }
     if (sub === "preview") {
@@ -90,10 +99,14 @@ export async function handleReport(client, args, global) {
         const startDate = String(flags.from || flags.start || flags.startDate || "");
         const endDate = String(flags.to || flags.end || flags.endDate || "");
         if (!filePath || !startDate || !endDate) {
-            throw new Error("usage: gamealgo report preview --pack report-pack.json --from YYYY-MM-DD --to YYYY-MM-DD [--platform ios|android|rest] [--tab name] [--group name] [--chart name] [--selector k=v]");
+            throw new Error("usage: gamealgo report preview --pack report-pack.json --from YYYY-MM-DD --to YYYY-MM-DD [--platform ios|android|rest] [--tab name] [--group name] [--chart name] [--selector k=v] [--sample-rows 0..20] [--full] [--format json|csv] [--out file-or-directory]");
         }
+        requireReportQueryScope(flags, "report preview");
         const content = await readJsonFile(filePath);
         const timeoutMs = reportTimeoutMs(flags);
+        const format = reportOutputFormat(flags.format);
+        const full = reportFullOutput(flags) || format === "csv";
+        const sampleRows = reportSampleRows(flags, full);
         const platform = await resolveCliReportPlatform(client, flags.platform, selectors.platform, startDate, endDate);
         const startedAt = Date.now();
         const stopProgress = startProgress("Previewing report results", timeoutMs);
@@ -111,28 +124,147 @@ export async function handleReport(client, args, global) {
                 chartId: optionalString(flags["chart-id"]),
                 platform,
                 selectors,
+                responseMode: full ? "full" : "summary",
+                sampleRows,
             }, { timeoutMs });
         }
         finally {
             stopProgress();
         }
         const elapsedMs = Date.now() - startedAt;
-        const outputValue = withCliMeta(response, { elapsedMs, timeoutMs });
+        const rawOutputValue = withCliMeta(response, { elapsedMs, timeoutMs });
+        const statusSummary = summarizeReportDashboard(rawOutputValue, { command: "report.preview", sampleRows });
+        const outputValue = full ? rawOutputValue : statusSummary;
         process.stderr.write(`Report preview finished in ${formatDuration(elapsedMs)}.\n`);
-        if (flags.out) {
-            await writeTextFile(String(flags.out), JSON.stringify(outputValue, null, 2) + "\n");
-            await printResult({
-                ok: true,
-                out: String(flags.out),
-                results: Array.isArray(outputValue.results) ? outputValue.results.length : 0,
+        await writeReportQueryOutput(outputValue, flags, global, elapsedMs, statusSummary.ok);
+        return;
+    }
+    throw new Error("usage: gamealgo report <pull|validate|publish|manifest|result|preview>");
+}
+function reportFullOutput(flags) {
+    if (flags.full === undefined)
+        return false;
+    if (flags.full !== true)
+        throw new Error("--full does not accept a value");
+    return true;
+}
+function reportSampleRows(flags, full) {
+    const sampleRows = normalizeReportSampleRows(flags["sample-rows"]);
+    if (full && flags["sample-rows"] !== undefined) {
+        throw new Error("--sample-rows cannot be combined with --full or --format csv");
+    }
+    return sampleRows;
+}
+function requireReportQueryScope(flags, command) {
+    const scopeFlags = ["tab", "tab-id", "group", "group-id", "chart", "chart-id"];
+    if (scopeFlags.some((flag) => optionalString(flags[flag])))
+        return;
+    throw new Error(`${command} requires one of --tab, --tab-id, --group, --group-id, --chart, or --chart-id`);
+}
+export function reportOutputFormat(value) {
+    if (value === undefined || value === null || value === "")
+        return "json";
+    if (typeof value !== "string")
+        throw new Error("--format requires json or csv");
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "json" || normalized === "csv")
+        return normalized;
+    throw new Error("--format must be json or csv");
+}
+async function writeReportQueryOutput(outputValue, flags, global, elapsedMs, succeeded) {
+    const format = reportOutputFormat(flags.format);
+    const out = optionalString(flags.out);
+    if (flags.out === true)
+        throw new Error("--out requires a file path");
+    if (format === "csv") {
+        if (!out && global.json)
+            throw new Error("--format csv cannot be combined with --json unless --out is provided");
+        if (out) {
+            const exports = reportDashboardCsvExports(outputValue);
+            const files = reportCsvOutputFiles(exports, out);
+            for (const file of files) {
+                warnTruncatedCsv(file.exported);
+                await writeTextFile(file.out, file.exported.content);
+            }
+            const first = files[0];
+            const summary = files.length === 1 ? {
+                ok: succeeded,
+                out: first.out,
+                format,
+                reportId: first.exported.reportId,
+                chartId: first.exported.chartId,
+                chartTitle: first.exported.chartTitle,
+                rows: first.exported.rowCount,
+                columns: first.exported.columns.length,
+                truncated: first.exported.truncated,
                 elapsedMs,
-            }, global);
+            } : {
+                ok: succeeded,
+                out,
+                format,
+                results: files.length,
+                files: files.map((file) => ({
+                    out: file.out,
+                    reportId: file.exported.reportId,
+                    chartId: file.exported.chartId,
+                    chartTitle: file.exported.chartTitle,
+                    rows: file.exported.rowCount,
+                    columns: file.exported.columns.length,
+                    truncated: file.exported.truncated,
+                })),
+                elapsedMs,
+            };
+            await printResult(summary, global);
             return;
         }
-        await printResult(outputValue, global);
+        const exported = reportDashboardCsv(outputValue);
+        warnTruncatedCsv(exported);
+        process.stdout.write(exported.content);
+        if (!succeeded)
+            markCommandFailed();
         return;
     }
-    throw new Error("usage: gamealgo report <pull|validate|publish|manifest|result|preview>");
+    if (out) {
+        await writeTextFile(out, JSON.stringify(outputValue, null, 2) + "\n");
+        const outputObject = outputValue && typeof outputValue === "object" && !Array.isArray(outputValue)
+            ? outputValue
+            : {};
+        await printResult({
+            ok: succeeded,
+            out,
+            results: Array.isArray(outputObject.results)
+                ? outputObject.results.length
+                : Array.isArray(outputObject.items) ? outputObject.items.length : 0,
+            elapsedMs,
+        }, global);
+        return;
+    }
+    await printResult(outputValue, global);
+    if (!succeeded)
+        markCommandFailed();
+}
+function reportCsvOutputFiles(exports, out) {
+    if (exports.length === 1)
+        return [{ out, exported: exports[0] }];
+    if (extname(out).toLowerCase() === ".csv") {
+        throw new Error(`CSV export matched ${exports.length} charts; use --chart-id to select one chart or pass a directory to --out`);
+    }
+    return exports.map((exported, index) => ({
+        out: join(out, `${String(index + 1).padStart(2, "0")}-${reportCsvBaseName(exported, index)}.csv`),
+        exported,
+    }));
+}
+function reportCsvBaseName(exported, index) {
+    const candidate = exported.chartId || exported.reportId || `report-${index + 1}`;
+    return candidate
+        .replace(/[^A-Za-z0-9_.-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        || `report-${index + 1}`;
+}
+function warnTruncatedCsv(exported) {
+    if (!exported.truncated)
+        return;
+    process.stderr.write(`Warning: CSV contains a truncated report result${exported.rowLimit ? ` (limit ${exported.rowLimit})` : ""}.\n`);
 }
 export async function resolveCliReportPlatform(client, flagValue, selectorValue, startDate, endDate) {
     const flagPlatform = optionalCliReportPlatform(flagValue, "--platform");

package/dist/event-catalog-diff.js

@@ -0,0 +1,113 @@
+import { objectValue } from "./resources.js";
+export function diffReportPackEventCatalog(reportPackValue, catalogResponseValue) {
+    const reportPack = objectValue(reportPackValue);
+    if (!reportPack)
+        throw new Error("report pack must be a JSON object");
+    const reportEvents = reportPack.events === undefined ? {} : objectValue(reportPack.events);
+    if (!reportEvents)
+        throw new Error("report pack events must be an object");
+    const catalogResponse = objectValue(catalogResponseValue);
+    if (!catalogResponse || !Array.isArray(catalogResponse.events)) {
+        throw new Error("event catalog response is missing events");
+    }
+    const catalogEvents = catalogResponse.events.flatMap((rawEvent) => {
+        const event = objectValue(rawEvent);
+        const eventType = stringValue(event?.eventType);
+        return event && eventType ? [{ eventType, event }] : [];
+    });
+    const catalogByType = new Map(catalogEvents.map(({ eventType, event }) => [eventType, event]));
+    const errors = [];
+    const items = [];
+    let missingEventCount = 0;
+    let missingFieldCount = 0;
+    let typeConflictCount = 0;
+    let blockedEventCount = 0;
+    let deprecatedEventCount = 0;
+    for (const [eventType, rawReportEvent] of Object.entries(reportEvents).sort(([left], [right]) => left.localeCompare(right))) {
+        const reportEvent = objectValue(rawReportEvent);
+        const reportFields = objectValue(reportEvent?.fields) ?? {};
+        const catalogEvent = catalogByType.get(eventType);
+        const missingFields = [];
+        const typeConflicts = [];
+        if (!catalogEvent) {
+            missingEventCount += 1;
+            for (const [fieldId, rawReportField] of Object.entries(reportFields).sort(([left], [right]) => left.localeCompare(right))) {
+                missingFields.push({ id: fieldId, type: stringValue(objectValue(rawReportField)?.type) });
+            }
+            missingFieldCount += missingFields.length;
+            errors.push({ scope: `event:${eventType}`, message: "Event is not registered in the event catalog" });
+            items.push({
+                eventType,
+                catalogStatus: "missing",
+                ...(missingFields.length ? { missingFields } : {}),
+            });
+            continue;
+        }
+        const catalogStatus = stringValue(catalogEvent.status) || "active";
+        if (catalogStatus === "blocked") {
+            blockedEventCount += 1;
+            errors.push({ scope: `event:${eventType}`, message: "Event is blocked in the event catalog" });
+        }
+        else if (catalogStatus === "deprecated") {
+            deprecatedEventCount += 1;
+            errors.push({ scope: `event:${eventType}`, message: "Event is deprecated in the event catalog" });
+        }
+        const catalogFields = objectValue(catalogEvent.fields) ?? {};
+        for (const [fieldId, rawReportField] of Object.entries(reportFields).sort(([left], [right]) => left.localeCompare(right))) {
+            const reportType = stringValue(objectValue(rawReportField)?.type);
+            const catalogField = objectValue(catalogFields[fieldId]);
+            if (!catalogField) {
+                missingFields.push({ id: fieldId, type: reportType });
+                continue;
+            }
+            const catalogType = stringValue(catalogField.type);
+            if (reportType && catalogType && reportType !== catalogType) {
+                typeConflicts.push({ id: fieldId, reportType, catalogType });
+            }
+        }
+        missingFieldCount += missingFields.length;
+        typeConflictCount += typeConflicts.length;
+        if (missingFields.length) {
+            errors.push({
+                scope: `event:${eventType}`,
+                message: `${missingFields.length} report field(s) are not registered in the event catalog`,
+            });
+        }
+        if (typeConflicts.length) {
+            errors.push({
+                scope: `event:${eventType}`,
+                message: `${typeConflicts.length} report field type(s) conflict with the event catalog`,
+            });
+        }
+        if (catalogStatus !== "active" || missingFields.length || typeConflicts.length) {
+            items.push({
+                eventType,
+                catalogStatus,
+                ...(missingFields.length ? { missingFields } : {}),
+                ...(typeConflicts.length ? { typeConflicts } : {}),
+            });
+        }
+    }
+    return {
+        schemaVersion: 1,
+        command: "events.diff",
+        ok: errors.length === 0,
+        summary: {
+            reportEventCount: Object.keys(reportEvents).length,
+            catalogEventCount: catalogEvents.length,
+            issueEventCount: items.length,
+            missingEventCount,
+            missingFieldCount,
+            typeConflictCount,
+            blockedEventCount,
+            deprecatedEventCount,
+        },
+        errors,
+        warnings: [],
+        items,
+        truncated: false,
+    };
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}

package/dist/http.js

@@ -1,5 +1,17 @@
 import { formatDuration } from "./output.js";
 import { normalizeHost } from "./utils.js";
+export class HttpRequestError extends Error {
+    status;
+    errorCode;
+    details;
+    constructor(status, message, errorCode, details) {
+        super(message);
+        this.name = "HttpRequestError";
+        this.status = status;
+        this.errorCode = errorCode;
+        this.details = details;
+    }
+}
 export async function requestJson(host, path, init) {
     const { timeoutMs, ...requestInit } = init;
     let response;
@@ -18,13 +30,30 @@ export async function requestJson(host, path, init) {
     const text = await response.text();
     const json = parseJsonResponse(text);
     if (!response.ok) {
-        throw new Error(formatHttpError(response.status, response.statusText, text, json));
+        const body = json && typeof json === "object" && !Array.isArray(json) ? json : undefined;
+        const errorCode = typeof body?.error === "string" ? body.error : undefined;
+        const details = body?.details && typeof body.details === "object" && !Array.isArray(body.details)
+            ? body.details
+            : undefined;
+        throw new HttpRequestError(response.status, formatHttpError(response.status, response.statusText, text, json), errorCode, details);
     }
     if (text && json === undefined) {
         throw new Error(`Invalid JSON response from ${path}: ${truncateBody(text)}`);
     }
     return json ?? null;
 }
+export function cliErrorPayload(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!(error instanceof HttpRequestError))
+        return { ok: false, error: message };
+    return {
+        ok: false,
+        error: message,
+        status: error.status,
+        ...(error.errorCode ? { errorCode: error.errorCode } : {}),
+        ...(error.details ? { details: error.details } : {}),
+    };
+}
 export function parseJsonResponse(text) {
     if (!text)
         return null;

package/dist/main.js

@@ -12,6 +12,8 @@ import { handleFileResource } from "./commands/resources.js";
 import { handleSkill } from "./commands/skill.js";
 import { loadPackageMetadata } from "./config.js";
 import { handleDocs, handleHelp } from "./docs.js";
+import { handleDynamicConfig } from "./commands/dynamic-config.js";
+import { cliErrorPayload } from "./http.js";
 import { printResult } from "./output.js";
 export async function main() {
     const args = process.argv.slice(2);
@@ -76,6 +78,10 @@ export async function main() {
             await handleFileResource(client, args, global, "config");
             return;
         }
+        if (command === "dynamic-config") {
+            await handleDynamicConfig(client, args, global);
+            return;
+        }
         if (command === "report") {
             await handleReport(client, args, global);
             return;
@@ -105,7 +111,7 @@ export async function main() {
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         if (global.json) {
-            console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+            console.log(JSON.stringify(cliErrorPayload(error), null, 2));
         }
         else {
             console.error(`Error: ${message}`);

package/dist/output.js

@@ -62,6 +62,7 @@ export function formatDuration(ms) {
 export async function printResult(value, global) {
     if (global.json) {
         console.log(JSON.stringify(value, null, 2));
+        markExplicitFailure(value);
         return;
     }
     if (typeof value === "string") {
@@ -69,6 +70,15 @@ export async function printResult(value, global) {
         return;
     }
     console.log(YAML.stringify(value).trimEnd());
+    markExplicitFailure(value);
+}
+export function markCommandFailed() {
+    process.exitCode = 1;
+}
+function markExplicitFailure(value) {
+    if (value && typeof value === "object" && !Array.isArray(value) && value.ok === false) {
+        markCommandFailed();
+    }
 }
 export async function confirm(question) {
     const rl = createInterface({ input, output });

package/dist/report-csv.js

@@ -0,0 +1,87 @@
+export function reportDashboardCsv(value) {
+    const exports = reportDashboardCsvExports(value);
+    if (exports.length !== 1) {
+        throw new Error(`CSV output to stdout or one file requires exactly one matching chart, but the query returned ${exports.length}`);
+    }
+    return exports[0];
+}
+export function reportDashboardCsvExports(value) {
+    const dashboard = recordValue(value);
+    const results = Array.isArray(dashboard?.results) ? dashboard.results : [];
+    if (!results.length)
+        throw new Error("CSV export did not receive any matching chart results");
+    return results.map(reportResultCsv);
+}
+function reportResultCsv(value) {
+    const result = recordValue(value);
+    if (!result)
+        throw new Error("CSV export received an invalid report result");
+    if (typeof result.error === "string" && result.error.trim()) {
+        throw new Error(`cannot export failed report result: ${result.error.trim()}`);
+    }
+    const rows = Array.isArray(result.rows)
+        ? result.rows.map((row) => recordValue(row) || {})
+        : [];
+    const declaredColumns = Array.isArray(result.columns)
+        ? result.columns.filter((column) => typeof column === "string" && Boolean(column.trim()))
+        : [];
+    const columns = uniqueStrings(declaredColumns.length ? declaredColumns : rows.flatMap((row) => Object.keys(row)));
+    if (!columns.length) {
+        throw new Error("CSV export result is not ready because the Server returned no columns; retry with --refresh or wait for the background refresh");
+    }
+    const lines = [
+        columns.map(csvCell).join(","),
+        ...rows.map((row) => columns.map((column) => csvCell(row[column])).join(",")),
+    ];
+    const chart = recordValue(result.chart);
+    const rowLimit = positiveIntegerOrUndefined(result.rowLimit);
+    return {
+        content: `\uFEFF${lines.join("\r\n")}\r\n`,
+        columns,
+        rowCount: rows.length,
+        reportId: optionalString(result.reportId),
+        chartId: optionalString(chart?.id),
+        chartTitle: optionalString(chart?.title),
+        truncated: result.truncated === true,
+        ...(rowLimit ? { rowLimit } : {}),
+    };
+}
+export function csvCell(value) {
+    let text;
+    if (value === null || value === undefined)
+        text = "";
+    else if (typeof value === "string")
+        text = protectSpreadsheetFormula(value);
+    else if (typeof value === "number")
+        text = Number.isFinite(value) ? String(value) : "";
+    else if (typeof value === "boolean" || typeof value === "bigint")
+        text = String(value);
+    else {
+        try {
+            text = JSON.stringify(value) ?? "";
+        }
+        catch {
+            text = String(value);
+        }
+    }
+    if (/[",\r\n]/.test(text) || /^\s|\s$/.test(text))
+        return `"${text.replaceAll('"', '""')}"`;
+    return text;
+}
+function protectSpreadsheetFormula(value) {
+    return /^\s*[=+\-@]/.test(value) ? `'${value}` : value;
+}
+function recordValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}
+function optionalString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function positiveIntegerOrUndefined(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+}

package/dist/report-summary.js

@@ -0,0 +1,300 @@
+export const REPORT_SUMMARY_SCHEMA_VERSION = 1;
+export const REPORT_SUMMARY_MAX_ITEMS = 200;
+export const REPORT_SUMMARY_MAX_ISSUES = 100;
+export const REPORT_SUMMARY_MAX_SAMPLE_ROWS = 20;
+export function summarizeReportValidation(value) {
+    const root = objectValue(value);
+    const validation = objectValue(root?.validation);
+    const errorMessages = stringValues(validation?.errors);
+    const warningMessages = stringValues(validation?.warnings);
+    const statements = arrayValues(objectValue(root?.sqlPreview)?.statements);
+    const statementItems = statements.map((raw) => {
+        const statement = objectValue(raw);
+        const sql = typeof statement?.sql === "string" ? statement.sql : "";
+        const declaredBytes = finiteNonNegativeNumber(statement?.bytes);
+        return compactObject({
+            kind: "sql",
+            id: stringValue(statement?.id),
+            title: stringValue(statement?.title),
+            bytes: declaredBytes ?? utf8Bytes(sql),
+        });
+    });
+    const errors = issueValues(errorMessages, "validation");
+    const warnings = issueValues(warningMessages, "validation");
+    const items = statementItems.slice(0, REPORT_SUMMARY_MAX_ITEMS);
+    return {
+        schemaVersion: REPORT_SUMMARY_SCHEMA_VERSION,
+        command: "report.validate",
+        ok: validation?.ok === true && errorMessages.length === 0,
+        summary: {
+            errorCount: errorMessages.length,
+            warningCount: warningMessages.length,
+            eventTypeCount: arrayValues(validation?.eventTypes).length,
+            datasetCount: arrayValues(validation?.datasets).length,
+            reportCount: arrayValues(validation?.reports).length,
+            sqlStatementCount: statements.length,
+        },
+        errors: errors.values,
+        warnings: warnings.values,
+        items,
+        truncated: errors.truncated || warnings.truncated || statementItems.length > items.length,
+    };
+}
+export function summarizeReportManifest(value) {
+    const root = objectValue(value);
+    const reportPack = compactReportPack(root?.reportPack);
+    const manifest = objectValue(root?.manifest);
+    const tabs = arrayValues(manifest?.tabs);
+    const experimentViews = arrayValues(manifest?.experimentViews);
+    const reportIds = arrayValues(manifest?.reports)
+        .map((report) => typeof report === "string" ? report : stringValue(objectValue(report)?.id))
+        .filter(Boolean);
+    const returnedReportIds = [...new Set(reportIds)].slice(0, REPORT_SUMMARY_MAX_ITEMS);
+    const allItems = [];
+    let groupCount = 0;
+    let chartCount = 0;
+    for (const rawTab of tabs) {
+        const tab = objectValue(rawTab);
+        const groups = arrayValues(tab?.groups);
+        groupCount += groups.length;
+        for (const rawGroup of groups) {
+            const group = objectValue(rawGroup);
+            const charts = arrayValues(group?.charts);
+            chartCount += charts.length;
+            for (const rawChart of charts) {
+                allItems.push(chartManifestItem(rawChart, group, {
+                    scope: "dashboard",
+                    tabId: stringValue(tab?.id),
+                    tabTitle: stringValue(tab?.title),
+                }));
+            }
+        }
+    }
+    for (const rawView of experimentViews) {
+        const view = objectValue(rawView);
+        const groups = arrayValues(view?.groups);
+        groupCount += groups.length;
+        for (const rawGroup of groups) {
+            const group = objectValue(rawGroup);
+            const charts = arrayValues(group?.charts);
+            chartCount += charts.length;
+            for (const rawChart of charts) {
+                allItems.push(chartManifestItem(rawChart, group, {
+                    scope: "experiment",
+                    strategy: stringValue(view?.strategy),
+                    viewTitle: stringValue(view?.title),
+                }));
+            }
+        }
+    }
+    const items = allItems.slice(0, REPORT_SUMMARY_MAX_ITEMS);
+    return {
+        schemaVersion: REPORT_SUMMARY_SCHEMA_VERSION,
+        command: "report.manifest",
+        ok: Boolean(manifest),
+        summary: compactObject({
+            reportPack,
+            title: stringValue(manifest?.title),
+            tabCount: tabs.length,
+            experimentViewCount: experimentViews.length,
+            groupCount,
+            chartCount,
+            reportCount: reportIds.length,
+            reportIds: returnedReportIds,
+            returnedItemCount: items.length,
+        }),
+        errors: manifest ? [] : [{ scope: "manifest", message: "Report manifest response is missing manifest" }],
+        warnings: [],
+        items,
+        truncated: allItems.length > items.length || reportIds.length > returnedReportIds.length,
+    };
+}
+export function summarizeReportDashboard(value, options) {
+    const root = objectValue(value);
+    const results = arrayValues(root?.results);
+    const requestedSampleRows = normalizeReportSampleRows(options.sampleRows);
+    const allErrors = [];
+    const allWarnings = [];
+    const allItems = [];
+    const statusCounts = {};
+    let totalRows = 0;
+    let sourceTruncated = false;
+    for (let index = 0; index < results.length; index += 1) {
+        const result = objectValue(results[index]);
+        const chart = objectValue(result?.chart);
+        const tab = objectValue(result?.tab);
+        const group = objectValue(result?.group);
+        const chartId = stringValue(chart?.id) || `result-${index + 1}`;
+        const scope = `chart:${chartId}`;
+        const rows = arrayValues(result?.rows);
+        const rowCount = finiteNonNegativeNumber(result?.rowCount) ?? rows.length;
+        const status = reportResultStatus(result);
+        const error = stringValue(result?.error);
+        const truncated = result?.truncated === true;
+        totalRows += rowCount;
+        statusCounts[status] = (statusCounts[status] ?? 0) + 1;
+        if (error)
+            allErrors.push({ scope, message: error });
+        if (truncated) {
+            sourceTruncated = true;
+            const rowLimit = finiteNonNegativeNumber(result?.rowLimit);
+            allWarnings.push({
+                scope,
+                message: `Report result is truncated${rowLimit === undefined ? "" : ` at ${rowLimit} rows`}`,
+            });
+        }
+        if (result?.stale === true) {
+            allWarnings.push({ scope, message: "Report result is stale" });
+        }
+        allItems.push(compactObject({
+            kind: "chart-result",
+            status,
+            tabId: stringValue(tab?.id),
+            tabTitle: stringValue(tab?.title),
+            groupId: stringValue(group?.id),
+            groupTitle: stringValue(group?.title),
+            chartId,
+            chartTitle: stringValue(chart?.title),
+            chartType: stringValue(chart?.type),
+            reportId: stringValue(result?.reportId),
+            columns: columnNames(result?.columns),
+            rowCount,
+            cached: typeof result?.cached === "boolean" ? result.cached : undefined,
+            cachedAt: stringValue(result?.cachedAt),
+            stale: typeof result?.stale === "boolean" ? result.stale : undefined,
+            truncated,
+            rowLimit: finiteNonNegativeNumber(result?.rowLimit),
+            error,
+            sampleRows: requestedSampleRows > 0 ? rows.slice(0, requestedSampleRows) : undefined,
+        }));
+    }
+    const errors = limitIssues(allErrors);
+    const warnings = limitIssues(allWarnings);
+    const items = allItems.slice(0, REPORT_SUMMARY_MAX_ITEMS);
+    const incompleteCount = Object.entries(statusCounts)
+        .filter(([status]) => status !== "ready")
+        .reduce((sum, [, count]) => sum + count, 0);
+    return {
+        schemaVersion: REPORT_SUMMARY_SCHEMA_VERSION,
+        command: options.command,
+        ok: allErrors.length === 0 && incompleteCount === 0,
+        summary: compactObject({
+            reportPack: compactReportPack(root?.reportPack),
+            dateRange: objectValue(root?.dateRange),
+            selectors: objectValue(root?.selectors),
+            resultCount: results.length,
+            statusCounts,
+            totalRows,
+            sampleRowsPerResult: requestedSampleRows,
+            returnedItemCount: items.length,
+            cli: objectValue(root?.cli),
+        }),
+        errors: errors.values,
+        warnings: warnings.values,
+        items,
+        truncated: sourceTruncated || errors.truncated || warnings.truncated || allItems.length > items.length,
+    };
+}
+export function normalizeReportSampleRows(value) {
+    if (value === undefined || value === null || value === "")
+        return 0;
+    if (typeof value === "boolean")
+        throw new Error("--sample-rows requires a non-negative integer");
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0 || parsed > REPORT_SUMMARY_MAX_SAMPLE_ROWS) {
+        throw new Error(`--sample-rows must be an integer between 0 and ${REPORT_SUMMARY_MAX_SAMPLE_ROWS}`);
+    }
+    return parsed;
+}
+function chartManifestItem(rawChart, group, location) {
+    const chart = objectValue(rawChart);
+    const views = objectValue(chart?.views);
+    const reportIds = new Set();
+    const reportId = stringValue(chart?.report);
+    if (reportId)
+        reportIds.add(reportId);
+    for (const rawView of Object.values(views ?? {})) {
+        const viewReportId = stringValue(objectValue(rawView)?.report);
+        if (viewReportId)
+            reportIds.add(viewReportId);
+    }
+    return compactObject({
+        kind: "chart",
+        ...location,
+        groupId: stringValue(group?.id),
+        groupTitle: stringValue(group?.title),
+        standardRef: stringValue(group?.standardRef),
+        chartId: stringValue(chart?.id),
+        chartTitle: stringValue(chart?.title),
+        chartType: stringValue(chart?.type),
+        reportIds: [...reportIds],
+        selectorIds: arrayValues(group?.selectors)
+            .map((selector) => stringValue(objectValue(selector)?.id))
+            .filter(Boolean),
+        viewIds: views ? Object.keys(views) : [],
+    });
+}
+function reportResultStatus(result) {
+    if (stringValue(result?.error))
+        return "error";
+    if (result?.pending === true)
+        return "pending";
+    if (result?.retrying === true)
+        return "retrying";
+    if (result?.refreshing === true)
+        return "refreshing";
+    if (result?.stale === true)
+        return "stale";
+    return "ready";
+}
+function compactReportPack(value) {
+    const reportPack = objectValue(value);
+    if (!reportPack)
+        return undefined;
+    return compactObject({
+        gameId: stringValue(reportPack.gameId),
+        version: stringValue(reportPack.version),
+        status: stringValue(reportPack.status),
+        updatedAt: stringValue(reportPack.updatedAt),
+    });
+}
+function columnNames(value) {
+    return arrayValues(value).flatMap((column) => {
+        if (typeof column === "string")
+            return column ? [column] : [];
+        const object = objectValue(column);
+        const name = stringValue(object?.name) || stringValue(object?.id);
+        return name ? [name] : [];
+    });
+}
+function issueValues(messages, scope) {
+    return limitIssues(messages.map((message) => ({ scope, message })));
+}
+function limitIssues(values) {
+    return {
+        values: values.slice(0, REPORT_SUMMARY_MAX_ISSUES),
+        truncated: values.length > REPORT_SUMMARY_MAX_ISSUES,
+    };
+}
+function objectValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function arrayValues(value) {
+    return Array.isArray(value) ? value : [];
+}
+function stringValues(value) {
+    return arrayValues(value).filter((item) => typeof item === "string");
+}
+function stringValue(value) {
+    return typeof value === "string" && value ? value : undefined;
+}
+function finiteNonNegativeNumber(value) {
+    const number = Number(value);
+    return Number.isFinite(number) && number >= 0 ? number : undefined;
+}
+function compactObject(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+}
+function utf8Bytes(value) {
+    return new TextEncoder().encode(value).byteLength;
+}

package/dist/utils.js

@@ -14,6 +14,12 @@ export function integrationPlatform(value) {
         return platform;
     throw new Error("--platform must be ios, android, maker, or rest");
 }
+export function experimentPlatform(value) {
+    const platform = optionalString(value);
+    if (platform === "ios" || platform === "android" || platform === "rest")
+        return platform;
+    throw new Error("--platform must be ios, android, or rest for experiments");
+}
 export function optionalString(value) {
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gamealgo-cli",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "GameAlgo command-line client for AI agents and game developers",
   "repository": {
     "type": "git",

package/skills/gamealgo/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gamealgo
-description: Integrate and improve games with GameAlgo using the project-bound CLI, live Server documentation, and the Server-maintained optimization task catalog. Use when working on GameAlgo SDK setup, telemetry events, report packs, Adjust attribution, remote strategies, experiments, or when discovering supported GameAlgo iteration tasks for a game.
+description: Integrate and improve games with GameAlgo using the project-bound CLI, live Server documentation, and the Server-maintained optimization task catalog. Use when working on GameAlgo SDK setup, telemetry events, report packs, Adjust attribution, remote strategies, experiments, discovering supported GameAlgo iteration tasks, or changing player-facing game behavior that may need telemetry coverage.
 ---
 
 # GameAlgo
@@ -37,11 +37,17 @@ Use each topic's section list as the router. Read the whole topic only when the
 - Calling or changing a concrete public SDK function: additionally run `gamealgo docs api <function> --platform <platform>` for each affected function. Never infer one platform's API from another.
 - Adding or changing events: additionally run `gamealgo events list --days 30 --json` before defining fields or names.
 - Querying an existing dashboard or report: read `gamealgo docs reports --section report-query` plus the section that defines the relevant metric or template. Creating, changing, previewing, or publishing Report Packs, charts, report SQL, or business metrics: list the `reports` sections and read every section affected by the change before interpreting data or editing definitions.
-- Creating or changing remote configuration, strategies, experiments, variants, objectives, rollout, or assessment: list the `experiments` sections and read every section affected by the change; also load the integration plan and exact API documentation when client code changes.
+- Creating or changing remote configuration, dynamic config pipelines, strategies, experiments, variants, objectives, rollout, or assessment: list the `experiments` sections and read every section affected by the change; also load the integration plan and exact API documentation when client code changes.
 - Adjust or marketing attribution work: load the selected optimization task when one applies, read every topic in its `docs`, and load the integration plan and exact identifier/attribution APIs for the target platform.
 
 If work crosses domains, combine their requirements. For example, an advertising event used by an experiment report requires the integration plan, event inventory, SDK API documentation, relevant report sections, and relevant experiment sections. Read a section once per turn unless the task expands or the Server documentation version changes.
 
+For `report validate`, `report manifest`, `report preview`, and JSON `report result`, use the default compact output. It provides the stable `schemaVersion`, `command`, `ok`, `summary`, `errors`, `warnings`, `items`, and `truncated` fields needed by an agent; do not recreate summaries with ad-hoc `jq`. Add `--sample-rows <n>` only when a small value sample is necessary. Use `--full` only when the task genuinely requires complete generated SQL, chart definitions, or every returned row; use CSV export rather than full JSON when the goal is data extraction.
+
+When changing an existing Report Pack, run `gamealgo report pull --out <working-pack.json>` before editing and use that current published Pack as the baseline. Do not start from a remembered or stale local copy. Run `gamealgo events diff --pack <working-pack.json>` after defining the Pack events; if it reports missing fields, type conflicts, or blocked/deprecated events, inspect the actual game call sites and prepare real business descriptions rather than inventing catalog text from field names. The diff is read-only and does not authorize `events apply` or event activation.
+
+Validate with the compact default output, then preview every chart or group affected by the change without querying unrelated tabs. A report query must explicitly select a tab, group, or chart. A globally unique bare chart id is accepted; if the Server returns `ambiguous_chart_id`, use its candidate ids and the local Pack structure to retry without asking the developer to choose an internal chart id. Before applying event metadata or publishing the Pack, show the exact changes and impact unless the developer already authorized them. After publishing, pull the effective Pack again and verify the expected manifest or report result.
+
 For initial integration or business dashboard work, standard dashboards are only the baseline. During the initial integration, inspect the actual game loop and define a separate game-specific new-user flow dashboard with meaningful milestones and drop-off diagnostics. Add required milestone telemetry and event catalog fields in the same integration instead of waiting for production volume. Validate the pipeline with test data; label business conclusions as awaiting data when production samples are immature, but do not omit the dashboard design.
 
 ## Follow Mandatory Checkpoints
@@ -53,6 +59,18 @@ For initial integration or business dashboard work, standard dashboards are only
 5. Before publishing reports, remote configuration, scripts, strategies, experiments, rollout changes, or other externally visible mutations, show the relevant diff and impact unless the user has already explicitly authorized that exact operation.
 6. After execution, verify with real configuration retrieval, accepted non-debug events, report results, or experiment state as appropriate. A code diff or successful request alone is not business verification.
 
+## Keep Production Analysis Off The Developer Workstation
+
+For production telemetry investigations, execute partition-scale scans and aggregations with managed Alibaba Cloud compute such as DataWorks/MaxCompute or Kyuubi/Spark, and return only the small aggregated result needed for diagnosis.
+
+The built-in domestic Data Bridge Paimon backend is not a distributed SQL pushdown engine: PyPaimon plans Paimon splits, reads OSS data into an Arrow table inside the Bridge pod, and only then executes the SQL with DuckDB. The current runner also does not translate SQL predicates into `read_builder.with_filter(...)`, so SQL `dt`, `game`, or `platform` filters do not guarantee Paimon split pruning. Do not use this backend for production raw/enriched partition scans or describe it as Paimon aggregating inside the storage service. Limit it to tightly bounded summary-table reads or emergency diagnostics until the query path is backed by managed compute.
+
+- Never use the local PyPaimon/DuckDB launcher to calculate production counts, DAU, hourly volume, event coverage, or source-to-enriched reconciliation. That launcher materializes selected Paimon partition data on the local machine even when the submitted SQL contains only aggregates.
+- Do not pull production detail rows or whole partitions to the local workspace and aggregate them afterward.
+- Put partition filters, game filters, grouping, distinct counts, joins, and same-elapsed-window comparisons in the SQL sent to the managed query engine, and verify its execution plan actually prunes partitions and columns.
+- Local Paimon access is limited to catalog/schema/partition metadata and a deliberately tiny `LIMIT` sample when the schema cannot otherwise be established.
+- If no managed query path is available, stop and give the developer a bounded SQL query to run. Do not silently fall back to a local or Bridge-Pod partition scan.
+
 Reading documentation does not grant permission to mutate production. CLI and Server validation, scopes, project binding, and explicit approval requirements still apply.
 
 ## Integration Details
@@ -69,6 +87,51 @@ Reuse events with the same business meaning, register new fields with their real
 
 For every game, prefer stable, human-readable Chinese values for business dimensions that will appear directly in report legends, axes, selectors, or tables. This includes values such as level or stage type, game mode, placement, item name, and business outcome or failure reason. Keep event names, field names, IDs, SQL aliases, and protocol-defined enums in their required technical format. Do not rename values already used by a live game solely to translate them, because that would split one historical dimension into multiple report values.
 
+## Revisit Telemetry When Gameplay Changes
+
+When work adds or materially changes player-facing gameplay, onboarding, progression, economy, advertising, purchases, rewards, or important success and failure paths, proactively compare the new behavior with the existing GameAlgo telemetry. Derive the affected behavior from the current conversation and repository diff; do not make the developer restate the feature in a separate event configuration or prompt.
+
+- Do not add telemetry mechanically for visual-only changes, refactors, or behavior already covered by an event with the same semantics.
+- If existing telemetry is sufficient, say so briefly and do not ask a redundant question.
+- If a meaningful decision or funnel step would remain unobservable, present a concise proposal as soon as the gap is clear: the question it answers, the standard or existing event to reuse (or the new custom event), exact trigger boundary, essential fields, expected volume bound, and any report it enables. Ask whether to include that telemetry in the current change; do not silently expand a feature request into new data collection.
+- If the developer explicitly asks to update or optimize telemetry from the current context, treat that as authorization to inspect all relevant changes in the conversation and implement one coherent local telemetry patch without asking them to enumerate the features again. It does not by itself authorize publishing event-catalog or Report Pack changes; disclose those exact external mutations and follow the normal publication checkpoint.
+- When telemetry was already explicitly requested, implement it with the feature instead of asking again.
+
+After approval, update the actual emission call sites and their normal-flow tests together. Include catalog fields or reporting changes only when they are needed for the stated question, and then follow the event-volume and publication safeguards below.
+
+## Bound Custom Event Volume
+
+Before adding or changing a custom event, prefer a protocol-standard event or an existing custom event with the same meaning. Keep the event type stable and put variable values in payload fields; never generate event types from item IDs, levels, timestamps, user input, or other runtime values.
+
+Inspect every call site for render/update loops, timers, polling, transport retries, duplicate lifecycle callbacks, and re-entrant listeners. State the trigger boundary and estimate the maximum calls per user, session, context, and active user-day. Use the game's active-user estimate to describe the expected daily volume when it is available.
+
+- Standard SDK semantic events are governed by their protocol semantics. Do not disguise custom telemetry as a standard event to bypass safeguards.
+- The SDK limits custom events to 1,000 occurrences per `context × eventType`, 5,000 total occurrences per context, and 100 distinct custom event types per context.
+- A custom event with an unbounded trigger or an expected rate above 1,000 calls per context requires explicit developer review before implementation. Explain the expected volume, storage and processing impact, and the guard that makes the trigger bounded.
+- Never add client-side retries around `track`, rename an event after rejection, remove its custom-event prefix, declare it standard, raise a safety limit, or call a lower-level transport to bypass a quota.
+- Treat an SDK `event_guard` diagnostic as evidence of a telemetry bug or unexpectedly high-frequency design. Find and fix the emission path before asking to change a limit.
+
+Before delivery, report the estimated bound, normal-flow tests, the limiting loop or callback, and behavior once the local quota is reached.
+
+## Treat Dynamic Config As A Production Publisher
+
+A dynamic config pipeline is Server-side automation that turns aggregated Report Pack inputs into a live config file. It does not authorize SDK changes, detailed production-data downloads, or live publication by itself.
+
+- Define bounded aggregate inputs with Report Pack syntax. Keep filters, joins, aggregation, and data reduction in the managed query rather than passing event detail to JavaScript.
+- Keep transforms synchronous and deterministic. They may use only the supplied datasets, previous output, and scheduled metadata; never depend on network, filesystem, environment variables, wall-clock APIs, randomness, async functions, or Promise output.
+- The output file name and content type belong to the reviewed pipeline definition. The script may return only file content and JSON diagnostics.
+- Before publishing or materially updating an active pipeline, show the target game, input reports and windows, complete script diff, output file and content type, schedule, expected behavior, failure behavior, and user-facing or operational risks. Obtain explicit approval for that exact publication unless the user already gave it after seeing those details.
+- Prefer a disabled pipeline or a local script test while details are still under discussion. After an authorized publish, trigger one run, inspect the persisted run result and generated file version, and confirm that an unchanged second run is hash-deduplicated before treating the automation as verified.
+- Do not raise the 1 MiB script/input/output caps, the 5,000-row per-dataset cap, the 5-second execution cap, or the minimum 60-minute schedule to bypass a failing design. Reduce data in the Report Pack or simplify the transform.
+
+Use `gamealgo dynamic-config list|get|publish|run|runs` for lifecycle operations. Dynamic config output continues through the ordinary SDK config-file delivery mechanism, so do not change client SDK code merely to consume a generated file that already uses the existing config API.
+
+## Respect Blocked Events
+
+A blocked event is a persistent ingestion safety state. You may inspect its diagnostics, analyze data read-only, fix the client call site, and run local validation, but you must not reactivate it, register an equivalent replacement event, declare it standard, switch credentials, call a lower-level transport, or otherwise bypass the block without fresh explicit approval. Applying ordinary catalog metadata must not reactivate a blocked or deprecated event.
+
+Before asking to reactivate an event, tell the developer why it was blocked, the faulty call path, the implemented fix, the previous and expected event rate per context and active user-day, the validation performed, and the remaining risk. Only an unambiguous instruction given after that disclosure authorizes the exact `blocked` to `active` transition. Use the dedicated CLI activation command with its required reason and exact event-name confirmation, then verify both the catalog state and newly observed event health. Do not edit the database or repeatedly reactivate an event that becomes blocked again without a new diagnosis and approval.
+
 ## Initialize At The Earliest Safe Lifecycle Point
 
 Initialize GameAlgo at the beginning of the earliest runtime lifecycle hook where its minimal required dependencies are available. Do not place it after save loading, scene creation, asset loading, UI construction, ad initialization, or a broad game-module bootstrap merely for organizational convenience. Any unhandled failure before the call would otherwise exclude an opened user from telemetry, and an SDK initialization watchdog cannot report a failure when the SDK was never started.
@@ -100,6 +163,32 @@ When client code implements an experiment or remote Strategy, define a stable, t
 
 Before delivery, inspect changed client code for Variant or assignment-identity access and verify none of it reaches business conditionals. Test active control and treatment configs, missing configuration, and the post-promotion shape where the Variant becomes `default` while the promoted config remains active; unchanged parameters must produce unchanged game behavior regardless of the Variant name.
 
+## Preserve Experiment Platform Scope
+
+A Strategy key is shared by the game and keeps a global fallback default, while every Run belongs to exactly one runtime platform: `ios`, `android`, or `rest` (`rest` includes TapTap Maker). A promoted Run updates only its own platform default. Other platform defaults remain unchanged, and a platform without an explicit default continues to use the global fallback.
+
+- When a Run includes `variantId: default`, the Server snapshots the effective default for that Run's platform, falling back to the global Strategy default only when that platform has no promoted default.
+- `experiment run promote` needs no platform flag because the Run records its platform.
+- When rolling a platform back to a global historical version, pass `experiment strategy rollback ... --platform <ios|android|rest>` so the global version is copied into that platform default rather than replacing the global fallback.
+- Treat `experiment strategy publish` and `experiment strategy default` as global-fallback operations; they do not overwrite existing promoted platform defaults.
+
+## Require Explicit Approval Before Publishing Experiments
+
+Treat publishing a live experiment as a two-step workflow. Before approval, limit work to read-only analysis, experiment ideas, and local drafts. Do not publish an experiment-specific Strategy or Strategy version, create or start a Run, allocate traffic, or otherwise mutate live experiment state.
+
+Before asking for approval, tell the developer:
+
+- the target game and environment, eligible audience, and exclusions;
+- the hypothesis, primary metric, and decision criterion;
+- the exact control and treatment differences, including parameter values or scripts;
+- the traffic allocation and planned duration, sample size, or review checkpoint;
+- the expected benefit and realistic product, revenue, retention, user-experience, and technical risks that apply; and
+- the stop-loss conditions and rollback or cancellation plan.
+
+Then explicitly ask whether to publish that exact experiment. Only an unambiguous confirmation given after this disclosure authorizes publication. Earlier broad instructions such as “优化一下”, “做个实验”, or “按你判断”, and authorization for code, report, or configuration work do not authorize publishing an experiment. If a material detail changes after approval—including the target game, audience, variants, parameters or scripts, traffic, duration, objective, decision criterion, or risk profile—disclose the change and obtain fresh approval before publishing.
+
+After an authorized publication, retrieve and report the actual Strategy and Run IDs, status, scope, and rollback path. Do not silently create another experiment, Run, round, or rollout. A direct request to pause, cancel, or roll back an existing experiment is sufficient authority for that protective action and must not be blocked by this publication gate.
+
 ## Protect D0 Monetization In Maker Experiments
 
 For TapTap Maker and other Maker games, do not autonomously design, create, or start an experiment that removes all ads from a user's first local day, delays the first ad until D1 or later, or otherwise moves the game's core D0 ad inventory to a later day. Many Maker games lose a large share of users before D1, so this is a direct D0 revenue-risk decision rather than an ordinary ad-timing adjustment. A broad request to optimize ads is not approval for this design.