@witchpot/gmc 0.9.0 → 0.11.0

package/src/requests.js

@@ -410,6 +410,117 @@ export function buildRequest(command, options, positional) {
     };
   }
 
+  // NAK-934. Same route shape as `gmc games ai-disclosure`: a plain numeric
+  // appid, no --source. The window flags mirror the server grammar exactly
+  // (follower-history's `range` XOR `from`/`to`), and are validated here so a
+  // malformed window is a usage error rather than a charged 400. Omitted flags
+  // are omitted from the query so the server's `all` default stays its own.
+  if (matches(command, ["games", "price-history"])) {
+    const usage = "gmc games price-history <appid> [--range 7d|1m|1y|all] [--from YYYY-MM-DD] [--to YYYY-MM-DD] --json";
+    assertSupportedOptions(options, {
+      command: "gmc games price-history",
+      allowed: ["range", "from", "to"]
+    });
+    const appid = assertAppid(positional[0], usage);
+    assertNoExtraPositionals(positional, { expected: 1, usage });
+    if (options.range != null && (options.from != null || options.to != null)) {
+      writeJsonError({
+        code: "CLI_USAGE_ERROR",
+        message: "--range cannot be combined with --from or --to."
+      });
+      process.exit(EXIT_USAGE);
+    }
+    const range = options.range == null
+      ? undefined
+      : assertEnumQueryOption(options.range, "--range", HISTORY_RANGES);
+    if (options.from != null) assertCalendarDate(options.from, "--from");
+    if (options.to != null) assertCalendarDate(options.to, "--to");
+    // Both are zero-padded YYYY-MM-DD here, so string order is date order.
+    // Only an explicit pair is checked: an omitted --to is the SERVER's today,
+    // which the local clock must not second-guess.
+    if (options.from != null && options.to != null && String(options.from) > String(options.to)) {
+      writeJsonError({
+        code: "CLI_USAGE_ERROR",
+        message: "--from must be on or before --to."
+      });
+      process.exit(EXIT_USAGE);
+    }
+    return {
+      path: `/api/v1/steam/games/${encodeURIComponent(String(appid))}/price-history`,
+      query: {
+        ...(range ? { range } : {}),
+        ...(options.from != null ? { from: String(options.from) } : {}),
+        ...(options.to != null ? { to: String(options.to) } : {})
+      }
+    };
+  }
+
+  // NAK-934 specimen sheet. The follower-history route owns the window grammar
+  // price-history borrowed, so the flags and their local checks are identical.
+  if (matches(command, ["games", "follower-history"])) {
+    const usage = "gmc games follower-history <appid> [--range 7d|1m|1y|all] [--from YYYY-MM-DD] [--to YYYY-MM-DD] --json";
+    assertSupportedOptions(options, { command: "gmc games follower-history", allowed: ["range", "from", "to"] });
+    const appid = assertAppid(positional[0], usage);
+    assertNoExtraPositionals(positional, { expected: 1, usage });
+    if (options.range != null && (options.from != null || options.to != null)) {
+      writeJsonError({ code: "CLI_USAGE_ERROR", message: "--range cannot be combined with --from or --to." });
+      process.exit(EXIT_USAGE);
+    }
+    const range = options.range == null ? undefined : assertEnumQueryOption(options.range, "--range", HISTORY_RANGES);
+    if (options.from != null) assertCalendarDate(options.from, "--from");
+    if (options.to != null) assertCalendarDate(options.to, "--to");
+    if (options.from != null && options.to != null && String(options.from) > String(options.to)) {
+      writeJsonError({ code: "CLI_USAGE_ERROR", message: "--from must be on or before --to." });
+      process.exit(EXIT_USAGE);
+    }
+    return {
+      path: `/api/v1/steam/games/${encodeURIComponent(String(appid))}/follower-history`,
+      query: {
+        ...(range ? { range } : {}),
+        ...(options.from != null ? { from: String(options.from) } : {}),
+        ...(options.to != null ? { to: String(options.to) } : {})
+      }
+    };
+  }
+
+  // NAK-934 specimen sheet. include is the route's opt-in list; its only value
+  // is rank_series, checked locally so a typo is a usage error.
+  if (matches(command, ["games", "events"])) {
+    const usage = "gmc games events <appid> [--include rank_series] --json";
+    assertSupportedOptions(options, { command: "gmc games events", allowed: ["include"] });
+    if (options.repeatedOptions?.has("include")) {
+      writeJsonError({
+        code: "CLI_USAGE_ERROR",
+        message: "--include may be given once; its only value is rank_series",
+        usage
+      });
+      process.exit(EXIT_USAGE);
+    }
+    const appid = assertAppid(positional[0], usage);
+    assertNoExtraPositionals(positional, { expected: 1, usage });
+    const include = options.include == null ? undefined : assertEnumQueryOption(options.include, "--include", STEAM_EVENTS_INCLUDE);
+    return {
+      path: `/api/v1/steam/games/${encodeURIComponent(String(appid))}/events`,
+      query: include ? { include } : {}
+    };
+  }
+
+  // NAK-934. No query parameters at all (the ai-disclosure shape), so any
+  // flag is a usage error rather than a silently ignored narrowing.
+  if (matches(command, ["games", "screenshot-labels"])) {
+    const usage = "gmc games screenshot-labels <appid> --json";
+    assertSupportedOptions(options, {
+      command: "gmc games screenshot-labels",
+      allowed: []
+    });
+    const appid = assertAppid(positional[0], usage);
+    assertNoExtraPositionals(positional, { expected: 1, usage });
+    return {
+      path: `/api/v1/steam/games/${encodeURIComponent(String(appid))}/screenshot-labels`,
+      query: {}
+    };
+  }
+
   if (matches(command, ["reviews", "patterns"])) {
     assertSource(options.source);
     const isCompare = positional[0] === "compare";
@@ -650,6 +761,215 @@ 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" })
+    };
+  }
+
+  // NAK-723. The saved-experiences surface: the only WORKSPACE-SCOPED Roblox
+  // commands. The five reads above are anonymous and shared-cacheable; these
+  // three carry one workspace's own data and resolve through the same unified
+  // auth `gmc lists` uses, so they are modelled on that family rather than on
+  // the Roblox read family beside them.
+  //
+  // THE SCOPE FLAGS BELONG TO `saved` ALONE, and the two writes take none. A
+  // `--country` on a save is refused here rather than dropped, matching both
+  // the REST allowlist (`SAVED_MUTATION_PARAMS` is empty) and the MCP tool's
+  // per-action allowlist: a save that quietly ignored a scope flag would look
+  // correct while answering a question the caller did not ask.
+  //
+  // SAVED MEMBERSHIP IS SCOPE-INDEPENDENT. The flags on `saved` decide which
+  // of `in_scope` / `out_of_scope` / `not_tracked` each saved experience is
+  // in, never which experiences are listed — so no flag here can add or drop
+  // a row, and an `out_of_scope` row is saved and tracked, not missing.
+  if (matches(command, ["roblox", "saved"])) {
+    assertSupportedOptions(options, {
+      command: "gmc roblox saved",
+      allowed: ["country", "device", "sort", "as-of", "eligibility-days"]
+    });
+    assertNoExtraPositionals(positional, { expected: 0, usage: "gmc roblox saved --json" });
+    return {
+      path: "/api/v1/roblox/saved",
+      // Deliberately no --limit and no --cursor: the saved set is capped per
+      // workspace and one response always holds all of it. Accepting either
+      // would imply the list can hide part of itself.
+      query: pickQuery(options, {
+        country: "country",
+        device: "device",
+        sort: "sort",
+        "as-of": "as_of",
+        "eligibility-days": "eligibility_days"
+      })
+    };
+  }
+
+  // Both writes are IDEMPOTENT and report the state that now holds. A repeat
+  // answers `changed: false` with the same body and is success, not a failure
+  // to retry — nothing here turns that into a non-zero exit.
+  //
+  // The id reaches the wire as the decimal STRING `assertUniverseId` returned.
+  // Coercing it to a number would both lose precision above 2^53 and trip the
+  // server's own `requireSavedUniverseId`, which refuses a JSON number outright
+  // because a number is exactly what a caller sends when it has routed a Steam
+  // appid into this path.
+  if (matches(command, ["roblox", "save"])) {
+    assertSupportedOptions(options, { command: "gmc roblox save", allowed: [] });
+    const universeId = assertUniverseId(positional[0], "gmc roblox save <universeId> --json");
+    assertNoExtraPositionals(positional, {
+      expected: 1,
+      usage: "gmc roblox save <universeId> --json"
+    });
+    return {
+      path: "/api/v1/roblox/saved",
+      method: "POST",
+      query: {},
+      body: { universeId }
+    };
+  }
+
+  // Removes the id from THIS WORKSPACE's saved set. It does not delete an
+  // experience, does not touch collection, and removing something that is not
+  // saved is `changed: false` rather than a 404.
+  if (matches(command, ["roblox", "remove"])) {
+    assertSupportedOptions(options, { command: "gmc roblox remove", allowed: [] });
+    const universeId = assertUniverseId(positional[0], "gmc roblox remove <universeId> --json");
+    assertNoExtraPositionals(positional, {
+      expected: 1,
+      usage: "gmc roblox remove <universeId> --json"
+    });
+    return {
+      path: `/api/v1/roblox/saved/${encodeURIComponent(universeId)}`,
+      method: "DELETE",
+      query: {}
+    };
+  }
+
   return null;
 }
 
