@witchpot/gmc 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to the Game Market Copilot CLI will be recorded here.
 
+## 0.1.5 - 2026-06-12
+
+- Added `gmc games success-report` for the per-game Success Factor Analysis
+  report (executive summary plus markdown body; plan-gated like the API).
+- Added `--coverage <basic|partial|full[,...]>` to games search, count,
+  aggregate, benchmark, resolve, review patterns, and cohort workflows so
+  agents can scope cohorts to researched titles before spending quota.
+- Added cohort `skippedReasons` tallies to review-pattern and cohort evidence
+  summaries so "no data collected" is distinguishable from "no findings".
+- Added a `node --test` unit harness for CLI request planning (`npm test`).
+
+## 0.1.4 - 2026-06-01
+
+- Reissued the beta CLI package after the count and aggregate API server
+  implementation was committed for deployment alignment.
+
 ## 0.1.3 - 2026-06-01
 
 - Added `gmc games count` for fast Steam catalog counts with bounded filters.

package/README.md

@@ -76,9 +76,12 @@ when using output in agent answers.
 - `gmc auth status`
 - `gmc schema`
 - `gmc games search`
+- `gmc games count`
+- `gmc games aggregate`
 - `gmc games resolve`
 - `gmc games detail`
 - `gmc games analysis`
+- `gmc games success-report`
 - `gmc campaigns signals`
 - `gmc games topics`
 - `gmc games compare`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@witchpot/gmc",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "private": false,
   "description": "Command line tools for Game Market Copilot market research.",
   "license": "UNLICENSED",
