@witchpot/gmc 0.6.0 → 0.9.0

package/src/help.js

@@ -29,8 +29,11 @@ Usage:
   gmc tags --q <term> --limit <number> --json
   gmc lists --json
   gmc lists create --name <name> --kind manual --json
-  gmc lists games <id> --json
+  gmc lists create --name <name> --kind filter --filter '<json>' --json
+  gmc lists games <id> --limit <number> --cursor <cursor> --json
   gmc lists add <id> --app-ids <appid[,appid...]> --json
+  gmc lists resolve <id> --json
+  gmc lists materialize <id> --confirm --json
   gmc games search --source steam --query <text> --json
   gmc games count --source steam --release-year <year> --reviews-gt <number> --json
   gmc games aggregate --source steam --metric count,median_reviews --group-by release_year --json
@@ -44,6 +47,11 @@ Usage:
   gmc campaigns signals --source steam <externalId> --json
   gmc games compare --source steam <externalId> <externalId...> --focus market --json
   gmc games topics --source steam <externalId> --json
+  gmc games language-topics --source steam <externalId> --json
+  gmc games language-topics --source steam <externalId> --min-reviews <number> --include-insufficient --json
+  gmc games review-history --source steam <externalId> --json
+  gmc games more-like-this --source steam <externalId> --country <country> --json
+  gmc games ai-disclosure <appid> --json
   gmc reviews patterns --source steam --tags <tag_slug[,tag_slug...]> --reviews-min <number> --json
   gmc reviews patterns --source steam --tags <tag_slug[,tag_slug...]> --sample-size <number> --preset summary --json
   gmc marketing patterns --source steam --tags <tag_slug[,tag_slug...]> --reviews-min <number> --json
@@ -56,7 +64,12 @@ Usage:
   gmc cohort brief --source steam --list <id> --json
   gmc showcases search --query <text> --json
   gmc showcases fit --source steam <externalId> --deadline-before <YYYY-MM-DD> --json
+  gmc showcases history --source steam <externalId> --json
   gmc showcases patterns --source steam --tags <tag_slug[,tag_slug...]> --json
+  gmc steam trend-stories --locale en --json
+  gmc steam tag-trends --view featured --json
+  gmc steam tag-trends --view table --sort release_share_delta --order desc --json
+  gmc steam tag-trends --view tag --tag <tag_slug> --json
 
 Tag taxonomy:
   gmc tags --json                    List the full tag dictionary (slug, name).
@@ -71,11 +84,193 @@ Tag taxonomy:
   <term> first to resolve a genre or keyword to valid slugs before
   building a --tags filter.
 
