@witchpot/gmc 0.1.0

package/src/constants.js

@@ -0,0 +1,66 @@
+import { homedir } from "node:os";
+import path from "node:path";
+
+export const EXIT_UNEXPECTED = 1;
+export const EXIT_USAGE = 2;
+export const EXIT_CONFIG = 3;
+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.0";
+
+export const DEFAULT_API_BASE_URL = "https://gamemarketcopilot.com";
+export const DEFAULT_CONFIG_PATH = path.join(homedir(), ".config", "gmc", "config.json");
+
+export const SUPPORTED_BETA_COMMANDS = [
+  "gmc status --json",
+  "gmc auth status --json",
+  "gmc schema --json",
+  "gmc --version",
+  "gmc update --json",
+  "gmc games search --source steam --query <text> --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",
+  "gmc campaigns signals --source steam <externalId> --json",
+  "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 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"
+];
+
+export const PROVISIONAL_BETA_COMMANDS = [
+  "gmc reviews patterns compare --source steam --tags <tag_slug[,tag_slug...]> --segment price --json",
+  "gmc marketing patterns --source steam --tags <tag_slug[,tag_slug...]> --reviews-min <number> --json",
+  "gmc marketing timing --source steam --tags <tag_slug[,tag_slug...]> --json",
+  "gmc creators patterns --source steam --tags <tag_slug[,tag_slug...]> --json",
+  "gmc cohort trends --source steam --tags <tag_slug[,tag_slug...]> --json",
+  "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 showcases patterns --source steam --tags <tag_slug[,tag_slug...]> --json"
+];
+
+export const COMPARE_FOCUSES = ["overview", "market", "reviews", "marketing", "audience", "showcases"];
+export const COMPARE_FOCUS_SECTIONS = {
+  overview: [],
+  market: [],
+  reviews: ["reviews"],
+  marketing: ["marketing", "creators", "media"],
+  audience: ["reviews", "coverage", "creators"],
+  showcases: ["showcases"]
+};
+
+export const DEFAULT_BENCHMARK_LIMIT = "20";
+export const DEFAULT_CAMPAIGN_SIGNALS_LIMIT = "30";
+export const DEFAULT_COHORT_WORKFLOW_LIMIT = "20";
+export const DEFAULT_RESOLVE_LIMIT = "10";
+export const DEFAULT_REVIEW_PATTERNS_LIMIT = "20";
+export const DEFAULT_REVIEW_PATTERNS_MAX_TOPICS_PER_GAME = "10";
+export const DEFAULT_REVIEW_PATTERNS_MIN_GAMES = "3";
+export const DEFAULT_SHOWCASE_FIT_LIMIT = "25";
+export const MAX_SAMPLE_PAGES = 10;
+export const MAX_SAMPLE_SIZE = 500;

package/src/help.js

@@ -0,0 +1,60 @@
+import {
+  CLI_VERSION,
+  PROVISIONAL_BETA_COMMANDS,
+  SUPPORTED_BETA_COMMANDS
+} from "./constants.js";
+
+export function printHelp() {
+  process.stdout.write(`Game Market Copilot CLI
+
+Version:
+  ${CLI_VERSION}
+
+Usage:
+  gmc --version
+  gmc status --json
+  gmc auth status --json
+  gmc login
+  gmc login --no-open
+  gmc login --api-key <key>
+  gmc logout
+  gmc update --json
+  gmc config get --json
+  gmc config set apiBaseUrl <url>
+  gmc schema --json
+  gmc games search --source steam --query <text> --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
+  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 campaigns signals --source steam <externalId> --json
+  gmc games compare --source steam <externalId> <externalId...> --focus market --json
+  gmc games topics --source steam <externalId> --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
+  gmc marketing timing --source steam --tags <tag_slug[,tag_slug...]> --json
+  gmc creators patterns --source steam --tags <tag_slug[,tag_slug...]> --json
+  gmc cohort trends --source steam --tags <tag_slug[,tag_slug...]> --json
+  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 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
+
+Supported beta commands:
+${SUPPORTED_BETA_COMMANDS.map((command) => `  ${command}`).join("\n")}
+
+Provisional beta commands:
+${PROVISIONAL_BETA_COMMANDS.map((command) => `  ${command}`).join("\n")}
+
+Environment:
+  GMC_API_BASE_URL  Defaults to https://gamemarketcopilot.com
+  GMC_API_KEY       Workspace API key, sent only as an Authorization header
+  GMC_CLI_CREDENTIAL Browser-login CLI credential, sent only as an Authorization header
+  GMC_CONFIG_PATH   Optional JSON config with apiBaseUrl and apiKey
+`);
+}

package/src/main.js