@@ -36,6 +36,7 @@
     "access": "public"
   },
   "scripts": {
+    "test": "node --test src/*.test.js",
     "release:check": "node scripts/check-release-readiness.mjs && node scripts/smoke-pack.mjs",
     "prepublishOnly": "npm run release:check",
     "smoke:beta": "node scripts/smoke-beta.mjs",

package/src/args.js

@@ -71,7 +71,7 @@ function isCommandToken(command, token) {
     return ["get", "set"].includes(token);
   }
   if (command[0] === "games") {
-    return ["search", "count", "aggregate", "resolve", "benchmark", "detail", "analysis", "compare", "topics"].includes(token);
+    return ["search", "count", "aggregate", "resolve", "benchmark", "detail", "analysis", "compare", "topics", "success-report"].includes(token);
   }
   if (command[0] === "reviews") {
     return token === "patterns";

package/src/constants.js

@@ -8,7 +8,7 @@ export const EXIT_API = 4;
 
 export const CLI_PACKAGE_NAME = "@witchpot/gmc";
 export const CLI_BETA_PACKAGE_NAME = "@witchpot/gmc";
-export const CLI_VERSION = "0.1.3";
+export const CLI_VERSION = "0.1.5";
 
 export const DEFAULT_API_BASE_URL = "https://gamemarketcopilot.com";
 export const DEFAULT_CONFIG_PATH = path.join(homedir(), ".config", "gmc", "config.json");
@@ -25,6 +25,7 @@ export const SUPPORTED_BETA_COMMANDS = [
   "gmc games resolve --source steam --query <title> --json",
   "gmc games detail --source steam <externalId> --json",
   "gmc games analysis --source steam <externalId> --sections reviews,marketing --json",
+  "gmc games success-report --source steam <externalId> --json",
   "gmc campaigns signals --source steam <externalId> --json",
   "gmc games topics --source steam <externalId> --json",
   "gmc games compare --source steam <externalId> <externalId...> --focus market --json",

package/src/help.js

@@ -31,6 +31,7 @@ Usage:
   gmc games detail --source steam <externalId> --json
   gmc games detail --source steam <externalId> --fields title,snapshot.rating,snapshot.reviews --json
   gmc games analysis --source steam <externalId> --sections reviews,marketing --json
+  gmc games success-report --source steam <externalId> --json
   gmc campaigns signals --source steam <externalId> --json
   gmc games compare --source steam <externalId> <externalId...> --focus market --json
   gmc games topics --source steam <externalId> --json
@@ -81,6 +82,9 @@ Filters:
   --rating-min <number>       Inclusive rating lower bound, 0-100.
   --price-min <number>        Inclusive price lower bound.
   --price-max <number>        Inclusive price upper bound.
+  --coverage <list>           Research coverage levels: basic, partial, full.
+                              Use --coverage full,partial to keep only games
+                              with collected analysis data.
 
 Sorting:
   --sort <key>                reviews_desc, reviews_asc, rating_desc,

package/src/requests.js

@@ -129,6 +129,18 @@ export function buildRequest(command, options, positional) {
     };
   }
 
+  if (matches(command, ["games", "success-report"])) {
+    assertSource(options.source);
+    const externalId = positional[0];
+    assertExternalId(externalId, "gmc games success-report --source steam <externalId> --json");
+    return {
+      path: `/api/v1/steam/games/${encodeURIComponent(externalId)}/success-report`,
+      query: pickQuery(options, {
+        locale: "locale"
+      })
+    };
+  }
+
   if (matches(command, ["campaigns", "signals"])) {
     assertSource(options.source);
     const externalId = positional[0];
@@ -426,12 +438,14 @@ function buildGameCountQuery(options) {
     "rating-min": "ratingMin",
     "price-min": "priceMin",
     "price-max": "priceMax",
+    coverage: "coverage",
     locale: "locale"
   });
 
   applyReleaseYearAlias(query, options);
   assertReviewBoundOptions(options);
   if (query.tags) query.tags = normalizeTagSlugCsv(query.tags);
+  if (query.coverage) query.coverage = assertCoverageCsv(query.coverage);
   return query;
 }
 
@@ -588,6 +602,18 @@ function assertBoundedPositiveIntegerOption(value, optionName, maxValue) {
   return number;
 }
 
+function assertCoverageCsv(value) {
+  const levels = parseCsvString(value).map((level) => level.toLowerCase());
+  if (levels.length === 0 || levels.some((level) => !["basic", "partial", "full"].includes(level))) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: "--coverage accepts a comma-separated subset of: basic, partial, full"
+    });
+    process.exit(EXIT_USAGE);
+  }
+  return levels.join(",");
+}
+
 function assertReviewPatternSentiment(value) {
   const sentiment = String(value);
   if (!["positive", "negative", "mixed"].includes(sentiment)) {

package/src/requests.test.js

@@ -0,0 +1,104 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseArgs } from "./args.js";
+import { buildRequest } from "./requests.js";
+
+function buildRequestFromArgv(argv) {
+  const { command, options, positional } = parseArgs(argv);
+  return buildRequest(command, options, positional);
+}
+
+test("games success-report builds the success-report request plan", () => {
+  const request = buildRequestFromArgv([
+    "games",
+    "success-report",
+    "--source",
+    "steam",
+    "1062090",
+    "--json"
+  ]);
+
+  assert.equal(request.path, "/api/v1/steam/games/1062090/success-report");
+  assert.deepEqual(request.query, {});
+});
+
+test("games success-report forwards locale", () => {
+  const request = buildRequestFromArgv([
+    "games",
+    "success-report",
+    "--source",
+    "steam",
+    "1062090",
+    "--locale",
+    "ja",
+    "--json"
+  ]);
+
+  assert.equal(request.path, "/api/v1/steam/games/1062090/success-report");
+  assert.deepEqual(request.query, { locale: "ja" });
+});
+
+test("games detail request plan stays unchanged", () => {
+  const request = buildRequestFromArgv([
+    "games",
+    "detail",
+    "--source",
+    "steam",
+    "1062090",
+    "--json"
+  ]);
+
+  assert.equal(request.path, "/api/v1/steam/games/1062090");
+  assert.deepEqual(request.query, {});
+});
+
+test("games search forwards coverage as a filter", () => {
+  const request = buildRequestFromArgv([
+    "games",
+    "search",
+    "--source",
+    "steam",
+    "--coverage",
+    "full,partial",
+    "--reviews-min",
+    "1000",
+    "--json"
+  ]);
+
+  assert.equal(request.path, "/api/v1/steam/games");
+  assert.equal(request.query.coverage, "full,partial");
+  assert.equal(request.query.reviewsMin, "1000");
+});
+
+test("games count forwards coverage for cohort pre-estimation", () => {
+  const request = buildRequestFromArgv([
+    "games",
+    "count",
+    "--source",
+    "steam",
+    "--coverage",
+    "full",
+    "--json"
+  ]);
+
+  assert.equal(request.path, "/api/v1/steam/games/count");
+  assert.equal(request.query.coverage, "full");
+});
+
+test("reviews patterns forwards coverage into the cohort search request", () => {
+  const request = buildRequestFromArgv([
+    "reviews",
+    "patterns",
+    "--source",
+    "steam",
+    "--tags",
+    "roguelike",
+    "--coverage",
+    "full,partial",
+    "--json"
+  ]);
+
+  assert.equal(request.kind, "reviewPatterns");
+  assert.equal(request.searchRequest.query.coverage, "full,partial");
+});

package/src/workflows.js

@@ -437,6 +437,15 @@ export function composeBenchmarkPayload(request, search, options = {}) {
   };
 }
 
