@witchpot/gmc 0.6.0 → 0.9.0

package/src/requests.test.js

@@ -3,6 +3,8 @@ 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);
@@ -136,6 +138,48 @@ test("games count forwards coverage for cohort pre-estimation", () => {
   assert.equal(request.query.coverage, "full");
 });
 
+/**
+ * NAK-247. Before this, --has-demo had no mapping in buildGameCountQuery: the
+ * generic arg parser (args.js) accepts any --flag with no allowlist for
+ * games search/count/aggregate, so a caller's --has-demo silently vanished
+ * rather than reaching the server — an accepted-then-dropped request that
+ * still gets charged unfiltered. Covers all three commands that share
+ * buildGameCountQuery, and both true/false (false is a real filter value,
+ * not "unset").
+ */
+test("(NAK-247) games search/count/aggregate forward --has-demo as the hasDemo query param", () => {
+  const search = buildRequestFromArgv(["games", "search", "--source", "steam", "--has-demo", "true", "--json"]);
+  assert.equal(search.query.hasDemo, "true");
+
+  const count = buildRequestFromArgv(["games", "count", "--source", "steam", "--has-demo", "false", "--json"]);
+  assert.equal(count.query.hasDemo, "false");
+
+  const aggregate = buildRequestFromArgv([
+    "games",
+    "aggregate",
+    "--source",
+    "steam",
+    "--metric",
+    "count",
+    "--has-demo",
+    "true",
+    "--json"
+  ]);
+  assert.equal(aggregate.query.hasDemo, "true");
+});
+
+test("(NAK-247) --has-demo normalizes case and rejects a non-boolean value with a usage error rather than silently dropping the filter", () => {
+  const mixedCase = buildRequestFromArgv(["games", "count", "--source", "steam", "--has-demo", "FALSE", "--json"]);
+  assert.equal(mixedCase.query.hasDemo, "false");
+
+  const { output, exitCode } = captureUsageFailure(() =>
+    buildRequestFromArgv(["games", "count", "--source", "steam", "--has-demo", "maybe", "--json"])
+  );
+  assert.equal(exitCode, 2);
+  assert.equal(output.error.code, "CLI_USAGE_ERROR");
+  assert.match(output.error.message, /--has-demo must be true or false/);
+});
+
 test("reviews patterns forwards coverage into the cohort search request", () => {
   const request = buildRequestFromArgv([
     "reviews",
@@ -173,6 +217,69 @@ test("lists create builds a POST request body", () => {
   });
 });
 
+test("lists games forwards limit, offset and cursor (NAK-525)", () => {
+  const request = buildRequestFromArgv(["lists", "games", "list-1", "--limit", "50", "--cursor", "c1", "--json"]);
+
+  assert.equal(request.path, "/api/v1/lists/list-1/games");
+  assert.equal(request.method, undefined);
+  // A dropped --cursor walks the list by offset while the caller believes it is
+  // following the cursor, which silently reorders a resolution-backed page.
+  assert.deepEqual(request.query, { limit: "50", cursor: "c1" });
+});
+
+test("lists resolve posts to the resolve endpoint with no body (NAK-525)", () => {
+  const request = buildRequestFromArgv(["lists", "resolve", "list-1", "--json"]);
+
+  assert.equal(request.path, "/api/v1/lists/list-1/resolve");
+  assert.equal(request.method, "POST");
+  assert.deepEqual(request.query, {});
+  assert.equal(request.body, undefined);
+});
+
+test("lists materialize posts with --confirm, and an empty body means the current revision (NAK-525)", () => {
+  const request = buildRequestFromArgv(["lists", "materialize", "list-1", "--confirm", "--json"]);
+
+  assert.equal(request.path, "/api/v1/lists/list-1/materialize");
+  assert.equal(request.method, "POST");
+  assert.deepEqual(request.query, {});
+  assert.equal(request.body, undefined);
+});
+
+test("lists materialize sends --expected-revision as the compare-and-swap body (NAK-525)", () => {
+  const request = buildRequestFromArgv([
+    "lists",
+    "materialize",
+    "list-1",
+    "--confirm",
+    "--expected-revision",
+    "4",
+    "--json"
+  ]);
+
+  assert.deepEqual(request.body, { expectedDefinitionRevision: 4 });
+});
+
+test("lists materialize and lists resolve are real command tokens, not positionals (NAK-525)", () => {
+  // A token missing from the args.js whitelist falls through to positional and
+  // silently runs the bare `gmc lists` index with exit 0 — the worst possible
+  // failure mode for a destructive-adjacent command.
+  for (const [subcommand, path] of [
+    ["materialize", "/api/v1/lists/list-1/materialize"],
+    ["resolve", "/api/v1/lists/list-1/resolve"]
+  ]) {
+    const { command, positional } = parseArgs(["lists", subcommand, "list-1", "--confirm", "--json"]);
+    assert.deepEqual(command, ["lists", subcommand]);
+    assert.deepEqual(positional, ["list-1"]);
+    assert.equal(buildRequest(command, { confirm: true, json: true }, positional).path, path);
+  }
+});
+
+test("--confirm is a boolean flag, so it does not swallow the flag after it (NAK-525)", () => {
+  const { options } = parseArgs(["lists", "materialize", "list-1", "--confirm", "--json"]);
+  assert.equal(options.confirm, true);
+  assert.equal(options.json, true);
+});
+
 test("lists add maps comma-separated app ids to item mutation body", () => {
   const request = buildRequestFromArgv([
     "lists",
@@ -232,3 +339,961 @@ test("sampled workflows keep exact totals in a separate count request", () => {
     releaseTo: "2025-12-31"
   });
 });
+
+test("showcases history builds a showcaseHistory request plan requesting the showcases analysis section", () => {
+  const request = buildRequestFromArgv([
+    "showcases",
+    "history",
+    "--source",
+    "steam",
+    "730",
+    "--json"
+  ]);
+
+  assert.equal(request.kind, "showcaseHistory");
+  assert.equal(request.source, "steam");
+  assert.equal(request.externalId, "730");
+  assert.deepEqual(request.detailQuery, { sections: "showcases" });
+});
+
+test("showcases history forwards locale", () => {
+  const request = buildRequestFromArgv([
+    "showcases",
+    "history",
+    "--source",
+    "steam",
+    "730",
+    "--locale",
+    "ja",
+    "--json"
+  ]);
+
+  assert.deepEqual(request.detailQuery, { sections: "showcases", locale: "ja" });
+});
+
+test("games more-like-this targets the canonical route with no country by default", () => {
+  const request = buildRequestFromArgv([
+    "games",
+    "more-like-this",
+    "--source",
+    "steam",
+    "730",
+    "--json"
+  ]);
+
+  assert.equal(request.path, "/api/v1/steam/games/730/more-like-this");
+  // The server owns the us default; the CLI must not send a country of its
+  // own invention, or the two defaults could drift apart.
+  assert.deepEqual(request.query, {});
+});
+
+test("games more-like-this forwards an explicit country, normalized", () => {
+  const request = buildRequestFromArgv([
+    "games",
+    "more-like-this",
+    "--source",
+    "steam",
+    "730",
+    "--country",
+    "JP",
+    "--json"
+  ]);
+
+  assert.equal(request.path, "/api/v1/steam/games/730/more-like-this");
+  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", () => {
+  const request = buildRequestFromArgv([
+    "games",
+    "language-topics",
+    "--source",
+    "steam",
+    "730",
+    "--json"
+  ]);
+
+  assert.equal(request.path, "/api/v1/steam/games/730/review-topics/languages");
+  // The server owns the min_reviews default (30) and the include_insufficient
+  // default (false). The CLI must not send a copy of either, or the two
+  // defaults could drift apart.
+  assert.deepEqual(request.query, {});
+});
+
+test("games language-topics forwards min_reviews and include_insufficient", () => {
+  const request = buildRequestFromArgv([
+    "games",
+    "language-topics",
+    "--source",
+    "steam",
+    "730",
+    "--min-reviews",
+    "50",
+    "--include-insufficient",
+    "--json"
+  ]);
+
+  assert.equal(request.path, "/api/v1/steam/games/730/review-topics/languages");
+  assert.deepEqual(request.query, { min_reviews: "50", include_insufficient: "true" });
+});
+
+test("games language-topics accepts both ends of the documented min_reviews range", () => {
+  for (const value of ["10", "200"]) {
+    const request = buildRequestFromArgv([
+      "games",
+      "language-topics",
+      "--source",
+      "steam",
+      "730",
+      "--min-reviews",
+      value,
+      "--json"
+    ]);
+
+    assert.deepEqual(request.query, { min_reviews: value });
+  }
+});
+
+test("games language-topics rejects an out-of-range min_reviews before any request is built", () => {
+  for (const value of ["9", "201", "30.5", "abc"]) {
+    const { output, exitCode } = captureUsageFailure(() =>
+      buildRequestFromArgv([
+        "games",
+        "language-topics",
+        "--source",
+        "steam",
+        "730",
+        "--min-reviews",
+        value,
+        "--json"
+      ])
+    );
+
+    assert.equal(exitCode, 2);
+    assert.equal(output.error.code, "CLI_USAGE_ERROR");
+    // Same bound, same wording direction as the REST 400 (param min_reviews).
+    assert.match(output.error.message, /--min-reviews must be an integer between 10 and 200/);
+  }
+});
+
+/**
+ * `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` (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.
+ */
+test("games language-topics rejects the exponent and hex spellings REST rejects", () => {
+  for (const value of ["1e2", "0x64", "1_0", " 50", "+50", "50 "]) {
+    const { output, exitCode } = captureUsageFailure(() =>
+      buildRequestFromArgv([
+        "games",
+        "language-topics",
+        "--source",
+        "steam",
+        "730",
+        "--min-reviews",
+        value,
+        "--json"
+      ])
+    );
+
+    assert.equal(exitCode, 2, `expected --min-reviews ${JSON.stringify(value)} to be rejected`);
+    assert.equal(output.error.code, "CLI_USAGE_ERROR");
+    assert.match(output.error.message, /--min-reviews must be an integer between 10 and 200/);
+  }
+});
+
+/**
+ * Boolean flags are presence-only. `--include-insufficient=false` previously
+ * parsed to TRUE (the inline value was discarded), which inverted exactly the
+ * intent the caller spelled out. A usage error is the only reading that cannot
+ * silently do the opposite of what was asked.
+ */
+test("a boolean flag rejects the --flag=value spelling instead of silently reading it as true", () => {
+  for (const flag of ["--include-insufficient=false", "--include-insufficient=true", "--json=false"]) {
+    const { output, exitCode } = captureUsageFailure(() =>
+      buildRequestFromArgv([
+        "games",
+        "language-topics",
+        "--source",
+        "steam",
+        "730",
+        flag,
+        "--json"
+      ])
+    );
+
+    assert.equal(exitCode, 2, `expected ${flag} to be rejected`);
+    assert.equal(output.error.code, "CLI_USAGE_ERROR");
+    assert.match(output.error.message, /is a flag and takes no value/);
+  }
+});
+
+/**
+ * NAK-428 found the same silent-ignore gap here: this endpoint's whole
+ * parameter surface is `min_reviews` + `include_insufficient`, so a --limit or
+ * --locale was accepted and dropped, and the caller's narrowing vanished with
+ * exit 0.
+ */
+test("games language-topics rejects request-shaping flags the endpoint does not have", () => {
+  for (const [flag, value] of [
+    ["--limit", "50"],
+    ["--locale", "ja"],
+    ["--offset", "10"],
+    ["--language", "japanese"]
+  ]) {
+    const { output, exitCode } = captureUsageFailure(() =>
+      buildRequestFromArgv([
+        "games",
+        "language-topics",
+        "--source",
+        "steam",
+        "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 language-topics`)
+    );
+  }
+});
+
+test("games language-topics rejects an extra positional argument", () => {
+  const { output, exitCode } = captureUsageFailure(() =>
+    buildRequestFromArgv(["games", "language-topics", "--source", "steam", "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("the bare boolean flag still enables the option", () => {
+  const request = buildRequestFromArgv([
+    "games",
+    "language-topics",
+    "--source",
+    "steam",
+    "730",
+    "--include-insufficient",
+    "--json"
+  ]);
+
+  assert.deepEqual(request.query, { include_insufficient: "true" });
+});
+
+// --- gmc games review-history (NAK-428) ----------------------------------
+
+test("games review-history targets the canonical route", () => {
+  const request = buildRequestFromArgv([
+    "games",
+    "review-history",
+    "--source",
+    "steam",
+    "730",
+    "--json"
+  ]);
+
+  assert.equal(request.path, "/api/v1/steam/games/730/review-history");
+  assert.deepEqual(request.query, {});
+});
+
+/**
+ * The endpoint takes NO query parameters. Range presets are a display concern
+ * the web UI applies client-side over the full series, so a --range/--from/
+ * --to/--limit here would make the CLI, rather than the service, decide which
+ * observations a caller sees.
+ *
+ * Not supporting them is not the same as tolerating them. Accepting the flag
+ * and dropping it returns the FULL series with exit 0, so the caller who asked
+ * for a window reads the unwindowed answer as the windowed one — the failure is
+ * invisible at exactly the moment it matters. Each rejection is asserted
+ * individually so a partial allowlist cannot pass on the strength of its
+ * neighbours.
+ */
+test("games review-history rejects every request-shaping flag by name", () => {
+  for (const [flag, value] of [
+    ["--range", "1y"],
+    ["--from", "2026-01-01"],
+    ["--to", "2026-08-01"],
+    ["--limit", "50"],
+    ["--locale", "ja"],
+    ["--offset", "10"]
+  ]) {
+    const { output, exitCode } = captureUsageFailure(() =>
+      buildRequestFromArgv([
+        "games",
+        "review-history",
+        "--source",
+        "steam",
+        "730",
+        flag,
+        value,
+        "--json"
+      ])
+    );
+
+    assert.equal(exitCode, 2, `expected ${flag} to be rejected`);
+    assert.equal(output.error.code, "CLI_USAGE_ERROR");
+    // The message has to name the flag the caller typed: "unsupported option"
+    // alone leaves them guessing which of several it was.
+    assert.match(
+      output.error.message,
+      new RegExp(`\\${flag} is not supported by gmc games review-history`)
+    );
+  }
+});
+
+/**
+ * Output shaping never reaches the wire, so it must not trip the allowlist.
+ */
+test("games review-history still accepts the global output flags", () => {
+  const request = buildRequestFromArgv([
+    "games",
+    "review-history",
+    "--source",
+    "steam",
+    "730",
+    "--fields",
+    "series",
+    "--json"
+  ]);
+
+  assert.equal(request.path, "/api/v1/steam/games/730/review-history");
+  assert.deepEqual(request.query, {});
+});
+
+/**
+ * A second bare argument is either a typo or a second appid the caller expected
+ * to be fetched. Both readings are worse when the first app's history comes
+ * back as if nothing were wrong.
+ */
+test("games review-history rejects an extra positional argument", () => {
+  const { output, exitCode } = captureUsageFailure(() =>
+    buildRequestFromArgv(["games", "review-history", "--source", "steam", "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("games review-history percent-encodes the external id into the path", () => {
+  const request = buildRequestFromArgv([
+    "games",
+    "review-history",
+    "--source",
+    "steam",
+    "7 30",
+    "--json"
+  ]);
+
+  assert.equal(request.path, "/api/v1/steam/games/7%2030/review-history");
+});
+
+test("games review-history rejects a missing external id", () => {
+  const { output, exitCode } = captureUsageFailure(() =>
+    buildRequestFromArgv(["games", "review-history", "--source", "steam", "--json"])
+  );
+
+  assert.equal(exitCode, 2);
+  assert.equal(output.error.code, "CLI_USAGE_ERROR");
+  assert.match(output.error.message, /gmc games review-history --source steam <externalId> --json/);
+});
+
+test("games review-history rejects a non-steam source", () => {
+  const { output, exitCode } = captureUsageFailure(() =>
+    buildRequestFromArgv(["games", "review-history", "--source", "epic", "730", "--json"])
+  );
+
+  assert.equal(exitCode, 2);
+  assert.equal(output.error.code, "CLI_USAGE_ERROR");
+  assert.match(output.error.message, /Only --source steam is supported/);
+});
+
+/**
+ * The CLI reports usage errors by writing a JSON error to stdout and calling
+ * process.exit — there is no throwing variant to assert on. Replacing exit
+ * with a throw is what makes the bounded-error path testable in-process; the
+ * captured code and payload are exactly what a real shell would see.
+ */
+function captureUsageFailure(run) {
+  const originalWrite = process.stdout.write;
+  const originalExit = process.exit;
+  const chunks = [];
+  let exitCode;
+  process.stdout.write = (chunk) => {
+    chunks.push(String(chunk));
+    return true;
+  };
+  process.exit = (code) => {
+    exitCode = code;
+    throw new Error("__cli_exit__");
+  };
+  try {
+    run();
+    throw new Error("expected the CLI to exit with a usage error");
+  } catch (error) {
+    if (error.message !== "__cli_exit__") throw error;
+  } finally {
+    process.stdout.write = originalWrite;
+    process.exit = originalExit;
+  }
+
+  return { output: JSON.parse(chunks.join("")), exitCode };
+}
+
+test("games aggregate forwards as_of and compare_as_of (NAK-248)", () => {
+  const request = buildRequestFromArgv([
+    "games",
+    "aggregate",
+    "--source",
+    "steam",
+    "--metric",
+    "count",
+    "--group-by",
+    "release_year",
+    "--as-of",
+    "2026-08-01",
+    "--compare-as-of",
+    "2026-06-01",
+    "--json"
+  ]);
+
+  assert.equal(request.path, "/api/v1/steam/games/aggregate");
+  assert.equal(request.query.as_of, "2026-08-01");
+  assert.equal(request.query.compare_as_of, "2026-06-01");
+});
+
+test("games aggregate omits the comparison params when they are not supplied", () => {
+  const request = buildRequestFromArgv([
+    "games",
+    "aggregate",
+    "--source",
+    "steam",
+    "--metric",
+    "count",
+    "--json"
+  ]);
+
+  assert.equal("as_of" in request.query, false);
+  assert.equal("compare_as_of" in request.query, false);
+});
+
+test("help documents the v2 query envelope and both new lists commands (NAK-525)", () => {
+  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 lists resolve <id> --json"));
+  assert.ok(help.includes("gmc lists materialize <id> --confirm --json"));
+  assert.ok(help.includes("gmc lists games <id> --limit <number> --cursor <cursor> --json"));
+  // The envelope itself, not just its name: a caller composing --filter needs
+  // the shape and the rule that structured decides membership.
+  assert.ok(help.includes('"version":2,"mode":"query"'));
+  assert.ok(help.includes("structured decides membership"));
+  assert.ok(help.includes("total_kind"));
+  assert.ok(help.includes("RESOLUTION_REQUIRED"));
+});
+
+/**
+ * NAK-207. `--event-name` reaches games search/count/aggregate through the
+ * SAME shared query builder as every other filter, so an event cohort can be
+ * combined with tags and bounds in one command. Validating the slug is the
+ * server's job (INVALID_EVENT with suggestions); the CLI only refuses a blank
+ * value, which the query parser would otherwise drop, leaving the caller
+ * reading the whole catalog as an event cohort.
+ */
+test("(NAK-207) games search/count/aggregate forward --event-name as the eventName query param", () => {
+  const search = buildRequestFromArgv([
+    "games", "search", "--source", "steam", "--event-name", "tokyo_game_dungeon_2026", "--json"
+  ]);
+  assert.equal(search.query.eventName, "tokyo_game_dungeon_2026");
+
+  const count = buildRequestFromArgv([
+    "games", "count", "--source", "steam", "--event-name", "nextfest_june_2026", "--json"
+  ]);
+  assert.equal(count.query.eventName, "nextfest_june_2026");
+
+  const aggregate = buildRequestFromArgv([
+    "games", "aggregate", "--source", "steam", "--metric", "count",
+    "--event-name", "nextfest_june_2026", "--json"
+  ]);
+  assert.equal(aggregate.query.eventName, "nextfest_june_2026");
+});
+
+test("(NAK-207) --event-name composes with the other filters instead of replacing them", () => {
+  const request = buildRequestFromArgv([
+    "games", "count", "--source", "steam",
+    "--event-name", "tokyo_game_dungeon_2026",
+    "--tags", "roguelite",
+    "--rating-min", "80",
+    "--json"
+  ]);
+  assert.equal(request.query.eventName, "tokyo_game_dungeon_2026");
+  assert.equal(request.query.tags, "roguelite");
+  assert.equal(request.query.ratingMin, "80");
+});
+
+test("(NAK-207) a blank --event-name is a usage error, not a silently unfiltered request", () => {
+  const { output, exitCode } = captureUsageFailure(() =>
+    buildRequestFromArgv(["games", "count", "--source", "steam", "--event-name", "   ", "--json"])
+  );
+  assert.equal(exitCode, 2);
+  assert.equal(output.error.code, "CLI_USAGE_ERROR");
+  assert.match(output.error.message, /--event-name must be a non-empty Steam event slug/);
+});
+
+/**
+ * NAK-587. `--catalog-as-of` reaches games search/count/aggregate through the
+ * SAME shared query builder as every other filter (it is a filter, not a
+ * snapshot dial like `--as-of`), and it is forwarded under the REST spelling
+ * `catalog_as_of` rather than a camelCase one — matching `as_of` /
+ * `compare_as_of`, the other date parameters.
+ */
+test("(NAK-587) games search/count/aggregate forward --catalog-as-of as the catalog_as_of query param", () => {
+  const search = buildRequestFromArgv([
+    "games", "search", "--source", "steam", "--catalog-as-of", "2026-08-01", "--json"
+  ]);
+  assert.equal(search.query.catalog_as_of, "2026-08-01");
+
+  const count = buildRequestFromArgv([
+    "games", "count", "--source", "steam", "--catalog-as-of", "2026-08-01", "--json"
+  ]);
+  assert.equal(count.query.catalog_as_of, "2026-08-01");
+
+  const aggregate = buildRequestFromArgv([
+    "games", "aggregate", "--source", "steam", "--metric", "count",
+    "--catalog-as-of", "2026-08-01", "--json"
+  ]);
+  assert.equal(aggregate.query.catalog_as_of, "2026-08-01");
+});
+
+test("(NAK-587) --catalog-as-of composes with the other filters and with --as-of", () => {
+  const request = buildRequestFromArgv([
+    "games", "aggregate", "--source", "steam", "--metric", "count",
+    "--catalog-as-of", "2026-08-01",
+    "--as-of", "2026-08-15",
+    "--tags", "roguelite",
+    "--rating-min", "80",
+    "--json"
+  ]);
+  // The two dates are different dials and must both survive: `as_of` chooses
+  // the metric snapshot, `catalog_as_of` chooses the population.
+  assert.equal(request.query.catalog_as_of, "2026-08-01");
+  assert.equal(request.query.as_of, "2026-08-15");
+  assert.equal(request.query.tags, "roguelite");
+  assert.equal(request.query.ratingMin, "80");
+});
+
+test("(NAK-587) a blank --catalog-as-of is a usage error, not a silently unfiltered request", () => {
+  const { output, exitCode } = captureUsageFailure(() =>
+    buildRequestFromArgv(["games", "count", "--source", "steam", "--catalog-as-of", "   ", "--json"])
+  );
+  assert.equal(exitCode, 2);
+  assert.equal(output.error.code, "CLI_USAGE_ERROR");
+  assert.match(output.error.message, /--catalog-as-of must be a date in YYYY-MM-DD format/);
+});
+
+test("(NAK-587) an omitted --catalog-as-of leaves the query untouched", () => {
+  const request = buildRequestFromArgv(["games", "count", "--source", "steam", "--json"]);
+  assert.equal("catalog_as_of" in request.query, false);
+});
+
+/**
+ * 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, 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", () => {
+  const search = buildRequestFromArgv([
+    "games", "search", "--source", "steam", "--ai-disclosure", "disclosed", "--json"
+  ]);
+  assert.equal(search.query.aiDisclosure, "disclosed");
+
+  const count = buildRequestFromArgv([
+    "games", "count", "--source", "steam", "--ai-disclosure", "absent", "--json"
+  ]);
+  assert.equal(count.query.aiDisclosure, "absent");
+
+  const aggregate = buildRequestFromArgv([
+    "games", "aggregate", "--source", "steam", "--metric", "count",
+    "--ai-disclosure", "unconfirmed", "--json"
+  ]);
+  assert.equal(aggregate.query.aiDisclosure, "unconfirmed");
+});
+
+test("(NAK-773) --ai-disclosure accepts each of the three enum values", () => {
+  for (const value of ["disclosed", "absent", "unconfirmed"]) {
+    const request = buildRequestFromArgv(["games", "count", "--source", "steam", "--ai-disclosure", value, "--json"]);
+    assert.equal(request.query.aiDisclosure, value);
+  }
+});
+
+test("(NAK-773) --ai-disclosure composes with the other filters instead of replacing them", () => {
+  const request = buildRequestFromArgv([
+    "games", "count", "--source", "steam",
+    "--ai-disclosure", "disclosed",
+    "--tags", "roguelite",
+    "--rating-min", "80",
+    "--json"
+  ]);
+  assert.equal(request.query.aiDisclosure, "disclosed");
+  assert.equal(request.query.tags, "roguelite");
+  assert.equal(request.query.ratingMin, "80");
+});
+
+test("(NAK-773) an invalid --ai-disclosure value is a usage error, not a silently unfiltered request", () => {
+  const { output, exitCode } = captureUsageFailure(() =>
+    buildRequestFromArgv(["games", "count", "--source", "steam", "--ai-disclosure", "confirmed", "--json"])
+  );
+  assert.equal(exitCode, 2);
+  assert.equal(output.error.code, "CLI_USAGE_ERROR");
+  assert.match(output.error.message, /--ai-disclosure must be one of: disclosed, absent, unconfirmed/);
+});
+
+test("(NAK-773) --ai-disclosure is case-sensitive: a differently-cased value is rejected, not normalized", () => {
+  const { output, exitCode } = captureUsageFailure(() =>
+    buildRequestFromArgv(["games", "count", "--source", "steam", "--ai-disclosure", "Disclosed", "--json"])
+  );
+  assert.equal(exitCode, 2);
+  assert.equal(output.error.code, "CLI_USAGE_ERROR");
+  assert.match(output.error.message, /--ai-disclosure must be one of: disclosed, absent, unconfirmed/);
+});
+
+test("(NAK-773) a blank --ai-disclosure is a usage error, not a silently unfiltered request", () => {
+  const { output, exitCode } = captureUsageFailure(() =>
+    buildRequestFromArgv(["games", "count", "--source", "steam", "--ai-disclosure", "   ", "--json"])
+  );
+  assert.equal(exitCode, 2);
+  assert.equal(output.error.code, "CLI_USAGE_ERROR");
+  assert.match(output.error.message, /--ai-disclosure must be one of: disclosed, absent, unconfirmed/);
+});
+
+test("(NAK-773) an omitted --ai-disclosure leaves the query untouched", () => {
+  const request = buildRequestFromArgv(["games", "count", "--source", "steam", "--json"]);
+  assert.equal("aiDisclosure" in request.query, false);
+});
+
+/**
+ * NAK-773. The aggregate `--group-by` cross-tab is a plain pass-through
+ * string (buildGameAggregateQuery forwards it verbatim via pickQuery), so a
+ * multi-dimension cross-tab like `release_month,ai_disclosure` needs no
+ * special-casing here -- proving that is the point of this test, not
+ * asserting new behavior.
+ */
+test("(NAK-773) --group-by release_month,ai_disclosure flows through the aggregate builder unchanged", () => {
+  const request = buildRequestFromArgv([
+    "games", "aggregate", "--source", "steam", "--metric", "count",
+    "--group-by", "release_month,ai_disclosure",
+    "--json"
+  ]);
+  assert.equal(request.query.groupBy, "release_month,ai_disclosure");
+});
+
+test("(NAK-773) --ai-disclosure composes with the release_month,ai_disclosure cross-tab", () => {
+  const request = buildRequestFromArgv([
+    "games", "aggregate", "--source", "steam", "--metric", "count",
+    "--group-by", "release_month,ai_disclosure",
+    "--ai-disclosure", "unconfirmed",
+    "--json"
+  ]);
+  assert.equal(request.query.groupBy, "release_month,ai_disclosure");
+  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`.
+ *
+ * The CLI is a pass-through here on purpose — the per-view allowlist, the enum
+ * members and the two limit ceilings live on the server, so these tests pin
+ * the MAPPING (flag name to query parameter, and omission when unset) rather
+ * than restating a contract the CLI does not own.
+ */
+test("(NAK-706) steam tag-trends defaults to the bare endpoint and lets the server pick the view", () => {
+  const request = buildRequestFromArgv(["steam", "tag-trends", "--json"]);
+
+  assert.equal(request.path, "/api/v1/steam/tag-trends");
+  // Empty, not {view: "featured"}: a default copied here could drift from the
+  // server's.
+  assert.deepEqual(request.query, {});
+});
+
+test("(NAK-706) steam tag-trends maps every flag to its query parameter", () => {
+  const request = buildRequestFromArgv([
+    "steam", "tag-trends",
+    "--view", "table",
+    "--family", "mechanic",
+    "--q", "cozy",
+    "--supply-direction", "up",
+    "--sort", "current_share",
+    "--order", "asc",
+    "--limit", "50",
+    "--cursor", "abc.def",
+    "--json"
+  ]);
+
+  assert.equal(request.path, "/api/v1/steam/tag-trends");
+  assert.deepEqual(request.query, {
+    view: "table",
+    family: "mechanic",
+    q: "cozy",
+    // The one renaming: the CLI's kebab-case flag reaches the endpoint's
+    // snake_case parameter.
+    supply_direction: "up",
+    sort: "current_share",
+    order: "asc",
+    limit: "50",
+    cursor: "abc.def"
+  });
+});
+
+test("(NAK-706) steam tag-trends forwards --tag for the single-tag view", () => {
+  const request = buildRequestFromArgv(["steam", "tag-trends", "--view", "tag", "--tag", "cozy", "--json"]);
+
+  assert.deepEqual(request.query, { view: "tag", tag: "cozy" });
+});
+
+test("(NAK-706) a flag the endpoint has no parameter for is a usage error, not a dropped narrowing", () => {
+  const { output, exitCode } = captureUsageFailure(() =>
+    buildRequestFromArgv(["steam", "tag-trends", "--view", "board", "--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 steam tag-trends/);
+});
+
+test("(NAK-706) a stray positional is a usage error rather than a silently ignored argument", () => {
+  const { output, exitCode } = captureUsageFailure(() =>
+    buildRequestFromArgv(["steam", "tag-trends", "cozy", "--json"])
+  );
+
+  assert.equal(exitCode, 2);
+  assert.equal(output.error.code, "CLI_USAGE_ERROR");
+  assert.match(output.error.message, /Unexpected extra argument "cozy"/);
+});
+
+test('trend-stories preserves story, edition, locale and list pagination options', () => {
+  assert.deepEqual(buildRequestFromArgv(['steam', 'trend-stories', '--story', 'story-id', '--edition', 'edition-id', '--locale', 'ja', '--json']), {
+    path: '/api/v1/steam/trend-stories', query: { story: 'story-id', edition: 'edition-id', locale: 'ja' }
+  });
+  assert.deepEqual(buildRequestFromArgv(['steam', 'trend-stories', '--tag', 'cozy', '--limit', '1', '--offset', '1', '--fields', 'summary', '--json']).query, { tag: 'cozy', limit: '1', offset: '1', fields: 'summary' });
+  assert.equal(captureUsageFailure(() => buildRequestFromArgv(['steam', 'trend-stories', '--family', 'mood'])).exitCode, 2);
+  assert.equal(captureUsageFailure(() => buildRequestFromArgv(['steam', 'trend-stories', 'unexpected'])).exitCode, 2);
+});