@witchpot/gmc 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to the Game Market Copilot CLI will be recorded here.
+
+## 0.1.0 - Unreleased
+
+- Added the initial JSON-first `gmc` command set for status, schema, Steam game
+  search, resolve, detail, analysis, topics, compare, benchmark, review
+  patterns, Showcase search, and Showcase fit workflows.
+- Added API-key login, logout, local config, environment-variable config, field
+  projection, and summary presets.
+- Added a non-mutating `gmc update --json` command that reports the current
+  version and closed-beta npm update commands.
+- Added the common evidence-pack shape for CLI-composed workflows.
+- Marked the first closed-beta command set as supported and broader cohort
+  workflows as provisional.
+- Prepared the package for public npm beta-tag publishing with metadata and
+  server-boundary release checks, packed-tarball smoke validation, and
+  `publish:beta` plus `publish:beta:dry-run` scripts.

package/README.md

@@ -0,0 +1,118 @@
+# Game Market Copilot CLI
+
+`gmc` is the JSON-first command line client for Game Market Copilot. It wraps
+stable `/api/v1` endpoints so Codex, Claude Code, and other agents can answer
+market questions from bounded API evidence instead of reading Supabase directly.
+
+## 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:
+
+```bash
+npm run gmc -- --help
+```
+
+The package name for beta distribution is `@witchpot/gmc` with the
+`gmc` binary. Before publishing a beta build, run:
+
+```bash
+npm run gmc:release:check
+npm run gmc:publish:beta:dry-run
+npm run gmc:publish:beta
+```
+
+Closed-beta setup details live in
+[`docs/closed-beta-onboarding.md`](../../docs/closed-beta-onboarding.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
+data.
+
+## Auth
+
+Interactive browser login is the preferred local setup path:
+
+```bash
+gmc login
+gmc auth status --json
+```
+
+Use API-key auth for CI, headless agents, or restricted browser environments:
+
+```bash
+gmc login --api-key <display-once workspace API key> --api-base-url https://gamemarketcopilot.com
+gmc auth status --json
+```
+
+Non-interactive agents and CI can use environment variables:
+
+```bash
+export GMC_API_BASE_URL=https://gamemarketcopilot.com
+export GMC_API_KEY=<display-once workspace API key>
+# or
+export GMC_CLI_CREDENTIAL=<display-once browser-login CLI credential>
+gmc auth status --json
+```
+
+The CLI never prints the raw key or credential after login. Status and config output show only
+a non-secret prefix.
+
+## First Queries
+
+```bash
+gmc schema --json
+gmc update --json
+gmc games resolve --source steam --query Timberborn --json
+gmc games detail --source steam 1062090 --json
+gmc campaigns signals --source steam 1062090 --json
+gmc games benchmark --source steam --tags city_builder,automation --reviews-min 1000 --preset summary --json
+gmc showcases fit --source steam 1062090 --json
+```
+
+Preserve `meta.requestId`, `meta.entitlements`, `warnings`, and `pagination`
+when using output in agent answers.
+
+## Supported Beta Commands
+
+- `gmc status`
+- `gmc auth status`
+- `gmc schema`
+- `gmc games search`
+- `gmc games resolve`
+- `gmc games detail`
+- `gmc games analysis`
+- `gmc campaigns signals`
+- `gmc games topics`
+- `gmc games compare`
+- `gmc games benchmark`
+- `gmc reviews patterns`
+- `gmc showcases search`
+- `gmc showcases fit`
+
+Other cohort, marketing, creator, pricing, and showcase-pattern commands are
+available as provisional evidence packs. Their names and output fields may still
+change before the closed-beta contract is frozen.
+
+## Updates
+
+`gmc update --json` reports the current CLI version and the package-manager
+commands to use after closed-beta npm distribution is available. It does not
+mutate the local install yet.
+
+## Beta Smoke
+
+Run the beta smoke script with a production-like API and beta credential:
+
+```bash
+GMC_API_BASE_URL=https://gamemarketcopilot.com \
+GMC_API_KEY=<display-once workspace API key> \
+npm run gmc:smoke:beta
+```
+
+The script validates the JSON envelope for status, schema, title resolution,
+detail, benchmark, and Showcase fit commands. It prints a redacted summary with
+request IDs, warning counts, pagination presence, and entitlement metadata
+presence. Non-JSON responses include HTTP status, content type, and request path
+so Cloudflare Access interstitials can be diagnosed without printing HTML.

package/bin/gmc.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+import { isCliEntryPoint, 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();
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@witchpot/gmc",
+  "version": "0.1.0",
+  "private": false,
+  "description": "JSON-first CLI for Game Market Copilot API and agent workflows.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/witchpot/game-market-copilot.git",
+    "directory": "packages/gmc-cli"
+  },
+  "homepage": "https://gamemarketcopilot.com",
+  "bugs": {
+    "url": "https://gamemarketcopilot.com"
+  },
+  "type": "module",
+  "bin": {
+    "gmc": "bin/gmc.mjs"
+  },
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "scripts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "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",
+    "pack:check": "node scripts/smoke-pack.mjs --dry-run",
+    "smoke:pack": "node scripts/smoke-pack.mjs",
+    "publish:beta:dry-run": "npm publish --tag beta --access public --dry-run --cache /tmp/gmc-npm-cache",
+    "publish:beta": "npm publish --tag beta --access public --cache /tmp/gmc-npm-cache"
+  }
+}

