@witchpot/gmc 0.1.9 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to the Game Market Copilot CLI will be recorded here.
 
 ## Unreleased
 
+## 0.2.0 - 2026-07-04
+
+- Added workspace game list commands for creating, listing, resolving, and
+  mutating saved cohorts from the CLI.
+- Added saved game lists as a cohort source for agent workflows and evidence
+  packs, including manual-list item notes.
+- Updated packaged schema/help output to include the new list routes and
+  commands.
+
 ## 0.1.9 - 2026-07-03
 
 - Clarified packaged Agent Skill docs so Claude Code uses `gmc skill install`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@witchpot/gmc",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "private": false,
   "description": "Command line tools for Game Market Copilot market research.",
   "license": "UNLICENSED",

package/src/args.js

@@ -56,6 +56,7 @@ function isCommandToken(command, token) {
       "creators",
       "cohort",
       "showcases",
+      "lists",
       "auth",
       "login",
       "logout",
@@ -95,6 +96,9 @@ function isCommandToken(command, token) {
   if (command[0] === "showcases") {
     return ["search", "fit", "patterns"].includes(token);
   }
+  if (command[0] === "lists") {
+    return ["create", "show", "games", "add", "remove", "delete"].includes(token);
+  }
   return false;
 }
 

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.9";
+export const CLI_VERSION = "0.2.0";
 
 export const DEFAULT_API_BASE_URL = "https://gamemarketcopilot.com";
 export const DEFAULT_CONFIG_PATH = path.join(homedir(), ".config", "gmc", "config.json");
@@ -33,6 +33,8 @@ export const SUPPORTED_BETA_COMMANDS = [
   "gmc games topics --source steam <externalId> --json",
   "gmc games compare --source steam <externalId> <externalId...> --focus market --json",
   "gmc games benchmark --source steam --tags <tag_slug[,tag_slug...]> --reviews-min <number> --json",
+  "gmc lists --json",
+  "gmc lists games <id> --json",
   "gmc reviews patterns --source steam --tags <tag_slug[,tag_slug...]> --reviews-min <number> --json",
   "gmc showcases search --query <text> --json",
   "gmc showcases fit --source steam <externalId> --deadline-before <YYYY-MM-DD> --json"
@@ -47,6 +49,7 @@ export const PROVISIONAL_BETA_COMMANDS = [
   "gmc cohort pricing --source steam --tags <tag_slug[,tag_slug...]> --json",
   "gmc cohort compare --source steam --tags <tag_slug[,tag_slug...]> --json",
   "gmc cohort brief --source steam --tags <tag_slug[,tag_slug...]> --json",
+  "gmc cohort brief --source steam --list <id> --json",
   "gmc showcases patterns --source steam --tags <tag_slug[,tag_slug...]> --json"
 ];
 

package/src/help.js

@@ -25,6 +25,10 @@ Usage:
   gmc skill print --format agents-md
   gmc skill status --json
   gmc schema --json
+  gmc lists --json
+  gmc lists create --name <name> --kind manual --json
+  gmc lists games <id> --json
+  gmc lists add <id> --app-ids <appid[,appid...]> --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
@@ -47,6 +51,7 @@ Usage:
   gmc cohort pricing --source steam --tags <tag_slug[,tag_slug...]> --json
   gmc cohort compare --source steam --tags <tag_slug[,tag_slug...]> --json
   gmc cohort brief --source steam --tags <tag_slug[,tag_slug...]> --json
+  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 patterns --source steam --tags <tag_slug[,tag_slug...]> --json

package/src/requests.js

@@ -37,6 +37,80 @@ export function buildRequest(command, options, positional) {
     };
   }
 
+  if (matches(command, ["lists"])) {
+    return {
+      path: "/api/v1/lists",
+      query: {}
+    };
+  }
+
+  if (matches(command, ["lists", "create"])) {
+    const kind = assertListKind(options.kind ?? "manual");
+    return {
+      path: "/api/v1/lists",
+      method: "POST",
+      query: {},
+      body: {
+        name: assertRequiredOption(options.name, "--name"),
+        kind,
+        ...(options.description ? { description: options.description } : {}),
+        ...(kind === "filter" ? { filter: parseJsonOption(options.filter, "--filter") } : {}),
+        ...(options.sort ? { sort: parseJsonOption(options.sort, "--sort") } : {})
+      }
+    };
+  }
+
+  if (matches(command, ["lists", "show"])) {
+    const id = assertListId(positional[0], "gmc lists show <id> --json");
+    return {
+      path: `/api/v1/lists/${encodeURIComponent(id)}`,
+      query: {}
+    };
+  }
+
+  if (matches(command, ["lists", "games"])) {
+    const id = assertListId(positional[0], "gmc lists games <id> --json");
+    return {
+      path: `/api/v1/lists/${encodeURIComponent(id)}/games`,
+      query: pickQuery(options, {
+        limit: "limit",
+        offset: "offset"
+      })
+    };
+  }
+
+  if (matches(command, ["lists", "add"])) {
+    const id = assertListId(positional[0], "gmc lists add <id> --app-ids <ids> --json");
+    return {
+      path: `/api/v1/lists/${encodeURIComponent(id)}/items`,
+      method: "POST",
+      query: {},
+      body: {
+        appids: parseAppIdsOption(options["app-ids"] ?? options.appids),
+        ...(options.note ? { note: options.note } : {})
+      }
+    };
+  }
+
+  if (matches(command, ["lists", "remove"])) {
+    const id = assertListId(positional[0], "gmc lists remove <id> --app-ids <id> --json");
+    const [appid] = parseAppIdsOption(options["app-ids"] ?? options.appids);
+    return {
+      path: `/api/v1/lists/${encodeURIComponent(id)}/items/${encodeURIComponent(String(appid))}`,
+      method: "DELETE",
+      query: {}
+    };
+  }
+
+  if (matches(command, ["lists", "delete"])) {
+    const id = assertListId(positional[0], "gmc lists delete <id> --json");
+    return {
+      path: `/api/v1/lists/${encodeURIComponent(id)}`,
+      method: "DELETE",
+      query: {}
+    };
+  }
+
   if (matches(command, ["games", "search"])) {
     assertSource(options.source);
     return {
@@ -199,11 +273,20 @@ export function buildRequest(command, options, positional) {
     );
     const sentiment = options.sentiment == null ? undefined : assertReviewPatternSentiment(options.sentiment);
     const sampling = buildSamplingOptions(options, DEFAULT_REVIEW_PATTERNS_LIMIT);
-    const query = {
-      sort: "reviews_desc",
-      limit: sampling?.pageLimit ?? DEFAULT_REVIEW_PATTERNS_LIMIT,
-      ...buildGameSearchQuery(options, { includeTotal: false })
-    };
+    const listId = options.list == null ? undefined : assertListId(options.list, "--list <id>");
+    const query = listId
+      ? {
+          list: listId,
+          limit: sampling?.pageLimit ?? DEFAULT_REVIEW_PATTERNS_LIMIT,
+          ...pickQuery(options, {
+            offset: "offset"
+          })
+        }
+      : {
+          sort: "reviews_desc",
+          limit: sampling?.pageLimit ?? DEFAULT_REVIEW_PATTERNS_LIMIT,
+          ...buildGameSearchQuery(options, { includeTotal: false })
+        };
     if (sampling && options.limit == null) query.limit = sampling.pageLimit;
 
     return {
@@ -211,14 +294,14 @@ export function buildRequest(command, options, positional) {
       source: "steam",
       query,
       sampling,
-      countRequest: buildOptionalGameCountRequest(options),
+      countRequest: listId ? undefined : buildOptionalGameCountRequest(options),
       minGames,
       maxTopicsPerGame,
       sentiment,
       topic: options.topic,
       compareBy: isCompare ? String(options.segment ?? "price") : undefined,
       searchRequest: {
-        path: "/api/v1/steam/games",
+        path: listId ? `/api/v1/lists/${encodeURIComponent(listId)}/games` : "/api/v1/steam/games",
         query
       },
       topicQuery: {
@@ -360,6 +443,38 @@ export function buildRequest(command, options, positional) {
 function buildCohortEvidenceRequest({ workflow, evidenceType, sections, options }) {
   assertSource(options.source);
   const sampling = buildSamplingOptions(options, DEFAULT_COHORT_WORKFLOW_LIMIT);
+  if (options.list != null) {
+    const listId = assertListId(options.list, "--list <id>");
+    const query = {
+      list: listId,
+      limit: sampling?.pageLimit ?? DEFAULT_COHORT_WORKFLOW_LIMIT,
+      ...pickQuery(options, {
+        offset: "offset"
+      })
+    };
+    if (sampling && options.limit == null) query.limit = sampling.pageLimit;
+    return {
+      kind: "cohortEvidence",
+      source: "steam",
+      workflow,
+      evidenceType,
+      sections,
+      query,
+      sampling,
+      searchRequest: {
+        path: `/api/v1/lists/${encodeURIComponent(listId)}/games`,
+        query
+      },
+      analysisQuery: sections.length
+        ? {
+            ...pickQuery(options, {
+              locale: "locale"
+            }),
+            sections: sections.join(",")
+          }
+        : undefined
+    };
+  }
   const query = {
     sort: "reviews_desc",
     limit: sampling?.pageLimit ?? DEFAULT_COHORT_WORKFLOW_LIMIT,
@@ -658,6 +773,73 @@ function assertResolveQuery(value) {
   }
 }
 
+function assertRequiredOption(value, optionName) {
+  if (value == null || String(value).trim() === "") {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: `Missing required option ${optionName}`
+    });
+    process.exit(EXIT_USAGE);
+  }
+  return String(value);
+}
+
+function assertListKind(value) {
+  if (value !== "manual" && value !== "filter") {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: "--kind must be manual or filter"
+    });
+    process.exit(EXIT_USAGE);
+  }
+  return value;
+}
+
+function assertListId(value, usage) {
+  if (value == null || String(value).trim() === "") {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: `Missing list id. Usage: ${usage}`
+    });
+    process.exit(EXIT_USAGE);
+  }
+  return String(value);
+}
+
+function parseJsonOption(value, optionName) {
+  if (value == null) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: `${optionName} is required`
+    });
+    process.exit(EXIT_USAGE);
+  }
+  try {
+    const parsed = JSON.parse(String(value));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("expected object");
+    return parsed;
+  } catch {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: `${optionName} must be a JSON object`
+    });
+    process.exit(EXIT_USAGE);
+  }
+}
+
+function parseAppIdsOption(value) {
+  const appids = parseCsvString(assertRequiredOption(value, "--app-ids"))
+    .map((item) => Number(item));
+  if (appids.length === 0 || appids.some((appid) => !Number.isSafeInteger(appid) || appid <= 0)) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: "--app-ids must be a comma-separated list of positive integers"
+    });
+    process.exit(EXIT_USAGE);
+  }
+  return appids;
+}
+
 function assertCompareExternalIds(values) {
   if (values.length < 2) {
     writeJsonError({

package/src/requests.test.js

@@ -119,6 +119,64 @@ test("reviews patterns forwards coverage into the cohort search request", () =>
   assert.equal(request.searchRequest.query.includeTotal, false);
 });
 
+test("lists create builds a POST request body", () => {
+  const request = buildRequestFromArgv([
+    "lists",
+    "create",
+    "--name",
+    "Competitors",
+    "--kind",
+    "manual",
+    "--json"
+  ]);
+
+  assert.equal(request.path, "/api/v1/lists");
+  assert.equal(request.method, "POST");
+  assert.deepEqual(request.body, {
+    name: "Competitors",
+    kind: "manual"
+  });
+});
+
+test("lists add maps comma-separated app ids to item mutation body", () => {
+  const request = buildRequestFromArgv([
+    "lists",
+    "add",
+    "list-1",
+    "--app-ids",
+    "730,570",
+    "--note",
+    "genre refs",
+    "--json"
+  ]);
+
+  assert.equal(request.path, "/api/v1/lists/list-1/items");
+  assert.equal(request.method, "POST");
+  assert.deepEqual(request.body, {
+    appids: [730, 570],
+    note: "genre refs"
+  });
+});
+
+test("cohort brief can use a saved game list as its cohort source", () => {
+  const request = buildRequestFromArgv([
+    "cohort",
+    "brief",
+    "--source",
+    "steam",
+    "--list",
+    "list-1",
+    "--json"
+  ]);
+
+  assert.equal(request.kind, "cohortEvidence");
+  assert.equal(request.searchRequest.path, "/api/v1/lists/list-1/games");
+  assert.deepEqual(request.searchRequest.query, {
+    list: "list-1",
+    limit: "20"
+  });
+});
+
 test("sampled workflows keep exact totals in a separate count request", () => {
   const request = buildRequestFromArgv([
     "games",

package/src/workflows.js

@@ -25,7 +25,11 @@ export async function executeRequestPlan(baseUrl, request, { apiKey }) {
     return executeShowcaseFitRequest(baseUrl, request, { apiKey });
   }
 
-  const response = await fetchJson(createRequestUrl(baseUrl, request), { apiKey });
+  const response = await fetchJson(createRequestUrl(baseUrl, request), {
+    apiKey,
+    method: request.method,
+    body: request.body
+  });
   return request.transform ? request.transform(response) : response;
 }
 
@@ -216,12 +220,12 @@ async function executeShowcaseFitRequest(baseUrl, request, { apiKey }) {
 async function executeSearchPages(baseUrl, searchRequest, sampling, { apiKey }) {
   if (!sampling) {
     return {
-      searches: [await fetchJson(createRequestUrl(baseUrl, searchRequest), { apiKey })],
+      searches: [normalizeSearchEnvelope(await fetchJson(createRequestUrl(baseUrl, searchRequest), { apiKey }))],
       pageErrors: []
     };
   }
 
-  const firstSearch = await fetchJson(createRequestUrl(baseUrl, searchRequest), { apiKey });
+  const firstSearch = normalizeSearchEnvelope(await fetchJson(createRequestUrl(baseUrl, searchRequest), { apiKey }));
   const searches = [firstSearch];
   const pageErrors = [];
   let nextOffset = firstSearch?.pagination?.nextOffset;
@@ -244,8 +248,9 @@ async function executeSearchPages(baseUrl, searchRequest, sampling, { apiKey })
       break;
     }
 
-    searches.push(pageResult.payload);
-    nextOffset = pageResult.payload?.pagination?.nextOffset;
+    const normalizedPage = normalizeSearchEnvelope(pageResult.payload);
+    searches.push(normalizedPage);
+    nextOffset = normalizedPage?.pagination?.nextOffset;
   }
 
   return {
@@ -254,6 +259,18 @@ async function executeSearchPages(baseUrl, searchRequest, sampling, { apiKey })
   };
 }
 
+function normalizeSearchEnvelope(payload) {
+  if (Array.isArray(payload?.data?.games)) {
+    return {
+      ...payload,
+      data: payload.data.games,
+      list: payload.data.list,
+      notes: payload.data.notes
+    };
+  }
+  return payload;
+}
+
 async function fetchOptionalCount(baseUrl, countRequest, { apiKey }) {
   if (!countRequest) return undefined;
   return fetchJson(createRequestUrl(baseUrl, countRequest), { apiKey });
@@ -682,7 +699,8 @@ export function composeCohortEvidencePayload(request, result, options = {}) {
   const searches = Array.isArray(result.searches) ? result.searches : [result.search];
   const searchPageErrors = Array.isArray(result.searchPageErrors) ? result.searchPageErrors : [];
   const analysisResults = Array.isArray(result.analysisResults) ? result.analysisResults : [];
-  const entries = analysisResults.map((entry) => buildCohortEvidenceGame(request, entry));
+  const listNotes = collectListNotes(searches);
+  const entries = analysisResults.map((entry) => buildCohortEvidenceGame(request, entry, listNotes));
   const included = entries.filter((entry) => !entry.skippedReason);
   const skipped = entries
     .filter((entry) => entry.skippedReason)
@@ -737,6 +755,7 @@ export function composeCohortEvidencePayload(request, result, options = {}) {
             releaseDate: entry.releaseDate,
             coverage: entry.coverage,
             tags: entry.tags,
+            ...(entry.listNote ? { listNote: entry.listNote } : {}),
             patternEvidence: entry.patternEvidence
           }
         })),
@@ -760,6 +779,7 @@ export function composeCohortEvidencePayload(request, result, options = {}) {
         releaseDate: entry.releaseDate,
         coverage: entry.coverage,
         tags: entry.tags,
+        ...(entry.listNote ? { listNote: entry.listNote } : {}),
         patternEvidence: entry.patternEvidence
       })),
       skipped
@@ -854,11 +874,16 @@ export function composeShowcaseFitPayload(request, result, options = {}) {
   };
 }
 
-async function fetchJson(url, { apiKey }) {
+async function fetchJson(url, { apiKey, method = "GET", body } = {}) {
   let response;
   try {
     response = await fetch(url, {
-      headers: buildRequestHeaders(apiKey)
+      method,
+      headers: {
+        ...buildRequestHeaders(apiKey),
+        ...(body == null ? {} : { "content-type": "application/json" })
+      },
+      ...(body == null ? {} : { body: JSON.stringify(body) })
     });
   } catch (error) {
     writeJsonError({
@@ -1357,7 +1382,7 @@ function buildReviewPatternSegments(games, segment) {
     }));
 }
 
-function buildCohortEvidenceGame(request, entry) {
+function buildCohortEvidenceGame(request, entry, listNotes = new Map()) {
   const game = entry.game ?? {};
   const externalId = asString(entry.externalId ?? game?.externalId ?? game?.appid);
   const sections = getAnalysisSections(entry.analysis);
@@ -1378,6 +1403,7 @@ function buildCohortEvidenceGame(request, entry) {
     coverage: game?.coverage,
     tags: getRankedTagNames(game).slice(0, 8),
     genres: game?.genres,
+    listNote: lookupListNote(listNotes, game?.appid, externalId),
     analysis: entry.analysis,
     sections,
     patternEvidence,
@@ -1386,6 +1412,23 @@ function buildCohortEvidenceGame(request, entry) {
   };
 }
 
+function collectListNotes(searches) {
+  const notes = new Map();
+  for (const search of searches) {
+    if (!search?.notes || typeof search.notes !== "object") continue;
+    for (const [appid, note] of Object.entries(search.notes)) {
+      if (typeof note === "string" && note.trim()) notes.set(String(appid), note);
+    }
+  }
+  return notes;
+}
+
+function lookupListNote(notes, appid, externalId) {
+  if (!notes?.size) return undefined;
+  const appidKey = appid == null ? undefined : String(appid);
+  return (appidKey ? notes.get(appidKey) : undefined) ?? (externalId ? notes.get(String(externalId)) : undefined);
+}
+
 function buildCohortEvidenceSummary(request, entries, pagination) {
   return {
     sampleSize: entries.length,

package/src/workflows.test.js

@@ -1,7 +1,7 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 
-import { composeBenchmarkPayload, composeCohortEvidencePayload } from "./workflows.js";
+import { composeBenchmarkPayload, composeCohortEvidencePayload, executeRequestPlan } from "./workflows.js";
 
 test("cohort evidence summarizes skipped games by reason", () => {
   const request = {
@@ -105,3 +105,58 @@ test("benchmark attaches exact total only when a count response is supplied", ()
   assert.equal(payload.pagination.total, 123);
   assert.deepEqual(payload.meta.upstreamRequests.map((entry) => entry.kind), ["search", "count"]);
 });
+
+test("executeRequestPlan normalizes list game resolution for cohort workflows", async () => {
+  const originalFetch = globalThis.fetch;
+  const seenUrls = [];
+  globalThis.fetch = async (url) => {
+    seenUrls.push(String(url));
+    if (String(url).includes("/analysis")) {
+      return jsonResponse({
+        data: { appid: 730, sections: {} },
+        meta: { requestId: "analysis_req" }
+      });
+    }
+    return jsonResponse({
+      data: {
+        list: { id: "list-1", name: "Competitors", kind: "manual" },
+        games: [{ appid: 730, externalId: "730", title: "Example", reviews: 100 }],
+        notes: { 730: "Positioning reference" }
+      },
+      pagination: { limit: 20, offset: 0, total: 1, nextOffset: null },
+      meta: { requestId: "list_req", source: "static-fixture" }
+    });
+  };
+
+  try {
+    const payload = await executeRequestPlan("https://gmc.test", {
+      kind: "cohortEvidence",
+      source: "steam",
+      workflow: "cohortTrends",
+      evidenceType: "trends",
+      sections: [],
+      query: { list: "list-1", limit: "20" },
+      searchRequest: {
+        path: "/api/v1/lists/list-1/games",
+        query: { list: "list-1", limit: "20" }
+      }
+    }, { apiKey: "gmck_test" });
+
+    assert.equal(payload.data.cohort.returnedGames, 1);
+    assert.equal(payload.data.cohort.included[0].externalId, "730");
+    assert.equal(payload.data.cohort.included[0].evidence.listNote, "Positioning reference");
+    assert.equal(payload.data.games[0].listNote, "Positioning reference");
+    assert.ok(seenUrls.some((url) => url.includes("/api/v1/lists/list-1/games")));
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+function jsonResponse(payload, status = 200) {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    headers: new Headers({ "content-type": "application/json" }),
+    json: async () => payload
+  };
+}