+Review topics by review language:
+  gmc games language-topics --source steam <externalId> --json
+                                      One game's review topics broken down by
+                                      the language each review was written in.
+  --min-reviews <number>              Evidence floor applied to the distinct
+                                      review count behind a row, 10-200
+                                      (server default 30).
+  --include-insufficient              Also return rows below that floor, capped
+                                      by the server, with coverage reporting
+                                      the cut.
+
+  Read data.evidenceState first. ready means at least one topic x language row
+  cleared the floor; insufficient_evidence means rows exist but none cleared
+  it; not_analyzed means no rows exist. The last two are thin evidence and no
+  data — never report either as zero mentions or absent sentiment.
+
+  Coverage is the analyzed subset only (about 2,500 titles today), selected
+  for review analysis rather than sampled from the catalog. It is not a
+  full-catalog population measurement, so do not extrapolate a share of Steam
+  from it.
+
+  Review language is the language a review was written in. It is not a
+  country, a region, a market, or a culture, and must not be reported as one.
+
+  data.rows[].counts and .rates are observed; data.rows[].estimates are
+  sample-expanded and carry samplingWeightMethod. Keep the two apart, and date
+  every claim with data.snapshot (periodStart/periodEnd/analysisVersion/
+  generatedAt).
+
+  Examples:
+    gmc games language-topics --source steam 730 --json
+    gmc games language-topics --source steam 730 --min-reviews 50 --json
+    gmc games language-topics --source steam 730 --include-insufficient --json
+
+Review-count history:
+  gmc games review-history --source steam <externalId> --json
+                                      One game's full daily total-review
+                                      series, plus the collected lifecycle and
+                                      announcement events and the observed
+                                      major-discount windows beside it.
+
+  There are no parameters beyond the external id. The whole series is always
+  returned; window it yourself and state the window you chose. A --range,
+  --from, --to, --limit or --locale is rejected as a usage error rather than
+  ignored, so a narrowing you asked for can never be silently dropped.
+
+  data.series is published-run-only and contamination-filtered: an observation
+  more than 2% below the highest earlier one for the same game is withheld as
+  invalid. Differences taken from it are safe to report, but the newest point
+  can lag the game's headline review count until that day's run is published.
+  Collection can have real gaps, so scale by date and never by array index.
+
+  Empty data.events or data.discountWindows mean no events were COLLECTED for
+  those sources — never that no releases, announcements, or discounts
+  happened. Announcements come from official Steam feeds, capped at the most
+  recent 1000 items, and are clustered to one event per UTC day.
+
+  A discount window is an observed state at the >=20% collection threshold,
+  not an exact Steam sale period. endDate is EXCLUSIVE (the first observation
+  back below the threshold), a null endDate means no end observed yet, and
+  discountPercent is the opening observation.
+
+  Events support temporal comparison only. A review-count movement beside an
+  event is co-occurrence, never attribution.
+
+  Examples:
+    gmc games review-history --source steam 730 --json
+
+AI-disclosure text and history:
+  gmc games ai-disclosure <appid> --json
+                                      One game's developer-authored AI-use
+                                      disclosure text, the store page it was
+                                      read from, and its observed history of
+                                      change. There are no parameters beyond
+                                      the appid.
+
+  data.state is disclosed, absent, or unconfirmed. absent means no
+  disclosure block was observed on the store page -- never that the title
+  uses no generative AI. unconfirmed means Game Market Copilot has not yet
+  successfully observed the store page either way, including a title never
+  attempted at all.
+
+  data.disclosureText is the developer's own wording, normalized only for
+  whitespace and never classified or summarized by Game Market Copilot. It
+  is null unless state is disclosed. data.sourceUrl is the store page the
+  observation was read from.
+
+  data.events lists only OBSERVED changes to the state, oldest first; a
+  title's first observation is a baseline and never appears as an event.
+
+  Example:
+    gmc games ai-disclosure 730 --json
+
+Steam tag trends:
+  gmc steam tag-trends --view <view> --json
+                                      Tag supply trends over one frozen monthly
+                                      generation: how the share of new paid
+                                      Steam releases carrying each tag moved
+                                      between two three-month periods.
+  --view <view>                       featured | board | group | table | tag.
+                                      Defaults to featured.
+  --family <family>                   Taxonomy family filter (board/group/table).
+  --q <term>                          Substring over tag slug and name
+                                      (board/group/table).
+  --supply-direction <direction>      up | down | unresolved | insufficient
+                                      (board/group/table).
+  --sort <key>                        release_share_delta | current_share |
+                                      known_members | median_reviews | slug
+                                      (table only).
+  --order <asc|desc>                  Table sort direction (table only).
+  --limit <number>                    group 1-50, table 1-100.
+  --cursor <cursor>                   Continuation token (group/table).
+  --tag <tag_slug>                    Required for --view tag.
+
+  Parameters are allowlisted per view and fail closed. Passing one the view
+  does not accept is a 400 naming it, not a filter that is quietly ignored, so
+  a narrowing you asked for can never be dropped while the answer looks right.
+
+  Read data.status and data.readiness before quoting anything. status "stale"
+  means no newer generation published: the payload keeps its ORIGINAL asOf and
+  the values that were truthful then, so date every claim by data.asOf rather
+  than by when you ran the command. readiness "limited" is a successful
+  partial-data answer, not an error.
+
+  Report release share as the [lower, upper] interval. The width is UNMEASURED
+  titles, not noise: unknownTagMembers are titles with no complete tag
+  observation and are never titles known to lack the tag. A
+  releaseShareDifferenceRange containing 0 means the data cannot separate the
+  two periods.
+
+  All four directions are measurements. "unresolved" means the difference
+  interval spans zero and "insufficient" means the tag is below the evidence
+  floor — neither is missing data and neither is "no change".
+
+  Every observed* field is computed over current.observedReviewMembers titles,
+  not over the whole cohort; quote that denominator. item.titles is a bounded
+  display sample, not the tag's membership (use current.knownMembers).
+
+  Before the first generation publishes, the endpoint answers 404
+  TAG_TRENDS_UNAVAILABLE. That is the documented pre-publication state, not an
+  outage and not worth retrying on a schedule.
+
+  Examples:
+    gmc steam tag-trends --view featured --json
+    gmc steam tag-trends --view board --family mechanic --q cozy --json
+    gmc steam tag-trends --view table --sort current_share --limit 50 --json
+    gmc steam tag-trends --view tag --tag cozy --json
+
 Binary aliases:
   gmcp and game-market-copilot run the same CLI. Use them when a shell
   alias shadows gmc (Oh My Zsh's git plugin defines gmc as
   'git merge --continue').
 
