gamealgo-cli 0.4.1 → 0.4.3

package/README.md

@@ -47,7 +47,25 @@ gamealgo report advanced run --query-id battle_analysis --from 2026-09-04 --to 2
 gamealgo report advanced list
 ```
 
-The current CLI reads legacy v1 Packs during migration, but all Report Pack write commands require `schemaVersion: 2`. Advanced query runs are explicit, are never preloaded, and remain available as immutable reports for 30 days.
+All Report Packs use `schemaVersion: 2`, with custom `groups[].views` or platform-owned `groups[].standard`. Advanced query runs are explicit, are never preloaded, and remain available as immutable reports for 30 days.
+
+Managed marketing lifecycle queries can choose their runtime cohort shape without editing or publishing the Pack. For example, this returns one row per channel, Campaign, and country with D0–D30 retention as columns:
+
+```bash
+gamealgo report advanced run \
+  --query-id retention_drilldown \
+  --platform ios \
+  --from 2026-08-08 \
+  --to 2026-09-22 \
+  --observation-end 2026-09-22 \
+  --group-by network,campaign,country_code \
+  --day-offsets 0-30 \
+  --pivot-metric retention_rate \
+  --filter network=Meta \
+  --wait --out retention.json --json
+```
+
+Repeat `--filter field=value1,value2` for `cohort_dt`, `day_offset`, `network`, `campaign`, `campaign_id`, `country_code`, or `platform`. The CLI combines different fields with AND, merges repeated values for the same field, and automatically adds the internal `day_offset` grouping when `--group-by` is present. `--pivot-metric` accepts `retention_rate`, `active_users`, `daily_revenue`, `cumulative_revenue`, `ltv`, or `roas`; `--min-cohort-size` removes undersized groups.
 
 Help and documentation are fetched from the configured Server on every invocation. The CLI intentionally does not keep a documentation cache.
 

package/dist/commands/report.js

@@ -165,6 +165,7 @@ export async function handleReport(client, args, global) {
 async function handleAdvancedReport(client, args, global) {
     const action = args.shift();
     if (action === "run") {
+        const marketingFilters = parseMarketingCohortFilterFlags(args);
         const flags = parseFlags(args);
         const queryId = requiredTextFlag(flags["query-id"], "--query-id");
         const startDate = requiredTextFlag(flags.from || flags.start || flags.startDate, "--from");
@@ -180,6 +181,7 @@ async function handleAdvancedReport(client, args, global) {
         const pack = packPath ? await readJsonFile(packPath) : undefined;
         if (pack !== undefined)
             assertWritableReportPackV2(pack, "report advanced run");
+        const marketingCohort = marketingCohortRunOptions(flags, marketingFilters);
         const wait = booleanFlag(flags.wait, "--wait");
         const timeoutMs = reportTimeoutMs(flags) ?? 15 * 60 * 1000;
         await announceTargetGame(client);
@@ -189,6 +191,7 @@ async function handleAdvancedReport(client, args, global) {
             endDate,
             platform,
             ...(pack !== undefined ? { pack } : {}),
+            ...(marketingCohort ? { marketingCohort } : {}),
         }, { timeoutMs: Math.min(timeoutMs, 30_000) });
         if (!wait) {
             await writeAdvancedOutput(created, flags, global);
@@ -229,6 +232,143 @@ async function handleAdvancedReport(client, args, global) {
     }
     throw new Error("usage: gamealgo report advanced <run|get|list>");
 }
+const MARKETING_COHORT_DIMENSIONS = new Set([
+    "cohort_dt",
+    "day_offset",
+    "network",
+    "campaign",
+    "campaign_id",
+    "country_code",
+    "platform",
+]);
+const MARKETING_COHORT_PIVOT_METRICS = new Set([
+    "retention_rate",
+    "active_users",
+    "daily_revenue",
+    "cumulative_revenue",
+    "ltv",
+    "roas",
+]);
+function parseMarketingCohortFilterFlags(args) {
+    const grouped = new Map();
+    for (let index = 0; index < args.length;) {
+        if (args[index] !== "--filter") {
+            index += 1;
+            continue;
+        }
+        const expression = args[index + 1];
+        if (!expression || expression.startsWith("--"))
+            throw new Error("--filter requires field=value");
+        const separator = expression.indexOf("=");
+        if (separator <= 0)
+            throw new Error("--filter must use field=value or field=value1,value2");
+        const field = normalizeMarketingCohortDimension(expression.slice(0, separator).trim(), "--filter");
+        const values = expression.slice(separator + 1).split(",").map((value) => value.trim()).filter(Boolean);
+        if (!values.length)
+            throw new Error(`--filter ${field} requires at least one value`);
+        grouped.set(field, [...new Set([...(grouped.get(field) ?? []), ...values])]);
+        args.splice(index, 2);
+    }
+    return [...grouped].map(([field, values]) => ({ field, values }));
+}
+function marketingCohortRunOptions(flags, filters) {
+    const cohortFlagNames = ["observation-end", "group-by", "day-offsets", "min-cohort-size", "pivot-metric"];
+    if (!filters.length && !cohortFlagNames.some((flag) => flags[flag] !== undefined))
+        return undefined;
+    const observationEndDate = optionalTextFlag(flags["observation-end"], "--observation-end");
+    if (observationEndDate && !isIsoDate(observationEndDate)) {
+        throw new Error("--observation-end must use YYYY-MM-DD");
+    }
+    const groupByValue = optionalTextFlag(flags["group-by"], "--group-by");
+    const groupBy = groupByValue
+        ? [...new Set(groupByValue.split(",")
+                .map((field) => normalizeMarketingCohortDimension(field.trim(), "--group-by"))
+                .filter(Boolean))]
+        : undefined;
+    if (groupBy && !groupBy.includes("day_offset"))
+        groupBy.push("day_offset");
+    const dayOffsetsValue = optionalTextFlag(flags["day-offsets"], "--day-offsets");
+    const dayOffsets = dayOffsetsValue ? parseMarketingCohortDayOffsets(dayOffsetsValue) : undefined;
+    const minCohortSizeValue = optionalTextFlag(flags["min-cohort-size"], "--min-cohort-size");
+    const minCohortSize = minCohortSizeValue === undefined ? undefined : Number(minCohortSizeValue);
+    if (minCohortSize !== undefined && (!Number.isInteger(minCohortSize) || minCohortSize < 1 || minCohortSize > 1_000_000)) {
+        throw new Error("--min-cohort-size must be an integer between 1 and 1000000");
+    }
+    const pivotMetric = optionalTextFlag(flags["pivot-metric"], "--pivot-metric");
+    if (pivotMetric && !MARKETING_COHORT_PIVOT_METRICS.has(pivotMetric)) {
+        throw new Error(`--pivot-metric must be one of ${[...MARKETING_COHORT_PIVOT_METRICS].join(", ")}`);
+    }
+    if (pivotMetric && !groupBy) {
+        throw new Error("--group-by is required when --pivot-metric is used");
+    }
+    const filter = filters.length === 0
+        ? undefined
+        : filters.length === 1
+            ? marketingCohortFilter(filters[0])
+            : { op: "and", filters: filters.map(marketingCohortFilter) };
+    return {
+        ...(observationEndDate ? { observationEndDate } : {}),
+        ...(groupBy ? { groupBy } : {}),
+        ...(dayOffsets ? { dayOffsets } : {}),
+        ...(minCohortSize !== undefined ? { minCohortSize } : {}),
+        ...(pivotMetric ? { pivotMetric } : {}),
+        ...(filter ? { filter } : {}),
+    };
+}
+function marketingCohortFilter(input) {
+    const values = input.field === "day_offset"
+        ? input.values.map((value) => {
+            const day = Number(value);
+            if (!Number.isInteger(day) || day < 0 || day > 30) {
+                throw new Error("--filter day_offset values must be integers between 0 and 30");
+            }
+            return day;
+        })
+        : input.values;
+    return values.length === 1
+        ? { field: input.field, op: "eq", value: values[0] }
+        : { field: input.field, op: "in", values };
+}
+function normalizeMarketingCohortDimension(value, flag) {
+    const aliases = {
+        channel: "network",
+        country: "country_code",
+        "campaign-id": "campaign_id",
+    };
+    const normalized = aliases[value] ?? value;
+    if (!MARKETING_COHORT_DIMENSIONS.has(normalized)) {
+        throw new Error(`${flag} dimension must be one of ${[...MARKETING_COHORT_DIMENSIONS].join(", ")}`);
+    }
+    return normalized;
+}
+function parseMarketingCohortDayOffsets(value) {
+    const offsets = new Set();
+    for (const part of value.split(",").map((item) => item.trim()).filter(Boolean)) {
+        const match = part.match(/^D?(\d+)(?:\s*-\s*D?(\d+))?$/i);
+        if (!match)
+            throw new Error("--day-offsets must use 0-30 or a comma-separated list such as 0,1,7,14,30");
+        const start = Number(match[1]);
+        const end = match[2] === undefined ? start : Number(match[2]);
+        if (start > end || start < 0 || end > 30) {
+            throw new Error("--day-offsets values must be between 0 and 30");
+        }
+        for (let day = start; day <= end; day += 1)
+            offsets.add(day);
+    }
+    if (!offsets.size)
+        throw new Error("--day-offsets requires at least one value");
+    return [...offsets].sort((left, right) => left - right);
+}
+function optionalTextFlag(value, flag) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || !value.trim())
+        throw new Error(`${flag} requires a value`);
+    return value.trim();
+}
+function isIsoDate(value) {
+    return /^\d{4}-\d{2}-\d{2}$/.test(value) && Number.isFinite(Date.parse(`${value}T00:00:00.000Z`));
+}
 async function waitForAdvancedReport(client, runId, timeoutMs, startedAt) {
     while (true) {
         const response = await client.getAdvancedReportRun(runId, true);

package/package.json

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

package/skills/gamealgo/SKILL.md

@@ -49,9 +49,9 @@ When changing an existing Report Pack, run `gamealgo report pull --out <working-
 
 Validate with the compact default output, then use `report preview` to inspect v2 validation and generated Dataset SQL without running a warehouse query. After publishing, verify only the affected tab, group, or View with `report result`; do not query unrelated tabs. A report result request must explicitly select a tab, group, or chart/View. A globally unique bare id is accepted; if the Server returns an ambiguity error, use its candidate ids and the local Pack structure to retry without asking the developer to choose an internal 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 and materialized result state.
 