package/scripts/check-release-readiness.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+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/main.js",
+  "src/requests.js",
+  "src/workflows.js",
+  "README.md",
+  "CHANGELOG.md"
+];
+
+const requiredFileGlobs = ["bin", "src", "scripts", "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/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.");
+}
+
+if (packageJson.bin?.gmc !== "bin/gmc.mjs") {
+  failures.push("bin.gmc must point to bin/gmc.mjs.");
+}
+
+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}.`);
+}
+
+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}`);
+    }
+  }
+}
+
+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/smoke-beta.mjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+const packageDir = path.resolve(new URL("..", import.meta.url).pathname);
+const cliBin = path.join(packageDir, "bin", "gmc.mjs");
+const workDir = mkdtempSync(path.join(tmpdir(), "gmc-cli-beta-smoke-"));
+const configPath = path.join(workDir, "config.json");
+const allowApiErrors = process.argv.includes("--allow-api-errors");
+
+const smokeCommands = [
+  {
+    name: "version",
+    args: ["--version", "--json"],
+    validate: (payload) => requireFields(payload, ["data.name", "data.version"])
+  },
+  {
+    name: "update",
+    args: ["update", "--json"],
+    validate: (payload) => requireFields(payload, ["data.currentVersion", "data.commands.npmGlobal"])
+  },
+  {
+    name: "auth status",
+    args: ["auth", "status", "--json"],
+    validate: (payload) => requireSuccessEnvelope(payload, ["data.caller", "data.cli"])
+  },
+  {
+    name: "schema",
+    args: ["schema", "--json"],
+    validate: (payload) => requireSuccessEnvelope(payload, ["data.version", "data.cliCommands"])
+  },
+  {
+    name: "resolve Timberborn",
+    args: ["games", "resolve", "--source", "steam", "--query", "Timberborn", "--json"],
+    validate: (payload) => requireComposedEnvelope(payload, ["data.candidates", "data.resolution"])
+  },
+  {
+    name: "detail Timberborn",
+    args: ["games", "detail", "--source", "steam", "1062090", "--json"],
+    validate: (payload) => requireSuccessEnvelope(payload, ["data.title"])
+  },
+  {
+    name: "benchmark city builder automation",
+    args: [
+      "games",
+      "benchmark",
+      "--source",
+      "steam",
+      "--tags",
+      "city_builder,automation",
+      "--reviews-min",
+      "1000",
+      "--preset",
+      "summary",
+      "--json"
+    ],
+    validate: (payload) => requireComposedEnvelope(payload, ["data.summary"])
+  },
+  {
+    name: "showcase fit Timberborn",
+    args: ["showcases", "fit", "--source", "steam", "1062090", "--json"],
+    validate: (payload) => requireComposedEnvelope(payload, ["data.matches", "data.summary"])
+  }
+];
+
+try {
+  const results = smokeCommands.map(runSmokeCommand);
+  const failed = results.filter((result) => result.status === "failed");
+  const summary = {
+    ok: failed.length === 0,
+    apiBaseUrl: process.env.GMC_API_BASE_URL || "https://gamemarketcopilot.com",
+    auth: {
+      apiKeyConfigured: Boolean(process.env.GMC_API_KEY)
+    },
+    allowApiErrors,
+    commands: results
+  };
+
+  process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+  if (failed.length > 0) process.exit(1);
+} finally {
+  rmSync(workDir, { recursive: true, force: true });
+}
+
+function runSmokeCommand(command) {
+  const result = spawnSync(process.execPath, [cliBin, ...command.args], {
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      GMC_CONFIG_PATH: configPath
+    }
+  });
+
+  const payload = parseJson(result.stdout);
+  if (!payload.ok) {
+    return {
+      name: command.name,
+      status: "failed",
+      exitCode: result.status,
+      error: `stdout was not valid JSON: ${payload.error}`
+    };
+  }
+
+  if (payload.value?.error) {
+    const stable = isStableError(payload.value.error);
+    const status = allowApiErrors && stable ? "api_error_allowed" : "failed";
+    return {
+      name: command.name,
+      status,
+      exitCode: result.status,
+      error: summarizeError(payload.value.error)
+    };
+  }
+
+  if (result.status !== 0) {
+    return {
+      name: command.name,
+      status: "failed",
+      exitCode: result.status,
+      error: "command exited non-zero without a structured error envelope"
+    };
+  }
+
+  const validation = command.validate(payload.value);
+  if (!validation.ok) {
+    return {
+      name: command.name,
+      status: "failed",
+      exitCode: result.status,
+      error: validation.error
+    };
+  }
+
+  return {
+    name: command.name,
+    status: "passed",
+    exitCode: result.status,
+    requestId: payload.value.meta?.requestId,
+    upstreamRequestIds: Array.isArray(payload.value.meta?.upstreamRequests)
+      ? payload.value.meta.upstreamRequests.map((request) => request?.requestId).filter(Boolean)
+      : undefined,
+    warnings: Array.isArray(payload.value.warnings) ? payload.value.warnings.length : 0,
+    hasPagination: Boolean(payload.value.pagination),
+    hasEntitlements: Boolean(payload.value.meta?.entitlements),
+    hasUpstreamEntitlements: Array.isArray(payload.value.meta?.upstreamRequests)
+      ? payload.value.meta.upstreamRequests.some((request) => request?.entitlements)
+      : undefined
+  };
+}
+
+function parseJson(stdout) {
+  try {
+    return {
+      ok: true,
+      value: JSON.parse(stdout)
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : "unknown parse error"
+    };
+  }
+}
+
+function requireSuccessEnvelope(payload, fields) {
+  const base = requireFields(payload, ["data", "meta.requestId", ...fields]);
+  if (!base.ok) return base;
+  return {
+    ok: true
+  };
+}
+
+function requireComposedEnvelope(payload, fields) {
+  const base = requireFields(payload, ["data", "meta.requestId", "meta.upstreamRequests", ...fields]);
+  if (!base.ok) return base;
+  if (!Array.isArray(payload.meta.upstreamRequests) || payload.meta.upstreamRequests.length === 0) {
+    return {
+      ok: false,
+      error: "meta.upstreamRequests must include at least one request"
+    };
+  }
+  return {
+    ok: true
+  };
+}
+
+function requireFields(payload, fields) {
+  const missing = fields.filter((field) => getPath(payload, field) == null);
+  if (missing.length > 0) {
+    return {
+      ok: false,
+      error: `missing fields: ${missing.join(", ")}`
+    };
+  }
+  return {
+    ok: true
+  };
+}
+
+function getPath(value, pathName) {
+  return pathName.split(".").reduce((current, part) => current?.[part], value);
+}
+
+function isStableError(error) {
+  return Boolean(error && typeof error.code === "string" && typeof error.message === "string");
+}
+
+function summarizeError(error) {
+  return {
+    code: error.code,
+    message: error.message,
+    requestId: error.requestId,
+    status: error.status,
+    contentType: error.contentType,
+    path: error.path
+  };
+}

