@puzzmo/cli 1.0.50 → 1.0.52

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"
@@ -30,8 +31,12 @@ const uploadCommand = defineCommand({
   args: {
     dir: { type: "positional", description: "Directory to scan", required: false, default: "." },
     verbose: { type: "boolean", description: "Print request URLs and full error bodies", alias: "v" },
+    "create-missing": {
+      type: "boolean",
+      description: "Create games that don't exist yet without an interactive prompt (for CI).",
+    },
   },
-  run: ({ args }) => upload(args.dir, { verbose: args.verbose }),
+  run: ({ args }) => upload(args.dir, { verbose: args.verbose, createMissing: args["create-missing"] }),
 })
 
 const validateCommand = defineCommand({
@@ -42,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(),
@@ -79,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;

package/src/queries/gameRuntimes.ts

@@ -0,0 +1,64 @@
+import { graphql, query } from "../util/belay.js"
+import type { cliGameRuntimesQuery } from "./__generated__/cliGameRuntimesQuery.graphql.js"
+
+const gameRuntimesQuery = graphql`
+  query cliGameRuntimesQuery($token: String!) {
+    teamForToken(token: $token) {
+      slug
+      games(first: 500) {
+        edges {
+          node {
+            slug
+            runtime {
+              currentVersion {
+                assetsSha
+              }
+              nextVersion {
+                assetsSha
+              }
+              previousVersion {
+                assetsSha
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+`
+
+/** The deployed runtime build SHAs for a game, read from its runtime's current/next/previous version slots. */
+export type GameVersions = {
+  /** SHA of the live/current runtime build */
+  current: string | null
+  /** SHA of the staged "next" runtime build, if one exists */
+  next: string | null
+  /** SHA of the previous runtime build, if one exists */
+  previous: string | null
+}
+
+/**
+ * Fetches the runtime build SHAs for every game in the token's team, keyed by game slug. The token is sent both as
+ * the `teamForToken` argument and as the Bearer header — the latter is what unlocks the team-gated `runtime` field.
+ */
+export const fetchTeamGameVersions = async (apiURL: string, token: string): Promise<Map<string, GameVersions>> => {
+  const { data, errors } = await query<cliGameRuntimesQuery>(gameRuntimesQuery, {
+    variables: { token },
+    url: `${apiURL}/graphql`,
+    headers: { Authorization: `Bearer ${token}` },
+  })
+
+  if (errors?.length) throw new Error(`teamForToken failed: ${errors.map((e) => e.message).join("; ")}`)
+
+  const versions = new Map<string, GameVersions>()
+  for (const edge of data?.teamForToken?.games?.edges ?? []) {
+    const game = edge?.node
+    if (!game) continue
+    versions.set(game.slug, {
+      current: game.runtime?.currentVersion?.assetsSha || null,
+      next: game.runtime?.nextVersion?.assetsSha || null,
+      previous: game.runtime?.previousVersion?.assetsSha || null,
+    })
+  }
+  return versions
+}

package/src/util/api.ts

@@ -7,6 +7,9 @@ export type PuzzmoFile = {
     displayName: string
     slug: string
     teamID: string
+    oneliner?: string
+    description?: string
+    highlightColor?: string
   }
   // This is what we're calling 'augmentations' publicly
   integrations?: Record<string, unknown>

package/src/util/belay.ts

@@ -0,0 +1,56 @@
+// "belay lite" — a local copy of the parts of @puzzmo-com/belay the CLI needs.
+// The CLI is published to npm and ships unbundled, so it can't depend on the private,
+// source-only belay package; this vendors the tiny query/graphql helpers instead.
+// The `graphql` tag lets the Relay compiler validate these queries and generate types
+// (see the "cli" project in relay.config.json). Keep this in sync with packages/belay.
+
+/** Standard GraphQL error shape */
+export type GraphQLError = {
+  message: string
+  locations?: Array<{ line: number; column: number }>
+  path?: Array<string | number>
+  extensions?: Record<string, unknown>
+}
+
+/** GraphQL response shape */
+export type GraphQLResponse<TData> = {
+  data?: TData
+  errors?: GraphQLError[]
+}
+
+/** Operation type with variables and response — matches Relay's generated operation types */
+export type OperationType = {
+  variables: Record<string, unknown>
+  response: unknown
+}
+
+/** Request options for the query function */
+export type RequestOptions<TVariables> = {
+  variables: TVariables
+  url: string
+  headers?: HeadersInit
+  signal?: AbortSignal
+}
+
+/**
+ * A graphql tagged template literal that returns the query string. This lets the Relay
+ * compiler pick up and validate the operation (and generate its types) without bundling relay-runtime.
+ */
+export const graphql = (strings: TemplateStringsArray): string => strings[0]!
+
+/** Execute a GraphQL query via fetch, typed with a Relay-generated operation type. */
+export const query = async <T extends OperationType>(
+  queryString: string,
+  options: RequestOptions<T["variables"]>,
+): Promise<GraphQLResponse<T["response"]>> => {
+  const { variables, url, headers, signal } = options
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...headers },
+    signal,
+    body: JSON.stringify({ query: queryString, variables }),
+  })
+
+  return response.json() as Promise<GraphQLResponse<T["response"]>>
+}