-### Use Report Pack v2 For New Work
+### Use Report Pack v2
 
-New, validated, previewed, or published Report Packs must declare `schemaVersion: 2`. Unversioned v1 Packs may still be pulled and queried during migration, but they are read-only; do not edit them in place, pass them to a write command, or add v2 branches to their Report/Chart model. v2 uses independent `datasets`, inline `groups[].views`, `tabs`, and optional `advancedQueries`; it has no top-level `reports` or `charts`, no `groups[].standard`, and no author-managed Pack version.
+Every Report Pack must declare `schemaVersion: 2`. v2 uses independent `datasets`, inline `groups[].views`, platform-owned `groups[].standard`, `tabs`, and optional `experimentViews` and `advancedQueries`. It has no top-level `reports` or `charts` and no author-managed Pack version. Generate, explain, validate, preview, and publish only this structure; do not expose migration-era formats to the developer.
 
 An ordinary v2 Dataset must read only `adn.dwd_gamealgo_events_enriched_di`, include `dt` in its output grain, and be independently computable for each natural day. Before selector filtering, each `datasetFingerprint × platform × dt` must remain at or below 100 rows and 128 KiB. Estimate the output cardinality from every `groupBy` dimension before publishing. If it may exceed either limit, reduce or bucket dimensions, split the business question, or move it into `advancedQueries`; a table View, front-end selector, or `dataset.limit` does not bypass the ordinary limit.
 