package/scripts/smoke-pack.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const packageDir = path.resolve(new URL("..", import.meta.url).pathname);
+const dryRunOnly = process.argv.includes("--dry-run");
+const workDir = mkdtempSync(path.join(tmpdir(), "gmc-cli-pack-"));
+const npmCache = path.join(workDir, "npm-cache");
+
+try {
+  run("npm", ["pack", "--dry-run"], {
+    cwd: packageDir,
+    env: {
+      npm_config_cache: npmCache
+    }
+  });
+
+  if (dryRunOnly) process.exit(0);
+
+  const packResult = run("npm", ["pack", "--json", "--pack-destination", workDir], {
+    cwd: packageDir,
+    env: {
+      npm_config_cache: npmCache
+    },
+    capture: true
+  });
+  const packed = JSON.parse(packResult.stdout);
+  const filename = packed?.[0]?.filename;
+  if (!filename) throw new Error("npm pack did not return a tarball filename");
+
+  const projectDir = path.join(workDir, "project");
+  run("npm", ["init", "-y"], {
+    cwd: workDir,
+    env: {
+      npm_config_cache: npmCache
+    }
+  });
+  run("npm", ["install", path.join(workDir, filename)], {
+    cwd: workDir,
+    env: {
+      npm_config_cache: npmCache
+    }
+  });
+
+  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 } });
+} finally {
+  rmSync(workDir, { recursive: true, force: true });
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd,
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      npm_config_dry_run: "false",
+      ...(options.env ?? {})
+    },
+    stdio: options.capture ? ["ignore", "pipe", "pipe"] : "inherit"
+  });
+
+  if (result.status !== 0) {
+    const stderr = result.stderr ? `\n${result.stderr}` : "";
+    throw new Error(`${command} ${args.join(" ")} failed with exit code ${result.status}${stderr}`);
+  }
+
+  return result;
+}