@witchpot/gmc 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to the Game Market Copilot CLI will be recorded here.
 
+## 0.10.0 - 2026-09-22
+
+- New `gmc roblox` command family (NAK-715, Provisional): `charts` (one
+  recorded ranking cohort as of a cutoff), `experiences` (the tracked
+  catalog with filters, sorts and signed-cursor pagination), `experience
+  <universeId>` (one experience with per-metric observation times),
+  `history <universeId> --granularity hourly|daily` (retained observations
+  with explicit gaps), and `coverage` (the configured cohort matrix with
+  per-dimension freshness). Universe ids are decimal strings end to end —
+  they are never Steam appids, and the commands reject one. The Roblox
+  surface went live in production on 2026-09-22 (NAK-725); the commands
+  stay Provisional until the surface has been through a broader real-data
+  smoke period.
+
+- The Roblox read endpoints reject impossible calendar dates in every
+  offset spelling (`as_of=2026-02-31T12:00:00+09:00` is now a 400 naming
+  the nonexistent date instead of silently answering for March 3), and
+  history gap counts always reconcile with the expected point count.
+
+- Not yet mapped: the saved-experiences surface (`/api/v1/roblox/saved`,
+  NAK-723) is live over REST and MCP; a CLI mapping will follow.
+
 ## 0.9.0 - 2026-09-16
 
 - New `--release-status <released|upcoming|tba>` filter on the games

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@witchpot/gmc",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "private": false,
   "description": "Command line tools for Game Market Copilot market research.",
   "license": "UNLICENSED",

package/src/args.js

