@witchpot/gmc 0.9.0 → 0.11.0

package/src/requests.test.js

@@ -514,6 +514,111 @@ test("games ai-disclosure is listed as Provisional (NAK-804)", () => {
   assert.ok(PROVISIONAL_BETA_COMMANDS.includes("gmc games ai-disclosure <appid> --json"));
 });
 
+// --- gmc games price-history / screenshot-labels (NAK-934) ----------------
+//
+// The ai-disclosure route shape: a plain numeric appid, no --source.
+
+test("games price-history targets the steam route and leaves the window to the server by default", () => {
+  const request = buildRequestFromArgv(["games", "price-history", "730", "--json"]);
+
+  assert.equal(request.path, "/api/v1/steam/games/730/price-history");
+  assert.deepEqual(request.query, {});
+});
+
+test("games price-history forwards --range, or --from/--to, verbatim", () => {
+  assert.deepEqual(
+    buildRequestFromArgv(["games", "price-history", "730", "--range", "1y", "--json"]).query,
+    { range: "1y" }
+  );
+  assert.deepEqual(
+    buildRequestFromArgv([
+      "games", "price-history", "730", "--from", "2026-01-01", "--to", "2026-03-31", "--json"
+    ]).query,
+    { from: "2026-01-01", to: "2026-03-31" }
+  );
+});
+
+test("games price-history rejects a bad window before any request", () => {
+  for (const [argv, message] of [
+    [["--range", "90d"], /--range must be one of: 7d, 1m, 1y, all/],
+    [["--range", "1y", "--from", "2026-01-01"], /--range cannot be combined with --from or --to/],
+    [["--from", "2026/01/01"], /--from must use YYYY-MM-DD/],
+    [["--to", "yesterday"], /--to must use YYYY-MM-DD/],
+    // Real calendar dates only, as on the server (NAK-934 review).
+    [["--from", "2026-02-30"], /--from must be a real calendar date/],
+    [["--to", "2025-02-29"], /--to must be a real calendar date/],
+    [["--from", "2026-13-01"], /--from must be a real calendar date/],
+    [["--to", "2026-04-00"], /--to must be a real calendar date/],
+    // An explicit pair must be ordered.
+    [["--from", "2026-05-01", "--to", "2026-04-01"], /--from must be on or before --to/],
+    [["--country", "jp"], /--country is not supported by gmc games price-history/],
+    [["--source", "steam"], /--source is not supported by gmc games price-history/]
+  ]) {
+    const { output, exitCode } = captureUsageFailure(() =>
+      buildRequestFromArgv(["games", "price-history", "730", ...argv, "--json"])
+    );
+    assert.equal(exitCode, 2, argv.join(" "));
+    assert.equal(output.error.code, "CLI_USAGE_ERROR");
+    assert.match(output.error.message, message);
+  }
+});
+
+test("games price-history accepts a leap day, a single-day window and a lone --from", () => {
+  assert.deepEqual(
+    buildRequestFromArgv(["games", "price-history", "730", "--from", "2024-02-29", "--json"]).query,
+    { from: "2024-02-29" }
+  );
+  assert.deepEqual(
+    buildRequestFromArgv([
+      "games", "price-history", "730", "--from", "2026-04-01", "--to", "2026-04-01", "--json"
+    ]).query,
+    { from: "2026-04-01", to: "2026-04-01" }
+  );
+});
+
+test("games price-history rejects a malformed appid and an extra positional", () => {
+  for (const argv of [["0x2da"], ["730", "440"], []]) {
+    const { output, exitCode } = captureUsageFailure(() =>
+      buildRequestFromArgv(["games", "price-history", ...argv, "--json"])
+    );
+    assert.equal(exitCode, 2, argv.join(" "));
+    assert.equal(output.error.code, "CLI_USAGE_ERROR");
+  }
+});
+
+test("games screenshot-labels targets the steam route and takes no options", () => {
+  const request = buildRequestFromArgv(["games", "screenshot-labels", "730", "--fields", "labels", "--json"]);
+  assert.equal(request.path, "/api/v1/steam/games/730/screenshot-labels");
+  assert.deepEqual(request.query, {});
+
+  const { output, exitCode } = captureUsageFailure(() =>
+    buildRequestFromArgv(["games", "screenshot-labels", "730", "--limit", "5", "--json"])
+  );
+  assert.equal(exitCode, 2);
+  assert.match(output.error.message, /--limit is not supported by gmc games screenshot-labels/);
+});
+
+test("help documents the NAK-934 commands and lists them as Provisional", () => {
+  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 price-history <appid> [--range <preset>]"));
+  assert.ok(help.includes("gmc games screenshot-labels <appid> --json"));
+  assert.ok(help.includes("MODEL OUTPUT"));
+  assert.ok(PROVISIONAL_BETA_COMMANDS.includes("gmc games price-history <appid> --range 7d|1m|1y|all --json"));
+  assert.ok(PROVISIONAL_BETA_COMMANDS.includes("gmc games screenshot-labels <appid> --json"));
+});
+
 // --- gmc games language-topics (NAK-455) ---------------------------------
 
 test("games language-topics targets the canonical route and sends no invented parameters", () => {
@@ -1297,3 +1402,443 @@ 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`
+    );
+  }
+});
+
+/**
+ * NAK-723: `gmc roblox saved | save | remove`.
+ *
+ * The saved surface is workspace-scoped and MUTATING, so these tests pin what
+ * the read tests above do not have to: which flags belong to the list and not
+ * to the writes, that the two writes carry the right HTTP method and path,
+ * and that the id reaches the BODY as a decimal string rather than a number.
+ */
+test("(NAK-723) roblox saved reads the bare endpoint and lets the server pick the scope", () => {
+  assert.deepEqual(buildRequestFromArgv(["roblox", "saved", "--json"]), {
+    path: "/api/v1/roblox/saved",
+    // Empty, not {country: "all"}: a default copied here could drift from the
+    // server's, exactly as on the read family.
+    query: {}
+  });
+});
+
+test("(NAK-723) roblox saved maps every scope flag to its query parameter", () => {
+  const request = buildRequestFromArgv([
+    "roblox", "saved",
+    "--country", "JP",
+    "--device", "computer",
+    "--sort", "top-trending",
+    "--as-of", "2026-09-20T00:00:00.000Z",
+    "--eligibility-days", "30",
+    "--json"
+  ]);
+
+  assert.equal(request.path, "/api/v1/roblox/saved");
+  assert.equal(request.method, undefined);
+  assert.deepEqual(request.query, {
+    country: "JP",
+    device: "computer",
+    sort: "top-trending",
+    as_of: "2026-09-20T00:00:00.000Z",
+    eligibility_days: "30"
+  });
+});
+
+/**
+ * The saved set is capped per workspace and one response always holds all of
+ * it. Accepting a pager would imply the list can hide part of itself, and the
+ * REST allowlist rejects both.
+ */
+test("(NAK-723) roblox saved is not paginated and refuses a pager rather than dropping it", () => {
+  for (const flag of ["--limit", "--cursor", "--offset"]) {
+    const { output, exitCode } = captureUsageFailure(() =>
+      buildRequestFromArgv(["roblox", "saved", flag, "10", "--json"])
+    );
+    assert.equal(exitCode, 2, `expected ${flag} to be refused`);
+    assert.match(output.error.message, /is not supported by gmc roblox saved/);
+  }
+});
+
+test("(NAK-723) roblox save posts the id as a decimal string body", () => {
+  const request = buildRequestFromArgv(["roblox", "save", "4924922222", "--json"]);
+
+  assert.equal(request.path, "/api/v1/roblox/saved");
+  assert.equal(request.method, "POST");
+  assert.deepEqual(request.query, {});
+  assert.deepEqual(request.body, { universeId: "4924922222" });
+  // The server refuses a JSON number outright, because a number is what a
+  // caller sends when it has routed a Steam appid into this path.
+  assert.equal(typeof request.body.universeId, "string");
+});
+
+/**
+ * Above 2^53 a number would round into a DIFFERENT experience's id, and the
+ * body is where that would silently succeed.
+ */
+test("(NAK-723) a large universe id keeps every digit through the save body", () => {
+  const request = buildRequestFromArgv(["roblox", "save", "9007199254740993", "--json"]);
+  assert.deepEqual(request.body, { universeId: "9007199254740993" });
+  assert.notEqual(String(Number("9007199254740993")), request.body.universeId);
+});
+
+test("(NAK-723) roblox remove deletes the per-id path", () => {
+  const request = buildRequestFromArgv(["roblox", "remove", "4924922222", "--json"]);
+
+  assert.equal(request.path, "/api/v1/roblox/saved/4924922222");
+  assert.equal(request.method, "DELETE");
+  assert.deepEqual(request.query, {});
+  assert.equal(request.body, undefined);
+});
+
+/**
+ * The scope flags belong to `saved` alone. A save that quietly ignored
+ * --country would look correct while answering a question nobody asked, and
+ * the identical REST request is a 400.
+ */
+test("(NAK-723) the writes take no flags, so a scope flag is a usage error", () => {
+  for (const subcommand of ["save", "remove"]) {
+    for (const [flag, value] of [["--country", "JP"], ["--as-of", "2026-09-20T00:00:00.000Z"]]) {
+      const { output, exitCode } = captureUsageFailure(() =>
+        buildRequestFromArgv(["roblox", subcommand, "4924922222", flag, value, "--json"])
+      );
+      assert.equal(exitCode, 2, `expected ${subcommand} ${flag} to be refused`);
+      assert.equal(output.error.code, "CLI_USAGE_ERROR");
+      assert.match(output.error.message, new RegExp(`is not supported by gmc roblox ${subcommand}`));
+      // A command with an empty allowlist says so, rather than rendering
+      // "Supported options: ." and reading like a truncated message.
+      assert.match(output.error.message, /This command takes no options\./);
+    }
+  }
+});
+
+/**
+ * The same lexical contract the read commands enforce, applied before any
+ * request is built: a spelling the server's `parseRobloxId` rejects must not
+ * reach the wire looking fine, and the message must name the Steam-appid
+ * confusion rather than only "invalid id".
+ */
+test("(NAK-723) a malformed universe id fails fast on both writes", () => {
+  for (const subcommand of ["save", "remove"]) {
+    for (const bad of ["730.0", "0x2da", "7e2", "-1", "0", "007", "abc"]) {
+      const { output, exitCode } = captureUsageFailure(() =>
+        buildRequestFromArgv(["roblox", subcommand, bad, "--json"])
+      );
+      assert.equal(exitCode, 2, `expected ${subcommand} ${bad} to be refused`);
+      assert.equal(output.error.code, "CLI_USAGE_ERROR");
+      assert.match(output.error.message, /not a Steam appid/);
+      assert.match(output.error.message, new RegExp(`gmc roblox ${subcommand} <universeId>`));
+    }
+
+    const missing = captureUsageFailure(() => buildRequestFromArgv(["roblox", subcommand, "--json"]));
+    assert.equal(missing.exitCode, 2, `expected a missing id on ${subcommand} to be refused`);
+  }
+});
+
+/**
+ * A bare Steam appid is a LEXICALLY valid universe id on both sides, so it is
+ * forwarded and the server's tracked-cohort gate answers NOT_FOUND naming that
+ * fact. Guessing from the id's magnitude here would invent a rule the server
+ * does not have and would reject real small universe ids.
+ */
+test("(NAK-723) a lexically valid small id is forwarded for the server's cohort gate to judge", () => {
+  assert.deepEqual(buildRequestFromArgv(["roblox", "save", "730", "--json"]).body, {
+    universeId: "730"
+  });
+});
+
+test("(NAK-723) a stray positional on a write is a usage error, not a second id", () => {
+  for (const subcommand of ["save", "remove"]) {
+    const { exitCode } = captureUsageFailure(() =>
+      buildRequestFromArgv(["roblox", subcommand, "4924922222", "4924922223", "--json"])
+    );
+    assert.equal(exitCode, 2, `expected a second id on ${subcommand} to be refused`);
+  }
+});
+
+/**
+ * A token missing from the args.js whitelist falls through to positional, so
+ * `gmc roblox save <id>` would parse as the unknown command `roblox` — the same
+ * trap `lists materialize` documents, and worse here because both are writes.
+ */
+test("(NAK-723) saved, save and remove are real command tokens, not positionals", () => {
+  for (const subcommand of ["saved", "save", "remove"]) {
+    const { command, positional } = parseArgs(["roblox", subcommand, "4924922222", "--json"]);
+    assert.deepEqual(command, ["roblox", subcommand]);
+    // The id is the command's own positional, so the branch above receives it
+    // rather than the subcommand name landing here as a stray argument.
+    assert.deepEqual(positional, ["4924922222"]);
+  }
+
+  // And `saved` takes none, so the same token there is an extra argument
+  // rather than a silently ignored one.
+  assert.equal(
+    captureUsageFailure(() => buildRequestFromArgv(["roblox", "saved", "4924922222", "--json"])).exitCode,
+    2
+  );
+});
+
+test("(NAK-723) the saved commands are published as provisional in --help", () => {
+  for (const command of [
+    "gmc roblox saved --country all --json",
+    "gmc roblox save <universeId> --json",
+    "gmc roblox remove <universeId> --json"
+  ]) {
+    assert.ok(
+      PROVISIONAL_BETA_COMMANDS.includes(command),
+      `${command} must stay listed as provisional`
+    );
+  }
+
+  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 roblox saved --country all --json"));
+  assert.ok(help.includes("gmc roblox save <universeId> --json"));
+  assert.ok(help.includes("gmc roblox remove <universeId> --json"));
+  // The two facts an agent most needs from the help text, and the two most
+  // expensive to get wrong: a repeat write is success, and an out-of-scope row
+  // is still saved.
+  assert.match(help, /changed: false is success/);
+  assert.match(help, /out_of_scope is saved and\s+tracked/);
+});
+
+// --- gmc games follower-history / events (NAK-934) -------------------------
+
+test("games follower-history targets the steam route and leaves the window to the server by default", () => {
+  const request = buildRequestFromArgv(["games", "follower-history", "2436940", "--json"]);
+  assert.equal(request.path, "/api/v1/steam/games/2436940/follower-history");
+  assert.deepEqual(request.query, {});
+});
+
+test("games follower-history passes a preset or an explicit window", () => {
+  assert.deepEqual(buildRequestFromArgv(["games", "follower-history", "730", "--range", "1y", "--json"]).query, { range: "1y" });
+  assert.deepEqual(
+    buildRequestFromArgv(["games", "follower-history", "730", "--from", "2026-01-01", "--to", "2026-06-30", "--json"]).query,
+    { from: "2026-01-01", to: "2026-06-30" }
+  );
+});
+
+test("games follower-history rejects a bad window before any request", () => {
+  for (const [argv, message] of [
+    [["--range", "1y", "--from", "2026-01-01"], /--range cannot be combined with --from or --to/],
+    [["--range", "90d"], /--range must be one of: 7d, 1m, 1y, all/],
+    [["--from", "2026/01/01"], /--from must use YYYY-MM-DD/],
+    [["--from", "2026-02-30"], /--from must be a real calendar date/],
+    [["--from", "2026-05-01", "--to", "2026-04-01"], /--from must be on or before --to/],
+    [["--country", "jp"], /--country is not supported by gmc games follower-history/]
+  ]) {
+    const { output, exitCode } = captureUsageFailure(() =>
+      buildRequestFromArgv(["games", "follower-history", "730", ...argv, "--json"])
+    );
+    assert.equal(exitCode, 2, argv.join(" "));
+    assert.equal(output.error.code, "CLI_USAGE_ERROR");
+    assert.match(output.error.message, message);
+  }
+});
+
+test("games events targets the steam route, with rank_series opt-in", () => {
+  assert.equal(buildRequestFromArgv(["games", "events", "3364220", "--json"]).path, "/api/v1/steam/games/3364220/events");
+  assert.deepEqual(buildRequestFromArgv(["games", "events", "3364220", "--json"]).query, {});
+  assert.deepEqual(buildRequestFromArgv(["games", "events", "3364220", "--include", "rank_series", "--json"]).query, { include: "rank_series" });
+});
+
+test("games events rejects an unknown include value and unsupported flags", () => {
+  for (const [argv, message] of [
+    [["--include", "ranks"], /--include must be one of: rank_series/],
+    [["--include", "bad", "--include", "rank_series"], /--include may be given once; its only value is rank_series/],
+    [["--include", "rank_series", "--include=rank_series"], /--include may be given once/],
+    [["--range", "1y"], /--range is not supported by gmc games events/]
+  ]) {
+    const { output, exitCode } = captureUsageFailure(() =>
+      buildRequestFromArgv(["games", "events", "730", ...argv, "--json"])
+    );
+    assert.equal(exitCode, 2, argv.join(" "));
+    assert.equal(output.error.code, "CLI_USAGE_ERROR");
+    assert.match(output.error.message, message);
+  }
+});
+
+test("the new commands are listed and documented", async () => {
+  const { PROVISIONAL_BETA_COMMANDS } = await import("./constants.js");
+  assert.ok(PROVISIONAL_BETA_COMMANDS.some((command) => command.startsWith("gmc games follower-history ")));
+  assert.ok(PROVISIONAL_BETA_COMMANDS.some((command) => command.startsWith("gmc games events ")));
+});