@witchpot/gmc 0.8.0 → 0.10.0

package/src/requests.js

@@ -387,6 +387,29 @@ export function buildRequest(command, options, positional) {
     };
   }
 
+  // NAK-804. A different route shape from every other `games` sub-path above:
+  // there is exactly one game namespace behind it, keyed on the plain numeric
+  // appid, so there is no --source flag to select and no `assertSource` call.
+  // The endpoint takes no query parameters at all (the review-history
+  // sibling's shape), so `assertSupportedOptions` closes the same gap that
+  // one documents: an unsupported flag would otherwise be silently dropped
+  // and answer with exit 0 as if the narrowing had been applied.
+  if (matches(command, ["games", "ai-disclosure"])) {
+    assertSupportedOptions(options, {
+      command: "gmc games ai-disclosure",
+      allowed: []
+    });
+    const appid = assertAppid(positional[0], "gmc games ai-disclosure <appid> --json");
+    assertNoExtraPositionals(positional, {
+      expected: 1,
+      usage: "gmc games ai-disclosure <appid> --json"
+    });
+    return {
+      path: `/api/v1/games/${encodeURIComponent(String(appid))}/ai-disclosure`,
+      query: {}
+    };
+  }
+
   if (matches(command, ["reviews", "patterns"])) {
     assertSource(options.source);
     const isCompare = positional[0] === "compare";
@@ -627,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;
 }
 