+Query-backed lists (--kind filter):
+
+  --filter takes the games API's camelCase filter object, e.g.
+  --filter '{"tags":["cozy"],"reviewsMin":500}'
+
+  It also accepts the version 2 query envelope, which pairs structured
+  conditions with an optional natural-language one:
+
+    {"version":2,"mode":"query",
+     "structured":{"tags":["cozy"],"reviewsMin":500},
+     "semanticQuery":"games about running a shop",
+     "semanticMode":"rank"}
+
+  structured decides membership. semanticQuery only orders results inside
+  that universe under semanticMode "rank" (the default); under "narrow" it
+  also narrows membership, and the reported total is then approximate or a
+  floor rather than an exact count. Read total_kind in the response before
+  quoting any number as exact.
+
+  A list with a semanticQuery needs a resolution before its games can be
+  read: "gmc lists games <id>" answers 409 RESOLUTION_REQUIRED until you run
+  "gmc lists resolve <id>". Resolve costs 2 credits every time, including
+  when an existing resolution is reused, and it never changes membership.
+
+  "gmc lists materialize <id> --confirm" FREEZES the list's current members.
+  After it the list no longer follows its definition, and the only way back
+  is to discard the frozen rows. It costs 2 credits, requires --confirm, and
+  takes an optional --expected-revision <n> compare-and-swap so a definition
+  edit landing after your resolve fails the call instead of freezing the
+  wrong query. A definition using catalogAsOf cannot be frozen at all --
+  400 SNAPSHOT_DEFINITION_UNSUPPORTED, nothing written, and retrying will
+  never succeed: a snapshot is a fixed set of games, while that predicate is
+  re-evaluated against a growing availability history. Read the list live.
+
 Supported commands:
 ${SUPPORTED_BETA_COMMANDS.map((command) => `  ${command}`).join("\n")}
 
@@ -113,6 +308,39 @@ Filters:
   --coverage <list>           Research coverage levels: basic, partial, full.
                               Use --coverage full,partial to keep only games
                               with collected analysis data.
+  --has-demo <true|false>     Filter on whether the app has a linked demo in
+                              app_demo_map. false means no demo linkage was
+                              observed in collected appdetails, not confirmed
+                              absence.
+  --event-name <slug>         Restrict to the current participants of one
+                              Steam event (a steam_events.event_name slug).
+                              Membership is resolved at query time, so the
+                              cohort follows collection updates. Unknown slugs
+                              return INVALID_EVENT with suggestions; list
+                              valid slugs at GET /api/v1/events.
+  --catalog-as-of <date>      YYYY-MM-DD. Keep only titles Game Market Copilot
+                              had NOT observed as delisted on that date. Not a
+                              snapshot dial: --as-of picks which metrics are
+                              read, this picks which titles exist, and the two
+                              combine. Incomplete on purpose -- a title with no
+                              availability observation by that date is KEPT, so
+                              a real-data result carries the warning
+                              catalog_as_of_observation_bounded (plus
+                              catalog_as_of_predates_coverage when the date is
+                              older than the observation window) and is not a
+                              complete historical catalog. A static-fixture
+                              result carries catalog_as_of_filter_unavailable
+                              instead: there is no availability history behind
+                              fixtures, so the filter was not applied at all.
+  --release-status <value>    released, upcoming, or tba. An exact match on
+                              top of the guard that already drops any title
+                              still marked upcoming after its provisional
+                              release date has passed, on every query.
+  --ai-disclosure <value>     disclosed, absent, or unconfirmed. absent means
+                              no AI-use disclosure was observed in collected
+                              data -- not confirmed non-use. unconfirmed means
+                              Game Market Copilot has not yet successfully
+                              observed a disclosure state either way.
 
 Sorting:
   --sort <key>                reviews_desc, reviews_asc, rating_desc,
