@puzzmo/cli 1.0.51 → 1.0.53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@puzzmo/cli",
-  "version": "1.0.51",
+  "version": "1.0.53",
   "type": "module",
   "bin": {
     "puzzmo": "./lib/index.js"

package/schemas/puzzmo-file-schema.json

@@ -51,7 +51,7 @@
           },
           "required": ["dir"],
           "additionalProperties": false,
-          "description": "Where the built game artifacts live for this game. Used by `puzzmo upload` and `puzzmo validate` to find the dist folder when running from a repo root. If omitted, the CLI looks for a `dist`, `build`, or `built` folder — first next to puzzmo.json, then walking up to the repo root, optionally with `<slug>` as a sub-folder for shared output dirs."
+          "description": "Where the built game artifacts live for this game. Used by `puzzmo games upload` and `puzzmo games validate` to find the dist folder when running from a repo root. If omitted, the CLI looks for a `dist`, `build`, or `built` folder — first next to puzzmo.json, then walking up to the repo root, optionally with `<slug>` as a sub-folder for shared output dirs."
         }
       },
       "required": ["game"],

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/upload.ts

@@ -164,6 +164,8 @@ const uploadOneGame = async (game: DiscoveredGame, opts: UploadOneOptions): Prom
   for (const file of files) totalBytes += fs.statSync(file).size
   console.log(`  ${plural(files.length, "file")}, ${formatBytes(totalBytes)} (sha ${sha.slice(0, 8)})`)
 
+  warnAboutAbsoluteScriptURLs(distDir)
+
   const result = await uploadFiles(
     apiURL,
     credential.token,
@@ -377,6 +379,34 @@ const maybeCreateMissingGame = async (
   }
 }
 
+/**
+ * Warns when dist/index.html loads its JS via absolute URLs. Games are served from a per-version subpath
+ * (e.g. puzzmousercontent.com/assets/<hash>/...), so a "/assets/foo.js" src resolves to the host root and 404s.
+ * The fix is a relative base — e.g. `base: "./"` in vite.config.ts — so srcs become "./assets/foo.js".
+ */
+const warnAboutAbsoluteScriptURLs = (distDir: string): void => {
+  const indexPath = path.join(distDir, "index.html")
+  if (!fs.existsSync(indexPath)) return
+
+  const html = fs.readFileSync(indexPath, "utf-8")
+  const offenders: string[] = []
+  const scriptRe = /<script\b[^>]*\bsrc\s*=\s*["']([^"']+)["']/gi
+  let match: RegExpExecArray | null
+  while ((match = scriptRe.exec(html)) !== null) {
+    if (isAbsoluteAssetURL(match[1])) offenders.push(match[1])
+  }
+  if (!offenders.length) return
+
+  console.log(yellow(`  Warning: index.html loads JS via absolute URLs, which will break as game is served from a subpath:`))
+  for (const url of offenders) console.log(yellow(`      ${url}`))
+  console.log(
+    yellow(`    Use relative paths instead — set \`base: "./"\` in your vite.config.ts (or your bundler's equivalent) and rebuild.`),
+  )
+}
+
+/** True for URLs that resolve outside the game's own folder: site-root ("/x"), protocol-relative ("//x"), or fully-qualified ("https://x"). */
+const isAbsoluteAssetURL = (url: string): boolean => url.startsWith("/") || /^[a-z][a-z0-9+.-]*:\/\//i.test(url)
+
 /** Formats a byte count as a human-readable string */
 const formatBytes = (bytes: number): string => {
   if (bytes < 1024) return `${bytes} B`

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(),