@witchpot/gmc 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -2,7 +2,21 @@
 
 All notable changes to the Game Market Copilot CLI will be recorded here.
 
-## 0.1.1 - Unreleased
+## 0.1.3 - 2026-06-01
+
+- Added `gmc games count` for fast Steam catalog counts with bounded filters.
+- Added `gmc games aggregate` for count, average, median, percentile, and bucket
+  summaries over Steam catalog cohorts.
+- Added bucket threshold forwarding for price, review, and rating distribution
+  workflows.
+- Fixed the npm executable entrypoint so `gmc` runs correctly through npm,
+  Volta, and other package-manager shims.
+- Added packed-tarball smoke validation for actual CLI stdout to catch silent
+  executable startup regressions.
+- Improved browser-login token exchange diagnostics for non-JSON Access
+  responses and accepted direct or nested credential response envelopes.
+
+## 0.1.1 - 2026-06-01
 
 - Updated npm package description and README introduction for public beta users.
 

package/README.md

@@ -6,25 +6,21 @@ showcases.
 
 ## Install
 
-The CLI package is published to npm with a public package and beta dist-tag. If
-the beta package has not been published in the current environment yet, run from
-this repository:
+Install the beta CLI:
 
 ```bash
-npm run gmc -- --help
+npm install -g @witchpot/gmc@beta
+gmc --version
 ```
 
-The package name for beta distribution is `@witchpot/gmc` with the
-`gmc` binary. Before publishing a beta build, run:
+Or run it without a global install:
 
 ```bash
-npm run gmc:release:check
-npm run gmc:publish:beta:dry-run
-npm run gmc:publish:beta
+npx @witchpot/gmc@beta --version
 ```
 
-Closed-beta setup details live in
-[`docs/closed-beta-onboarding.md`](../../docs/closed-beta-onboarding.md).
+A fuller user guide lives in
+[`docs/gmc-cli-user-guide.md`](../../docs/gmc-cli-user-guide.md).
 
 Closed-beta access is controlled by GMC API credentials, not npm package
 visibility. Installing the public package does not grant access to paid or beta

package/bin/gmc.mjs

@@ -1,50 +1,5 @@
 #!/usr/bin/env node
 
-import { isCliEntryPoint, runCliEntryPoint } from "../src/main.js";
+import { runCliEntryPoint } from "../src/main.js";
 
-export { BOOLEAN_OPTIONS, matches, parseArgs } from "../src/args.js";
-export {
-  buildLoginUrl,
-  exchangeAuthorizationCode,
-  extractCredentialFromTokenPayload,
-  runBrowserLogin
-} from "../src/browser-login.js";
-export { handleLocalCommand, loadConfig, parseBaseUrl } from "../src/config.js";
-export {
-  CLI_BETA_PACKAGE_NAME,
-  CLI_PACKAGE_NAME,
-  CLI_VERSION,
-  PROVISIONAL_BETA_COMMANDS,
-  SUPPORTED_BETA_COMMANDS
-} from "../src/constants.js";
-export { writeJsonError } from "../src/output.js";
-export { applyFieldsProjection, applyOutputProjection } from "../src/projection.js";
-export {
-  buildRequest,
-  buildRequestHeaders,
-  createRequestUrl,
-  filterShowcasesByDeadline
-} from "../src/requests.js";
-export {
-  buildHttpApiError,
-  buildNonJsonApiError,
-  composeBenchmarkPayload,
-  composeCampaignSignalsPayload,
-  composeCohortEvidencePayload,
-  composeComparePayload,
-  composeReviewPatternsPayload,
-  composeResolvePayload,
-  composeShowcaseFitPayload,
-  executeRequestPlan
-} from "../src/workflows.js";
-export {
-  buildCliAuthStatus,
-  enrichAuthStatusOutput,
-  isCliEntryPoint,
-  main,
-  runCliEntryPoint
-} from "../src/main.js";
-
-if (isCliEntryPoint(import.meta.url)) {
-  runCliEntryPoint();
-}
+runCliEntryPoint();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@witchpot/gmc",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": false,
   "description": "Command line tools for Game Market Copilot market research.",
   "license": "UNLICENSED",
@@ -14,6 +14,11 @@
     "url": "https://gamemarketcopilot.com"
   },
   "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
   "bin": {
     "gmc": "bin/gmc.mjs"
   },

