@puzzmo/cli 1.0.38 → 1.0.40

package/src/util/api.ts

@@ -19,6 +19,17 @@ export type PuzzmoFile = {
 
 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 }
@@ -108,9 +119,17 @@ const uploadFile = async (url: string, token: string, filePath: string, baseDir:
     step,
     verbose,
   )
+  if (res.status === 413) throw new Error(`File ${relativePath} is too large to upload (${formatBytes(content.length)})`)
   return (await readResponse(res, fullURL, step, verbose)) as FileResponse
 }
 
+/** Formats a byte count as a human-readable string (e.g. "1.6 MB") */
+const formatBytes = (bytes: number): string => {
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}
+
 /** Multi-step upload: init -> batched file uploads -> complete */
 export const uploadFiles = async (
   token: string,
@@ -127,13 +146,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/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,18 @@
+{
+  "name": "__SLUG__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@puzzmo/cli": "*",
+    "@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"
+  }
+}

package/templates/minesweeper/src/appBundle.ts

@@ -0,0 +1,122 @@
+import type { AppBundle, ThumbnailConfig } from "@puzzmo/sdk"
+import { svgFontFaceCSSRaw } from "@puzzmo/sdk/fonts"
+import { createEncoder, defineSchema } from "@puzzmo/sdk/inputs"
+
+type Puzzle = { rows: number; cols: number; mines: [number, number][] }
+type State = { revealed: boolean[]; flagged: boolean[] }
+
+/** Mirrors the schema in src/main.ts so a saved input string round-trips here too. */
+const stateSchema = defineSchema<State>({
+  version: 1,
+  fields: {
+    revealed: { type: "bitArray" },
+    flagged: { type: "bitArray" },
+  },
+})
+
+const escapeXml = (s: string) => s.replace(/[<>&"']/g, (c) => `&#${c.charCodeAt(0)};`)
+
+/**
+ * Renders a small SVG preview of the puzzle. When an `inputStr` is supplied the
+ * preview reflects the player's progress; otherwise it shows a blank board.
+ *
+ * The host renders this in lists/share cards/completion screens — there's no DOM,
+ * no animation, no theme variables. We bake colors from `config.theme` directly.
+ */
+export const renderThumbnail: AppBundle["renderThumbnail"] = (puzzleStr: string, inputStr?: string, config?: ThumbnailConfig): string => {
+  const puzzle = JSON.parse(puzzleStr) as Puzzle
+  const { rows, cols } = puzzle
+  const cells = rows * cols
+  const mineSet = new Set(puzzle.mines.map(([r, c]) => r * cols + c))
+
+  let revealed: boolean[] = new Array(cells).fill(false)
+  let flagged: boolean[] = new Array(cells).fill(false)
+
+  if (inputStr) {
+    try {
+      const codec = createEncoder(stateSchema, { revealed: { length: cells }, flagged: { length: cells } })
+      const decoded = codec.decode(codec.migrate(inputStr))
+      revealed = decoded.revealed
+      flagged = decoded.flagged
+    } catch {
+      // Bad/old state: fall back to a blank thumbnail.
+    }
+  }
+
+  const theme = config?.theme
+  const bg = theme?.a_bg ?? "#1a1a1a"
+  const cellHidden = theme?.g_unsolved ?? "#3a3a3a"
+  const cellShown = theme?.g_bg ?? "#1f1f1f"
+  const border = theme?.g_outline ?? "#4a4a4a"
+  const mineColor = theme?.error ?? "#ff5555"
+  const flagColor = theme?.subBrand ?? "#ffaa55"
+  const numberColor = theme?.g_textDark ?? "#1b1b28"
+
+  const size = 200
+  const pad = 4
+  const gap = 1
+  const cellW = (size - pad * 2 - gap * (cols - 1)) / cols
+  const cellH = (size - pad * 2 - gap * (rows - 1)) / rows
+
+  const parts: string[] = []
+  parts.push(`<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="0 0 ${size} ${size}">`)
+  // Embed the @font-face rule so the SVG renders with Puzzmo's bundled font
+  // even outside the game (host previews, share cards, opengraph).
+  parts.push(`<style>${svgFontFaceCSSRaw(["RedHatMono-Bold"])}</style>`)
+  parts.push(`<rect width="${size}" height="${size}" fill="${escapeXml(bg)}"/>`)
+
+  for (let i = 0; i < cells; i++) {
+    const r = Math.floor(i / cols)
+    const c = i % cols
+    const x = pad + c * (cellW + gap)
+    const y = pad + r * (cellH + gap)
+    const isRevealed = revealed[i]
+    const fill = isRevealed ? cellShown : cellHidden
+    parts.push(
+      `<rect x="${x.toFixed(2)}" y="${y.toFixed(2)}" width="${cellW.toFixed(2)}" height="${cellH.toFixed(2)}" fill="${escapeXml(fill)}" stroke="${escapeXml(border)}" stroke-width="0.5"/>`,
+    )
+
+    if (isRevealed && mineSet.has(i)) {
+      const cx = x + cellW / 2
+      const cy = y + cellH / 2
+      const rad = Math.min(cellW, cellH) * 0.25
+      parts.push(`<circle cx="${cx.toFixed(2)}" cy="${cy.toFixed(2)}" r="${rad.toFixed(2)}" fill="${escapeXml(mineColor)}"/>`)
+    } else if (isRevealed && !mineSet.has(i)) {
+      const n = countAdjacent(mineSet, i, rows, cols)
+      if (n > 0) {
+        const cx = x + cellW / 2
+        const cy = y + cellH / 2 + cellH * 0.32
+        const fontSize = Math.min(cellW, cellH) * 0.7
+        parts.push(
+          `<text x="${cx.toFixed(2)}" y="${cy.toFixed(2)}" text-anchor="middle" font-family="RedHatMono-Bold, ui-monospace, monospace" font-size="${fontSize.toFixed(1)}" font-weight="700" fill="${escapeXml(numberColor)}">${n}</text>`,
+        )
+      }
+    } else if (flagged[i]) {
+      const cx = x + cellW / 2
+      const cy = y + cellH / 2 + cellH * 0.32
+      const fontSize = Math.min(cellW, cellH) * 0.7
+      parts.push(
+        `<text x="${cx.toFixed(2)}" y="${cy.toFixed(2)}" text-anchor="middle" font-family="RedHatMono-Bold, ui-monospace, monospace" font-size="${fontSize.toFixed(1)}" fill="${escapeXml(flagColor)}">⚑</text>`,
+      )
+    }
+  }
+
+  parts.push(`</svg>`)
+  return parts.join("")
+}
+
+const countAdjacent = (mineSet: Set<number>, i: number, rows: number, cols: number): number => {
+  const r = Math.floor(i / cols)
+  const c = i % cols
+  let n = 0
+  for (let dr = -1; dr <= 1; dr++) {
+    for (let dc = -1; dc <= 1; dc++) {
+      if (dr === 0 && dc === 0) continue
+      const nr = r + dr
+      const nc = c + dc
+      if (nr < 0 || nr >= rows || nc < 0 || nc >= cols) continue
+      if (mineSet.has(nr * cols + nc)) n++
+    }
+  }
+  return n
+}

package/templates/minesweeper/src/main.ts

@@ -0,0 +1,236 @@
+import { createPuzzmoSDK, type Theme } from "@puzzmo/sdk"
+import { createEncoder, defineSchema, type EncoderResult } from "@puzzmo/sdk/inputs"
+
+/** Decoded puzzle definition shipped from the host. The host serializes this as JSON. */
+type Puzzle = { rows: number; cols: number; mines: [number, number][] }
+
+/** Persisted player progress. `won` is derived, not stored. */
+type State = { revealed: boolean[]; flagged: boolean[] }
+
+const MINE_PENALTY_MS = 60_000
+
+/**
+ * Schema for serializing per-cell boolean state. `bitArray` packs 4 cells per hex char,
+ * so a 16x16 board ≈ 64 chars instead of a multi-kilobyte JSON blob.
+ */
+const stateSchema = defineSchema<State>({
+  version: 1,
+  fields: {
+    revealed: { type: "bitArray" },
+    flagged: { type: "bitArray" },
+  },
+})
+
+/**
+ * Construct the host SDK. Resolves messaging with the embed, manages the timer, and
+ * surfaces lifecycle events ("start", "settingsUpdate", etc.).
+ */
+const sdk = createPuzzmoSDK()
+
+const boardEl = document.getElementById("board")!
+const hudLeftEl = document.getElementById("hudLeft")!
+const hudRightEl = document.getElementById("hudRight")!
+
+let puzzle: Puzzle = { rows: 9, cols: 9, mines: [] }
+let state: State = { revealed: [], flagged: [] }
+let mineSet = new Set<number>()
+let stateCodec: EncoderResult<State> | null = null
+let won = false
+
+/** Maps the Puzzmo Theme onto the CSS custom properties consumed by style.css. */
+const applyTheme = (theme: Theme) => {
+  const r = document.documentElement.style
+  r.setProperty("--bg", theme.a_bg)
+  r.setProperty("--panel", theme.a_infoBG)
+  r.setProperty("--cell", theme.g_unsolved)
+  r.setProperty("--cell-revealed", theme.g_bg)
+  r.setProperty("--border", theme.g_outline)
+  r.setProperty("--text", theme.fg)
+  r.setProperty("--text-on-cell", theme.g_textDark)
+  r.setProperty("--accent", theme.key)
+  r.setProperty("--mine", theme.error)
+  r.setProperty("--flag", theme.subBrand)
+  r.setProperty("--n1", theme.player)
+  r.setProperty("--n2", theme.alt1)
+  r.setProperty("--n3", theme.alt2)
+  r.setProperty("--n4", theme.alt3)
+  r.setProperty("--n5", theme.error)
+  r.setProperty("--n6", theme.keyStrong)
+  r.setProperty("--n7", theme.playerLight)
+  r.setProperty("--n8", theme.alwaysDark)
+}
+
+const idx = (r: number, c: number) => r * puzzle.cols + c
+
+const neighbours = (i: number): number[] => {
+  const r = Math.floor(i / puzzle.cols)
+  const c = i % puzzle.cols
+  const out: number[] = []
+  for (let dr = -1; dr <= 1; dr++) {
+    for (let dc = -1; dc <= 1; dc++) {
+      if (dr === 0 && dc === 0) continue
+      const nr = r + dr
+      const nc = c + dc
+      if (nr < 0 || nr >= puzzle.rows || nc < 0 || nc >= puzzle.cols) continue
+      out.push(idx(nr, nc))
+    }
+  }
+  return out
+}
+
+const countAdjacentMines = (i: number) => neighbours(i).filter((n) => mineSet.has(n)).length
+
+const reveal = (i: number, isUserClick: boolean) => {
+  if (state.revealed[i] || state.flagged[i]) return
+  state.revealed[i] = true
+  if (mineSet.has(i)) {
+    /**
+     * `addPenalty(ms)` adds to the timer's tracked "added time", surfaced separately
+     * in `display()` and reported via `gameCompleted({ additionalTimeAddedSecs })`.
+     */
+    if (isUserClick) sdk.timer.addPenalty(MINE_PENALTY_MS)
+    return
+  }
+  if (countAdjacentMines(i) === 0) for (const n of neighbours(i)) reveal(n, false)
+}
+
+const checkWin = () => {
+  const safe = puzzle.rows * puzzle.cols - mineSet.size
+  let revealedSafe = 0
+  for (let i = 0; i < state.revealed.length; i++) if (state.revealed[i] && !mineSet.has(i)) revealedSafe++
+  if (revealedSafe === safe) won = true
+}
+
+const flaggedCount = () => state.flagged.reduce((acc, v) => acc + (v ? 1 : 0), 0)
+
+const render = () => {
+  boardEl.innerHTML = ""
+  for (let i = 0; i < puzzle.rows * puzzle.cols; i++) {
+    const cell = document.createElement("button")
+    cell.className = "cell"
+    cell.dataset.i = String(i)
+    if (state.revealed[i]) {
+      cell.classList.add("revealed")
+      if (mineSet.has(i)) {
+        cell.classList.add("mine")
+        cell.textContent = "✸"
+      } else {
+        const n = countAdjacentMines(i)
+        if (n > 0) {
+          cell.dataset.n = String(n)
+          cell.textContent = String(n)
+        }
+      }
+    } else if (state.flagged[i]) {
+      cell.classList.add("flagged")
+      cell.textContent = "⚑"
+    }
+    boardEl.appendChild(cell)
+  }
+  if (won) {
+    hudLeftEl.textContent = "completed"
+    hudRightEl.textContent = ""
+  } else {
+    hudLeftEl.textContent = `${mineSet.size} mines`
+    hudRightEl.textContent = `${flaggedCount()} flags`
+  }
+}
+
+/**
+ * Called once on win. Reports gameplay metrics back to the host via:
+ * - `sdk.gameCompleted(gameplay, augmentations)` — durable record + deeds
+ * - `sdk.showCompletionScreen(content, gameplay, completed)` — the host's win UI
+ */
+const onComplete = () => {
+  const elapsed = Math.round(sdk.timer.timeSecs())
+  const penalty = Math.round(sdk.timer.addedTimeSecs())
+  const data = { elapsedTimeSecs: elapsed, additionalTimeAddedSecs: penalty, pointsAwarded: 0, completed: true }
+  sdk.gameCompleted(data, { deeds: [] })
+  sdk.showCompletionScreen([{ type: "md", text: penalty > 0 ? `**Cleared!** With ${penalty}s in penalties.` : "**Cleared!**" }], data, true)
+}
+
+const persistState = () => {
+  if (!stateCodec) return
+  /**
+   * `sdk.updateGameState(string)` ships an opaque string back to the host so progress
+   * survives a reload. We use the SDK's input encoder for compactness over JSON.
+   */
+  sdk.updateGameState(stateCodec.encode(state))
+}
+
+const handleClick = (e: MouseEvent) => {
+  const target = e.target as HTMLElement
+  if (!target.classList.contains("cell")) return
+  if (won) return
+  const i = Number(target.dataset.i)
+  if (e.shiftKey || e.button === 2) {
+    if (!state.revealed[i]) state.flagged[i] = !state.flagged[i]
+  } else {
+    reveal(i, true)
+    checkWin()
+  }
+  persistState()
+  render()
+  if (won) onComplete()
+}
+
+const blankState = (cells: number): State => ({ revealed: new Array(cells).fill(false), flagged: new Array(cells).fill(false) })
+
+const setupBoard = (data: Puzzle, savedState?: State) => {
+  puzzle = data
+  mineSet = new Set(data.mines.map(([r, c]) => idx(r, c)))
+  const cells = data.rows * data.cols
+  state = savedState ?? blankState(cells)
+  /**
+   * `bitArray` requires each field's length in the encoder context to round-trip
+   * correctly. We rebuild the codec whenever the board dimensions change.
+   */
+  stateCodec = createEncoder(stateSchema, {
+    revealed: { length: cells },
+    flagged: { length: cells },
+  })
+  won = false
+  // Publish board dimensions to CSS so grid tracks + cell font-size scale purely from the stylesheet.
+  boardEl.style.setProperty("--cols", String(data.cols))
+  boardEl.style.setProperty("--rows", String(data.rows))
+  checkWin()
+  render()
+}
+
+/**
+ * Lifecycle entrypoint:
+ * - `sdk.gameReady()` blocks until the host sends puzzle/state/theme.
+ * - `sdk.gameLoaded()` tells the host we're done bootstrapping; the host will
+ * then dispatch `start` (or restore a paused session).
+ */
+const init = async () => {
+  const { puzzleString, inputString, theme } = await sdk.gameReady()
+  if (theme) applyTheme(theme)
+  const parsed = puzzleString ? (JSON.parse(puzzleString) as Puzzle) : puzzle
+  const cells = parsed.rows * parsed.cols
+  /**
+   * Decode prior progress with the encoder so older save formats can be migrated
+   * via the schema's `migrations` map (none yet, but wired up for free).
+   */
+  const tempCodec = createEncoder(stateSchema, { revealed: { length: cells }, flagged: { length: cells } })
+  const saved = inputString ? (tempCodec.decode(tempCodec.migrate(inputString)) as State) : undefined
+  setupBoard(parsed, saved)
+  sdk.gameLoaded()
+}
+
+sdk.on("start", () => {
+  render()
+})
+
+/** The host re-emits its theme (and other settings) when the player toggles light/dark. */
+sdk.on("settingsUpdate", (data: { theme?: Theme }) => {
+  if (data?.theme) applyTheme(data.theme)
+})
+
+boardEl.addEventListener("click", handleClick)
+boardEl.addEventListener("contextmenu", (e) => {
+  e.preventDefault()
+  handleClick(e)
+})
+
+init()