@witchpot/gmc 0.6.0 → 0.9.0

package/src/requests.js

@@ -9,6 +9,8 @@ import {
   DEFAULT_REVIEW_PATTERNS_MIN_GAMES,
   DEFAULT_SHOWCASE_FIT_LIMIT,
   EXIT_USAGE,
+  LANGUAGE_TOPIC_MIN_REVIEWS_CEILING,
+  LANGUAGE_TOPIC_MIN_REVIEWS_FLOOR,
   MAX_SAMPLE_PAGES,
   MAX_SAMPLE_SIZE
 } from "./constants.js";
@@ -88,7 +90,11 @@ export function buildRequest(command, options, positional) {
       path: `/api/v1/lists/${encodeURIComponent(id)}/games`,
       query: pickQuery(options, {
         limit: "limit",
-        offset: "offset"
+        offset: "offset",
+        // NAK-525: a resolution-backed list pages by signed cursor. Before this
+        // the flag was accepted and silently dropped, which walks the list by
+        // offset while the caller believes it is following the cursor.
+        cursor: "cursor"
       })
     };
   }
@@ -125,6 +131,43 @@ export function buildRequest(command, options, positional) {
     };
   }
 
+  // NAK-525. Non-destructive: computes (or reuses) the materialized resolution a
+  // natural-language list definition needs before its games can be read. Costs 2
+  // credits, including on a reuse.
+  if (matches(command, ["lists", "resolve"])) {
+    const id = assertListId(positional[0], "gmc lists resolve <id> --json");
+    return {
+      path: `/api/v1/lists/${encodeURIComponent(id)}/resolve`,
+      method: "POST",
+      query: {}
+    };
+  }
+
+  // NAK-525. Destructive-adjacent: freezes the list's CURRENT members, so it
+  // stops following its definition, and is undone only by discarding the frozen
+  // rows. `--confirm` is required for the same reason the tool surfaces require
+  // `confirm: true` — this must be a decision, not a typo.
+  if (matches(command, ["lists", "materialize"])) {
+    const id = assertListId(positional[0], "gmc lists materialize <id> --confirm --json");
+    if (options.confirm !== true) {
+      exitWithUsage(
+        "Freezing a list stops it from updating and can only be undone by discarding the frozen rows. Re-run with --confirm once you are sure. Usage: gmc lists materialize <id> --confirm --json"
+      );
+    }
+    return {
+      path: `/api/v1/lists/${encodeURIComponent(id)}/materialize`,
+      method: "POST",
+      query: {},
+      // An empty body means "freeze the current revision" (the server treats a
+      // malformed non-empty body as a 400 rather than an omission), and
+      // --expected-revision is the compare-and-swap a caller uses after an
+      // explicit resolve.
+      ...(options["expected-revision"] != null
+        ? { body: { expectedDefinitionRevision: assertPositiveIntegerOption(options["expected-revision"], "--expected-revision") } }
+        : {})
+    };
+  }
+
   if (matches(command, ["games", "search"])) {
     assertSource(options.source);
     return {
@@ -274,6 +317,99 @@ export function buildRequest(command, options, positional) {
     };
   }
 
+  // NAK-455. The parameter surface is exactly the REST parameter surface —
+  // `min_reviews` and `include_insufficient` — and nothing more. There is no
+  // language filter, topic filter, or row limit here because the API has
+  // none; a client-side one would make the CLI, rather than the service,
+  // decide which evidence a caller sees.
+  if (matches(command, ["games", "language-topics"])) {
+    assertSource(options.source);
+    assertSupportedOptions(options, {
+      command: "gmc games language-topics",
+      allowed: ["source", "min-reviews", "include-insufficient"]
+    });
+    const externalId = positional[0];
+    assertExternalId(externalId, "gmc games language-topics --source steam <externalId> --json");
+    assertNoExtraPositionals(positional, {
+      expected: 1,
+      usage: "gmc games language-topics --source steam <externalId> --json"
+    });
+    const minReviews = options["min-reviews"] == null
+      ? undefined
+      : assertLanguageTopicMinReviews(options["min-reviews"]);
+    return {
+      path: `/api/v1/steam/games/${encodeURIComponent(externalId)}/review-topics/languages`,
+      query: {
+        // Omitted when unset so the server owns the default (30) and the two
+        // cannot drift apart.
+        ...(minReviews != null ? { min_reviews: String(minReviews) } : {}),
+        ...(options["include-insufficient"] ? { include_insufficient: "true" } : {})
+      }
+    };
+  }
+
+  // NAK-428. The endpoint takes NO query parameters: the full daily series is
+  // always returned, and range presets are a display concern the web UI
+  // applies client-side. A --from/--to/--range invented here would make the
+  // CLI, rather than the service, decide which observations a caller sees —
+  // and would hide exactly the collection gaps a caller has to reason about.
+  //
+  // Not supporting them is not the same as tolerating them: a request-shaping
+  // flag that is accepted and dropped returns the FULL series with exit 0, so
+  // a caller who asked for a window reads the unwindowed answer as the
+  // windowed one. `assertSupportedOptions` turns that into a usage error.
+  if (matches(command, ["games", "review-history"])) {
+    assertSource(options.source);
+    assertSupportedOptions(options, {
+      command: "gmc games review-history",
+      allowed: ["source"]
+    });
+    const externalId = positional[0];
+    assertExternalId(externalId, "gmc games review-history --source steam <externalId> --json");
+    assertNoExtraPositionals(positional, {
+      expected: 1,
+      usage: "gmc games review-history --source steam <externalId> --json"
+    });
+    return {
+      path: `/api/v1/steam/games/${encodeURIComponent(externalId)}/review-history`,
+      query: {}
+    };
+  }
+
+  if (matches(command, ["games", "more-like-this"])) {
+    assertSource(options.source);
+    const externalId = positional[0];
+    assertExternalId(externalId, "gmc games more-like-this --source steam <externalId> --json");
+    const country = options.country == null ? undefined : assertMoreLikeThisCountry(options.country);
+    return {
+      path: `/api/v1/steam/games/${encodeURIComponent(externalId)}/more-like-this`,
+      query: country ? { country } : {}
+    };
+  }
+
+  // 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";
@@ -451,6 +587,69 @@ export function buildRequest(command, options, positional) {
     };
   }
 