@@ -1010,6 +1330,11 @@ function assertSource(source = "steam") {
   }
 }
 
+// Mirrors GAME_FOLLOWER_HISTORY_RANGE_PRESETS on the server, which the
+// price-history endpoint reuses (NAK-934). The server remains the authority.
+const HISTORY_RANGES = ["7d", "1m", "1y", "all"];
+const STEAM_EVENTS_INCLUDE = ["rank_series"];
+
 function assertDate(value, optionName) {
   if (!/^\d{4}-\d{2}-\d{2}$/.test(String(value))) {
     writeJsonError({
@@ -1020,6 +1345,30 @@ function assertDate(value, optionName) {
   }
 }
 
+// `assertDate` plus a real-calendar check, mirroring the server's
+// `parseCalendarDateParam` (follower-history.ts) so `2026-02-30` is a usage
+// error here instead of a request. Kept separate from `assertDate`, whose
+// other caller (--deadline-before) is not in scope for this rule.
+function assertCalendarDate(value, optionName) {
+  assertDate(value, optionName);
+  const [year, month, day] = String(value).split("-").map(Number);
+  const probe = new Date(Date.UTC(year, month - 1, day));
+  // Date.UTC maps years 0-99 into the 1900s; restore the year so the check
+  // is about the DAY being real, as on the server.
+  probe.setUTCFullYear(year);
+  if (
+    probe.getUTCFullYear() !== year ||
+    probe.getUTCMonth() !== month - 1 ||
+    probe.getUTCDate() !== day
+  ) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: `${optionName} must be a real calendar date`
+    });
+    process.exit(EXIT_USAGE);
+  }
+}
+
 function assertPositiveIntegerOption(value, optionName) {
   const number = Number(value);
   if (!Number.isInteger(number) || number < 1) {
@@ -1184,10 +1533,17 @@ const GLOBAL_CLI_OPTIONS = new Set(["json", "help", "version", "fields", "preset
 function assertSupportedOptions(options, { command, allowed }) {
   for (const key of Object.keys(options)) {
     if (GLOBAL_CLI_OPTIONS.has(key) || allowed.includes(key)) continue;
-    const supported = allowed.map((name) => `--${name}`).join(", ");
+    // NAK-723: an empty allowlist rendered as "Supported options: ." — which
+    // reads like a message with its list missing rather than like a command
+    // that takes no options. `gmc roblox save`/`remove` are the second and
+    // third such command (after `gmc games ai-disclosure`), so it is spelled
+    // out here once, in the MCP tool's own wording for the same case.
+    const supported = allowed.length
+      ? `Supported options: ${allowed.map((name) => `--${name}`).join(", ")}.`
+      : "This command takes no options.";
     writeJsonError({
       code: "CLI_USAGE_ERROR",
-      message: `--${key} is not supported by ${command}. Supported options: ${supported}. The endpoint does not accept it, so it would be ignored rather than applied.`
+      message: `--${key} is not supported by ${command}. ${supported} The endpoint does not accept it, so it would be ignored rather than applied.`
     });
     process.exit(EXIT_USAGE);
   }
@@ -1243,6 +1599,46 @@ function assertAppid(value, usage) {
   return appid;
 }
 
+/**
+ * NAK-715. Validates the universeId positional for the Roblox per-experience
+ * commands, mirroring the path-parameter check the app applies. NAK-723 shares
+ * it with `roblox save` / `roblox remove`, where the same string is also the
+ * request BODY's `universeId` — the regex below is character-for-character the
+ * server's own `parseRobloxId`, so the two surfaces accept and reject the same
+ * spellings.
+ *
+ * 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.
+ *
+ * What this CANNOT catch, deliberately: a bare Steam appid like `730` is a
+ * lexically valid universe id, on this side and on the server's. It is
+ * forwarded, and the server's tracked-cohort gate answers NOT_FOUND naming
+ * exactly that — "not in the tracked cohort, so saving it would create a row
+ * nothing could explain". Guessing here from the id's magnitude instead would
+ * invent a rule the server does not have and would reject real small universe
+ * ids, which is a worse failure than the precise 404.
+ */
+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({