@@ -134,11 +362,20 @@ Count and aggregation:
   Use gmc games count when you only need the number of matching games.
   Use gmc games aggregate for grouped metrics such as count by year,
   median reviews by year, or count by an explicit price/review/rating bucket.
+  Add --as-of to read a past published snapshot, and --compare-as-of to get a
+  per-app-paired comparison between two dates in data.comparison. Report the
+  comparison's exclusions, paired_beyond_lookback and insufficient_coverage
+  rather than inferring a trend from them. --compare-as-of does not support
+  --group-by tag, primary_market_tag, or ai_disclosure, nor the
+  --ai-disclosure filter. It DOES combine with --event-name and
+  --catalog-as-of: the comparison cohort applies the same Steam event
+  participation and catalog-availability predicates as the rows beside it.
 
 Examples:
   gmc games search --source steam --release-year 2025 --reviews-min 1000 --json
   gmc games count --source steam --release-year 2025 --reviews-gt 1000 --json
   gmc games aggregate --source steam --metric count,median_reviews --group-by release_year --reviews-gt 1000 --json
   gmc games aggregate --source steam --metric count --group-by price_bucket --bucket price:0,5,10,20,40 --json
+  gmc games aggregate --source steam --metric count --group-by release_year --as-of 2026-08-01 --compare-as-of 2026-06-01 --json
 `);
 }

package/src/index.js

@@ -37,5 +37,6 @@ export {
   composeReviewPatternsPayload,
   composeResolvePayload,
   composeShowcaseFitPayload,
+  composeShowcaseHistoryPayload,
   executeRequestPlan
 } from "./workflows.js";

package/src/main.js

@@ -10,7 +10,7 @@ import { matches, parseArgs } from "./args.js";
 import { handleLocalCommand, loadConfig, parseBaseUrl } from "./config.js";
 import { printGamesSearchHelp, printHelp } from "./help.js";
 import { writeJsonError } from "./output.js";
-import { applyOutputProjection } from "./projection.js";
+import { applyOutputProjection, assertPresetApplicable } from "./projection.js";
 import { buildRequest } from "./requests.js";
 import { trackCliCommandExecuted } from "./telemetry.js";
 import { executeRequestPlan } from "./workflows.js";
@@ -71,6 +71,12 @@ export async function main(argv = process.argv.slice(2)) {
     process.exit(EXIT_USAGE);
   }
 
+  // NAK-804 cross-model review: validated BEFORE the metered request below,
+  // not only afterward inside applyOutputProjection — an inapplicable
+  // --preset must never pay for the HTTP round trip (or its credit charge)
+  // only to be rejected once the response is already back.
+  assertPresetApplicable({ fields: options.fields, preset: options.preset, request });
+
   if (request.requiresApiKey && !apiKey) {
     writeJsonError({
       code: "CLI_MISSING_CONFIG",

package/src/main.test.js

@@ -0,0 +1,130 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { main } from "./main.js";
+import { assertPresetApplicable } from "./projection.js";
+
+/**
+ * Async counterpart to the `captureUsageFailure` helper in requests.test.js:
+ * `main()` is async, so `process.exit` must be mocked to throw INTO the
+ * awaited call rather than a synchronous one.
+ */
+async function captureCliExit(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 {
+    await run();
+    throw new Error("expected the CLI to exit");
+  } catch (error) {
+    if (error.message !== "__cli_exit__") throw error;
+  } finally {
+    process.stdout.write = originalWrite;
+    process.exit = originalExit;
+  }
+
+  return { output: JSON.parse(chunks.join("")), exitCode };
+}
+
+/**
+ * NAK-804 cross-model review (Codex Sol): `gmc games ai-disclosure 730
+ * --preset summary --json` used to build the request, send it, and only
+ * THEN discover in applyOutputProjection that ai-disclosure supports no
+ * preset — charging a credit for a call whose answer was always going to be
+ * a usage error. The counting fetch stub below is the direct evidence that
+ * the metered request never fires: if the ordering regresses, this test
+ * fails on `fetchCalls === 0` even though the exit code/message stay right.
+ */
+test("(NAK-804) an unsupported --preset is rejected before the metered request executes", async () => {
+  const originalFetch = globalThis.fetch;
+  let fetchCalls = 0;
+  globalThis.fetch = async () => {
+    fetchCalls += 1;
+    throw new Error("fetch must not be called once --preset is rejected");
+  };
+
+  try {
+    const { output, exitCode } = await captureCliExit(() =>
+      main(["games", "ai-disclosure", "730", "--preset", "summary", "--json"])
+    );
+
+    assert.equal(fetchCalls, 0);
+    assert.equal(exitCode, 2);
+    assert.equal(output.error.code, "CLI_USAGE_ERROR");
+    assert.match(
+      output.error.message,
+      /--preset summary is supported for gmc reviews patterns, gmc games benchmark, and gmc cohort\/pattern workflows/
+    );
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+/**
+ * The same early check is generic (it reuses resolvePresetFields exactly),
+ * not an ai-disclosure special case: an unknown preset NAME is rejected
+ * before the request too, for any command.
+ */
+test("(NAK-804) an unknown --preset value is rejected before the metered request executes", async () => {
+  const originalFetch = globalThis.fetch;
+  let fetchCalls = 0;
+  globalThis.fetch = async () => {
+    fetchCalls += 1;
+    throw new Error("fetch must not be called once --preset is rejected");
+  };
+
+  try {
+    const { output, exitCode } = await captureCliExit(() =>
+      main(["games", "ai-disclosure", "730", "--preset", "not-a-real-preset", "--json"])
+    );
+
+    assert.equal(fetchCalls, 0);
+    assert.equal(exitCode, 2);
+    assert.equal(output.error.code, "CLI_USAGE_ERROR");
+    assert.match(output.error.message, /--preset must be one of: summary/);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+/**
+ * Negative control on the pure check itself (no CLI/network plumbing
+ * needed): a request `kind` that IS in the preset allowlist must not be
+ * rejected — the early check only intercepts INAPPLICABLE presets, not
+ * every --preset call.
+ */
+test("(NAK-804) assertPresetApplicable does not reject a preset the request kind supports", () => {
+  assert.doesNotThrow(() =>
+    assertPresetApplicable({ preset: "summary", request: { kind: "reviewPatterns" } })
+  );
+  assert.doesNotThrow(() =>
+    assertPresetApplicable({ preset: "summary", request: { kind: "benchmark" } })
+  );
+  assert.doesNotThrow(() =>
+    assertPresetApplicable({ preset: "summary", request: { kind: "cohortEvidence" } })
+  );
+});
+
+/**
+ * Same precedence rule applyOutputProjection enforces: --fields silences an
+ * otherwise-inapplicable --preset entirely, so passing both together must
+ * not trip the early check either.
+ */
+test("(NAK-804) assertPresetApplicable defers to --fields precedence, like applyOutputProjection", () => {
+  assert.doesNotThrow(() =>
+    assertPresetApplicable({
+      fields: "state",
+      preset: "summary",
+      request: { kind: undefined }
+    })
+  );
+});

package/src/projection.js

@@ -47,6 +47,27 @@ export function applyOutputProjection(payload, { fields, preset, request } = {})
   return applyFieldsProjection(payload, presetFields, `preset ${preset}`);
 }
 
+/**
+ * NAK-804 cross-model review (Codex Sol): every metered command built a
+ * usage-error-only exit on an inapplicable --preset, but the check ran
+ * INSIDE applyOutputProjection, which main() calls only AFTER the HTTP
+ * request already executed (and, for a metered endpoint, already charged a
+ * credit). This is the same validation, called right after buildRequest()
+ * and before that request is ever sent, so the usage error lands before any
+ * network call or charge. General fix, not ai-disclosure-specific: it reuses
+ * resolvePresetFields exactly, so any command missing from its
+ * kind-allowlist gets the early rejection for free.
+ *
+ * Mirrors applyOutputProjection's own precedence: --fields silences --preset
+ * entirely (never even inspected) both here and there, so the two agree on
+ * every input rather than only on the paths that reach a real request.
+ */
+export function assertPresetApplicable({ fields, preset, request } = {}) {
+  if (fields != null && fields !== "") return;
+  if (preset == null || preset === "") return;
+  resolvePresetFields(preset, request);
+}
+
 function resolvePresetFields(preset, request) {
   if (preset !== "summary") {
     writeJsonError({