@@ -749,6 +903,13 @@ function buildOptionalGameCountRequest(options) {
 // server would have rejected.
 const AI_DISCLOSURE_VALUES = ["disclosed", "absent", "unconfirmed"];
 
+// Mirrors RELEASE_STATUS_FILTER_VALUES in the app's games repository module
+// (NAK-803), which the market RPCs re-check against the same literal triple.
+// Kept as a local literal for the same reason as AI_DISCLOSURE_VALUES above:
+// the CLI package cannot import server code, and the server remains the
+// enforcing authority.
+const RELEASE_STATUS_VALUES = ["released", "upcoming", "tba"];
+
 function buildGameCountQuery(options) {
   const query = pickQuery(options, {
     query: "q",
@@ -834,6 +995,26 @@ function buildGameCountQuery(options) {
       AI_DISCLOSURE_VALUES
     );
   }
+  // NAK-803: --release-status is a FILTER, so it lives in the shared
+  // count-query builder and reaches games search, count and aggregate alike.
+  // `releaseStatus` was already in the REST contract but had no CLI mapping,
+  // which forced the CLI form of a "released games only" question to lean on
+  // the release window alone (see docs/cli-use-cases.md section 67). Like
+  // --ai-disclosure, the three values are a closed set the server enforces
+  // case-sensitively, so a mistyped value is a usage error here rather than a
+  // silently-unfiltered, still-charged request.
+  //
+  // Note this filter is an exact match layered ON TOP of the unconditional
+  // stale-upcoming guard (NAK-78): a title still marked `upcoming` past its
+  // provisional release date is dropped from every query regardless of this
+  // flag, so `--release-status upcoming` never resurrects one.
+  if (options["release-status"] != null) {
+    query.releaseStatus = assertEnumQueryOption(
+      options["release-status"],
+      "--release-status",
+      RELEASE_STATUS_VALUES
+    );
+  }
   return query;
 }
 
@@ -1168,6 +1349,59 @@ function assertExternalId(value, usage) {
   }
 }
 
+/**
+ * NAK-804. Validates the appid positional for `gmc games ai-disclosure`,
+ * mirroring the strict path-parameter check the app applies to every
+ * `/api/v1/.../games/{appid}` route: a plain positive decimal integer, and
+ * nothing else. The lexical test is deliberately `/^\d+$/` rather than
+ * `Number(value)`, the same reasoning `assertLanguageTopicMinReviews` above
+ * documents for `--min-reviews` -- `Number` also accepts the exponent, hex
+ * and decimal-point spellings ("7e2", "0x2da", "730.0") that the app's
+ * validator rejects outright, so letting those through here would mean a
+ * value the API answers 400 for silently reaches the wire as if it were
+ * fine. This check is advisory; the server remains the enforcing authority.
+ */
+function assertAppid(value, usage) {
+  const raw = value == null ? "" : String(value);
+  const appid = DECIMAL_INTEGER_RE.test(raw) ? Number.parseInt(raw, 10) : Number.NaN;
+  if (!Number.isSafeInteger(appid) || appid <= 0) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: `Missing or invalid appid (must be a positive integer). Usage: ${usage}`
+    });
+    process.exit(EXIT_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

@@ -4,6 +4,7 @@ import test from "node:test";
 import { parseArgs } from "./args.js";
 import { buildRequest } from "./requests.js";
 import { printHelp } from "./help.js";
+import { PROVISIONAL_BETA_COMMANDS } from "./constants.js";
 
 function buildRequestFromArgv(argv) {
   const { command, options, positional } = parseArgs(argv);
@@ -402,6 +403,117 @@ test("games more-like-this forwards an explicit country, normalized", () => {
   assert.deepEqual(request.query, { country: "jp" });
 });
 
+// --- gmc games ai-disclosure (NAK-804) ------------------------------------
+//
+// A different route shape from every other `games` sub-path tested above:
+// there is no --source flag (the endpoint is keyed on the plain numeric
+// appid, not a --source-qualified externalId) and no query parameters at
+// all, the review-history sibling's shape.
+
+test("games ai-disclosure targets the canonical route", () => {
+  const request = buildRequestFromArgv(["games", "ai-disclosure", "730", "--json"]);
+
+  assert.equal(request.path, "/api/v1/games/730/ai-disclosure");
+  assert.deepEqual(request.query, {});
+});
+
+test("games ai-disclosure rejects a missing appid", () => {
+  const { output, exitCode } = captureUsageFailure(() =>
+    buildRequestFromArgv(["games", "ai-disclosure", "--json"])
+  );
+
+  assert.equal(exitCode, 2);
+  assert.equal(output.error.code, "CLI_USAGE_ERROR");
+  assert.match(output.error.message, /gmc games ai-disclosure <appid> --json/);
+});
+
+/**
+ * The appid is a plain positive decimal integer, matching the strict
+ * path-parameter check the app applies to every `/api/v1/.../games/{appid}`
+ * route. Each rejected spelling is asserted individually: a string like
+ * "7e2" or "0x2da" round-trips through `Number()` into a valid-looking
+ * integer, so a looser check here would let a value through that the API
+ * answers 400 for.
+ */
+test("games ai-disclosure rejects non-numeric and malformed appid spellings", () => {
+  for (const badAppid of ["not-an-appid", "7e2", "0x2da", "730.5", "-730", "0", " 730", "730 "]) {
+    const { output, exitCode } = captureUsageFailure(() =>
+      buildRequestFromArgv(["games", "ai-disclosure", badAppid, "--json"])
+    );
+
+    assert.equal(exitCode, 2, `expected "${badAppid}" to be rejected`);
+    assert.equal(output.error.code, "CLI_USAGE_ERROR");
+    assert.match(output.error.message, /Missing or invalid appid/);
+  }
+});
+
+test("games ai-disclosure rejects request-shaping flags the endpoint does not have", () => {
+  for (const [flag, value] of [
+    ["--source", "steam"],
+    ["--locale", "ja"],
+    ["--limit", "50"]
+  ]) {
+    const { output, exitCode } = captureUsageFailure(() =>
+      buildRequestFromArgv(["games", "ai-disclosure", "730", flag, value, "--json"])
+    );
+
+    assert.equal(exitCode, 2, `expected ${flag} to be rejected`);
+    assert.equal(output.error.code, "CLI_USAGE_ERROR");
+    assert.match(
+      output.error.message,
+      new RegExp(`\\${flag} is not supported by gmc games ai-disclosure`)
+    );
+  }
+});
+
+/**
+ * Output shaping never reaches the wire, so it must not trip the allowlist.
+ */
+test("games ai-disclosure still accepts the global output flags", () => {
+  const request = buildRequestFromArgv(["games", "ai-disclosure", "730", "--fields", "state", "--json"]);
+
+  assert.equal(request.path, "/api/v1/games/730/ai-disclosure");
+  assert.deepEqual(request.query, {});
+});
+
+test("games ai-disclosure rejects an extra positional argument", () => {
+  const { output, exitCode } = captureUsageFailure(() =>
+    buildRequestFromArgv(["games", "ai-disclosure", "730", "440", "--json"])
+  );
+
+  assert.equal(exitCode, 2);
+  assert.equal(output.error.code, "CLI_USAGE_ERROR");
+  assert.match(output.error.message, /Unexpected extra argument "440"/);
+});
+
+test("help documents gmc games ai-disclosure (NAK-804)", () => {
+  const chunks = [];
+  const original = process.stdout.write;
+  process.stdout.write = (chunk) => {
+    chunks.push(String(chunk));
+    return true;
+  };
+  try {
+    printHelp();
+  } finally {
+    process.stdout.write = original;
+  }
+  const help = chunks.join("");
+
+  assert.ok(help.includes("gmc games ai-disclosure <appid> --json"));
+  assert.ok(help.includes("never that the title\n  uses no generative AI"));
+});
+
+test("games ai-disclosure is listed as Provisional (NAK-804)", () => {
+  // CHANGELOG, api.md and cli-use-cases.md all state that this command is
+  // Provisional in the beta command set. The help-output substring check
+  // above cannot pin this: "gmc games ai-disclosure <appid> --json" also
+  // appears verbatim in the Usage section on its own, so deleting this entry
+  // from PROVISIONAL_BETA_COMMANDS would leave every existing test green
+  // while the docs and reality diverge silently.
+  assert.ok(PROVISIONAL_BETA_COMMANDS.includes("gmc games ai-disclosure <appid> --json"));
+});
+
 // --- gmc games language-topics (NAK-455) ---------------------------------
 
 test("games language-topics targets the canonical route and sends no invented parameters", () => {
@@ -480,7 +592,7 @@ test("games language-topics rejects an out-of-range min_reviews before any reque
 /**
  * `Number("1e2")` and `Number("0x64")` are both 100, so a `Number`-based bounds
  * check would forward these spellings to an endpoint that rejects them:
- * `parseIntParam` (src/server/gmc/api/validation.ts) tests `/^-?\d+$/` and
+ * `parseIntParam` (in the app's API validation module) tests `/^-?\d+$/` and
  * answers 400 `min_reviews must be an integer`. The CLI must not turn a string
  * the API refuses into a successful request.
  */
@@ -921,8 +1033,8 @@ test("(NAK-587) an omitted --catalog-as-of leaves the query untouched", () => {
  * NAK-773. `--ai-disclosure` reaches games search/count/aggregate through the
  * SAME shared query builder as every other filter, and is forwarded verbatim
  * (kebab-case flag to camelCase query param) as the three literal values the
- * server matches case-sensitively (assertAiDisclosureFilterValue,
- * src/server/gmc/repositories/ai-disclosure.ts) -- the CLI does not
+ * server matches case-sensitively (assertAiDisclosureFilterValue, in the
+ * app's AI-disclosure repository module) -- the CLI does not
  * lower-case or trim a typo into a value the caller did not send.
  */
 test("(NAK-773) games search/count/aggregate forward --ai-disclosure as the aiDisclosure query param", () => {
@@ -1022,6 +1134,89 @@ test("(NAK-773) --ai-disclosure composes with the release_month,ai_disclosure cr
   assert.equal(request.query.aiDisclosure, "unconfirmed");
 });
 
+/**
+ * NAK-803. `--release-status` closes the CLI/REST divergence the
+ * AI-disclosure chart-ready recipe documented: `releaseStatus` was reachable
+ * on the REST endpoint but had no CLI mapping, so the CLI variant of a
+ * "released games only" question had to rely on the release window alone.
+ * The three values are the closed set the server enforces
+ * (RELEASE_STATUS_FILTER_VALUES in the app's games repository module, and
+ * the same literal triple the market RPCs re-check), so the CLI rejects
+ * anything outside it locally rather than normalizing a typo into a value
+ * the caller did not send.
+ */
+test("(NAK-803) games search/count/aggregate forward --release-status as the releaseStatus query param", () => {
+  const search = buildRequestFromArgv([
+    "games", "search", "--source", "steam", "--release-status", "released", "--json"
+  ]);
+  assert.equal(search.query.releaseStatus, "released");
+
+  const count = buildRequestFromArgv([
+    "games", "count", "--source", "steam", "--release-status", "upcoming", "--json"
+  ]);
+  assert.equal(count.query.releaseStatus, "upcoming");
+
+  const aggregate = buildRequestFromArgv([
+    "games", "aggregate", "--source", "steam", "--metric", "count",
+    "--release-status", "tba", "--json"
+  ]);
+  assert.equal(aggregate.query.releaseStatus, "tba");
+});
+
+test("(NAK-803) --release-status accepts each of the three enum values", () => {
+  for (const value of ["released", "upcoming", "tba"]) {
+    const request = buildRequestFromArgv(["games", "count", "--source", "steam", "--release-status", value, "--json"]);
+    assert.equal(request.query.releaseStatus, value);
+  }
+});
+
+test("(NAK-803) --release-status composes with the other filters instead of replacing them", () => {
+  const request = buildRequestFromArgv([
+    "games", "count", "--source", "steam",
+    "--release-status", "released",
+    "--ai-disclosure", "disclosed",
+    "--tags", "roguelite",
+    "--rating-min", "80",
+    "--json"
+  ]);
+  assert.equal(request.query.releaseStatus, "released");
+  assert.equal(request.query.aiDisclosure, "disclosed");
+  assert.equal(request.query.tags, "roguelite");
+  assert.equal(request.query.ratingMin, "80");
+});
+
+test("(NAK-803) an invalid --release-status value is a usage error, not a silently unfiltered request", () => {
+  const { output, exitCode } = captureUsageFailure(() =>
+    buildRequestFromArgv(["games", "count", "--source", "steam", "--release-status", "launched", "--json"])
+  );
+  assert.equal(exitCode, 2);
+  assert.equal(output.error.code, "CLI_USAGE_ERROR");
+  assert.match(output.error.message, /--release-status must be one of: released, upcoming, tba/);
+});
+
+test("(NAK-803) --release-status is case-sensitive: a differently-cased value is rejected, not normalized", () => {
+  const { output, exitCode } = captureUsageFailure(() =>
+    buildRequestFromArgv(["games", "count", "--source", "steam", "--release-status", "Released", "--json"])
+  );
+  assert.equal(exitCode, 2);
+  assert.equal(output.error.code, "CLI_USAGE_ERROR");
+  assert.match(output.error.message, /--release-status must be one of: released, upcoming, tba/);
+});
+
+test("(NAK-803) a blank --release-status is a usage error, not a silently unfiltered request", () => {
+  const { output, exitCode } = captureUsageFailure(() =>
+    buildRequestFromArgv(["games", "count", "--source", "steam", "--release-status", "   ", "--json"])
+  );
+  assert.equal(exitCode, 2);
+  assert.equal(output.error.code, "CLI_USAGE_ERROR");
+  assert.match(output.error.message, /--release-status must be one of: released, upcoming, tba/);
+});
+
+test("(NAK-803) an omitted --release-status leaves the query untouched", () => {
+  const request = buildRequestFromArgv(["games", "count", "--source", "steam", "--json"]);
+  assert.equal("releaseStatus" in request.query, false);
+});
+
 /**
  * NAK-706: `gmc steam tag-trends`.
  *
@@ -1102,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`
+    );
+  }
+});