@puzzmo/cli 1.0.36 → 1.0.38

package/lib/util/discoverGames.js

@@ -0,0 +1,181 @@
+import fs from "node:fs";
+import path from "node:path";
+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"];
+/** Walks `rootDir` looking for puzzmo.json files, validates each, and resolves their dist directory */
+export const discoverGames = async (rootDir) => {
+    const root = path.resolve(rootDir);
+    const puzzmoJsonPaths = findPuzzmoJsonFiles(root);
+    const games = [];
+    const errors = [];
+    for (const puzzmoJsonPath of puzzmoJsonPaths) {
+        const fileErrors = [];
+        let parsed;
+        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 });
+    }
+    return { games, errors };
+};
+/** Recursively finds puzzmo.json files under `dir`, skipping output / vendored folders. Tracks realpaths to avoid symlink cycles. */
+const findPuzzmoJsonFiles = (dir) => {
+    const found = [];
+    const visited = new Set();
+    const stack = [dir];
+    while (stack.length) {
+        const current = stack.pop();
+        const realCurrent = safeRealpath(current);
+        if (!realCurrent || visited.has(realCurrent))
+            continue;
+        visited.add(realCurrent);
+        let entries;
+        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, puzzmoJsonDir, repoRoot) => {
+    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, stop) => {
+    const dirs = [];
+    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, visited = new Set()) => {
+    const realDir = safeRealpath(dir);
+    if (!realDir || visited.has(realDir))
+        return false;
+    visited.add(realDir);
+    let entries;
+    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, fullPath) => {
+    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) => {
+    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) => {
+    if (!parsed || typeof parsed !== "object")
+        return undefined;
+    const game = parsed.game;
+    if (!game || typeof game !== "object")
+        return undefined;
+    const slug = game.slug;
+    return typeof slug === "string" ? slug : undefined;
+};
+//# sourceMappingURL=discoverGames.js.map

package/lib/util/discoverGames.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discoverGames.js","sourceRoot":"","sources":["../../src/util/discoverGames.ts"],"names":[],"mappings":"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"}

package/lib/util/validatePuzzmoFile.d.ts

@@ -6,6 +6,6 @@ type ValidationResult = {
     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 declare const validatePuzzmoJson: (data: unknown) => Promise<ValidationResult>;
 export {};

package/lib/util/validatePuzzmoFile.js

@@ -27,13 +27,13 @@ const getValidator = async () => {
     cachedValidator = new Validator(puzzmoSchema, "7");
     return cachedValidator;
 };
-/** 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) => {
     const validator = await getValidator();
     const toValidate = stripSchemaProperty(data);
     const result = validator.validate(toValidate);
     if (result.valid)
-        return { valid: true, data: data };
+        return { valid: true, data: toValidate };
     return {
         valid: false,
         errors: result.errors

package/lib/util/validatePuzzmoFile.js.map

@@ -1 +1 @@
-{"version":3,"file":"validatePuzzmoFile.js","sourceRoot":"","sources":["../../src/util/validatePuzzmoFile.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"validatePuzzmoFile.js","sourceRoot":"","sources":["../../src/util/validatePuzzmoFile.ts"],"names":[],"mappings":"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"}

package/package.json

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

package/src/commands/upload.ts

@@ -5,13 +5,30 @@ import path from "node:path"
 
 import { uploadFiles } from "../util/api.js"
 import { getAPIURL, getToken } from "../util/config.js"
-import { validatePuzzmoJson } from "../util/validatePuzzmoFile.js"
+import { discoverGames, type DiscoveredGame } from "../util/discoverGames.js"
 
 type UploadOptions = {
   verbose?: boolean
 }
 
-/** Uploads game build artifacts to Puzzmo */
+type GameSuccess = {
+  ok: true
+  slug: string
+  fileCount: number
+  totalBytes: number
+  versionID: string
+  assetsBase: string
+}
+
+type GameFailure = {
+  ok: false
+  slug: string
+  error: string
+}
+
+type GameResult = GameSuccess | GameFailure
+
+/** Uploads game build artifacts to Puzzmo by discovering puzzmo.json files in `dir` */
 export const upload = async (dir: string, options: UploadOptions = {}) => {
   const { verbose = false } = options
   const token = getToken()
@@ -20,64 +37,87 @@ export const upload = async (dir: string, options: UploadOptions = {}) => {
     process.exit(1)
   }
 
-  const distDir = path.resolve(dir)
-  if (!fs.existsSync(distDir)) {
+  const rootDir = path.resolve(dir)
+  if (!fs.existsSync(rootDir)) {
     console.error(`Directory not found: ${dir}`)
     process.exit(1)
   }
 
-  const files = collectFiles(distDir)
-  if (!files.length) {
-    console.error(`Directory is empty: ${dir}`)
+  const { games, errors: discoveryErrors } = await discoverGames(rootDir)
+
+  if (!games.length && !discoveryErrors.length) {
+    console.error(`No puzzmo.json files found under ${rootDir}`)
     process.exit(1)
   }
 
-  // Require and validate puzzmo.json
-  const puzzmoJsonPath = path.join(distDir, "puzzmo.json")
-  if (!fs.existsSync(puzzmoJsonPath)) {
-    console.error(`Missing puzzmo.json in ${dir}`)
-    console.error("Every game upload must include a puzzmo.json file.")
-    process.exit(1)
+  console.log(`Found ${games.length} game(s) under ${rootDir}`)
+  for (const game of games) {
+    console.log(`  - ${game.puzzmoFile.game.slug} (${path.relative(rootDir, game.distDir) || "."})`)
+  }
+  if (discoveryErrors.length) {
+    console.log(`\n${discoveryErrors.length} puzzmo.json file(s) could not be loaded:`)
+    for (const err of discoveryErrors) {
+      console.log(`  - ${err.slug ?? path.relative(rootDir, err.puzzmoJsonPath)}`)
+      for (const e of err.errors) console.log(`      ${e}`)
+    }
   }
 
-  let parsed: unknown
-  try {
-    parsed = JSON.parse(fs.readFileSync(puzzmoJsonPath, "utf-8"))
-  } catch (e) {
-    console.error(`Invalid puzzmo.json: ${e instanceof Error ? e.message : e}`)
-    process.exit(1)
+  const sha = getGitSHA(rootDir) || hashGames(games)
+  const description = getGitMessage(rootDir)
+  const repoURL = getGitRepoURL(rootDir)
+  if (description) console.log(`\nMessage: ${description}`)
+  if (repoURL) console.log(`Repo: ${repoURL}`)
+
+  const apiURL = getAPIURL()
+  const defaultURL = "https://api.puzzmo.com"
+  if (apiURL !== defaultURL) console.log(`API: ${apiURL}`)
+
+  const results: GameResult[] = []
+  for (const err of discoveryErrors) {
+    results.push({ ok: false, slug: err.slug ?? path.relative(rootDir, err.puzzmoJsonPath), error: err.errors.join("; ") })
   }
 
-  const validation = await validatePuzzmoJson(parsed)
-  if (!validation.valid) {
-    console.error(`Invalid puzzmo.json:\n`)
-    for (const err of validation.errors) console.error(`  ${err}`)
-    process.exit(1)
+  for (let i = 0; i < games.length; i++) {
+    const game = games[i]
+    console.log(`\n[${i + 1}/${games.length}] Uploading ${game.puzzmoFile.game.slug}`)
+    try {
+      const result = await uploadOneGame(game, { token, sha, description, repoURL, verbose, rootDir })
+      results.push(result)
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e)
+      console.error(`  Failed: ${message}`)
+      results.push({ ok: false, slug: game.puzzmoFile.game.slug, error: message })
+    }
   }
-  const puzzmoFile = validation.data
-  const gameSlug = puzzmoFile.game.slug
 
-  // Determine SHA
-  const sha = getGitSHA() || hashFiles(files)
+  printReport(results)
 
-  console.log(`\nUploading ${gameSlug} (${sha.slice(0, 8)})`)
-  console.log(`Directory: ${distDir}`)
-  console.log("")
+  const anyFailed = results.some((r) => !r.ok)
+  if (anyFailed) process.exit(1)
+}
 
-  let totalBytes = 0
-  for (const file of files) {
-    const size = fs.statSync(file).size
-    totalBytes += size
-    const rel = path.relative(distDir, file)
-    console.log(`  ${rel} (${formatBytes(size)})`)
-  }
+type UploadOneOptions = {
+  token: string
+  sha: string
+  description: string | null
+  repoURL: string | null
+  verbose: boolean
+  rootDir: string
+}
 
-  const apiURL = getAPIURL()
-  const defaultURL = "https://api.puzzmo.com"
+/** Uploads a single discovered game; throws on failure */
+const uploadOneGame = async (game: DiscoveredGame, opts: UploadOneOptions): Promise<GameSuccess> => {
+  const { token, sha, description, repoURL, verbose, rootDir } = opts
+  const { puzzmoFile, distDir } = game
+  const gameSlug = puzzmoFile.game.slug
+
+  const files = collectFiles(distDir)
+  if (!files.length) throw new Error(`Dist folder is empty: ${distDir}`)
 
-  console.log(`\n${files.length} file(s), ${formatBytes(totalBytes)} total`)
-  if (apiURL !== defaultURL) console.log(`Uploading to ${apiURL}...`)
-  else console.log("Uploading...")
+  console.log(`  Directory: ${path.relative(rootDir, distDir) || distDir}`)
+  let totalBytes = 0
+  for (const file of files) totalBytes += fs.statSync(file).size
+  console.log(`  ${files.length} file(s), ${formatBytes(totalBytes)} total (sha ${sha.slice(0, 8)})`)
 
   const result = await uploadFiles(
     token,
@@ -87,13 +127,34 @@ export const upload = async (dir: string, options: UploadOptions = {}) => {
     distDir,
     puzzmoFile,
     (batch, totalBatches, uploaded) => {
-      console.log(`  Batch ${batch}/${totalBatches} done (${uploaded} file(s) uploaded)`)
+      console.log(`    Batch ${batch}/${totalBatches} done (${uploaded} file(s) uploaded)`)
     },
-    { verbose },
+    { verbose, description, repoURL },
   )
 
-  console.log(`\nDone - ${result.versionID}`)
-  console.log(`Assets: ${result.assetsBase}`)
+  console.log(`  Done - ${result.versionID}`)
+  return {
+    ok: true,
+    slug: gameSlug,
+    fileCount: files.length,
+    totalBytes,
+    versionID: result.versionID,
+    assetsBase: result.assetsBase,
+  }
+}
+
+/** Prints a final summary of every game's outcome */
+const printReport = (results: GameResult[]) => {
+  console.log(`\nUpload report (${results.length} game${results.length === 1 ? "" : "s"})`)
+  const successes = results.filter((r): r is GameSuccess => r.ok)
+  const failures = results.filter((r): r is GameFailure => !r.ok)
+  for (const r of successes) {
+    console.log(`  OK   ${r.slug.padEnd(24)} ${formatBytes(r.totalBytes).padStart(8)}  ${r.versionID}`)
+  }
+  for (const r of failures) {
+    console.log(`  FAIL ${r.slug.padEnd(24)} ${r.error}`)
+  }
+  console.log(`\n${successes.length} succeeded, ${failures.length} failed`)
 }
 
 /** Collects all files in a directory recursively */
@@ -109,19 +170,54 @@ const collectFiles = (dir: string): string[] => {
 }
 
 /** Tries to get the shortest unique git SHA, returns null if not in a git repo */
-const getGitSHA = (): string | null => {
+const getGitSHA = (cwd: string): string | null => {
   try {
-    return execSync("git rev-parse --short HEAD", { encoding: "utf-8" }).trim()
+    return execSync("git rev-parse --short HEAD", { encoding: "utf-8", cwd }).trim()
   } catch {
     return null
   }
 }
 
-/** Hashes all file contents to produce a deterministic SHA */
-const hashFiles = (filePaths: string[]): string => {
+/** Gets the subject line of the latest commit, or null if not in a git repo */
+const getGitMessage = (cwd: string): string | null => {
+  try {
+    return execSync("git log -1 --pretty=%s", { encoding: "utf-8", cwd }).trim() || null
+  } catch {
+    return null
+  }
+}
+
+/** Gets the origin remote URL normalized to https, or null if unavailable */
+const getGitRepoURL = (cwd: string): string | null => {
+  try {
+    const raw = execSync("git config --get remote.origin.url", { encoding: "utf-8", cwd }).trim()
+    return raw ? normalizeRepoURL(raw) : null
+  } catch {
+    return null
+  }
+}
+
+/** Converts SSH-style git URLs to https; strips trailing .git */
+const normalizeRepoURL = (url: string): string => {
+  let normalized = url
+  // git@host:owner/repo(.git) -> https://host/owner/repo
+  const sshMatch = normalized.match(/^git@([^:]+):(.+)$/)
+  if (sshMatch) normalized = `https://${sshMatch[1]}/${sshMatch[2]}`
+  // ssh://git@host/owner/repo(.git) -> https://host/owner/repo
+  else if (normalized.startsWith("ssh://")) normalized = normalized.replace(/^ssh:\/\/(?:[^@]+@)?/, "https://")
+  // git://host/owner/repo(.git) -> https://host/owner/repo
+  else if (normalized.startsWith("git://")) normalized = normalized.replace(/^git:\/\//, "https://")
+  return normalized.replace(/\.git$/, "")
+}
+
+/** Hashes the dist contents of every game to produce a deterministic SHA across all uploads */
+const hashGames = (games: DiscoveredGame[]): string => {
   const hash = crypto.createHash("sha256")
-  for (const fp of filePaths.sort()) {
-    hash.update(fs.readFileSync(fp))
+  for (const game of games) {
+    for (const file of collectFiles(game.distDir).sort()) {
+      hash.update(file)
+      hash.update(fs.readFileSync(file))
+    }
   }
   return hash.digest("hex").slice(0, 12)
 }

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.
+  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
     }

package/src/util/api.ts

@@ -10,7 +10,11 @@ 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
@@ -25,6 +29,10 @@ export type UploadProgress = (batch: number, totalBatches: number, uploaded: num
 /** Options for uploadFiles */
 export type UploadFilesOptions = {
   verbose?: boolean
+  /** Commit message subject for the new GameRuntimeVersion */
+  description?: string | null
+  /** HTTPS repo URL to set on the GameRuntime */
+  repoURL?: string | null
 }
 
 /** Wraps fetch to surface the underlying network cause (DNS, ECONNREFUSED, TLS, etc.) */
@@ -56,9 +64,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
 }
@@ -112,12 +122,18 @@ export const uploadFiles = async (
   onProgress?: UploadProgress,
   options: UploadFilesOptions = {},
 ): Promise<CompleteResponse> => {
-  const { verbose = false } = options
+  const { verbose = false, description, repoURL } = options
   const apiURL = getAPIURL()
   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 }, "upload init", verbose)) as InitResponse
+  const init = (await jsonPost(
+    `${apiURL}/cliUpload`,
+    token,
+    { gameSlug, sha, puzzmoFile, description, repoURL },
+    "upload init",
+    verbose,
+  )) as InitResponse
   if (verbose) console.log(`  session: ${init.sessionID}`)
 
   // Step 2: Upload files in concurrent batches