gamealgo-cli 0.3.7 → 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) {
@@ -151,14 +152,21 @@ export class GameAlgoAdminClient {
     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);

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]");
@@ -66,7 +76,7 @@ export async function handleEvents(client, args, global) {
         return;
     }
     if (sub !== "count")
-        throw new Error("usage: gamealgo events <list|get|apply|deprecate|block|activate|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,7 +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";
@@ -18,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") {
@@ -35,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") {
@@ -45,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] [--format json|csv] [--out file-or-directory]");
+            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);
@@ -64,15 +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`);
-        await writeReportQueryOutput(outputValue, flags, global, elapsedMs);
+        await writeReportQueryOutput(outputValue, flags, global, elapsedMs, statusSummary.ok);
         return;
     }
     if (sub === "preview") {
@@ -82,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] [--format json|csv] [--out file-or-directory]");
+            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);
@@ -103,19 +124,43 @@ 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`);
-        await writeReportQueryOutput(outputValue, flags, global, elapsedMs);
+        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";
@@ -126,7 +171,7 @@ export function reportOutputFormat(value) {
         return normalized;
     throw new Error("--format must be json or csv");
 }
-async function writeReportQueryOutput(outputValue, flags, global, elapsedMs) {
+async function writeReportQueryOutput(outputValue, flags, global, elapsedMs, succeeded) {
     const format = reportOutputFormat(flags.format);
     const out = optionalString(flags.out);
     if (flags.out === true)
@@ -143,7 +188,7 @@ async function writeReportQueryOutput(outputValue, flags, global, elapsedMs) {
             }
             const first = files[0];
             const summary = files.length === 1 ? {
-                ok: true,
+                ok: succeeded,
                 out: first.out,
                 format,
                 reportId: first.exported.reportId,
@@ -154,7 +199,7 @@ async function writeReportQueryOutput(outputValue, flags, global, elapsedMs) {
                 truncated: first.exported.truncated,
                 elapsedMs,
             } : {
-                ok: true,
+                ok: succeeded,
                 out,
                 format,
                 results: files.length,
@@ -175,19 +220,28 @@ async function writeReportQueryOutput(outputValue, flags, global, elapsedMs) {
         const exported = reportDashboardCsv(outputValue);
         warnTruncatedCsv(exported);
         process.stdout.write(exported.content);
+        if (!succeeded)
+            markCommandFailed();
         return;
     }
     if (out) {
         await writeTextFile(out, JSON.stringify(outputValue, null, 2) + "\n");
+        const outputObject = outputValue && typeof outputValue === "object" && !Array.isArray(outputValue)
+            ? outputValue
+            : {};
         await printResult({
-            ok: true,
+            ok: succeeded,
             out,
-            results: Array.isArray(outputValue.results) ? outputValue.results.length : 0,
+            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)

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

@@ -13,6 +13,7 @@ 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);
@@ -110,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-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.7",
+  "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
@@ -42,6 +42,12 @@ Use each topic's section list as the router. Read the whole topic only when the
 
 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
@@ -81,6 +87,18 @@ 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.
@@ -145,6 +163,15 @@ 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.