+  if (matches(command, ["showcases", "history"])) {
+    assertSource(options.source);
+    const externalId = positional[0];
+    assertExternalId(externalId, "gmc showcases history --source steam <externalId> --json");
+    return {
+      kind: "showcaseHistory",
+      source: "steam",
+      externalId,
+      detailQuery: {
+        ...pickQuery(options, {
+          locale: "locale"
+        }),
+        sections: "showcases"
+      }
+    };
+  }
+
+  if (matches(command, ["steam", "trend-stories"])) {
+    assertSupportedOptions(options, { command: "gmc steam trend-stories", allowed: ["story", "edition", "tag", "locale", "limit", "offset", "fields"] });
+    assertNoExtraPositionals(positional, { expected: 0, usage: "gmc steam trend-stories --json" });
+    return { path: "/api/v1/steam/trend-stories", query: pickQuery(options, { story: "story", edition: "edition", tag: "tag", locale: "locale", limit: "limit", offset: "offset", fields: "fields" }) };
+  }
+
+  // NAK-706. A thin pass-through to GET /api/v1/steam/tag-trends: the CLI
+  // forwards the flags it was given and the SERVER owns the contract — which
+  // view accepts which parameter, the enum members, the per-view limit
+  // ceilings, and the cursor binding. Re-implementing the per-view allowlist
+  // here would put a second copy of it in a package that ships on its own
+  // release cadence, and the copy that drifts is the one that rejects a
+  // request the service would have answered.
+  //
+  // `assertSupportedOptions` still runs, for the narrower thing it is for: a
+  // flag this ENDPOINT has no parameter for (`--source`, `--locale`,
+  // `--offset`) would otherwise be dropped silently and answer the unnarrowed
+  // question with exit 0.
+  if (matches(command, ["steam", "tag-trends"])) {
+    assertSupportedOptions(options, {
+      command: "gmc steam tag-trends",
+      allowed: ["view", "family", "q", "supply-direction", "sort", "order", "limit", "cursor", "tag"]
+    });
+    assertNoExtraPositionals(positional, {
+      expected: 0,
+      usage: "gmc steam tag-trends --view <view> --json"
+    });
+    return {
+      path: "/api/v1/steam/tag-trends",
+      // Every value is omitted when unset so the server owns each default
+      // (view=featured, sort=release_share_delta, order=desc, and the two
+      // per-view limits) and no default can drift into a copy kept here.
+      query: pickQuery(options, {
+        view: "view",
+        family: "family",
+        q: "q",
+        "supply-direction": "supply_direction",
+        sort: "sort",
+        order: "order",
+        limit: "limit",
+        cursor: "cursor",
+        tag: "tag"
+      })
+    };
+  }
+
   return null;
 }
 