package/scripts/check-release-readiness.mjs

@@ -9,6 +9,7 @@ const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
 
 const requiredFiles = [
   "bin/gmc.mjs",
+  "src/index.js",
   "src/main.js",
   "src/requests.js",
   "src/workflows.js",
@@ -26,6 +27,7 @@ const forbiddenPatterns = [
 
 const sourceFiles = [
   "bin/gmc.mjs",
+  "src/index.js",
   "src/args.js",
   "src/browser-login.js",
   "src/config.js",
@@ -56,6 +58,14 @@ if (packageJson.bin?.gmc !== "bin/gmc.mjs") {
   failures.push("bin.gmc must point to bin/gmc.mjs.");
 }
 
+if (packageJson.main !== "./src/index.js") {
+  failures.push("main must point to ./src/index.js.");
+}
+
+if (packageJson.exports?.["."] !== "./src/index.js") {
+  failures.push("exports['.'] must point to ./src/index.js.");
+}
+
 for (const required of requiredFileGlobs) {
   if (!packageJson.files?.includes(required)) {
     failures.push(`package.json files must include ${required}.`);

package/scripts/smoke-pack.mjs

@@ -48,8 +48,22 @@ try {
   const binName = process.platform === "win32" ? "gmc.cmd" : "gmc";
   const gmcBin = path.join(workDir, "node_modules", ".bin", binName);
   const configPath = path.join(projectDir, "config.json");
-  run(gmcBin, ["--help"], { env: { GMC_CONFIG_PATH: configPath } });
-  run(gmcBin, ["config", "get", "--json"], { env: { GMC_CONFIG_PATH: configPath } });
+  const helpResult = run(gmcBin, ["--help"], {
+    env: { GMC_CONFIG_PATH: configPath },
+    capture: true
+  });
+  if (!helpResult.stdout.includes("Game Market Copilot CLI") || !helpResult.stdout.includes("gmc --version")) {
+    throw new Error("Packed gmc --help did not print the expected help text");
+  }
+
+  const configResult = run(gmcBin, ["config", "get", "--json"], {
+    env: { GMC_CONFIG_PATH: configPath },
+    capture: true
+  });
+  const configPayload = JSON.parse(configResult.stdout);
+  if (configPayload?.data?.configPath !== configPath || configPayload?.data?.authMode !== "anonymous") {
+    throw new Error("Packed gmc config get --json did not print the expected config payload");
+  }
 } finally {
   rmSync(workDir, { recursive: true, force: true });
 }

package/src/args.js

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

package/src/browser-login.js

@@ -88,10 +88,11 @@ export async function exchangeAuthorizationCode({
   });
 
   const contentType = response.headers.get("content-type") ?? "";
-  const payload = contentType.includes("application/json")
+  const isJson = isJsonContentType(contentType);
+  const payload = isJson
     ? await response.json().catch(() => null)
     : null;
-  if (!contentType.includes("application/json")) {
+  if (!isJson) {
     writeJsonError({
       code: "CLI_API_ERROR",
       message: "GMC CLI authorization exchange returned a non-JSON response. If production is behind Cloudflare Access, allow CLI/API routes or use a Cloudflare service-token path for the CLI.",
@@ -151,6 +152,11 @@ function summarizeTokenExchangeResponse(response) {
   };
 }
 
+export function isJsonContentType(contentType) {
+  const mediaType = String(contentType).split(";")[0]?.trim().toLowerCase();
+  return mediaType === "application/json" || Boolean(mediaType?.endsWith("+json"));
+}
+
 function getObjectKeys(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
   return Object.keys(value).filter((key) => key !== "secret");

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.1";
+export const CLI_VERSION = "0.1.3";
 
 export const DEFAULT_API_BASE_URL = "https://gamemarketcopilot.com";
 export const DEFAULT_CONFIG_PATH = path.join(homedir(), ".config", "gmc", "config.json");
@@ -20,6 +20,8 @@ export const SUPPORTED_BETA_COMMANDS = [
   "gmc --version",
   "gmc update --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",
   "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",

package/src/help.js

@@ -23,6 +23,8 @@ Usage:
   gmc config set apiBaseUrl <url>
   gmc schema --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
   gmc games resolve --source steam --query <title> --json
   gmc games benchmark --source steam --tags <tag_slug[,tag_slug...]> --reviews-min <number> --json
   gmc games benchmark --source steam --tags <tag_slug[,tag_slug...]> --sample-size <number> --json
@@ -58,3 +60,51 @@ Environment:
   GMC_CONFIG_PATH   Optional JSON config with apiBaseUrl and apiKey
 `);
 }
+
+export function printGamesSearchHelp() {
+  process.stdout.write(`gmc games search
+
+Usage:
+  gmc games search --source steam [filters] [output options] --json
+
+Filters:
+  --query <text>              Search by title or supported metadata.
+  --tags <slug[,slug...]>     Filter by Steam tag slugs.
+  --tag-mode <and|or>         Match all tags or any tag.
+  --release-from <date>       Inclusive release date lower bound, YYYY-MM-DD.
+  --release-to <date>         Inclusive release date upper bound, YYYY-MM-DD.
+  --release-year <year>       Shortcut for that calendar year.
+  --reviews-min <number>      Inclusive lower bound, reviews >= number.
+  --reviews-max <number>      Inclusive upper bound, reviews <= number.
+  --reviews-gt <number>       Strict lower bound, reviews > number.
+  --reviews-lt <number>       Strict upper bound, reviews < number.
+  --rating-min <number>       Inclusive rating lower bound, 0-100.
+  --price-min <number>        Inclusive price lower bound.
+  --price-max <number>        Inclusive price upper bound.
+
+Sorting:
+  --sort <key>                reviews_desc, reviews_asc, rating_desc,
+                              rating_asc, release_desc, release_asc,
+                              price_asc, price_desc, title_asc, title_desc.
+
+Pagination:
+  --limit <number>            1-100, default 20.
+  --offset <number>           Offset for the next page.
+
+Output:
+  --fields <list>             Optional comma-separated field list.
+  --preset <name>             Optional preset when supported.
+  --json                      Required for structured agent workflows.
+
+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.
+
+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
+`);
+}

package/src/index.js

@@ -0,0 +1,42 @@
+export { BOOLEAN_OPTIONS, matches, parseArgs } from "./args.js";
+export {
+  buildLoginUrl,
+  exchangeAuthorizationCode,
+  extractCredentialFromTokenPayload,
+  isJsonContentType,
+  runBrowserLogin
+} from "./browser-login.js";
+export { handleLocalCommand, loadConfig, parseBaseUrl } from "./config.js";
+export {
+  CLI_BETA_PACKAGE_NAME,
+  CLI_PACKAGE_NAME,
+  CLI_VERSION,
+  PROVISIONAL_BETA_COMMANDS,
+  SUPPORTED_BETA_COMMANDS
+} from "./constants.js";
+export { writeJsonError } from "./output.js";
+export { applyFieldsProjection, applyOutputProjection } from "./projection.js";
+export {
+  buildRequest,
+  buildRequestHeaders,
+  createRequestUrl,
+  filterShowcasesByDeadline
+} from "./requests.js";
+export {
+  buildCliAuthStatus,
+  enrichAuthStatusOutput,
+  main,
+  runCliEntryPoint
+} from "./main.js";
+export {
+  buildHttpApiError,
+  buildNonJsonApiError,
+  composeBenchmarkPayload,
+  composeCampaignSignalsPayload,
+  composeCohortEvidencePayload,
+  composeComparePayload,
+  composeReviewPatternsPayload,
+  composeResolvePayload,
+  composeShowcaseFitPayload,
+  executeRequestPlan
+} from "./workflows.js";

package/src/main.js

@@ -1,4 +1,3 @@
-import { pathToFileURL } from "node:url";
 import {
   CLI_PACKAGE_NAME,
   CLI_VERSION,
@@ -9,7 +8,7 @@ import {
 } from "./constants.js";
 import { matches, parseArgs } from "./args.js";
 import { handleLocalCommand, loadConfig, parseBaseUrl } from "./config.js";
-import { printHelp } from "./help.js";
+import { printGamesSearchHelp, printHelp } from "./help.js";
 import { writeJsonError } from "./output.js";
 import { applyOutputProjection } from "./projection.js";
 import { buildRequest } from "./requests.js";
@@ -32,7 +31,16 @@ export async function main(argv = process.argv.slice(2)) {
     process.exit(0);
   }
 
-  if (options.help || (command.length === 0 && positional.length === 0)) {
+  if (options.help) {
+    if (matches(command, ["games", "search"])) {
+      printGamesSearchHelp();
+    } else {
+      printHelp();
+    }
+    process.exit(0);
+  }
+
+  if (command.length === 0 && positional.length === 0) {
     printHelp();
     process.exit(0);
   }
@@ -89,10 +97,6 @@ export function runCliEntryPoint() {
   });
 }
 
-export function isCliEntryPoint(importMetaUrl, argvEntry = process.argv[1]) {
-  return Boolean(argvEntry && importMetaUrl === pathToFileURL(argvEntry).href);
-}
-
 export function enrichAuthStatusOutput(payload, config) {
   if (!payload || typeof payload !== "object" || !payload.data || typeof payload.data !== "object") {
     return payload;

package/src/requests.js

@@ -45,6 +45,22 @@ export function buildRequest(command, options, positional) {
     };
   }
 
+  if (matches(command, ["games", "count"])) {
+    assertSource(options.source);
+    return {
+      path: "/api/v1/steam/games/count",
+      query: buildGameCountQuery(options)
+    };
+  }
+
+  if (matches(command, ["games", "aggregate"])) {
+    assertSource(options.source);
+    return {
+      path: "/api/v1/steam/games/aggregate",
+      query: buildGameAggregateQuery(options)
+    };
+  }
+
   if (matches(command, ["games", "resolve"])) {
     assertSource(options.source);
     const query = options.query ?? options.q ?? positional.join(" ");
@@ -383,6 +399,20 @@ function pickQuery(options, mapping) {
 }
 
 function buildGameSearchQuery(options) {
+  const query = {
+    ...buildGameCountQuery(options),
+    ...pickQuery(options, {
+      sort: "sort",
+      limit: "limit",
+      offset: "offset",
+      locale: "locale"
+    })
+  };
+
+  return query;
+}
+
+function buildGameCountQuery(options) {
   const query = pickQuery(options, {
     query: "q",
     tags: "tags",
@@ -391,19 +421,72 @@ function buildGameSearchQuery(options) {
     "release-to": "releaseTo",
     "reviews-min": "reviewsMin",
     "reviews-max": "reviewsMax",
+    "reviews-gt": "reviewsGt",
+    "reviews-lt": "reviewsLt",
     "rating-min": "ratingMin",
     "price-min": "priceMin",
     "price-max": "priceMax",
-    sort: "sort",
-    limit: "limit",
-    offset: "offset",
     locale: "locale"
   });
 
+  applyReleaseYearAlias(query, options);
+  assertReviewBoundOptions(options);
   if (query.tags) query.tags = normalizeTagSlugCsv(query.tags);
   return query;
 }
 
+function buildGameAggregateQuery(options) {
+  return {
+    ...buildGameCountQuery(options),
+    ...pickQuery(options, {
+      metric: "metric",
+      "group-by": "groupBy",
+      bucket: "bucket",
+      sort: "sort",
+      limit: "limit",
+      offset: "offset"
+    })
+  };
+}
+
+function applyReleaseYearAlias(query, options) {
+  const releaseYear = options["release-year"];
+  if (releaseYear == null) return;
+  if (!/^\d{4}$/.test(String(releaseYear))) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: "--release-year must use YYYY"
+    });
+    process.exit(EXIT_USAGE);
+  }
+  if (options["release-from"] != null || options["release-to"] != null) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: "Use either --release-year or --release-from/--release-to, not both"
+    });
+    process.exit(EXIT_USAGE);
+  }
+  query.releaseFrom = `${releaseYear}-01-01`;
+  query.releaseTo = `${releaseYear}-12-31`;
+}
+
+function assertReviewBoundOptions(options) {
+  if (options["reviews-min"] != null && options["reviews-gt"] != null) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: "Use either --reviews-min or --reviews-gt, not both"
+    });
+    process.exit(EXIT_USAGE);
+  }
+  if (options["reviews-max"] != null && options["reviews-lt"] != null) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: "Use either --reviews-max or --reviews-lt, not both"
+    });
+    process.exit(EXIT_USAGE);
+  }
+}
+
 function buildShowcaseSearchQuery(options) {
   return pickQuery(options, {
     query: "q",