@@ -0,0 +1,141 @@
+import { pathToFileURL } from "node:url";
+import {
+  CLI_PACKAGE_NAME,
+  CLI_VERSION,
+  EXIT_API,
+  EXIT_CONFIG,
+  EXIT_UNEXPECTED,
+  EXIT_USAGE
+} from "./constants.js";
+import { matches, parseArgs } from "./args.js";
+import { handleLocalCommand, loadConfig, parseBaseUrl } from "./config.js";
+import { printHelp } from "./help.js";
+import { writeJsonError } from "./output.js";
+import { applyOutputProjection } from "./projection.js";
+import { buildRequest } from "./requests.js";
+import { executeRequestPlan } from "./workflows.js";
+
+export async function main(argv = process.argv.slice(2)) {
+  const { command, options, positional } = parseArgs(argv);
+
+  if (options.version || matches(command, ["version"])) {
+    if (options.json) {
+      process.stdout.write(`${JSON.stringify({
+        data: {
+          name: CLI_PACKAGE_NAME,
+          version: CLI_VERSION
+        }
+      }, null, 2)}\n`);
+    } else {
+      process.stdout.write(`gmc ${CLI_VERSION}\n`);
+    }
+    process.exit(0);
+  }
+
+  if (options.help || (command.length === 0 && positional.length === 0)) {
+    printHelp();
+    process.exit(0);
+  }
+
+  const config = loadConfig();
+  const localOutput = await handleLocalCommand(command, options, positional, config);
+  if (localOutput) {
+    process.stdout.write(`${JSON.stringify(applyOutputProjection(localOutput, {
+      fields: options.fields,
+      preset: options.preset
+    }), null, 2)}\n`);
+    process.exit(0);
+  }
+
+  const baseUrl = parseBaseUrl(config.apiBaseUrl);
+  const apiKey = config.apiKey;
+  const request = buildRequest(command, options, positional);
+  if (!request) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: `Unknown command: ${[...command, ...positional].join(" ")}`
+    });
+    process.exit(EXIT_USAGE);
+  }
+
+  if (request.requiresApiKey && !apiKey) {
+    writeJsonError({
+      code: "CLI_MISSING_CONFIG",
+      message: "GMC_API_KEY or GMC_CLI_CREDENTIAL is required for this command"
+    });
+    process.exit(EXIT_CONFIG);
+  }
+
+  const response = await executeRequestPlan(baseUrl, request, { apiKey });
+  const payload = matches(command, ["auth", "status"])
+    ? enrichAuthStatusOutput(response, config)
+    : response;
+  const output = applyOutputProjection(payload, {
+    fields: options.fields,
+    preset: options.preset,
+    request
+  });
+
+  process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+}
+
+export function runCliEntryPoint() {
+  main().catch((error) => {
+    writeJsonError({
+      code: "CLI_UNEXPECTED_ERROR",
+      message: error instanceof Error ? error.message : "Unexpected CLI failure"
+    });
+    process.exit(EXIT_UNEXPECTED);
+  });
+}
+
+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;
+  }
+
+  return {
+    ...payload,
+    data: {
+      ...payload.data,
+      cli: buildCliAuthStatus(config)
+    }
+  };
+}
+
+export function buildCliAuthStatus(config) {
+  const authMode = getCliCredentialAuthMode(config);
+  return {
+    apiBaseUrl: config.apiBaseUrl,
+    configPath: config.configPath,
+    authMode,
+    credential: config.apiKey
+      ? {
+          type: authMode,
+          prefix: getApiKeyPrefix(config.apiKey)
+        }
+      : {
+          type: "none"
+        },
+    sources: config.sources
+  };
+}
+
+function getCliCredentialAuthMode(config) {
+  if (!config.apiKey) return "anonymous";
+  if (config.authMode === "cli_credential" || config.fileConfig?.authMode === "cli_credential") {
+    return "cli_credential";
+  }
+  if (String(config.apiKey).startsWith("gmcc_")) return "cli_credential";
+  return "api_key";
+}
+
+function getApiKeyPrefix(apiKey) {
+  return String(apiKey).slice(0, 12);
+}
+
+export { EXIT_API, EXIT_CONFIG, EXIT_UNEXPECTED, EXIT_USAGE };

package/src/output.js

@@ -0,0 +1,3 @@
+export function writeJsonError(error) {
+  process.stdout.write(`${JSON.stringify({ error }, null, 2)}\n`);
+}

package/src/projection.js