@@ -90,6 +90,11 @@ function isCommandToken(command, token) {
       // unknown command `steam` with a stray positional rather than reaching
       // the tag-trends branch.
       "steam",
+      // NAK-715. Same trap as `steam` above: a token missing from this list
+      // falls through to positional rather than erroring, so `gmc roblox
+      // charts` would parse as the unknown command `roblox` with a stray
+      // positional instead of reaching the charts branch.
+      "roblox",
       "auth",
       "login",
       "logout",
@@ -138,6 +143,9 @@ function isCommandToken(command, token) {
   if (command[0] === "steam") {
     return ["tag-trends", "trend-stories"].includes(token);
   }
+  if (command[0] === "roblox") {
+    return ["charts", "experiences", "experience", "history", "coverage"].includes(token);
+  }
   return false;
 }
 

package/src/constants.js

@@ -7,7 +7,7 @@ export const EXIT_CONFIG = 3;
 export const EXIT_API = 4;
 
 export const CLI_PACKAGE_NAME = "@witchpot/gmc";
-export const CLI_VERSION = "0.9.0";
+export const CLI_VERSION = "0.10.0";
 
 export const DEFAULT_API_BASE_URL = "https://gamemarketcopilot.com";
 export const DEFAULT_CONFIG_PATH = path.join(homedir(), ".config", "gmc", "config.json");
@@ -63,7 +63,15 @@ export const PROVISIONAL_BETA_COMMANDS = [
   "gmc steam tag-trends --view featured|board|group|table|tag --json",
   // NAK-804. New command; starts Provisional per the closed-beta roadmap's
   // default for anything not yet through broader real-data smoke testing.
-  "gmc games ai-disclosure <appid> --json"
+  "gmc games ai-disclosure <appid> --json",
+  // NAK-715/NAK-725. Enabled in production on 2026-09-22; stays Provisional
+  // per the closed-beta roadmap's default until the surface has been through
+  // a broader real-data smoke period (the NAK-804 rule), then graduates.
+  "gmc roblox charts --country all --sort top-playing-now --json",
+  "gmc roblox experiences --country all --limit 50 --json",
+  "gmc roblox experience <universeId> --json",
+  "gmc roblox history <universeId> --granularity daily|hourly --json",
+  "gmc roblox coverage --json"
 ];
 
 export const COMPARE_FOCUSES = ["overview", "market", "reviews", "marketing", "audience", "showcases"];

package/src/help.js

@@ -70,6 +70,11 @@ Usage:
   gmc steam tag-trends --view featured --json
   gmc steam tag-trends --view table --sort release_share_delta --order desc --json
   gmc steam tag-trends --view tag --tag <tag_slug> --json
+  gmc roblox charts --country all --sort top-playing-now --json
+  gmc roblox experiences --country all --limit 50 --json
+  gmc roblox experience <universeId> --json
+  gmc roblox history <universeId> --granularity daily --json
+  gmc roblox coverage --json
 
 Tag taxonomy:
   gmc tags --json                    List the full tag dictionary (slug, name).
@@ -232,6 +237,70 @@ Steam tag trends:
     gmc steam tag-trends --view table --sort current_share --limit 50 --json
     gmc steam tag-trends --view tag --tag cozy --json
 
+Roblox:
+  gmc roblox charts --json            One ranking cohort's stored chart
+                                      snapshot as of a cutoff.
+  gmc roblox experiences --json       Browse the tracked cohort with coverage.
+  gmc roblox experience <universeId> --json
+                                      One experience: metadata, metrics,
+                                      artwork.
+  gmc roblox history <universeId> --json
+                                      A bounded window of stored metric
+                                      observations.
+  gmc roblox coverage --json          What the surface has, per dimension.
+  --country <country>                 all | US | JP. Selects which CHART was
+                                      read, never a regional metric scope.
+  --device <device>                   computer.
+  --sort <sort>                       top-playing-now | top-trending |
+                                      top-revisited | fun-with-friends.
+  --as-of <instant>                   ISO 8601 cutoff; defaults to now. No
+                                      observation after it is considered.
+  --eligibility-days <number>         experiences only, 1-30 (default 7). How
+                                      far back a chart appearance still counts.
+  --min-player-count <number>         experiences only, on the resolved row.
+  --max-rank <number>                 experiences only, on the resolved row.
+  --genre <genre>                     experiences only, exact match.
+  --creator-type <type>               experiences only, e.g. Group or User.
+  --detail <enriched|chart_only>      experiences only. Omitted returns both.
+  --order-by <key>                    rank | player_count | last_chart_seen |
+                                      universe_id (experiences only).
+  --order <asc|desc>                  experiences only.
+  --granularity <hourly|daily>        history only. Defaults to daily.
+  --from <instant> --to <instant>     history only. Hourly windows span at most
+                                      90 days, daily at most 365.
+  --limit <number>                    charts 1-250, experiences 1-200.
+  --offset <number>                   charts only.
+  --cursor <cursor>                   experiences only. Continuation token.
+
+  A Roblox universe id is NOT a Steam appid. Ids travel as decimal strings
+  because they exceed the range a JSON number represents exactly, and nothing
+  here merges a Roblox experience with a Steam game.
+
+  Unknown is never zero. A null player count was not measured. price.known
+  false means the price is UNKNOWN, not that the experience is free. Zero
+  recorded votes gives no positive percentage at all, rather than 0%.
+
+  Nothing is fabricated to fill a gap. An absent cohort answers availability
+  "never_observed" with an empty entries list — a measurement about
+  collection, not an error and never another sort's ranking. History reports
+  unsampled periods in data.gaps and interpolates nothing, so a gap is not a
+  zero. Daily sampledPlayingMin/Max are the extremes of the SAMPLES, not the
+  day's peak; compare CCU only across points whose comparable is true.
+  Observed counter decreases are reported as-is and are not resets.
+
+  This is a curated tracked cohort, never all of Roblox. Quote
+  coverage.trackedUniverses as the denominator for any share.
+
+  While the surface is switched off the commands answer 404
+  ROBLOX_UNAVAILABLE. That is the documented not-available state, not an
+  outage and not worth retrying on a schedule.
+
+  Examples:
+    gmc roblox coverage --json
+    gmc roblox charts --country JP --sort top-trending --json
+    gmc roblox experiences --min-player-count 1000 --order-by player_count --json
+    gmc roblox history <universeId> --granularity hourly --json
+
 Binary aliases:
   gmcp and game-market-copilot run the same CLI. Use them when a shell
   alias shadows gmc (Oh My Zsh's git plugin defines gmc as

package/src/requests.js

@@ -650,6 +650,137 @@ export function buildRequest(command, options, positional) {
     };
   }
 
+  // NAK-715. Thin pass-throughs to the Roblox read endpoints, on the same rule
+  // the tag-trends branch above documents: the CLI forwards the flags it was
+  // given and the SERVER owns the contract — the per-endpoint allowlists, the
+  // enum members, the limit ceilings, the window bounds and the cursor
+  // binding. `assertSupportedOptions` still runs for the narrower thing it is
+  // for: a flag the endpoint has no parameter for would otherwise be dropped
+  // silently and answer the unnarrowed question with exit 0.
+  //
+  // A Roblox universe id is NOT a Steam appid and is never sent as a number.
+  // It travels as the decimal string the user typed, because these ids exceed
+  // the range a JS number represents exactly.
+  if (matches(command, ["roblox", "charts"])) {
+    assertSupportedOptions(options, {
+      command: "gmc roblox charts",
+      allowed: ["country", "device", "sort", "as-of", "limit", "offset"]
+    });
+    assertNoExtraPositionals(positional, {
+      expected: 0,
+      usage: "gmc roblox charts --country all --sort top-playing-now --json"
+    });
+    return {
+      path: "/api/v1/roblox/charts",
+      // Every value is omitted when unset so the server owns each default and
+      // no default can drift into a copy kept here.
+      query: pickQuery(options, {
+        country: "country",
+        device: "device",
+        sort: "sort",
+        "as-of": "as_of",
+        limit: "limit",
+        offset: "offset"
+      })
+    };
+  }
+
+  if (matches(command, ["roblox", "experiences"])) {
+    assertSupportedOptions(options, {
+      command: "gmc roblox experiences",
+      allowed: [
+        "country",
+        "device",
+        "sort",
+        "as-of",
+        "eligibility-days",
+        "min-player-count",
+        "max-rank",
+        "genre",
+        "name",
+        "creator-type",
+        "detail",
+        "order-by",
+        "order",
+        "limit",
+        "cursor"
+      ]
+    });
+    assertNoExtraPositionals(positional, {
+      expected: 0,
+      usage: "gmc roblox experiences --country all --limit 50 --json"
+    });
+    return {
+      path: "/api/v1/roblox/experiences",
+      query: pickQuery(options, {
+        country: "country",
+        device: "device",
+        sort: "sort",
+        "as-of": "as_of",
+        "eligibility-days": "eligibility_days",
+        "min-player-count": "min_player_count",
+        "max-rank": "max_rank",
+        genre: "genre",
+        name: "name",
+        "creator-type": "creator_type",
+        detail: "detail",
+        "order-by": "order_by",
+        order: "order",
+        limit: "limit",
+        cursor: "cursor"
+      })
+    };
+  }
+
+  if (matches(command, ["roblox", "experience"])) {
+    assertSupportedOptions(options, { command: "gmc roblox experience", allowed: ["as-of"] });
+    const universeId = assertUniverseId(
+      positional[0],
+      "gmc roblox experience <universeId> --json"
+    );
+    assertNoExtraPositionals(positional, {
+      expected: 1,
+      usage: "gmc roblox experience <universeId> --json"
+    });
+    return {
+      path: `/api/v1/roblox/experiences/${encodeURIComponent(universeId)}`,
+      query: pickQuery(options, { "as-of": "as_of" })
+    };
+  }
+
+  if (matches(command, ["roblox", "history"])) {
+    assertSupportedOptions(options, {
+      command: "gmc roblox history",
+      allowed: ["granularity", "from", "to", "as-of"]
+    });
+    const universeId = assertUniverseId(
+      positional[0],
+      "gmc roblox history <universeId> --granularity daily --json"
+    );
+    assertNoExtraPositionals(positional, {
+      expected: 1,
+      usage: "gmc roblox history <universeId> --granularity daily --json"
+    });
+    return {
+      path: `/api/v1/roblox/experiences/${encodeURIComponent(universeId)}/history`,
+      query: pickQuery(options, {
+        granularity: "granularity",
+        from: "from",
+        to: "to",
+        "as-of": "as_of"
+      })
+    };
+  }
+
+  if (matches(command, ["roblox", "coverage"])) {
+    assertSupportedOptions(options, { command: "gmc roblox coverage", allowed: ["as-of"] });
+    assertNoExtraPositionals(positional, { expected: 0, usage: "gmc roblox coverage --json" });
+    return {
+      path: "/api/v1/roblox/coverage",
+      query: pickQuery(options, { "as-of": "as_of" })
+    };
+  }
+
   return null;
 }
 
