@puzzmo/cli 1.0.37 → 1.0.39

package/src/commands/validate.ts

@@ -1,46 +1,39 @@
 import fs from "node:fs"
 import path from "node:path"
 
-import { validatePuzzmoJson } from "../util/validatePuzzmoFile.js"
+import { discoverGames } from "../util/discoverGames.js"
 
-/** CLI command: puzzmo validate [dir] */
+/** CLI command: puzzmo validate [dir] — discovers every puzzmo.json under dir and validates each */
 export const validate = async (dir: string) => {
-  const resolvedDir = path.resolve(dir)
-  const puzzmoJsonPath = path.join(resolvedDir, "puzzmo.json")
-
-  if (!fs.existsSync(puzzmoJsonPath)) {
-    console.error(`No puzzmo.json found in ${dir}`)
+  const rootDir = path.resolve(dir)
+  if (!fs.existsSync(rootDir)) {
+    console.error(`Directory not found: ${dir}`)
     process.exit(1)
   }
 
-  let raw: string
-  try {
-    raw = fs.readFileSync(puzzmoJsonPath, "utf-8")
-  } catch (e) {
-    console.error(`Could not read puzzmo.json: ${e instanceof Error ? e.message : e}`)
-    process.exit(1)
-  }
+  const { games, errors } = await discoverGames(rootDir)
 
-  let data: unknown
-  try {
-    data = JSON.parse(raw)
-  } catch (e) {
-    console.error(`Invalid JSON in puzzmo.json: ${e instanceof Error ? e.message : e}`)
+  if (!games.length && !errors.length) {
+    console.error(`No puzzmo.json files found under ${rootDir}`)
     process.exit(1)
   }
 
-  const result = await validatePuzzmoJson(data)
-  if (!result.valid) {
-    console.error(`puzzmo.json has ${result.errors.length} error(s):\n`)
-    for (const err of result.errors) console.error(`  ${err}`)
-    process.exit(1)
+  for (const game of games) {
+    const rel = path.relative(rootDir, game.puzzmoJsonPath) || game.puzzmoJsonPath
+    const integrations = game.puzzmoFile.integrations ? Object.keys(game.puzzmoFile.integrations) : []
+    const distRel = path.relative(rootDir, game.distDir) || game.distDir
+    console.log(`OK   ${game.puzzmoFile.game.slug.padEnd(24)} (${rel})`)
+    console.log(`     dist: ${distRel}`)
+    if (integrations.length) console.log(`     integrations: ${integrations.join(", ")}`)
   }
 
-  const { data: puzzmoFile } = result
-  console.log(`Valid puzzmo.json for "${puzzmoFile.game.displayName}" (${puzzmoFile.game.slug})`)
-
-  if (puzzmoFile.integrations) {
-    const keys = Object.keys(puzzmoFile.integrations)
-    if (keys.length) console.log(`Integrations: ${keys.join(", ")}`)
+  for (const err of errors) {
+    const rel = path.relative(rootDir, err.puzzmoJsonPath) || err.puzzmoJsonPath
+    const label = err.slug ?? rel
+    console.error(`FAIL ${label.padEnd(24)} (${rel})`)
+    for (const e of err.errors) console.error(`     ${e}`)
   }
+
+  console.log(`\n${games.length} valid, ${errors.length} invalid`)
+  if (errors.length) process.exit(1)
 }

package/src/index.ts

@@ -14,8 +14,8 @@ const printUsage = () => {
   puzzmo login <token>            Save a CLI auth token
   puzzmo game create [token]      Create a new Puzzmo game project
 
-  puzzmo upload <dir> [-v]        Upload game build from <dir> (slug from puzzmo.json). -v/--verbose prints request URLs and full error bodies.
-  puzzmo validate [dir]           Validate puzzmo.json in a directory (default: .)
+  puzzmo upload [dir] [-v]        Discover puzzmo.json files in [dir] (default: .) and upload each game's build. -v/--verbose prints request URLs and full error bodies. If a game does not exist on your account and stdin is a TTY, you'll be asked whether to create it (using your saved CLI token).
+  puzzmo validate [dir]           Discover and validate every puzzmo.json under [dir] (default: .)
   puzzmo migrate                  List and select migration skills from dev.puzzmo.com`)
 }
 
@@ -32,11 +32,7 @@ const run = async () => {
     }
     case "upload": {
       const verbose = args.includes("--verbose") || args.includes("-v")
-      const dir = args.find((a) => !a.startsWith("-"))
-      if (!dir) {
-        console.error("Usage: puzzmo upload <dir> [-v|--verbose]")
-        process.exit(1)
-      }
+      const dir = args.find((a) => !a.startsWith("-")) ?? "."
       await upload(dir, { verbose })
       break
     }
@@ -45,7 +41,9 @@ const run = async () => {
       if (subcommand === "create") {
         await gameCreate(subArgs)
       } else {
-        console.error("Usage: puzzmo game create [token] [--name <name>] [--url <url>] [--agent <agent>] [--pm <npm|yarn|pnpm>]")
+        console.error(
+          "Usage: puzzmo game create [--strategy <import|blank|prompt>] [--prompt <text>] [--name <name>] [--url <url>] [--agent <agent>] [--token <token>] [--pm <npm|yarn|pnpm>]",
+        )
         process.exit(1)
       }
       break

package/src/skills/runner.ts

@@ -82,3 +82,38 @@ export const runSkillsPipeline = async (agent: string, gameDir: string, repoCont
 export const runSkillsPipelineTUI = async (agent: string, gameDir: string, repoContext: string) => {
   await runPipelineTUI(agent, gameDir, repoContext)
 }
+
+/** Runs a single agent invocation, verifies the build, and commits. Used by one-shot prompt-driven flows. */
+export const runAgentWithBuildLoop = (agent: string, prompt: string, gameDir: string, label: string): boolean => {
+  console.log(`Running agent: ${label}`)
+  let result = invokeAgent(agent, prompt, gameDir)
+  if (!result.success) {
+    console.log(`  Agent failed, retrying...`)
+    result = invokeAgent(agent, prompt, gameDir)
+    if (!result.success) {
+      console.error(`  Agent failed after retry. Stopping.`)
+      return false
+    }
+  }
+
+  const buildResult = verifyBuild(gameDir)
+  if (!buildResult.success) {
+    console.log(`  Build failed, asking agent to fix...`)
+    const fixPrompt = `The vite build failed after the "${label}" step. Fix the build errors:\n\n${buildResult.error}`
+    invokeAgent(agent, fixPrompt, gameDir)
+    const retry = verifyBuild(gameDir)
+    if (!retry.success) {
+      console.error(`  Build still failing after fix attempt.`)
+      return false
+    }
+  }
+
+  try {
+    runCommand("git add -A", { cwd: gameDir })
+    gitCommit(`step: ${label}`, { cwd: gameDir })
+    console.log(`  Committed.`)
+  } catch {
+    console.log(`  No changes to commit.`)
+  }
+  return true
+}

package/src/util/api.ts

@@ -10,11 +10,26 @@ export type PuzzmoFile = {
     slug: string
     teamID: string
   }
+  // This is what we're calling 'augmentations' publicly
   integrations?: Record<string, unknown>
+  output?: {
+    dir: string
+  }
 }
 
 const BATCH_SIZE = 10
 
+/** Thrown when /cliUpload init returns a 404 because the game slug isn't registered yet. */
+export class GameNotFoundError extends Error {
+  constructor(
+    public readonly slug: string,
+    message: string,
+  ) {
+    super(message)
+    this.name = "GameNotFoundError"
+  }
+}
+
 type InitResponse = { sessionID: string; basePath: string; error?: string }
 type FileResponse = { path: string; error?: string }
 type CompleteResponse = { assetsBase: string; versionID: string; error?: string }
@@ -60,9 +75,11 @@ const readResponse = async (res: Response, url: string, step: string, verbose: b
     throw new Error(`Invalid JSON response during ${step} (${url}): ${verbose ? text : text.slice(0, 200)}`)
   }
   if (!res.ok) {
-    const serverMsg = (json as { error?: string }).error || res.statusText || "Unknown error"
+    const body = json as { error?: string; validationErrors?: string[] }
+    const serverMsg = body.error || res.statusText || "Unknown error"
+    const validation = body.validationErrors?.length ? `\n  - ${body.validationErrors.join("\n  - ")}` : ""
     const detail = verbose ? `\n${JSON.stringify(json, null, 2)}` : ""
-    throw new Error(`Server error during ${step} (${res.status} from ${url}): ${serverMsg}${detail}`)
+    throw new Error(`Server error during ${step} (${res.status} from ${url}): ${serverMsg}${validation}${detail}`)
   }
   return json
 }
@@ -121,13 +138,19 @@ export const uploadFiles = async (
   if (verbose) console.log(`  API URL: ${apiURL}`)
 
   // Step 1: Init session (includes puzzmo.json metadata)
-  const init = (await jsonPost(
-    `${apiURL}/cliUpload`,
-    token,
-    { gameSlug, sha, puzzmoFile, description, repoURL },
-    "upload init",
-    verbose,
-  )) as InitResponse
+  let init: InitResponse
+  try {
+    init = (await jsonPost(
+      `${apiURL}/cliUpload`,
+      token,
+      { gameSlug, sha, puzzmoFile, description, repoURL },
+      "upload init",
+      verbose,
+    )) as InitResponse
+  } catch (e) {
+    if (e instanceof Error && e.message.includes("Game not found:")) throw new GameNotFoundError(gameSlug, e.message)
+    throw e
+  }
   if (verbose) console.log(`  session: ${init.sessionID}`)
 
   // Step 2: Upload files in concurrent batches

package/src/util/createGame.ts

@@ -0,0 +1,60 @@
+import { getAPIURL } from "./config.js"
+
+const createUserGameMutation = `
+  mutation cliCreateUserGameMutation($teamAccessToken: String!, $input: CreateUserGameInput!) {
+    createUserGame(teamAccessToken: $teamAccessToken, input: $input) {
+      game { id slug displayName }
+      newAccessToken
+    }
+  }
+`
+
+type GraphQLError = { message: string }
+
+type CreateUserGameResponse = {
+  data?: {
+    createUserGame: {
+      game: { id: string; slug: string; displayName: string }
+      newAccessToken: string | null
+    } | null
+  }
+  errors?: GraphQLError[]
+}
+
+export type CreateUserGameOptions = {
+  /** A teamAccessToken (the same token saved by `puzzmo login`). The mutation uses it to identify the team. */
+  teamAccessToken: string
+  displayName: string
+}
+
+export type CreatedGame = { id: string; slug: string; displayName: string; newAccessToken: string | null }
+
+/** Calls the createUserGame mutation using a teamAccessToken for auth. */
+export const createUserGame = async (options: CreateUserGameOptions): Promise<CreatedGame> => {
+  const url = `${getAPIURL()}/graphql`
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      query: createUserGameMutation,
+      variables: {
+        teamAccessToken: options.teamAccessToken,
+        input: { displayName: options.displayName },
+      },
+    }),
+  })
+
+  if (!response.ok) throw new Error(`createUserGame request failed: ${response.status} ${response.statusText}`)
+
+  const result = (await response.json()) as CreateUserGameResponse
+
+  if (result.errors?.length) {
+    const message = result.errors.map((e) => e.message).join("; ")
+    throw new Error(`createUserGame failed: ${message}`)
+  }
+  if (!result.data?.createUserGame) throw new Error("createUserGame returned no data")
+
+  const { game, newAccessToken } = result.data.createUserGame
+  return { id: game.id, slug: game.slug, displayName: game.displayName, newAccessToken }
+}

package/src/util/discoverGames.ts

@@ -0,0 +1,203 @@
+import fs from "node:fs"
+import path from "node:path"
+
+import type { PuzzmoFile } from "./api.js"
+import { validatePuzzmoJson } from "./validatePuzzmoFile.js"
+
+/** Folder names that are skipped while walking the repo for puzzmo.json files */
+const ignoredDirs = new Set(["node_modules", ".git", ".turbo", ".next", ".cache", "dist", "build", "built", "output"])
+
+/** Folder names that are searched (in order) when resolving a game's dist directory */
+const outputDirNames = ["dist", "build", "built", "output"]
+
+/** A game discovered in the repo, with its parsed puzzmo.json and resolved dist directory */
+export type DiscoveredGame = {
+  /** Absolute path to the puzzmo.json file */
+  puzzmoJsonPath: string
+  /** Directory containing the puzzmo.json file */
+  puzzmoJsonDir: string
+  /** Validated puzzmo.json contents */
+  puzzmoFile: PuzzmoFile
+  /** Absolute path to the dist directory containing the build artifacts */
+  distDir: string
+}
+
+/** A puzzmo.json that was found but could not be used (invalid JSON, schema errors, missing dist) */
+export type DiscoveryError = {
+  puzzmoJsonPath: string
+  /** Slug pulled from the file when available, used for reporting */
+  slug?: string
+  errors: string[]
+}
+
+export type DiscoveryResult = {
+  games: DiscoveredGame[]
+  errors: DiscoveryError[]
+}
+
+/** Walks `rootDir` looking for puzzmo.json files, validates each, and resolves their dist directory */
+export const discoverGames = async (rootDir: string): Promise<DiscoveryResult> => {
+  const root = path.resolve(rootDir)
+  const puzzmoJsonPaths = findPuzzmoJsonFiles(root)
+
+  const games: DiscoveredGame[] = []
+  const errors: DiscoveryError[] = []
+
+  for (const puzzmoJsonPath of puzzmoJsonPaths) {
+    const fileErrors: string[] = []
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(fs.readFileSync(puzzmoJsonPath, "utf-8"))
+    } catch (e) {
+      errors.push({ puzzmoJsonPath, errors: [`Invalid JSON: ${e instanceof Error ? e.message : e}`] })
+      continue
+    }
+
+    const validation = await validatePuzzmoJson(parsed)
+    if (!validation.valid) {
+      const slug = pullSlug(parsed)
+      errors.push({ puzzmoJsonPath, slug, errors: validation.errors })
+      continue
+    }
+
+    const puzzmoFile = validation.data
+    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 (fileErrors.length) {
+      errors.push({ puzzmoJsonPath, slug: puzzmoFile.game.slug, errors: fileErrors })
+      continue
+    }
+
+    games.push({ puzzmoJsonPath, puzzmoJsonDir, puzzmoFile, distDir: distDir as string })
+  }
+
+  return { games, errors }
+}
+
+/** Recursively finds puzzmo.json files under `dir`, skipping output / vendored folders. Tracks realpaths to avoid symlink cycles. */
+const findPuzzmoJsonFiles = (dir: string): string[] => {
+  const found: string[] = []
+  const visited = new Set<string>()
+  const stack = [dir]
+  while (stack.length) {
+    const current = stack.pop() as string
+    const realCurrent = safeRealpath(current)
+    if (!realCurrent || visited.has(realCurrent)) continue
+    visited.add(realCurrent)
+
+    let entries: fs.Dirent[]
+    try {
+      entries = fs.readdirSync(realCurrent, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      const full = path.join(realCurrent, entry.name)
+      const kind = resolveEntryKind(entry, full)
+      if (kind === "directory") {
+        if (ignoredDirs.has(entry.name)) continue
+        if (entry.name.startsWith(".")) continue
+        stack.push(full)
+      } else if (kind === "file" && entry.name === "puzzmo.json") {
+        found.push(full)
+      }
+    }
+  }
+  return found.sort()
+}
+
+/** Resolves the dist directory for a discovered game, returning null if none can be found */
+const resolveDistDir = (puzzmoFile: PuzzmoFile, puzzmoJsonDir: string, repoRoot: string): string | null => {
+  if (puzzmoFile.output?.dir) {
+    const resolved = path.resolve(puzzmoJsonDir, puzzmoFile.output.dir)
+    return fs.existsSync(resolved) ? resolved : null
+  }
+
+  const slug = puzzmoFile.game.slug
+  const candidateDirs = walkUp(puzzmoJsonDir, repoRoot)
+  for (const baseDir of candidateDirs) {
+    for (const name of outputDirNames) {
+      const withSlug = path.join(baseDir, name, slug)
+      if (fs.existsSync(withSlug) && fs.statSync(withSlug).isDirectory()) return withSlug
+      const plain = path.join(baseDir, name)
+      if (fs.existsSync(plain) && fs.statSync(plain).isDirectory()) return plain
+    }
+  }
+  return null
+}
+
+/** Returns the directories from `start` walking up to (and including) `stop` */
+const walkUp = (start: string, stop: string): string[] => {
+  const dirs: string[] = []
+  let current = start
+  while (true) {
+    dirs.push(current)
+    if (current === stop) break
+    const parent = path.dirname(current)
+    if (parent === current) break
+    if (!current.startsWith(stop)) break
+    current = parent
+  }
+  return dirs
+}
+
+/** Returns true if the directory contains at least one file (recursively). Follows symlinks safely via a visited realpath set. */
+const hasFiles = (dir: string, visited: Set<string> = new Set()): boolean => {
+  const realDir = safeRealpath(dir)
+  if (!realDir || visited.has(realDir)) return false
+  visited.add(realDir)
+
+  let entries: fs.Dirent[]
+  try {
+    entries = fs.readdirSync(realDir, { withFileTypes: true })
+  } catch {
+    return false
+  }
+  for (const entry of entries) {
+    const full = path.join(realDir, entry.name)
+    const kind = resolveEntryKind(entry, full)
+    if (kind === "file") return true
+    if (kind === "directory" && hasFiles(full, visited)) return true
+  }
+  return false
+}
+
+/** Resolves the underlying type of a directory entry, following symlinks one level. Returns null for dangling links or other types. */
+const resolveEntryKind = (entry: fs.Dirent, fullPath: string): "file" | "directory" | null => {
+  if (entry.isFile()) return "file"
+  if (entry.isDirectory()) return "directory"
+  if (!entry.isSymbolicLink()) return null
+  try {
+    const stat = fs.statSync(fullPath)
+    if (stat.isFile()) return "file"
+    if (stat.isDirectory()) return "directory"
+  } catch {
+    // dangling symlink
+  }
+  return null
+}
+
+/** Resolves a path to its real location; returns null if the path can't be resolved (broken link, missing dir, etc.) */
+const safeRealpath = (p: string): string | null => {
+  try {
+    return fs.realpathSync(p)
+  } catch {
+    return null
+  }
+}
+
+/** Best-effort extraction of the slug from a malformed puzzmo.json for error reporting */
+const pullSlug = (parsed: unknown): string | undefined => {
+  if (!parsed || typeof parsed !== "object") return undefined
+  const game = (parsed as { game?: unknown }).game
+  if (!game || typeof game !== "object") return undefined
+  const slug = (game as { slug?: unknown }).slug
+  return typeof slug === "string" ? slug : undefined
+}

package/src/util/validatePuzzmoFile.ts

@@ -32,12 +32,12 @@ const getValidator = async () => {
 
 type ValidationResult = { valid: true; data: PuzzmoFile } | { valid: false; errors: string[] }
 
-/** Validates a parsed object against the puzzmo.json JSON schema */
+/** Validates a parsed object against the puzzmo.json JSON schema. Returned `data` has `$schema` stripped. */
 export const validatePuzzmoJson = async (data: unknown): Promise<ValidationResult> => {
   const validator = await getValidator()
   const toValidate = stripSchemaProperty(data)
   const result = validator.validate(toValidate)
-  if (result.valid) return { valid: true, data: data as PuzzmoFile }
+  if (result.valid) return { valid: true, data: toValidate as PuzzmoFile }
   return {
     valid: false,
     errors: result.errors

package/templates/minesweeper/README.md

@@ -0,0 +1,13 @@
+# __DISPLAY_NAME__
+
+A Minesweeper-style Puzzmo game scaffold.
+
+## Develop
+
+```
+yarn install   # or npm/pnpm
+yarn dev       # opens the Puzzmo simulator
+yarn build
+```
+
+Edit puzzles in `fixtures/puzzles/`. Game logic is in `src/main.ts`.

package/templates/minesweeper/fixtures/puzzles/easy/9x9.json

@@ -0,0 +1,16 @@
+{
+  "rows": 9,
+  "cols": 9,
+  "mines": [
+    [0, 2],
+    [1, 5],
+    [2, 0],
+    [3, 7],
+    [4, 3],
+    [5, 8],
+    [6, 1],
+    [7, 4],
+    [7, 6],
+    [8, 2]
+  ]
+}

package/templates/minesweeper/fixtures/puzzles/hard/16x16.json

@@ -0,0 +1,46 @@
+{
+  "rows": 16,
+  "cols": 16,
+  "mines": [
+    [0, 3],
+    [0, 11],
+    [1, 5],
+    [1, 14],
+    [2, 1],
+    [2, 8],
+    [2, 12],
+    [3, 4],
+    [3, 9],
+    [4, 0],
+    [4, 6],
+    [4, 13],
+    [5, 2],
+    [5, 10],
+    [5, 15],
+    [6, 5],
+    [6, 8],
+    [7, 1],
+    [7, 11],
+    [7, 14],
+    [8, 3],
+    [8, 7],
+    [9, 0],
+    [9, 9],
+    [9, 12],
+    [10, 5],
+    [10, 14],
+    [11, 2],
+    [11, 8],
+    [11, 11],
+    [12, 0],
+    [12, 6],
+    [12, 13],
+    [13, 4],
+    [13, 9],
+    [13, 15],
+    [14, 1],
+    [14, 7],
+    [14, 12],
+    [15, 10]
+  ]
+}

package/templates/minesweeper/index.html

@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no, viewport-fit=cover" />
+    <title>__DISPLAY_NAME__</title>
+    <link rel="stylesheet" href="./src/style.css" />
+  </head>
+  <body>
+    <main>
+      <div class="hud">
+        <span id="hudLeft">0 mines</span>
+        <span id="hudRight">0 flags</span>
+      </div>
+      <div id="board" class="board" aria-label="minesweeper board"></div>
+    </main>
+    <script type="module" src="./src/main.ts"></script>
+  </body>
+</html>

package/templates/minesweeper/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "__SLUG__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@puzzmo/sdk": "*"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vite": "^5.4.0"
+  }
+}

package/templates/minesweeper/puzzmo.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://dev.puzzmo.com/schema/puzzmo-file-schema.json",
+  "game": {
+    "displayName": "__DISPLAY_NAME__",
+    "slug": "__SLUG__",
+    "teamID": "REPLACE_ME"
+  },
+  "output": {
+    "dir": "dist"
+  }
+}