@@ -0,0 +1,163 @@
+import { EXIT_USAGE } from "./constants.js";
+import { writeJsonError } from "./output.js";
+
+export function applyFieldsProjection(payload, rawFields, label = "fields") {
+  if (rawFields == null || rawFields === "") return payload;
+
+  const fields = parseFields(rawFields);
+  if (fields.length === 0) {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: "--fields must include at least one field"
+    });
+    process.exit(EXIT_USAGE);
+  }
+
+  if (!payload || typeof payload !== "object" || !("data" in payload)) {
+    return projectValue(payload, fields);
+  }
+
+  const projection = projectValueWithMatches(payload.data, fields);
+  const missingFields = label === "fields"
+    ? fields.filter((field) => {
+        const pathParts = field.split(".").map((part) => part.trim()).filter(Boolean);
+        const normalizedPathParts = normalizeDataPath(pathParts);
+        return normalizedPathParts != null && !projection.matchedFields.has(field);
+      })
+    : [];
+
+  return {
+    ...payload,
+    data: projection.value,
+    warnings: [
+      ...(Array.isArray(payload.warnings) ? payload.warnings : []),
+      `${label} was applied client-side by the gmc CLI: ${fields.join(",")}`,
+      ...(missingFields.length
+        ? [`${label} were not found in data by the gmc CLI: ${missingFields.join(",")}`]
+        : [])
+    ]
+  };
+}
+
+export function applyOutputProjection(payload, { fields, preset, request } = {}) {
+  if (fields != null && fields !== "") return applyFieldsProjection(payload, fields);
+  if (preset == null || preset === "") return payload;
+
+  const presetFields = resolvePresetFields(preset, request);
+  return applyFieldsProjection(payload, presetFields, `preset ${preset}`);
+}
+
+function resolvePresetFields(preset, request) {
+  if (preset !== "summary") {
+    writeJsonError({
+      code: "CLI_USAGE_ERROR",
+      message: "--preset must be one of: summary"
+    });
+    process.exit(EXIT_USAGE);
+  }
+
+  if (request?.kind === "reviewPatterns") return "cohort,summary,patterns";
+  if (request?.kind === "benchmark") return "summary,sampledSummary";
+  if (request?.kind === "cohortEvidence") return "cohort,summary,patterns,segments";
+
+  writeJsonError({
+    code: "CLI_USAGE_ERROR",
+    message: "--preset summary is supported for gmc reviews patterns, gmc games benchmark, and gmc cohort/pattern workflows"
+  });
+  process.exit(EXIT_USAGE);
+}
+
+function parseFields(rawFields) {
+  return String(rawFields)
+    .split(",")
+    .map((field) => field.trim())
+    .filter(Boolean);
+}
+
+function projectValue(value, fields) {
+  if (Array.isArray(value)) {
+    return value.map((item) => projectObject(item, fields));
+  }
+  return projectObject(value, fields);
+}
+
+function projectValueWithMatches(value, fields) {
+  const matchedFields = new Set();
+  const projected = Array.isArray(value)
+    ? value.map((item) => projectObject(item, fields, matchedFields))
+    : projectObject(value, fields, matchedFields);
+
+  return {
+    value: projected,
+    matchedFields
+  };
+}
+
+function projectObject(value, fields, matchedFields) {
+  if (!value || typeof value !== "object") return value;
+
+  const projected = {};
+  for (const field of fields) {
+    const pathParts = field.split(".").map((part) => part.trim()).filter(Boolean);
+    const normalizedPathParts = normalizeDataPath(pathParts);
+    if (normalizedPathParts == null) continue;
+    if (normalizedPathParts.length === 0) return value;
+
+    const fieldValue = projectPath(value, normalizedPathParts);
+    if (fieldValue !== undefined) {
+      matchedFields?.add(field);
+      mergeProjected(projected, fieldValue);
+    }
+  }
+  return projected;
+}
+
+function normalizeDataPath(pathParts) {
+  if (pathParts.length === 0) return null;
+  if (!pathParts.every(isSafePathPart)) return null;
+  if (pathParts[0] === "data") return pathParts.slice(1);
+  if (["error", "meta", "pagination", "warnings"].includes(pathParts[0])) return null;
+  return pathParts;
+}
+
+function isSafePathPart(part) {
+  return part !== "__proto__" && part !== "prototype" && part !== "constructor";
+}
+
+function projectPath(value, pathParts) {
+  if (value == null) return undefined;
+  if (pathParts.length === 0) return value;
+
+  if (Array.isArray(value)) {
+    const items = value
+      .map((item) => projectPath(item, pathParts))
+    return items.some((item) => item !== undefined) ? items : undefined;
+  }
+
+  if (typeof value !== "object") return undefined;
+  const [head, ...tail] = pathParts;
+  const child = projectPath(value[head], tail);
+  return child === undefined ? undefined : { [head]: child };
+}
+
+function mergeProjected(target, source) {
+  for (const [key, value] of Object.entries(source)) {
+    target[key] = mergeValue(target[key], value);
+  }
+  return target;
+}
+
+function mergeValue(existing, incoming) {
+  if (incoming === undefined) return existing;
+  if (Array.isArray(existing) && Array.isArray(incoming)) {
+    return incoming.map((item, index) => mergeValue(existing[index], item));
+  }
+  if (isPlainObject(existing) && isPlainObject(incoming)) {
+    return mergeProjected({ ...existing }, incoming);
+  }
+  return incoming;
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}