@@ -1243,6 +1374,34 @@ function assertAppid(value, usage) {
   return appid;
 }
 
+/**
+ * NAK-715. Validates the universeId positional for the Roblox per-experience
+ * commands, mirroring the path-parameter check the app applies.
+ *
+ * It returns a STRING and never a number, which is the point: a Roblox
+ * universe id is a 64-bit value, and `Number.parseInt` would round anything
+ * above 2^53 into a different experience's id. The lexical test is
+ * `/^[1-9][0-9]*$/` for the same reason `assertAppid` above uses a lexical
+ * test — `Number` also accepts the exponent, hex and decimal-point spellings
+ * the app's validator rejects, and leading zeros would make one experience
+ * reachable under two spellings. This check is advisory; the server remains
+ * the enforcing authority.
+ *
+ * A Roblox universe id is NOT a Steam appid: the two id spaces are unrelated
+ * and this value never reaches a Steam route.
+ */
+function assertUniverseId(value, usage) {
+  const raw = value == null ? "" : String(value).trim();
+  if (!/^[1-9][0-9]{0,18}$/.test(raw)) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: `Missing or invalid universeId (must be a positive decimal Roblox universe id, not a Steam appid). Usage: ${usage}`
+    });
+    process.exit(EXIT_USAGE);
+  }
+  return raw;
+}
+
 function assertResolveQuery(value) {
   if (value == null || String(value).trim() === "") {
     writeJsonError({

package/src/requests.test.js

@@ -1297,3 +1297,174 @@ test('trend-stories preserves story, edition, locale and list pagination options
   assert.equal(captureUsageFailure(() => buildRequestFromArgv(['steam', 'trend-stories', '--family', 'mood'])).exitCode, 2);
   assert.equal(captureUsageFailure(() => buildRequestFromArgv(['steam', 'trend-stories', 'unexpected'])).exitCode, 2);
 });
+
+/**
+ * NAK-715: `gmc roblox ...`.
+ *
+ * The CLI is a pass-through here on the same rule the tag-trends block above
+ * documents — the per-endpoint allowlists, enum members, limit ceilings and
+ * window bounds live on the server — so these tests pin the MAPPING (flag name
+ * to query parameter, omission when unset, path construction) and the one
+ * thing the CLI does own: a universe id is a STRING and is not a Steam appid.
+ */
+test("(NAK-715) roblox charts defaults to the bare endpoint and lets the server pick the cohort", () => {
+  const request = buildRequestFromArgv(["roblox", "charts", "--json"]);
+
+  assert.equal(request.path, "/api/v1/roblox/charts");
+  // Empty, not {country: "all"}: a default copied here could drift from the
+  // server's.
+  assert.deepEqual(request.query, {});
+});
+
+test("(NAK-715) roblox charts maps every flag to its query parameter", () => {
+  const request = buildRequestFromArgv([
+    "roblox", "charts",
+    "--country", "JP",
+    "--device", "computer",
+    "--sort", "top-revisited",
+    "--as-of", "2026-09-14T00:00:00.000Z",
+    "--limit", "50",
+    "--offset", "10",
+    "--json"
+  ]);
+
+  assert.deepEqual(request.query, {
+    country: "JP",
+    device: "computer",
+    // Still forwarded although the source stopped publishing this sort: a
+    // historical cutoff has real data, and the server reports the gap.
+    sort: "top-revisited",
+    // The kebab-case flag reaches the endpoint's snake_case parameter.
+    as_of: "2026-09-14T00:00:00.000Z",
+    limit: "50",
+    offset: "10"
+  });
+});
+
+test("(NAK-715) roblox experiences maps the browse filters and the cursor", () => {
+  const request = buildRequestFromArgv([
+    "roblox", "experiences",
+    "--country", "US",
+    "--eligibility-days", "30",
+    "--min-player-count", "1000",
+    "--max-rank", "50",
+    "--genre", "Adventure",
+    "--creator-type", "Group",
+    "--detail", "chart_only",
+    "--order-by", "player_count",
+    "--order", "desc",
+    "--limit", "25",
+    "--cursor", "abc.def",
+    "--json"
+  ]);
+
+  assert.equal(request.path, "/api/v1/roblox/experiences");
+  assert.deepEqual(request.query, {
+    country: "US",
+    eligibility_days: "30",
+    min_player_count: "1000",
+    max_rank: "50",
+    genre: "Adventure",
+    creator_type: "Group",
+    detail: "chart_only",
+    order_by: "player_count",
+    order: "desc",
+    limit: "25",
+    cursor: "abc.def"
+  });
+});
+
+/**
+ * The id is carried as the decimal STRING the user typed. Parsing it into a
+ * number would round anything above 2^53 into a different experience's id.
+ */
+test("(NAK-715) a universe id travels as a decimal string, never as a number", () => {
+  const request = buildRequestFromArgv(["roblox", "experience", "9007199254740993", "--json"]);
+
+  assert.equal(request.path, "/api/v1/roblox/experiences/9007199254740993");
+  assert.deepEqual(request.query, {});
+});
+
+test("(NAK-715) roblox history builds the history path and maps the window flags", () => {
+  const request = buildRequestFromArgv([
+    "roblox", "history", "4924922222",
+    "--granularity", "hourly",
+    "--from", "2026-09-13T00:00:00.000Z",
+    "--to", "2026-09-20T00:00:00.000Z",
+    "--json"
+  ]);
+
+  assert.equal(request.path, "/api/v1/roblox/experiences/4924922222/history");
+  assert.deepEqual(request.query, {
+    granularity: "hourly",
+    from: "2026-09-13T00:00:00.000Z",
+    to: "2026-09-20T00:00:00.000Z"
+  });
+});
+
+test("(NAK-715) roblox coverage takes only the cutoff", () => {
+  assert.deepEqual(buildRequestFromArgv(["roblox", "coverage", "--json"]), {
+    path: "/api/v1/roblox/coverage",
+    query: {}
+  });
+
+  const { exitCode } = captureUsageFailure(() =>
+    buildRequestFromArgv(["roblox", "coverage", "--country", "JP", "--json"])
+  );
+  assert.equal(exitCode, 2);
+});
+
+/**
+ * A Steam appid spelling the app's validator rejects must not reach the wire
+ * looking fine, and it must never be mistaken for a universe id.
+ */
+test("(NAK-715) a malformed universe id is a usage error naming the Steam-appid confusion", () => {
+  for (const bad of ["730.0", "0x2da", "7e2", "-1", "0", "007", "abc"]) {
+    const { output, exitCode } = captureUsageFailure(() =>
+      buildRequestFromArgv(["roblox", "experience", bad, "--json"])
+    );
+    assert.equal(exitCode, 2, `expected ${bad} to be refused`);
+    assert.equal(output.error.code, "CLI_USAGE_ERROR");
+    assert.match(output.error.message, /not a Steam appid/);
+  }
+
+  const missing = captureUsageFailure(() => buildRequestFromArgv(["roblox", "history", "--json"]));
+  assert.equal(missing.exitCode, 2);
+});
+
+test("(NAK-715) a flag the endpoint has no parameter for is a usage error, not a dropped narrowing", () => {
+  const { output, exitCode } = captureUsageFailure(() =>
+    buildRequestFromArgv(["roblox", "charts", "--source", "steam", "--json"])
+  );
+
+  assert.equal(exitCode, 2);
+  assert.equal(output.error.code, "CLI_USAGE_ERROR");
+  assert.match(output.error.message, /--source is not supported by gmc roblox charts/);
+});
+
+test("(NAK-715) a stray positional is a usage error rather than a silently ignored argument", () => {
+  const { exitCode } = captureUsageFailure(() =>
+    buildRequestFromArgv(["roblox", "charts", "cozy", "--json"])
+  );
+  assert.equal(exitCode, 2);
+});
+
+/**
+ * Mirrors the tag-trends precedent: removing these from
+ * PROVISIONAL_BETA_COMMANDS would leave every test above green while the
+ * commands silently vanished from `--help`.
+ */
+test("(NAK-715) the roblox commands are published as provisional in --help", () => {
+  for (const command of [
+    "gmc roblox charts --country all --sort top-playing-now --json",
+    "gmc roblox experiences --country all --limit 50 --json",
+    "gmc roblox experience <universeId> --json",
+    "gmc roblox history <universeId> --granularity daily|hourly --json",
+    "gmc roblox coverage --json"
+  ]) {
+    assert.ok(
+      PROVISIONAL_BETA_COMMANDS.includes(command),
+      `${command} must stay listed as provisional`
+    );
+  }
+});