package/src/util/createGame.ts

@@ -25,6 +25,9 @@ export type CreateUserGameOptions = {
   /** A teamAccessToken (the same token saved by `puzzmo login`). The mutation uses it to identify the team. */
   teamAccessToken: string
   displayName: string
+  oneliner?: string
+  description?: string
+  highlightColor?: string
 }
 
 export type CreatedGame = { id: string; slug: string; displayName: string; newAccessToken: string | null }
@@ -40,7 +43,12 @@ export const createUserGame = async (options: CreateUserGameOptions): Promise<Cr
       query: createUserGameMutation,
       variables: {
         teamAccessToken: options.teamAccessToken,
-        input: { displayName: options.displayName },
+        input: {
+          displayName: options.displayName,
+          oneliner: options.oneliner,
+          description: options.description,
+          highlightColor: options.highlightColor,
+        },
       },
     }),
   })

package/src/util/discoverGames.ts

@@ -20,7 +20,10 @@ export type DiscoveredGame = {
   puzzmoJsonDir: string
   /** Validated puzzmo.json contents */
   puzzmoFile: PuzzmoFile
-  /** Absolute path to the dist directory containing the build artifacts */
+  /**
+   * Absolute path to the dist directory containing the build artifacts (empty string when discovered with requireDist: false and none was
+   * found)
+   */
   distDir: string
 }
 
@@ -37,8 +40,15 @@ export type DiscoveryResult = {
   errors: DiscoveryError[]
 }
 
+/** Options for {@link discoverGames} */
+export type DiscoverOptions = {
+  /** Require each game to have a non-empty dist folder (default true). Set false for commands that run before a build. */
+  requireDist?: boolean
+}
+
 /** Walks `rootDir` looking for puzzmo.json files, validates each, and resolves their dist directory */
-export const discoverGames = async (rootDir: string): Promise<DiscoveryResult> => {
+export const discoverGames = async (rootDir: string, options: DiscoverOptions = {}): Promise<DiscoveryResult> => {
+  const { requireDist = true } = options
   const root = path.resolve(rootDir)
   const puzzmoJsonPaths = findPuzzmoJsonFiles(root)
 
@@ -66,18 +76,20 @@ export const discoverGames = async (rootDir: string): Promise<DiscoveryResult> =
     const puzzmoJsonDir = path.dirname(puzzmoJsonPath)
     const distDir = resolveDistDir(puzzmoFile, puzzmoJsonDir, root)
 
-    if (!distDir) {
-      fileErrors.push(`Could not find a dist/build folder for ${puzzmoFile.game.slug}. Set "output.dir" in puzzmo.json.`)
-    } else if (!hasFiles(distDir)) {
-      fileErrors.push(`Dist folder is empty: ${distDir}`)
-    }
+    if (requireDist) {
+      if (!distDir) {
+        fileErrors.push(`Could not find a dist/build folder for ${puzzmoFile.game.slug}. Set "output.dir" in puzzmo.json.`)
+      } else if (!hasFiles(distDir)) {
+        fileErrors.push(`Dist folder is empty: ${distDir}`)
+      }
 
-    if (fileErrors.length) {
-      errors.push({ puzzmoJsonPath, slug: puzzmoFile.game.slug, errors: fileErrors })
-      continue
+      if (fileErrors.length) {
+        errors.push({ puzzmoJsonPath, slug: puzzmoFile.game.slug, errors: fileErrors })
+        continue
+      }
     }
 
-    games.push({ puzzmoJsonPath, puzzmoJsonDir, puzzmoFile, distDir: distDir as string })
+    games.push({ puzzmoJsonPath, puzzmoJsonDir, puzzmoFile, distDir: distDir ?? "" })
   }
 
   return { games, errors }

package/src/util/slugify.ts

@@ -0,0 +1,17 @@
+/**
+ * Converts a string to a URL-friendly slug. Mirrors packages/shared/slugify.ts —
+ * the CLI is standalone and does not depend on @puzzmo-com/shared, so the host's
+ * slug derivation is replicated here. Keep in sync with the shared version: the
+ * server derives a new game's slug from its displayName the same way, and
+ * `upload` uses this to refuse creating a game whose puzzmo.json slug wouldn't match.
+ */
+export const slugify = (text: string): string =>
+  text
+    .toString()
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .trim()
+    .replace(/\s+/g, "-")
+    .replace(/[^\w-]+/g, "")
+    .replace(/--+/g, "-")

package/templates/minesweeper/README.md

@@ -15,5 +15,5 @@ Edit puzzles in `fixtures/puzzles/`. Game logic is in `src/main.ts`.
 ## Deployment
 
 ```
-yarn puzzmo upload
+yarn puzzmo games upload
 ```