@@ -59,6 +59,8 @@ Keep ratio and average components as additive Dataset columns and calculate the
 
 Use `gamealgo report result` to read an existing ordinary v2 materialization for an explicit date range and scope. It never starts a DW query. Use `gamealgo report advanced run --query-id <id> --platform <platform> --from <date> --to <date>` only when an explicit high-dimensional or non-preloaded query is required. `--pack <file>` supplies an immutable v2 Pack snapshot for that Run without publishing it. `advanced get` and `advanced list` only read the saved Run/history. Advanced results are whole-run bounded to 20,000 rows and 20 MiB and retained for 30 days; never replace this path with local production scans or a hidden query side channel.
 
+For a managed `marketing/lifecycle` advanced Dataset, use runtime cohort flags instead of generating many near-duplicate Packs: `--observation-end <date>`, `--group-by <comma-separated dimensions>`, `--day-offsets <0-30|list>`, `--min-cohort-size <n>`, `--pivot-metric <metric>`, and repeatable `--filter field=value1,value2`. The CLI automatically adds `day_offset` to `--group-by`. Prefer pivoting one requested metric so the 20,000-row check applies after D0–D30 become columns. When the user wants one aggregate matrix for the selected acquisition range, omit `cohort_dt`; include it only when separate daily cohorts are explicitly required.
+
 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