@@ -565,6 +764,21 @@ function buildOptionalGameCountRequest(options) {
   };
 }
 
+// Mirrors AI_DISCLOSURE_FILTER_VALUES in the app's ai-disclosure repository
+// module (NAK-773). Kept as a local literal
+// because the CLI package cannot import server code; the server remains the
+// enforcing authority and re-validates case-sensitively against the same SQL
+// comparands, so a value this local check lets through is never one the
+// 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",
@@ -587,9 +801,133 @@ function buildGameCountQuery(options) {
   assertReviewBoundOptions(options);
   if (query.tags) query.tags = normalizeTagSlugCsv(query.tags);
   if (query.coverage) query.coverage = assertCoverageCsv(query.coverage);
+  // NAK-247: --has-demo is a genuine VALUE option (true|false is a real
+  // filter distinction, unlike a presence-only BOOLEAN_OPTIONS flag), so it
+  // is validated here rather than being folded into `pickQuery`, which would
+  // forward whatever string the caller typed straight to the server. Applied
+  // to the shared count-query builder so games search/count/aggregate all
+  // honor it, the same shared surface `hasDemo` reaches server-side
+  // (parseGameFilterQuery in the app's games repository module).
+  if (options["has-demo"] != null) {
+    query.hasDemo = assertBooleanQueryOption(options["has-demo"], "--has-demo");
+  }
+  // NAK-207: --event-name is a plain string VALUE option, forwarded verbatim.
+  // Validating the slug against the registry is the SERVER's job (an unknown
+  // event answers INVALID_EVENT with suggestions); the CLI only refuses a
+  // blank value, which would otherwise be dropped by the query parser and
+  // leave the caller reading an unfiltered catalog as an event cohort.
+  if (options["event-name"] != null) {
+    const eventName = String(options["event-name"]).trim();
+    if (!eventName) {
+      writeJsonError({
+        code: "CLI_USAGE_ERROR",
+        message: "--event-name must be a non-empty Steam event slug"
+      });
+      process.exit(EXIT_USAGE);
+    }
+    query.eventName = eventName;
+  }
+  // NAK-587: --catalog-as-of is a FILTER, so it lives in the shared count-query
+  // builder and reaches games search, count and aggregate alike — unlike
+  // --as-of/--compare-as-of below, which are aggregate-only snapshot dials.
+  //
+  // The CLI refuses only a blank value; the DATE contract belongs to the API (a
+  // malformed date is BAD_REQUEST param catalog_as_of), so the CLI cannot drift
+  // from it by re-implementing it.
+  if (options["catalog-as-of"] != null) {
+    const catalogAsOf = String(options["catalog-as-of"]).trim();
+    if (!catalogAsOf) {
+      writeJsonError({
+        code: "CLI_USAGE_ERROR",
+        message: "--catalog-as-of must be a date in YYYY-MM-DD format"
+      });
+      process.exit(EXIT_USAGE);
+    }
+    query.catalog_as_of = catalogAsOf;
+  }
+  // NAK-773: --ai-disclosure is a FILTER, so it lives in the shared
+  // count-query builder and reaches games search, count and aggregate alike,
+  // same as --has-demo and --event-name above. The three values are a closed
+  // set the server enforces case-sensitively against the literal comparands
+  // its SQL matches (assertAiDisclosureFilterValue in the app's
+  // ai-disclosure repository module), so the CLI rejects
+  // anything outside that set locally rather than lower-casing or trimming a
+  // typo into a value the caller did not send. `absent` means no disclosure
+  // was observed in collected data, not confirmed non-use, and `unconfirmed`
+  // means Game Market Copilot has not yet successfully recorded a disclosure
+  // result either way -- the CLI forwards the value verbatim and does not
+  // restate that distinction.
+  if (options["ai-disclosure"] != null) {
+    query.aiDisclosure = assertEnumQueryOption(
+      options["ai-disclosure"],
+      "--ai-disclosure",
+      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;
 }
 
+/**
+ * Validates a VALUE-taking (not presence-only) boolean CLI option and
+ * returns the canonical "true"/"false" string the REST query param expects.
+ * A caller who mistypes `--has-demo maybe` gets a usage error here rather
+ * than a silently-unfiltered, still-charged request — the same
+ * accepted-then-dropped failure mode `assertSupportedOptions` documents for
+ * unknown flags entirely, but for a KNOWN flag with an invalid value.
+ */
+function assertBooleanQueryOption(value, optionName) {
+  const normalized = String(value).trim().toLowerCase();
+  if (normalized === "true") return "true";
+  if (normalized === "false") return "false";
+  writeJsonError({
+    code: "CLI_USAGE_ERROR",
+    message: `${optionName} must be true or false`
+  });
+  process.exit(EXIT_USAGE);
+}
+
+/**
+ * Generic enum counterpart to `assertBooleanQueryOption` (NAK-773). No
+ * reusable enum-assert helper existed in this file before: the existing
+ * value-enum validators (`assertReviewPatternSentiment`, `assertCompareFocus`,
+ * `assertCoverageCsv`, `assertMoreLikeThisCountry`) are each written inline
+ * for their own flag, and some of them normalize case or trim first. This one
+ * does neither on purpose — it compares the raw string exactly, for flags
+ * such as --ai-disclosure whose server-side contract is deliberately
+ * case-sensitive, so a caller who mistypes the value (including a
+ * differently-cased or blank one) gets a usage error here rather than a
+ * silently-unfiltered, still-charged request.
+ */
+function assertEnumQueryOption(value, optionName, allowedValues) {
+  const stringValue = String(value);
+  if (allowedValues.includes(stringValue)) return stringValue;
+  writeJsonError({
+    code: "CLI_USAGE_ERROR",
+    message: `${optionName} must be one of: ${allowedValues.join(", ")}`
+  });
+  process.exit(EXIT_USAGE);
+}
+
 function buildGameAggregateQuery(options) {
   return {
     ...buildGameCountQuery(options),
@@ -599,7 +937,12 @@ function buildGameAggregateQuery(options) {
       bucket: "bucket",
       sort: "sort",
       limit: "limit",
-      offset: "offset"
+      offset: "offset",
+      // NAK-248: time-travel and the two-point comparison. `--as-of` was
+      // reachable on the REST endpoint but had no CLI mapping; the comparison
+      // needs it to pin the end of the window, so both land together.
+      "as-of": "as_of",
+      "compare-as-of": "compare_as_of"
     })
   };
 }
@@ -767,6 +1110,104 @@ function assertReviewPatternSentiment(value) {
   return sentiment;
 }
 
+// Mirrors MORE_LIKE_THIS_COUNTRIES on the server (NAK-456). Kept as a local
+// literal because the CLI package cannot import server code; the server
+// remains the enforcing authority and returns 400 for anything it rejects.
+const MORE_LIKE_THIS_COUNTRIES = ["de", "fr", "gb", "jp", "kr", "us"];
+
+function assertMoreLikeThisCountry(value) {
+  const country = String(value).trim().toLowerCase();
+  if (!MORE_LIKE_THIS_COUNTRIES.includes(country)) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: `--country must be one of: ${MORE_LIKE_THIS_COUNTRIES.join(", ")}`
+    });
+    process.exit(EXIT_USAGE);
+  }
+  return country;
+}
+
+/**
+ * Bounds check for `gmc games language-topics --min-reviews` (NAK-455).
+ * Rejects locally with the same 10-200 integer bound the REST endpoint
+ * enforces, so a typo costs a usage error rather than a round trip and an API
+ * credit. The server stays the enforcing authority.
+ *
+ * The lexical test is deliberately `/^\d+$/` rather than `Number(value)`:
+ * `Number` also accepts the exponent and hex spellings (`"1e2"`, `"0x64"` both
+ * become 100), which the REST endpoint rejects outright — `parseIntParam`
+ * (in the app's API validation module) tests `/^-?\d+$/` before parsing. Letting
+ * those through here would mean the same string the API answers 400 for
+ * silently returns a 200 through the CLI.
+ */
+const DECIMAL_INTEGER_RE = /^\d+$/;
+
+function assertLanguageTopicMinReviews(value) {
+  const raw = String(value);
+  const number = DECIMAL_INTEGER_RE.test(raw) ? Number(raw) : Number.NaN;
+  if (
+    !Number.isInteger(number)
+    || number < LANGUAGE_TOPIC_MIN_REVIEWS_FLOOR
+    || number > LANGUAGE_TOPIC_MIN_REVIEWS_CEILING
+  ) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: `--min-reviews must be an integer between ${LANGUAGE_TOPIC_MIN_REVIEWS_FLOOR} and ${LANGUAGE_TOPIC_MIN_REVIEWS_CEILING}`
+    });
+    process.exit(EXIT_USAGE);
+  }
+  return number;
+}
+
+/**
+ * Options every request-building command tolerates: CLI-level output shaping
+ * and switches that never reach the wire.
+ */
+const GLOBAL_CLI_OPTIONS = new Set(["json", "help", "version", "fields", "preset"]);
+
+/**
+ * NAK-428. Per-command option allowlist.
+ *
+ * `parseArgs` collects every `--flag` into one bag and each command reads only
+ * the keys it knows, so an unsupported flag used to be dropped on the floor.
+ * For a command whose endpoint takes no query parameters that silence fails in
+ * one specific direction: `gmc games review-history --range 1y` returned the
+ * FULL series with exit 0, and the caller who asked for a window had no signal
+ * that the narrowing was ignored — the unwindowed answer reads exactly like a
+ * windowed one. Naming the offending flag and exiting 2 is the only reading
+ * that cannot be mistaken for success.
+ *
+ * Deliberately applied per command rather than globally: a blanket unknown-flag
+ * rejection would change the behaviour of every other command in the same
+ * change, including flags callers may already be passing. Commands opt in.
+ */
+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(", ");
+    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.`
+    });
+    process.exit(EXIT_USAGE);
+  }
+}
+
+/**
+ * Counterpart to `assertSupportedOptions` for bare arguments: a second
+ * positional on a single-target command is either a typo or a second appid the
+ * caller expected to be fetched, and both readings are worse when the answer
+ * for the FIRST one comes back as if nothing were wrong.
+ */
+function assertNoExtraPositionals(positional, { expected, usage }) {
+  if (positional.length <= expected) return;
+  writeJsonError({
+    code: "CLI_USAGE_ERROR",
+    message: `Unexpected extra argument "${positional[expected]}". Usage: ${usage}`
+  });
+  process.exit(EXIT_USAGE);
+}
+
 function assertExternalId(value, usage) {
   if (!value) {
     writeJsonError({
@@ -777,6 +1218,31 @@ 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;
+}
+
 function assertResolveQuery(value) {
   if (value == null || String(value).trim() === "") {
     writeJsonError({
@@ -820,6 +1286,12 @@ function assertListId(value, usage) {
   return String(value);
 }
 
+/** NAK-525: usage failure that is not about a missing option. Same exit code and JSON envelope as every other usage error. */
+function exitWithUsage(message) {
+  writeJsonError({ code: "CLI_USAGE_ERROR", message });
+  process.exit(EXIT_USAGE);
+}
+
 function parseJsonOption(value, optionName) {
   if (value == null) {
     writeJsonError({