+function tallySkippedReasons(skipped) {
+  const reasons = {};
+  for (const entry of skipped) {
+    const reason = entry?.reason ?? "unknown";
+    reasons[reason] = (reasons[reason] ?? 0) + 1;
+  }
+  return reasons;
+}
+
 export function composeReviewPatternsPayload(request, result, options = {}) {
   const generatedAt = options.generatedAt ?? new Date().toISOString();
   const requestId = options.requestId ?? createCliRequestId();
@@ -495,6 +504,7 @@ export function composeReviewPatternsPayload(request, result, options = {}) {
         returnedGames: games.length,
         usableGames: usableGames.length,
         skippedGames: skipped.length,
+        skippedReasons: tallySkippedReasons(skipped),
         totalMatches: result.search?.pagination?.total,
         included: usableGames.map((game) => ({
           source: request.source,
@@ -687,6 +697,7 @@ export function composeCohortEvidencePayload(request, result, options = {}) {
         returnedGames: games.length,
         usableGames: included.length,
         skippedGames: skipped.length,
+        skippedReasons: tallySkippedReasons(skipped),
         totalMatches: result.search?.pagination?.total,
         included: included.map((entry) => ({
           source: request.source,

package/src/workflows.test.js

@@ -0,0 +1,80 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { composeCohortEvidencePayload } from "./workflows.js";
+
+test("cohort evidence summarizes skipped games by reason", () => {
+  const request = {
+    source: "steam",
+    workflow: "cohortTrends",
+    evidenceType: "trends",
+    sections: [],
+    query: { sort: "reviews_desc", limit: 20 }
+  };
+  const result = {
+    search: {
+      data: [
+        { appid: 1, title: "Usable", reviews: 100 },
+        { appid: 2, title: "Failed A" },
+        { appid: 3, title: "Failed B" },
+        { appid: 4, title: "No Id" }
+      ],
+      pagination: { limit: 20, offset: 0, total: 4, nextOffset: null }
+    },
+    analysisResults: [
+      { game: { appid: 1, title: "Usable", reviews: 100 }, externalId: "1" },
+      {
+        game: { appid: 2, title: "Failed A" },
+        externalId: "2",
+        skippedReason: "analysis_request_failed",
+        error: { code: "UPSTREAM_UNAVAILABLE" }
+      },
+      {
+        game: { appid: 3, title: "Failed B" },
+        externalId: "3",
+        skippedReason: "analysis_request_failed",
+        error: { code: "UPSTREAM_UNAVAILABLE" }
+      },
+      { game: { appid: 4, title: "No Id" }, skippedReason: "missing_external_id" }
+    ]
+  };
+
+  const payload = composeCohortEvidencePayload(request, result, {
+    generatedAt: "2026-06-12T00:00:00.000Z",
+    requestId: "req_test"
+  });
+
+  assert.equal(payload.data.cohort.returnedGames, 4);
+  assert.equal(payload.data.cohort.usableGames, 1);
+  assert.equal(payload.data.cohort.skippedGames, 3);
+  assert.deepEqual(payload.data.cohort.skippedReasons, {
+    analysis_request_failed: 2,
+    missing_external_id: 1
+  });
+});
+
+test("cohort evidence reports an empty reason tally when nothing is skipped", () => {
+  const request = {
+    source: "steam",
+    workflow: "cohortTrends",
+    evidenceType: "trends",
+    sections: [],
+    query: {}
+  };
+  const result = {
+    search: {
+      data: [{ appid: 1, title: "Usable", reviews: 100 }],
+      pagination: { limit: 20, offset: 0, total: 1, nextOffset: null }
+    },
+    analysisResults: [
+      { game: { appid: 1, title: "Usable", reviews: 100 }, externalId: "1" }
+    ]
+  };
+
+  const payload = composeCohortEvidencePayload(request, result, {
+    generatedAt: "2026-06-12T00:00:00.000Z",
+    requestId: "req_test"
+  });
+
+  assert.deepEqual(payload.data.cohort.skippedReasons, {});
+});