@puzzmo/cli 1.0.51 → 1.0.52

package/src/commands/changed.ts

@@ -0,0 +1,239 @@
+import { execFileSync } from "node:child_process"
+import fs from "node:fs"
+import path from "node:path"
+
+import { findTokensForTeam, getTokens, resolveServerForTeam, sourceToURL } from "../util/config.js"
+import { type DiscoveredGame, discoverGames } from "../util/discoverGames.js"
+import { fetchTeamGameVersions, type GameVersions } from "../queries/gameRuntimes.js"
+
+/** Which deployed build slot to diff against: the team's latest build, the staged next, or the previous one. */
+export type ChangedAgainst = "latest" | "next" | "previous"
+
+export type ChangedOptions = {
+  json?: boolean
+  list?: boolean
+  matrix?: boolean
+  ref?: string
+  against?: ChangedAgainst
+  includeUncommitted?: boolean
+}
+
+type GameStatus = "changed" | "unchanged" | "new"
+
+type ChangedEntry = {
+  slug: string
+  displayName: string
+  teamID: string
+  dir: string
+  baseSha: string | null
+  ref: string
+  status: GameStatus
+  changedFiles: number
+}
+
+type EvalResult = { entry: ChangedEntry } | { error: string }
+
+/** Reports which discovered games changed since their last deployed build, scoped per game folder. */
+export const changed = async (dir: string, options: ChangedOptions = {}) => {
+  const { json = false, list = false, matrix = false, against = "latest", includeUncommitted = false } = options
+
+  if (getTokens().length === 0) {
+    console.error("Not logged in. Run `puzzmo login <token>` or set PUZZMO_TOKEN.")
+    process.exit(1)
+  }
+
+  const rootDir = path.resolve(dir)
+  if (!fs.existsSync(rootDir)) {
+    console.error(`Directory not found: ${dir}`)
+    process.exit(1)
+  }
+
+  const repoRoot = getRepoRoot(rootDir)
+  if (!repoRoot) {
+    console.error(`Not a git repository: ${rootDir}`)
+    process.exit(1)
+  }
+
+  const ref = options.ref || "HEAD"
+  const refSha = revParseShort(ref, repoRoot)
+  if (!refSha) {
+    console.error(`Could not resolve git ref: ${ref}`)
+    process.exit(1)
+  }
+
+  const { games, errors: discoveryErrors } = await discoverGames(rootDir, { requireDist: false })
+  if (!games.length && !discoveryErrors.length) {
+    console.error(`No puzzmo.json files found under ${rootDir}`)
+    process.exit(1)
+  }
+
+  const hardErrors = discoveryErrors.map((err) => `${err.slug ?? path.relative(rootDir, err.puzzmoJsonPath)}: ${err.errors.join("; ")}`)
+
+  const teamVersions = new Map<string, Promise<Map<string, GameVersions>>>()
+  const results = await Promise.all(
+    games.map((game) => evaluateGame(game, { repoRoot, ref, refSha, against, includeUncommitted, teamVersions })),
+  )
+  const report: ChangedEntry[] = []
+  for (const result of results) {
+    if ("entry" in result) report.push(result.entry)
+    else hardErrors.push(result.error)
+  }
+
+  const buildable = report.filter((entry) => entry.status !== "unchanged")
+
+  if (json) console.log(JSON.stringify(report, null, 2))
+  else if (matrix) console.log(JSON.stringify({ include: buildable.map((entry) => ({ dir: entry.dir, slug: entry.slug })) }))
+  else if (list) for (const entry of buildable) console.log(entry.dir)
+  else if (report.length) printTable(report)
+  else if (!hardErrors.length) console.log(`No puzzmo.json files found under ${rootDir}`)
+
+  if (hardErrors.length) {
+    console.error(`\n${hardErrors.length} error${hardErrors.length === 1 ? "" : "s"}:`)
+    for (const message of hardErrors) console.error(`  ${message}`)
+    process.exit(1)
+  }
+}
+
+type EvalContext = {
+  repoRoot: string
+  ref: string
+  refSha: string
+  against: ChangedAgainst
+  includeUncommitted: boolean
+  // Memoizes the per-team runtime fetch so games sharing a team only hit the API once.
+  teamVersions: Map<string, Promise<Map<string, GameVersions>>>
+}
+
+/** Resolves one game's deployed SHA and diffs it against the ref. Returns either a report entry or a hard error. */
+const evaluateGame = async (game: DiscoveredGame, ctx: EvalContext): Promise<EvalResult> => {
+  const { slug, teamID } = game.puzzmoFile.game
+  const dir = toPosix(path.relative(ctx.repoRoot, game.puzzmoJsonDir)) || "."
+
+  const credential = await resolveServerForTeam(teamID)
+  if (!credential) {
+    const matches = findTokensForTeam(teamID)
+    const message =
+      matches.length === 0
+        ? `No saved token for team ${teamID}. Run \`puzzmo login <token>\`.`
+        : `Token for team ${teamID} is registered against ${matches.map((m) => m.source).join(", ")} but none of those servers are reachable.`
+    return { error: `${slug}: ${message}` }
+  }
+
+  let versions: GameVersions | undefined
+  try {
+    versions = (await getTeamVersions(teamID, credential, ctx)).get(slug)
+  } catch (e) {
+    return { error: `${slug}: ${e instanceof Error ? e.message : String(e)}` }
+  }
+
+  const baseSha = pickBaseSha(versions ?? null, ctx.against)
+
+  // Never deployed (or the chosen slot is empty) — nothing to diff against, so it's new and buildable.
+  if (!baseSha) return { entry: makeEntry(game, dir, null, ctx.refSha, "new", 0) }
+
+  // The deployed commit has to exist locally or we can't diff — fail loudly rather than guessing.
+  if (!commitExists(baseSha, ctx.repoRoot))
+    return {
+      error: `${slug}: deployed commit ${baseSha} not found locally. Fetch full git history (e.g. actions/checkout fetch-depth: 0).`,
+    }
+
+  const changedFiles = countChanges(baseSha, ctx.ref, game.puzzmoJsonDir, ctx.includeUncommitted)
+  return { entry: makeEntry(game, dir, baseSha, ctx.refSha, changedFiles > 0 ? "changed" : "unchanged", changedFiles) }
+}
+
+const makeEntry = (
+  game: DiscoveredGame,
+  dir: string,
+  baseSha: string | null,
+  ref: string,
+  status: GameStatus,
+  changedFiles: number,
+): ChangedEntry => ({
+  slug: game.puzzmoFile.game.slug,
+  displayName: game.puzzmoFile.game.displayName,
+  teamID: game.puzzmoFile.game.teamID,
+  dir,
+  baseSha,
+  ref,
+  status,
+  changedFiles,
+})
+
+/** Fetches a team's per-game runtime SHAs once, memoizing the in-flight promise so concurrent games share the call. */
+const getTeamVersions = (
+  teamID: string,
+  credential: { source: string; token: string },
+  ctx: EvalContext,
+): Promise<Map<string, GameVersions>> => {
+  let pending = ctx.teamVersions.get(teamID)
+  if (!pending) {
+    pending = fetchTeamGameVersions(sourceToURL(credential.source), credential.token)
+    ctx.teamVersions.set(teamID, pending)
+  }
+  return pending
+}
+
+/** Picks the baseline SHA for the chosen slot. `latest` is the most recent build the team has — the staged next, else the live current. */
+const pickBaseSha = (versions: GameVersions | null, against: ChangedAgainst): string | null => {
+  if (!versions) return null
+  if (against === "next") return versions.next
+  if (against === "previous") return versions.previous
+  return versions.next ?? versions.current
+}
+
+/** Counts files differing under `dir` between `base` and `ref`, optionally folding in uncommitted working-tree changes. */
+const countChanges = (base: string, ref: string, dir: string, includeUncommitted: boolean): number => {
+  const files = new Set(gitLines(["diff", "--name-only", `${base}..${ref}`, "--", "."], dir))
+  if (includeUncommitted) {
+    for (const file of gitLines(["diff", "--name-only", "--", "."], dir)) files.add(file) // unstaged
+    for (const file of gitLines(["diff", "--name-only", "--cached", "--", "."], dir)) files.add(file) // staged
+    for (const file of gitLines(["ls-files", "--others", "--exclude-standard", "--", "."], dir)) files.add(file) // untracked
+  }
+  return files.size
+}
+
+/** Prints the human-readable summary table. */
+const printTable = (report: ChangedEntry[]) => {
+  const headers = ["GAME", "STATUS", "BASE", "FILES"]
+  const rows = report.map((entry) => [entry.slug, entry.status, entry.baseSha ?? "—", String(entry.changedFiles)])
+  const widths = headers.map((header, i) => Math.max(header.length, ...rows.map((row) => row[i].length)))
+  const format = (cols: string[]) => cols.map((col, i) => col.padEnd(widths[i])).join("  ")
+
+  console.log(format(headers))
+  for (const row of rows) console.log(format(row))
+
+  const changedCount = report.filter((entry) => entry.status !== "unchanged").length
+  console.log(`\n${changedCount} of ${report.length} game${report.length === 1 ? "" : "s"} changed.`)
+}
+
+const getRepoRoot = (cwd: string): string | null => tryGit(["rev-parse", "--show-toplevel"], cwd)
+
+const revParseShort = (ref: string, cwd: string): string | null => tryGit(["rev-parse", "--short", ref], cwd)
+
+/** True if `sha` resolves to a commit object in the repo at `cwd`. */
+const commitExists = (sha: string, cwd: string): boolean => {
+  try {
+    execFileSync("git", ["rev-parse", "--verify", "--quiet", `${sha}^{commit}`], { cwd, stdio: "ignore" })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Runs a git command and returns its trimmed stdout, or null if it failed (git's own stderr is suppressed). */
+const tryGit = (args: string[], cwd: string): string | null => {
+  try {
+    return execFileSync("git", args, { encoding: "utf-8", cwd, stdio: ["ignore", "pipe", "ignore"] }).trim()
+  } catch {
+    return null
+  }
+}
+
+/** Runs a git command that emits one file path per line and returns the non-empty lines, or [] if it failed. */
+const gitLines = (args: string[], cwd: string): string[] => {
+  const out = tryGit(args, cwd)
+  if (out === null) return []
+  return out.split("\n").filter(Boolean)
+}
+
+const toPosix = (p: string): string => p.split(path.sep).join("/")

package/src/commands/validate.ts

@@ -3,7 +3,7 @@ import path from "node:path"
 
 import { discoverGames } from "../util/discoverGames.js"
 
-/** CLI command: puzzmo validate [dir] — discovers every puzzmo.json under dir and validates each */
+/** CLI command: puzzmo games validate [dir] — discovers every puzzmo.json under dir and validates each */
 export const validate = async (dir: string) => {
   const rootDir = path.resolve(dir)
   if (!fs.existsSync(rootDir)) {

package/src/index.ts

@@ -3,6 +3,7 @@
 import { defineCommand, runMain } from "citty"
 
 import { agentTest } from "./commands/agent-test.js"
+import { type ChangedAgainst, changed } from "./commands/changed.js"
 import { gameCreate } from "./commands/game/create.js"
 import { login } from "./commands/login.js"
 import { migrate } from "./commands/migrate.js"
@@ -46,6 +47,38 @@ const validateCommand = defineCommand({
   run: ({ args }) => validate(args.dir),
 })
 
+const changedCommand = defineCommand({
+  meta: { name: "changed", description: "Report which games changed since their last deployed build (for CI)." },
+  args: {
+    dir: { type: "positional", description: "Directory to scan", required: false, default: "." },
+    json: { type: "boolean", description: "Output a JSON report for every discovered game" },
+    list: { type: "boolean", description: "Output only the changed game folders, one per line" },
+    matrix: { type: "boolean", description: "Output a GitHub Actions matrix of the changed games" },
+    ref: { type: "string", description: "Git ref to compare against (default HEAD)" },
+    against: {
+      type: "enum",
+      options: ["latest", "next", "previous"],
+      description: "Which deployed build to use as the baseline (default latest)",
+    },
+    "include-uncommitted": { type: "boolean", description: "Also count uncommitted working-tree changes" },
+  },
+  run: ({ args }) =>
+    changed(args.dir, {
+      json: args.json,
+      list: args.list,
+      matrix: args.matrix,
+      ref: args.ref,
+      against: args.against as ChangedAgainst | undefined,
+      includeUncommitted: args["include-uncommitted"],
+    }),
+})
+
+// Commands that operate across every puzzmo.json in a repo live under `puzzmo games`.
+const gamesCommand = defineCommand({
+  meta: { name: "games", description: "Commands that run across all the games in your repo" },
+  subCommands: { changed: changedCommand, upload: uploadCommand, validate: validateCommand },
+})
+
 const migrateCommand = defineCommand({
   meta: { name: "migrate", description: "List and select migration skills from dev.puzzmo.com" },
   run: () => migrate(),
@@ -83,14 +116,37 @@ const gameCommand = defineCommand({
   subCommands: { create: gameCreateCommand },
 })
 
+/** Warn that a top-level command moved under `puzzmo games`, then run it anyway. */
+const movedToGames = (name: string) => console.warn(`"puzzmo ${name}" is now "puzzmo games ${name}". The old form still works for now.`)
+
+// Deprecated top-level aliases, kept hidden so existing scripts (e.g. `puzzmo upload`) keep working.
+const uploadAlias = defineCommand({
+  meta: { ...uploadCommand.meta, hidden: true },
+  args: uploadCommand.args,
+  run: ({ args }) => {
+    movedToGames("upload")
+    return upload(args.dir, { verbose: args.verbose })
+  },
+})
+
+const validateAlias = defineCommand({
+  meta: { ...validateCommand.meta, hidden: true },
+  args: validateCommand.args,
+  run: ({ args }) => {
+    movedToGames("validate")
+    return validate(args.dir)
+  },
+})
+
 const main = defineCommand({
   meta: { name: "puzzmo", description: "Puzzmo CLI" },
   subCommands: {
     login: loginCommand,
-    upload: uploadCommand,
-    validate: validateCommand,
+    games: gamesCommand,
     migrate: migrateCommand,
     game: gameCommand,
+    upload: uploadAlias,
+    validate: validateAlias,
     "agent-test": defineCommand({
       meta: { name: "agent-test", description: "Run the agent test harness", hidden: true },
       run: () => agentTest(),

package/src/queries/__generated__/cliGameRuntimesQuery.graphql.ts

@@ -0,0 +1,301 @@
+/**
+ * @generated SignedSource<<5f5ceed697fe8720947305fca5196bee>>
+ * @lightSyntaxTransform
+ */
+
+/* tslint:disable */
+/* eslint-disable */
+// @ts-nocheck
+
+import { ConcreteRequest } from 'relay-runtime';
+export type cliGameRuntimesQuery$variables = {
+  token: string;
+};
+export type cliGameRuntimesQuery$data = {
+  readonly teamForToken: {
+    readonly games: {
+      readonly edges: ReadonlyArray<{
+        readonly node: {
+          readonly runtime: {
+            readonly currentVersion: {
+              readonly assetsSha: string;
+            } | null | undefined;
+            readonly nextVersion: {
+              readonly assetsSha: string;
+            } | null | undefined;
+            readonly previousVersion: {
+              readonly assetsSha: string;
+            } | null | undefined;
+          } | null | undefined;
+          readonly slug: string;
+        };
+      } | null | undefined> | null | undefined;
+    };
+    readonly slug: string;
+  } | null | undefined;
+};
+export type cliGameRuntimesQuery = {
+  response: cliGameRuntimesQuery$data;
+  variables: cliGameRuntimesQuery$variables;
+};
+
+const node: ConcreteRequest = (function(){
+var v0 = [
+  {
+    "defaultValue": null,
+    "kind": "LocalArgument",
+    "name": "token"
+  }
+],
+v1 = [
+  {
+    "kind": "Variable",
+    "name": "token",
+    "variableName": "token"
+  }
+],
+v2 = {
+  "alias": null,
+  "args": null,
+  "kind": "ScalarField",
+  "name": "slug",
+  "storageKey": null
+},
+v3 = [
+  {
+    "kind": "Literal",
+    "name": "first",
+    "value": 500
+  }
+],
+v4 = {
+  "alias": null,
+  "args": null,
+  "kind": "ScalarField",
+  "name": "assetsSha",
+  "storageKey": null
+},
+v5 = [
+  (v4/*:: as any*/)
+],
+v6 = {
+  "alias": null,
+  "args": null,
+  "kind": "ScalarField",
+  "name": "id",
+  "storageKey": null
+},
+v7 = [
+  (v4/*:: as any*/),
+  (v6/*:: as any*/)
+];
+return {
+  "fragment": {
+    "argumentDefinitions": (v0/*:: as any*/),
+    "kind": "Fragment",
+    "metadata": null,
+    "name": "cliGameRuntimesQuery",
+    "selections": [
+      {
+        "alias": null,
+        "args": (v1/*:: as any*/),
+        "concreteType": "Team",
+        "kind": "LinkedField",
+        "name": "teamForToken",
+        "plural": false,
+        "selections": [
+          (v2/*:: as any*/),
+          {
+            "alias": null,
+            "args": (v3/*:: as any*/),
+            "concreteType": "GameConnection",
+            "kind": "LinkedField",
+            "name": "games",
+            "plural": false,
+            "selections": [
+              {
+                "alias": null,
+                "args": null,
+                "concreteType": "GameEdge",
+                "kind": "LinkedField",
+                "name": "edges",
+                "plural": true,
+                "selections": [
+                  {
+                    "alias": null,
+                    "args": null,
+                    "concreteType": "Game",
+                    "kind": "LinkedField",
+                    "name": "node",
+                    "plural": false,
+                    "selections": [
+                      (v2/*:: as any*/),
+                      {
+                        "alias": null,
+                        "args": null,
+                        "concreteType": "GameRuntime",
+                        "kind": "LinkedField",
+                        "name": "runtime",
+                        "plural": false,
+                        "selections": [
+                          {
+                            "alias": null,
+                            "args": null,
+                            "concreteType": "GameRuntimeVersion",
+                            "kind": "LinkedField",
+                            "name": "currentVersion",
+                            "plural": false,
+                            "selections": (v5/*:: as any*/),
+                            "storageKey": null
+                          },
+                          {
+                            "alias": null,
+                            "args": null,
+                            "concreteType": "GameRuntimeVersion",
+                            "kind": "LinkedField",
+                            "name": "nextVersion",
+                            "plural": false,
+                            "selections": (v5/*:: as any*/),
+                            "storageKey": null
+                          },
+                          {
+                            "alias": null,
+                            "args": null,
+                            "concreteType": "GameRuntimeVersion",
+                            "kind": "LinkedField",
+                            "name": "previousVersion",
+                            "plural": false,
+                            "selections": (v5/*:: as any*/),
+                            "storageKey": null
+                          }
+                        ],
+                        "storageKey": null
+                      }
+                    ],
+                    "storageKey": null
+                  }
+                ],
+                "storageKey": null
+              }
+            ],
+            "storageKey": "games(first:500)"
+          }
+        ],
+        "storageKey": null
+      }
+    ],
+    "type": "Query",
+    "abstractKey": null
+  },
+  "kind": "Request",
+  "operation": {
+    "argumentDefinitions": (v0/*:: as any*/),
+    "kind": "Operation",
+    "name": "cliGameRuntimesQuery",
+    "selections": [
+      {
+        "alias": null,
+        "args": (v1/*:: as any*/),
+        "concreteType": "Team",
+        "kind": "LinkedField",
+        "name": "teamForToken",
+        "plural": false,
+        "selections": [
+          (v2/*:: as any*/),
+          {
+            "alias": null,
+            "args": (v3/*:: as any*/),
+            "concreteType": "GameConnection",
+            "kind": "LinkedField",
+            "name": "games",
+            "plural": false,
+            "selections": [
+              {
+                "alias": null,
+                "args": null,
+                "concreteType": "GameEdge",
+                "kind": "LinkedField",
+                "name": "edges",
+                "plural": true,
+                "selections": [
+                  {
+                    "alias": null,
+                    "args": null,
+                    "concreteType": "Game",
+                    "kind": "LinkedField",
+                    "name": "node",
+                    "plural": false,
+                    "selections": [
+                      (v2/*:: as any*/),
+                      {
+                        "alias": null,
+                        "args": null,
+                        "concreteType": "GameRuntime",
+                        "kind": "LinkedField",
+                        "name": "runtime",
+                        "plural": false,
+                        "selections": [
+                          {
+                            "alias": null,
+                            "args": null,
+                            "concreteType": "GameRuntimeVersion",
+                            "kind": "LinkedField",
+                            "name": "currentVersion",
+                            "plural": false,
+                            "selections": (v7/*:: as any*/),
+                            "storageKey": null
+                          },
+                          {
+                            "alias": null,
+                            "args": null,
+                            "concreteType": "GameRuntimeVersion",
+                            "kind": "LinkedField",
+                            "name": "nextVersion",
+                            "plural": false,
+                            "selections": (v7/*:: as any*/),
+                            "storageKey": null
+                          },
+                          {
+                            "alias": null,
+                            "args": null,
+                            "concreteType": "GameRuntimeVersion",
+                            "kind": "LinkedField",
+                            "name": "previousVersion",
+                            "plural": false,
+                            "selections": (v7/*:: as any*/),
+                            "storageKey": null
+                          },
+                          (v6/*:: as any*/)
+                        ],
+                        "storageKey": null
+                      },
+                      (v6/*:: as any*/)
+                    ],
+                    "storageKey": null
+                  }
+                ],
+                "storageKey": null
+              }
+            ],
+            "storageKey": "games(first:500)"
+          },
+          (v6/*:: as any*/)
+        ],
+        "storageKey": null
+      }
+    ]
+  },
+  "params": {
+    "cacheID": "169b76dbd259ac615d2b712641a54087",
+    "id": null,
+    "metadata": {},
+    "name": "cliGameRuntimesQuery",
+    "operationKind": "query",
+    "text": "query cliGameRuntimesQuery(\n  $token: String!\n) {\n  teamForToken(token: $token) {\n    slug\n    games(first: 500) {\n      edges {\n        node {\n          slug\n          runtime {\n            currentVersion {\n              assetsSha\n              id\n            }\n            nextVersion {\n              assetsSha\n              id\n            }\n            previousVersion {\n              assetsSha\n              id\n            }\n            id\n          }\n          id\n        }\n      }\n    }\n    id\n  }\n}\n"
+  }
+};
+})();
+
+(node as any).hash = "6467f74d92adb125c762ed24be7d4ac8";
+
+export default node;