@witchpot/gmc 0.6.0 → 0.9.0

package/src/workflows.js

@@ -11,6 +11,7 @@ import {
   composeResolvePayload,
   composeReviewPatternsPayload,
   composeShowcaseFitPayload,
+  composeShowcaseHistoryPayload,
   getPreferredShowcaseTags,
   mergeSearchPages
 } from "@witchpot/gmc-core";
@@ -22,7 +23,8 @@ export {
   composeComparePayload,
   composeResolvePayload,
   composeReviewPatternsPayload,
-  composeShowcaseFitPayload
+  composeShowcaseFitPayload,
+  composeShowcaseHistoryPayload
 };
 
 export async function executeRequestPlan(baseUrl, request, { apiKey }) {
@@ -47,6 +49,9 @@ export async function executeRequestPlan(baseUrl, request, { apiKey }) {
   if (request.kind === "showcaseFit") {
     return executeShowcaseFitRequest(baseUrl, request, { apiKey });
   }
+  if (request.kind === "showcaseHistory") {
+    return executeShowcaseHistoryRequest(baseUrl, request, { apiKey });
+  }
 
   const response = await fetchJson(createRequestUrl(baseUrl, request), {
     apiKey,
@@ -240,6 +245,15 @@ async function executeShowcaseFitRequest(baseUrl, request, { apiKey }) {
   });
 }
 
+async function executeShowcaseHistoryRequest(baseUrl, request, { apiKey }) {
+  const detailRequest = {
+    path: `/api/v1/steam/games/${encodeURIComponent(request.externalId)}/analysis`,
+    query: request.detailQuery
+  };
+  const detail = await fetchJson(createRequestUrl(baseUrl, detailRequest), { apiKey });
+  return composeShowcaseHistoryPayload(request, { detail });
+}
+
 async function executeSearchPages(baseUrl, searchRequest, sampling, { apiKey }) {
   if (!sampling) {
     return {

package/src/workflows.test.js

@@ -152,6 +152,162 @@ test("executeRequestPlan normalizes list game resolution for cohort workflows",
   }
 });
 
+test("games language-topics passes the insufficient-evidence envelope through untouched", async () => {
+  // NAK-455: the CLI is a transport for this endpoint. Evidence state,
+  // coverage, denominators, and the raw/weighted split must arrive exactly as
+  // the API produced them — an insufficient_evidence answer must never be
+  // flattened into empty rows or a zero.
+  const envelope = {
+    data: {
+      appid: 730,
+      evidenceState: "insufficient_evidence",
+      snapshot: {
+        periodStart: "2026-02-06",
+        periodEnd: "2026-08-06",
+        analysisVersion: "v1",
+        generatedAt: "2026-08-06T04:00:00.000Z"
+      },
+      estimateCaveat: "Weighted values are estimates.",
+      coverage: {
+        totalRows: 226,
+        rowsAtThreshold: 0,
+        languagesAtThreshold: 0,
+        topicsAtThreshold: 0,
+        appliedMinReviews: 30,
+        insufficientRowsReturned: 1,
+        insufficientRowsTruncated: false
+      },
+      rows: [
+        {
+          appid: 730,
+          clusterId: 11,
+          topic: "performance",
+          language: "german",
+          counts: {
+            sourceReviews: 400,
+            sampledReviews: 90,
+            analyzedReviews: 21,
+            distinctReviews: 12
+          },
+          estimates: { samplingWeightMethod: "source_over_analyzed_by_language_voted_up_v1" },
+          evidence: { minimumN: 30, status: "insufficient_evidence", meetsRequestedThreshold: false }
+        }
+      ]
+    },
+    meta: { requestId: "req_test" },
+    warnings: []
+  };
+
+  const originalFetch = globalThis.fetch;
+  const seenUrls = [];
+  globalThis.fetch = async (url) => {
+    seenUrls.push(String(url));
+    return jsonResponse(envelope);
+  };
+
+  try {
+    const payload = await executeRequestPlan("https://gamemarketcopilot.com", {
+      path: "/api/v1/steam/games/730/review-topics/languages",
+      query: { include_insufficient: "true" }
+    }, { apiKey: "gmck_test" });
+
+    assert.deepEqual(payload, envelope);
+    assert.equal(payload.data.evidenceState, "insufficient_evidence");
+    assert.equal(payload.data.coverage.totalRows, 226);
+    assert.equal(payload.data.rows[0].counts.distinctReviews, 12);
+    assert.deepEqual(seenUrls, [
+      "https://gamemarketcopilot.com/api/v1/steam/games/730/review-topics/languages?include_insufficient=true"
+    ]);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("games review-history passes the three arrays through untouched", async () => {
+  // NAK-428: the CLI is a transport for this endpoint. An empty events or
+  // discountWindows array is a COLLECTION state the agent has to see as-is —
+  // the CLI must never drop, merge, or window the arrays, and must never turn
+  // an unmatched (open) discount window into a closed one.
+  const envelope = {
+    data: {
+      series: [
+        { date: "2026-08-01", totalReviews: 1000 },
+        { date: "2026-08-03", totalReviews: 1040 }
+      ],
+      events: [
+        { type: "release", date: "2026-07-01" },
+        {
+          type: "announcement",
+          date: "2026-08-02",
+          count: 3,
+          label: "Patch 1.2 is live",
+          url: "https://store.steampowered.com/news/app/730/view/1"
+        }
+      ],
+      discountWindows: [
+        { startDate: "2026-08-01", endDate: "2026-08-05", discountPercent: 33 },
+        { startDate: "2026-08-20", endDate: null, discountPercent: null }
+      ]
+    },
+    meta: { requestId: "req_test" },
+    warnings: []
+  };
+
+  const originalFetch = globalThis.fetch;
+  const seenUrls = [];
+  globalThis.fetch = async (url) => {
+    seenUrls.push(String(url));
+    return jsonResponse(envelope);
+  };
+
+  try {
+    const payload = await executeRequestPlan("https://gamemarketcopilot.com", {
+      path: "/api/v1/steam/games/730/review-history",
+      query: {}
+    }, { apiKey: "gmck_test" });
+
+    assert.deepEqual(payload, envelope);
+    // The gap between 08-01 and 08-03 survives: collection gaps are real and
+    // consumers must scale by date, not by array index.
+    assert.deepEqual(payload.data.series.map((point) => point.date), ["2026-08-01", "2026-08-03"]);
+    assert.equal(payload.data.discountWindows[1].endDate, null);
+    // No query string appended for an endpoint that takes no parameters.
+    assert.deepEqual(seenUrls, [
+      "https://gamemarketcopilot.com/api/v1/steam/games/730/review-history"
+    ]);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("games review-history passes an all-empty payload through as-is", async () => {
+  // Empty arrays mean "nothing collected", never "nothing happened". The CLI
+  // must hand the agent the same empty arrays the API produced rather than
+  // omitting the keys, which would read as absent fields.
+  const envelope = {
+    data: { series: [], events: [], discountWindows: [] },
+    meta: { requestId: "req_test" },
+    warnings: ["static_fixture_data"]
+  };
+
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = async () => jsonResponse(envelope);
+
+  try {
+    const payload = await executeRequestPlan("https://gamemarketcopilot.com", {
+      path: "/api/v1/steam/games/730/review-history",
+      query: {}
+    }, { apiKey: "gmck_test" });
+
+    assert.deepEqual(payload, envelope);
+    assert.deepEqual(payload.data.events, []);
+    assert.deepEqual(payload.data.discountWindows, []);
+    assert.deepEqual(payload.warnings, ["static_fixture_data"]);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
 function jsonResponse(payload, status = 200) {
   return {
     ok: status >= 200 && status < 300,

package/scripts/check-release-readiness.mjs

@@ -1,177 +0,0 @@
-#!/usr/bin/env node
-
-import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import path from "node:path";
-
-const packageDir = path.resolve(new URL("..", import.meta.url).pathname);
-const packageJsonPath = path.join(packageDir, "package.json");
-const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
-
-const requiredFiles = [
-  "bin/gmc.mjs",
-  "src/index.js",
-  "src/main.js",
-  "src/requests.js",
-  "src/workflows.js",
-  "skill/gmc-analysis/SKILL.md",
-  "skill/gmc-analysis/references/recipes.md",
-  "skill/gmc-analysis/references/pitfalls.md",
-  "skill/gmc-analysis/references/validity.md",
-  "skill/gmc-analysis/references/quota.md",
-  "skill/gmc-analysis/references/charts.md",
-  "skill/gmc-analysis/CHANGELOG.md",
-  "README.md",
-  "CHANGELOG.md"
-];
-
-const requiredFileGlobs = ["bin", "src", "scripts", "skill", "README.md", "CHANGELOG.md"];
-const forbiddenPatterns = [
-  { pattern: /@supabase\//, message: "CLI package must not import Supabase SDKs." },
-  { pattern: /@clerk\//, message: "CLI package must not import Clerk SDKs." },
-  { pattern: /src\/server|server\/gmc|server-only/, message: "CLI package must not import server-only app code." },
-  { pattern: /SUPABASE_[A-Z0-9_]*|CLERK_[A-Z0-9_]*|STRIPE_[A-Z0-9_]*/, message: "CLI package must not reference server secret environment variables." }
-];
-
-const sourceFiles = [
-  "bin/gmc.mjs",
-  "src/index.js",
-  "src/args.js",
-  "src/browser-login.js",
-  "src/config.js",
-  "src/constants.js",
-  "src/help.js",
-  "src/main.js",
-  "src/output.js",
-  "src/projection.js",
-  "src/requests.js",
-  "src/workflows.js"
-];
-
-const failures = [];
-
-if (packageJson.private === true) {
-  failures.push("packages/gmc-cli/package.json must not have private:true for beta publishing.");
-}
-
-if (packageJson.name !== "@witchpot/gmc") {
-  failures.push(`Unexpected package name: ${packageJson.name}`);
-}
-
-if (packageJson.publishConfig?.access !== "public") {
-  failures.push("publishConfig.access must be public for npm beta-tag publishing.");
-}
-
-for (const binName of ["gmc", "gmcp", "game-market-copilot"]) {
-  if (packageJson.bin?.[binName] !== "bin/gmc.mjs") {
-    failures.push(`bin.${binName} 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}.`);
-  }
-}
-
-for (const file of requiredFiles) {
-  if (!existsSync(path.join(packageDir, file))) {
-    failures.push(`Missing required package file: ${file}`);
-  }
-}
-
-const constantsPath = path.join(packageDir, "src/constants.js");
-const constantsSource = readFileSync(constantsPath, "utf8");
-const versionMatch = constantsSource.match(/CLI_VERSION\s*=\s*"([^"]+)"/);
-if (!versionMatch) {
-  failures.push("src/constants.js must export a string CLI_VERSION.");
-} else if (versionMatch[1] !== packageJson.version) {
-  failures.push(`CLI_VERSION (${versionMatch[1]}) must match package version (${packageJson.version}).`);
-}
-
-const changelog = readFileSync(path.join(packageDir, "CHANGELOG.md"), "utf8");
-if (!changelog.includes(`## ${packageJson.version} -`)) {
-  failures.push(`CHANGELOG.md must include a section for ${packageJson.version}.`);
-}
-
-const skillSource = readFileSync(path.join(packageDir, "skill/gmc-analysis/SKILL.md"), "utf8");
-const skillVersionMatch = skillSource.match(/^\s*version:\s*"?([0-9][0-9A-Za-z.\-]*)"?\s*$/m);
-if (!skillVersionMatch) {
-  failures.push("skill/gmc-analysis/SKILL.md must declare metadata.version in its frontmatter.");
-} else {
-  const skillChangelog = readFileSync(path.join(packageDir, "skill/gmc-analysis/CHANGELOG.md"), "utf8");
-  if (!skillChangelog.includes(`## ${skillVersionMatch[1]} -`)) {
-    failures.push(`skill CHANGELOG.md must include a section for skill version ${skillVersionMatch[1]}.`);
-  }
-}
-
-for (const file of sourceFiles) {
-  const source = readFileSync(path.join(packageDir, file), "utf8");
-  for (const forbidden of forbiddenPatterns) {
-    if (forbidden.pattern.test(source)) {
-      failures.push(`${file}: ${forbidden.message}`);
-    }
-  }
-}
-
-// The skill content-hash manifest (NAK-190) is also enforced by
-// src/skill-manifest.test.js, but release:check/prepublishOnly run WITHOUT
-// the test suite — recheck here so a stale manifest can never reach npm.
-const { buildSkillManifest, MANIFEST_PATH } = await import("./gen-skill-manifest.mjs");
-if (!existsSync(MANIFEST_PATH)) {
-  failures.push("skill/gmc-analysis.manifest.json is missing — run npm run skill:manifest.");
-} else {
-  const committedManifest = JSON.parse(readFileSync(MANIFEST_PATH, "utf8"));
-  const currentManifest = buildSkillManifest();
-  if (
-    committedManifest.contentHash !== currentManifest.contentHash ||
-    committedManifest.version !== currentManifest.version
-  ) {
-    failures.push(
-      "skill/gmc-analysis.manifest.json is stale: bump metadata.version in SKILL.md, run npm run skill:manifest, and re-sync the gmc-agent-skills distribution repo."
-    );
-  }
-}
-
-// The public distribution repo (github.com/witchpot-studio/gmc-agent-skills)
-// mirrors skill/gmc-analysis. When it is checked out as a workspace sibling,
-// a drift between the two is a release blocker — MCP-only users install the
-// skill from that repo and must get the same content the npm package ships.
-const explicitAgentSkillsDir = process.env.GMC_AGENT_SKILLS_DIR;
-const agentSkillsRepo =
-  explicitAgentSkillsDir ?? path.join(packageDir, "..", "..", "..", "gmc-agent-skills");
-const agentSkillsSyncScript = path.join(agentSkillsRepo, "scripts", "sync-from-cli.mjs");
-if (explicitAgentSkillsDir && !existsSync(agentSkillsSyncScript)) {
-  failures.push(
-    `GMC_AGENT_SKILLS_DIR is set but ${agentSkillsSyncScript} does not exist — fix the path or unset the variable.`
-  );
-} else if (existsSync(agentSkillsSyncScript)) {
-  const drift = spawnSync(process.execPath, ["scripts/sync-from-cli.mjs", "--check"], {
-    cwd: agentSkillsRepo,
-    encoding: "utf8",
-    // Pin the canonical source to THIS checkout — the sync script's own
-    // default (../GMC relative to the skills repo) could silently compare
-    // against a different GMC checkout.
-    env: { ...process.env, GMC_REPO_DIR: path.join(packageDir, "..", "..") }
-  });
-  if (drift.status !== 0) {
-    failures.push(
-      `gmc-agent-skills repo has drifted from skill/gmc-analysis — run node scripts/sync-from-cli.mjs there.\n${(drift.stderr || "").trim()}`
-    );
-  }
-}
-
-if (failures.length > 0) {
-  process.stderr.write(`GMC CLI release readiness failed:\n${failures.map((failure) => `- ${failure}`).join("\n")}\n`);
-  process.exit(1);
-}
-
-process.stdout.write(`GMC CLI release readiness ok: ${packageJson.name}@${packageJson.version}\n`);

package/scripts/gen-skill-manifest.mjs

@@ -1,151 +0,0 @@
-#!/usr/bin/env node
-
-// Regenerates skill/gmc-analysis.manifest.json — a content-hash fingerprint
-// of the packaged gmc-analysis skill (SKILL.md + references/ + CHANGELOG.md).
-//
-// Maintainer rule: any time skill/gmc-analysis/** content changes, bump
-// metadata.version in SKILL.md, then run `npm run skill:manifest` (in
-// packages/gmc-cli) to regenerate this manifest, and re-sync the
-// gmc-agent-skills distribution repo (node scripts/sync-from-cli.mjs there).
-// src/skill-manifest.test.js recomputes the same hash on every
-// `npm run test:cli` / `npm run verify` and fails loudly if it no longer
-// matches the committed manifest — this is the drift guard that would have
-// caught the unversioned charts.md changes in PR #18 / PR #43 (NAK-190).
-//
-// The manifest is written OUTSIDE skill/gmc-analysis/ on purpose: that
-// directory is mirrored byte-for-byte into the public gmc-agent-skills
-// distribution repo, and the manifest must never be part of (or affect the
-// hash of) the content it describes.
-
-import { spawnSync } from "node:child_process";
-import { createHash } from "node:crypto";
-import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const packageDir = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
-export const SKILL_DIR = path.join(packageDir, "skill", "gmc-analysis");
-export const MANIFEST_PATH = path.join(packageDir, "skill", "gmc-analysis.manifest.json");
-
-/** List every file under `dir`, as sorted relative POSIX paths. */
-export function listSkillFiles(dir = SKILL_DIR) {
-  const results = [];
-  walk(dir, dir, results);
-  return results.sort();
-}
-
-function walk(root, current, results) {
-  const entries = readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
-  for (const entry of entries) {
-    const abs = path.join(current, entry.name);
-    if (entry.isDirectory()) {
-      walk(root, abs, results);
-    } else if (entry.isFile()) {
-      results.push(path.relative(root, abs).split(path.sep).join("/"));
-    }
-  }
-}
-
-function sha256Hex(buffer) {
-  return createHash("sha256").update(buffer).digest("hex");
-}
-
-/**
- * Hash every file under `dir` and fold the per-file hashes into one
- * top-level sha256 over `relpath\nfilehash\n` lines (sorted, deterministic).
- */
-export function computeSkillContentHash(dir = SKILL_DIR) {
-  const files = listSkillFiles(dir);
-  const digest = createHash("sha256");
-  for (const relPath of files) {
-    const fileHash = sha256Hex(readFileSync(path.join(dir, relPath)));
-    digest.update(`${relPath}\n${fileHash}\n`);
-  }
-  return { contentHash: digest.digest("hex"), files: files.length };
-}
-
-/** Parse metadata.version out of SKILL.md source text; undefined when absent. */
-export function parseSkillVersion(source) {
-  const frontmatter = source.match(/^---\n([\s\S]*?)\n---/);
-  return frontmatter?.[1].match(/^\s*version:\s*"?([0-9][0-9A-Za-z.\-]*)"?\s*$/m)?.[1];
-}
-
-/** Read metadata.version from SKILL.md's YAML frontmatter. */
-export function readSkillManifestVersion(dir = SKILL_DIR) {
-  const version = parseSkillVersion(readFileSync(path.join(dir, "SKILL.md"), "utf8"));
-  if (!version) {
-    throw new Error(`${path.join(dir, "SKILL.md")} must declare metadata.version in its frontmatter.`);
-  }
-  return version;
-}
-
-/** Build the manifest object (version + contentHash + files) for `dir`. */
-export function buildSkillManifest(dir = SKILL_DIR) {
-  const { contentHash, files } = computeSkillContentHash(dir);
-  return { version: readSkillManifestVersion(dir), contentHash, files };
-}
-
-/**
- * Baseline manifest for the version-bump rule. The authoritative baseline is
- * the manifest COMMITTED ON origin/main (read via `git show`, so deleting or
- * hand-editing the local file cannot dodge the rule); the local file is only
- * a fallback for environments where the git baseline is unreadable.
- */
-function baselineSkillManifest() {
-  const result = spawnSync("git", ["show", "origin/main:packages/gmc-cli/skill/gmc-analysis.manifest.json"], {
-    cwd: packageDir,
-    encoding: "utf8"
-  });
-  if (result.status === 0 && typeof result.stdout === "string") {
-    try {
-      return JSON.parse(result.stdout);
-    } catch {
-      // fall through to the local file
-    }
-  }
-  if (existsSync(MANIFEST_PATH)) {
-    try {
-      return JSON.parse(readFileSync(MANIFEST_PATH, "utf8"));
-    } catch {
-      return undefined;
-    }
-  }
-  return undefined;
-}
-
-/**
- * Pure regen-permission rule (unit-tested in src/skill-manifest.test.js).
- * Content that differs from the baseline while keeping the baseline's
- * version is refused: once a version's content is on origin/main, changing
- * content under that version always requires a bump. A differing version
- * (the in-flight bump case, iterated freely within one branch) and a
- * missing baseline (true first generation) are allowed. There is
- * deliberately NO force escape hatch: an override flag would let
- * unversioned content changes reach npm and the public skills repo.
- */
-export function assertRegenAllowed({ baseline, next }) {
-  if (!baseline) return;
-  if (baseline.contentHash === next.contentHash) return;
-  if (baseline.version !== next.version) return;
-  throw new Error(
-    `skill content changed but metadata.version is still ${next.version}, whose content is already fixed by the baseline manifest (origin/main) — bump the version in SKILL.md, then rerun npm run skill:manifest.`
-  );
-}
-
-function main() {
-  const manifest = buildSkillManifest();
-  try {
-    assertRegenAllowed({ baseline: baselineSkillManifest(), next: manifest });
-  } catch (error) {
-    console.error(error.message);
-    process.exit(1);
-  }
-  writeFileSync(MANIFEST_PATH, `${JSON.stringify(manifest, null, 2)}\n`);
-  process.stdout.write(
-    `Wrote ${path.relative(packageDir, MANIFEST_PATH)}: version ${manifest.version}, ${manifest.files} files, contentHash ${manifest.contentHash}\n`
-  );
-}
-
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  main();
-}