From 6fb703727e79ce9fb3f09e925347849157d8858c Mon Sep 17 00:00:00 2001
From: David Sutherland <sutherland.dave@gmail.com>
Date: Thu, 27 Aug 2026 15:12:34 +0100
Subject: [PATCH 1/5] Adding validation to GameDetails objects

---
 docs/game/create.md           |  14 +-
 docs/game/details.md          |  26 +++-
 docs/game/ship.md             |   3 +
 src/commands/game/create.ts   |  38 ++++-
 src/commands/game/details.tsx |  20 ++-
 src/commands/game/ship.tsx    |  11 ++
 src/constants/godot.ts        |   5 +
 src/constants/index.ts        |   9 +-
 src/utils/index.ts            |   1 +
 src/utils/validation.ts       | 249 +++++++++++++++++++++++++++++++
 test/utils/validation.test.ts | 266 ++++++++++++++++++++++++++++++++++
 11 files changed, 624 insertions(+), 18 deletions(-)
 create mode 100644 src/constants/godot.ts
 create mode 100644 src/utils/validation.ts
 create mode 100644 test/utils/validation.test.ts

diff --git a/docs/game/create.md b/docs/game/create.md
index cafb95b1..6b4bd839 100644
--- a/docs/game/create.md
+++ b/docs/game/create.md
@@ -17,8 +17,11 @@ directory then you will need to use the `--force` flag to create a new game and
 overwrite this file with the config for the new game.
 
 ShipThis will detect the version of Godot you are using from your **project.godot**
-file. This can be changed with the [`shipthis game details`](/docs/reference/game/details)
-command.
+file. To set a different version, pass the `--gameEngineVersion` flag, or change it later
+with the [`shipthis game details`](/docs/reference/game/details) command.
+
+The CLI checks the values you pass. The rules are the same as the ones the
+[`shipthis game details`](/docs/reference/game/details) command applies.
 
 ## Example
 
@@ -28,8 +31,8 @@ command.
 
 ```help
 USAGE
-  $ shipthis game create [-f] [-q] [-a <value>] [-b <value>] [-e <value>] [-v <value>] [--gcpProjectId <value>]
-    [-c <value>] [-i <value>] [-l <value>] [-n <value>] [-s <value>] [-d true|false]
+  $ shipthis game create [-f] [-q] [-a <value>] [-b <value>] [-e godot] [-v <value>] [--gcpProjectId <value>] [-c
+    <value>] [-i <value>] [-l <value>] [-n <value>] [-s <value>] [-d true|false]
 
 FLAGS
   -a, --androidPackageName=<value>   Set the Android package name
@@ -37,7 +40,8 @@ FLAGS
   -c, --gcpServiceAccountId=<value>  Set the GCP service account ID
   -d, --useDemoCredentials=<option>  Use demo credentials for this project
                                      <options: true|false>
-  -e, --gameEngine=<value>           Set the game engine
+  -e, --gameEngine=<option>          Set the game engine
+                                     <options: godot>
   -f, --force
   -i, --iosBundleId=<value>          Set the iOS bundle ID
   -l, --liquidGlassIconPath=<value>  Set the Liquid Glass icon path
diff --git a/docs/game/details.md b/docs/game/details.md
index 1193776c..97e3e870 100644
--- a/docs/game/details.md
+++ b/docs/game/details.md
@@ -21,6 +21,27 @@ The following fields can only be changed if you have the `--force` flag set:
 After changing these values, you will need to trigger a new build of your game with [`shipthis game ship`](/docs/reference/game/ship)
 :::
 
+## Validation
+
+The CLI checks each value before it sends it to the server. A value the build server cannot
+use is reported here, in a second, rather than in a failed build minutes later.
+
+| Field | Rule |
+| --- | --- |
+| **name** | Not empty. 64 characters or less. |
+| **gameEngine** | `godot` only. |
+| **gameEngineVersion** | A supported Godot version, such as `4.2`. You can pin a patch, such as `4.2.1`. See [Godot versioning](/docs/guides/godot-versioning). |
+| **semanticVersion** | Three numbers, such as `1.2.3`. The App Store rejects a suffix such as `-beta`. See [versioning](/docs/guides/versioning). |
+| **buildNumber** | A whole number from 1 to 2100000000. The top value is the largest Google Play accepts as a versionCode. |
+| **androidPackageName** | Two or more segments, such as `com.mystudio.mygame`. Each segment starts with a letter and holds letters, numbers, and underscores only. See the [Android application ID rules](https://developer.android.com/build/configure-app-module#set-application-id). |
+| **iosBundleId** | The usual reverse-DNS form, such as `com.mystudio.mygame`. Letters, numbers, and hyphens only. See [CFBundleIdentifier](https://developer.apple.com/documentation/bundleresources/information-property-list/cfbundleidentifier). |
+| **liquidGlassIconPath** | A `.icon` folder that exists on your machine. See the [Liquid Glass guide](/docs/guides/liquid-glass). |
+
+The same checks run on [`shipthis game create`](/docs/reference/game/create), and on the
+`--gameEngineVersion` flag of [`shipthis game ship`](/docs/reference/game/ship).
+
+The **gcpProjectId** and **gcpServiceAccountId** fields are not checked here.
+
 ## Example
 
 [![asciicast](https://asciinema.org/a/5eIVmJYQ6MxDAlFVoVKXhGkYr.svg)](https://asciinema.org/a/5eIVmJYQ6MxDAlFVoVKXhGkYr)
@@ -29,7 +50,7 @@ After changing these values, you will need to trigger a new build of your game w
 
 ```help
 USAGE
-  $ shipthis game details [-g <value>] [-f] [-a <value>] [-b <value>] [-e <value>] [-v <value>] [--gcpProjectId
+  $ shipthis game details [-g <value>] [-f] [-a <value>] [-b <value>] [-e godot] [-v <value>] [--gcpProjectId
     <value>] [-c <value>] [-i <value>] [-l <value>] [-n <value>] [-s <value>] [-d true|false]
 
 FLAGS
@@ -38,7 +59,8 @@ FLAGS
   -c, --gcpServiceAccountId=<value>  Set the GCP service account ID
   -d, --useDemoCredentials=<option>  Use demo credentials for this project
                                      <options: true|false>
-  -e, --gameEngine=<value>           Set the game engine
+  -e, --gameEngine=<option>          Set the game engine
+                                     <options: godot>
   -f, --force                        Force the command to run
   -g, --gameId=<value>               The ID of the game
   -i, --iosBundleId=<value>          Set the iOS bundle ID
diff --git a/docs/game/ship.md b/docs/game/ship.md
index c9053e44..4665ea24 100644
--- a/docs/game/ship.md
+++ b/docs/game/ship.md
@@ -72,6 +72,9 @@ You can specify a different Godot version to use only for the current job. This
 shipthis game ship --platform android --follow --gameEngineVersion 4.5.1 --download game-4.5.1.aab
 ```
 
+The CLI checks this version before it builds the zip, so a typo stops the command in a second.
+See [Godot versioning](/docs/guides/godot-versioning) for the versions ShipThis supports.
+
 ## Help Output
 
 ```help
diff --git a/src/commands/game/create.ts b/src/commands/game/create.ts
index 2e9c1e5b..76894ab2 100644
--- a/src/commands/game/create.ts
+++ b/src/commands/game/create.ts
@@ -2,10 +2,16 @@ import {Flags} from '@oclif/core'
 
 import {createProject} from '@cli/api/index.js'
 import {BaseAuthenticatedCommand} from '@cli/baseCommands/index.js'
-import {DEFAULT_PLATFORM_GLOBS, DetailsFlags} from '@cli/constants/index.js'
+import {DEFAULT_PLATFORM_GLOBS, DetailsFlags, SUPPORTED_GODOT_VERSIONS} from '@cli/constants/index.js'
 import {GameEngine, ProjectDetails} from '@cli/types'
 import {getGodotProjectName, getGodotVersion, isCWDGodotGame} from '@cli/utils/godot.js'
-import {getInput} from '@cli/utils/index.js'
+import {
+  DetailsValues,
+  getDetailsWarnings,
+  getInput,
+  isSupportedGodotVersion,
+  validateDetailsValues,
+} from '@cli/utils/index.js'
 
 export default class GameCreate extends BaseAuthenticatedCommand<typeof GameCreate> {
   static override args = {}
@@ -25,6 +31,10 @@ export default class GameCreate extends BaseAuthenticatedCommand<typeof GameCrea
 
     const {force, name: flagName, quiet, ...details} = flags
 
+    this.validateOrError(details)
+
+    for (const warning of getDetailsWarnings(details)) this.warn(warning)
+
     if (this.hasProjectConfig() && !force) {
       throw new Error('This directory already has a ShipThis project. Use --force to overwrite.')
     }
@@ -41,9 +51,24 @@ export default class GameCreate extends BaseAuthenticatedCommand<typeof GameCrea
     }
 
     const name = await getName()
+    this.validateOrError({name})
 
     const gameEngine = GameEngine.GODOT
-    const gameEngineVersion = getGodotVersion()
+
+    // A version the user typed is already checked above. A version we read from project.godot
+    // only warns - an older CLI can have a list that the build server has moved past, and a
+    // hard stop there would block a build the server can do.
+    const detectedVersion = getGodotVersion()
+    const gameEngineVersion = details.gameEngineVersion || detectedVersion
+
+    if (!details.gameEngineVersion && !isSupportedGodotVersion(detectedVersion)) {
+      this.warn(
+        `Your project.godot targets Godot ${detectedVersion}, which this version of ShipThis does not know about.\n` +
+          `If the build fails, pin a supported version:\n\n` +
+          `  shipthis game details --gameEngineVersion ${SUPPORTED_GODOT_VERSIONS.at(-1)} --force\n\n` +
+          `See https://shipth.is/docs/guides/godot-versioning`,
+      )
+    }
 
     const projectDetails: ProjectDetails = {
       ...details,
@@ -61,4 +86,11 @@ export default class GameCreate extends BaseAuthenticatedCommand<typeof GameCrea
 
     if (!flags.quiet) await this.config.runCommand('game:status')
   }
+
+  // Stops the command on the first bad value, with the docs link for that field.
+  private validateOrError(values: DetailsValues): void {
+    const error = validateDetailsValues(values)
+    if (!error) return
+    this.error(error.message, {exit: 1, ref: error.ref, suggestions: error.suggestions})
+  }
 }
diff --git a/src/commands/game/details.tsx b/src/commands/game/details.tsx
index 1684a192..c9b7613a 100644
--- a/src/commands/game/details.tsx
+++ b/src/commands/game/details.tsx
@@ -5,7 +5,7 @@ import {BaseGameCommand} from '@cli/baseCommands/index.js'
 import {Command, StatusTable} from '@cli/components/index.js'
 import {DetailsFlags} from '@cli/constants/index.js'
 import {GameEngine} from '@cli/types'
-import {isValidSemVer} from '@cli/utils/index.js'
+import {getDetailsWarnings, validateDetailsValues} from '@cli/utils/index.js'
 
 export default class GameDetails extends BaseGameCommand<typeof GameDetails> {
   static override args = {}
@@ -42,21 +42,29 @@ export default class GameDetails extends BaseGameCommand<typeof GameDetails> {
       useDemoCredentials,
     } = valueFlags
 
-    if (semanticVersion && !isValidSemVer(semanticVersion))
-      throw new Error(`Invalid semantic version: ${semanticVersion}`)
+    // The values are checked before the --force gate, so a user who typed a wrong value and
+    // left out --force sees both faults in one go.
+    const validationError = validateDetailsValues(valueFlags)
+    if (validationError) {
+      this.error(validationError.message, {
+        exit: 1,
+        ref: validationError.ref,
+        suggestions: validationError.suggestions,
+      })
+    }
+
+    for (const warning of getDetailsWarnings(valueFlags)) this.warn(warning)
 
     if ((gameEngine || gameEngineVersion || iosBundleId || androidPackageName) && !force)
       throw new Error('Use --force to set the restricted fields')
 
-    if (gameEngine && gameEngine !== GameEngine.GODOT) throw new Error(`Game engine ${gameEngine} not supported`)
-
     let game = await this.getGame()
 
     const update = {
       details: {
         ...game.details,
         ...(androidPackageName && {androidPackageName}),
-        ...(buildNumber && {buildNumber}),
+        ...(buildNumber !== undefined && {buildNumber}),
         ...(gameEngine && {gameEngine: gameEngine as GameEngine}),
         ...(gameEngineVersion && {gameEngineVersion}),
         ...(gcpProjectId !== undefined && {gcpProjectId}),
diff --git a/src/commands/game/ship.tsx b/src/commands/game/ship.tsx
index b3d2a4e9..1c0bae04 100644
--- a/src/commands/game/ship.tsx
+++ b/src/commands/game/ship.tsx
@@ -6,6 +6,7 @@ import {BaseGameCommand} from '@cli/baseCommands/baseGameCommand.js'
 import {CommandGame, Ship} from '@cli/components/index.js'
 import {Job} from '@cli/types/api.js'
 import {getErrorMessage} from '@cli/utils/errors.js'
+import {validateDetailsValues} from '@cli/utils/validation.js'
 
 export default class GameShip extends BaseGameCommand<typeof GameShip> {
   static override args = {}
@@ -78,6 +79,16 @@ export default class GameShip extends BaseGameCommand<typeof GameShip> {
   }
 
   public async run(): Promise<void> {
+    // Checked before the zip and the upload, so a typo costs no wait.
+    const validationError = validateDetailsValues({gameEngineVersion: this.flags.gameEngineVersion})
+    if (validationError) {
+      this.error(validationError.message, {
+        exit: 1,
+        ref: validationError.ref,
+        suggestions: validationError.suggestions,
+      })
+    }
+
     await this.ensureWeAreInAProjectDir()
     const gameId = this.getGameId()
     if (!gameId) {
diff --git a/src/constants/godot.ts b/src/constants/godot.ts
new file mode 100644
index 00000000..3b626996
--- /dev/null
+++ b/src/constants/godot.ts
@@ -0,0 +1,5 @@
+// The Godot major.minor versions the build server has export templates for.
+// The server picks the patch, so this list holds no patch numbers - a user can still
+// pin one, such as 4.2.1. Add an entry when ShipThis adds support for a Godot release.
+// https://shipth.is/docs/guides/godot-versioning
+export const SUPPORTED_GODOT_VERSIONS = ['3.6', '4.0', '4.1', '4.2', '4.3', '4.4', '4.5', '4.6', '4.7']
diff --git a/src/constants/index.ts b/src/constants/index.ts
index 792eb4ed..326bfd2f 100644
--- a/src/constants/index.ts
+++ b/src/constants/index.ts
@@ -2,11 +2,16 @@ import {Flags} from '@oclif/core'
 
 export * from './cacheKeys.js'
 export * from './config.js'
+export * from './godot.js'
 
 export const DetailsFlags = {
   androidPackageName: Flags.string({char: 'a', description: 'Set the Android package name'}),
-  buildNumber: Flags.integer({char: 'b', description: 'Set the build number'}),
-  gameEngine: Flags.string({char: 'e', description: 'Set the game engine'}),
+  // The range matches MIN_BUILD_NUMBER and MAX_BUILD_NUMBER in utils/validation.ts. The
+  // parser message carries no docs link, so the validator repeats the check.
+  buildNumber: Flags.integer({char: 'b', description: 'Set the build number', max: 2_100_000_000, min: 1}),
+  // The value is not imported from the GameEngine enum - importing types here has caused a
+  // circular import before (see the DetailsFlags fix in 4a7357f).
+  gameEngine: Flags.string({char: 'e', description: 'Set the game engine', options: ['godot']}),
   gameEngineVersion: Flags.string({char: 'v', description: 'Set the game engine version'}),
   // No short char: -g is reserved CLI-wide for --gameId (see BaseGameCommand)
   gcpProjectId: Flags.string({description: 'Set the GCP project ID'}),
diff --git a/src/utils/index.ts b/src/utils/index.ts
index 23e46f69..3e581279 100644
--- a/src/utils/index.ts
+++ b/src/utils/index.ts
@@ -18,6 +18,7 @@ export * from './hooks/index.js'
 export * from './query/index.js'
 export * from './ship/index.js'
 export * from './uuid.js'
+export * from './validation.js'
 
 export function getStageColor(stage: JobStage) {
   switch (stage) {
diff --git a/src/utils/validation.ts b/src/utils/validation.ts
new file mode 100644
index 00000000..36dee8c8
--- /dev/null
+++ b/src/utils/validation.ts
@@ -0,0 +1,249 @@
+import fs from 'node:fs'
+
+import {SUPPORTED_GODOT_VERSIONS} from '@cli/constants/godot.js'
+
+// Docs pages the errors point at. An error without a page carries no ref.
+// ShipThis has no page on the two identifier formats, so those point at the platform that
+// sets the rule. Each link states the rule the message reports, and nothing more.
+const ANDROID_APPLICATION_ID_DOCS = 'https://developer.android.com/build/configure-app-module#set-application-id'
+const APPLE_BUNDLE_ID_DOCS =
+  'https://developer.apple.com/documentation/bundleresources/information-property-list/cfbundleidentifier'
+const GLASS_DOCS = 'https://shipth.is/docs/guides/liquid-glass'
+const GODOT_VERSIONING_DOCS = 'https://shipth.is/docs/guides/godot-versioning'
+const VERSIONING_DOCS = 'https://shipth.is/docs/guides/versioning'
+
+export const MAX_GAME_NAME_LENGTH = 64
+export const MIN_BUILD_NUMBER = 1
+// The largest value Google Play accepts as a versionCode
+export const MAX_BUILD_NUMBER = 2_100_000_000
+
+/**
+ * A validation failure. The fields match the options `this.error()` takes, so a caller
+ * passes them straight through and oclif prints the suggestions and the reference.
+ */
+export interface DetailsValidationError {
+  message: string
+  ref?: string
+  suggestions?: string[]
+}
+
+/** The details fields this module checks. Every other field passes through unchecked. */
+export interface DetailsValues {
+  androidPackageName?: string
+  buildNumber?: number
+  gameEngine?: string
+  gameEngineVersion?: string
+  iosBundleId?: string
+  liquidGlassIconPath?: string
+  name?: string
+  semanticVersion?: string
+}
+
+// Detection only ever produces a major.minor, and a user can add a patch (4.2.1).
+const GODOT_VERSION_SHAPE = /^\d+\.\d+(\.\d+)?$/
+// Three numbers and nothing else. A part has no leading zero.
+const STORE_VERSION_SHAPE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/
+const ANDROID_SEGMENT_SHAPE = /^[A-Za-z][\dA-Za-z_]*$/
+const IOS_SEGMENT_SHAPE = /^[\dA-Za-z-]+$/
+
+/** True when ShipThis has export templates for this Godot version. */
+export function isSupportedGodotVersion(version: string): boolean {
+  if (!GODOT_VERSION_SHAPE.test(version.trim())) return false
+  const [major, minor] = version.trim().split('.')
+  return SUPPORTED_GODOT_VERSIONS.includes(`${major}.${minor}`)
+}
+
+/**
+ * Reduces a near miss to a supported version, so the error can suggest it.
+ * "v4.2" and "4.2-stable" both reduce to "4.2". Returns null when nothing sensible comes out.
+ */
+function getSuggestedGodotVersion(value: string): null | string {
+  const match = value.trim().replace(/^v/i, '').match(/^(\d+)\.(\d+)/)
+  if (!match) return null
+  const majorMinor = `${Number(match[1])}.${Number(match[2])}`
+  return SUPPORTED_GODOT_VERSIONS.includes(majorMinor) ? majorMinor : null
+}
+
+/** True when the version is three numbers, which is what the App Store accepts. */
+export function isValidStoreVersion(version: string): boolean {
+  return STORE_VERSION_SHAPE.test(version.trim())
+}
+
+/** Reduces "1.2" to "1.2.0" and "1.2.3-beta" to "1.2.3". Returns null when nothing comes out. */
+function getSuggestedStoreVersion(value: string): null | string {
+  const match = value
+    .trim()
+    .replace(/^v/i, '')
+    .match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/)
+  if (!match) return null
+  const [, major, minor = '0', patch = '0'] = match
+  const candidate = `${Number(major)}.${Number(minor)}.${Number(patch)}`
+  return isValidStoreVersion(candidate) ? candidate : null
+}
+
+/**
+ * True when the package name is one Google Play accepts as an application ID.
+ * Java and Gradle may enforce other requirements which are not checked here.
+ */
+export function isValidAndroidPackageName(packageName: string): boolean {
+  const segments = packageName.trim().split('.')
+  if (segments.length < 2) return false
+  return segments.every((segment) => ANDROID_SEGMENT_SHAPE.test(segment))
+}
+
+/** True when the bundle ID is one Apple accepts. */
+export function isValidIosBundleId(bundleId: string): boolean {
+  const segments = bundleId.trim().split('.')
+  if (segments.length < 2) return false
+  return segments.every((segment) => IOS_SEGMENT_SHAPE.test(segment))
+}
+
+function validateName(name: string): DetailsValidationError | null {
+  if (name.trim().length === 0) return {message: 'The game name cannot be empty.'}
+  if (name.trim().length > MAX_GAME_NAME_LENGTH) {
+    return {
+      message: `The game name is ${name.trim().length} characters. The limit is ${MAX_GAME_NAME_LENGTH}.`,
+    }
+  }
+
+  return null
+}
+
+function validateGameEngine(gameEngine: string): DetailsValidationError | null {
+  if (gameEngine.trim().toLowerCase() === 'godot') return null
+  return {
+    message: `Game engine "${gameEngine}" is not supported. ShipThis builds Godot games.`,
+    suggestions: ['--gameEngine godot'],
+  }
+}
+
+function validateGameEngineVersion(version: string): DetailsValidationError | null {
+  if (isSupportedGodotVersion(version)) return null
+
+  const suggested = getSuggestedGodotVersion(version)
+  return {
+    message:
+      `"${version}" is not a Godot version that ShipThis builds.\n` +
+      `Supported versions: ${SUPPORTED_GODOT_VERSIONS.join(', ')}. ` +
+      `You can also pin a patch, such as 4.2.1.`,
+    ref: GODOT_VERSIONING_DOCS,
+    ...(suggested && {suggestions: [`--gameEngineVersion ${suggested}`]}),
+  }
+}
+
+function validateSemanticVersion(version: string): DetailsValidationError | null {
+  if (isValidStoreVersion(version)) return null
+
+  const hasSuffix = /[+-]/.test(version.trim())
+  const suggested = getSuggestedStoreVersion(version)
+  return {
+    message:
+      `"${version}" is not a valid semantic version. Use three numbers, such as 1.2.3.` +
+      (hasSuffix ? '\nThe App Store rejects a prerelease or build metadata suffix, such as -beta or +001.' : ''),
+    ref: VERSIONING_DOCS,
+    ...(suggested && {suggestions: [`--semanticVersion ${suggested}`]}),
+  }
+}
+
+function validateBuildNumber(buildNumber: number): DetailsValidationError | null {
+  if (Number.isInteger(buildNumber) && buildNumber >= MIN_BUILD_NUMBER && buildNumber <= MAX_BUILD_NUMBER) return null
+
+  return {
+    message:
+      `The build number must be a whole number from ${MIN_BUILD_NUMBER} to ${MAX_BUILD_NUMBER}.\n` +
+      `${MAX_BUILD_NUMBER} is the largest value Google Play accepts as a versionCode.`,
+    ref: VERSIONING_DOCS,
+  }
+}
+
+function validateAndroidPackageName(packageName: string): DetailsValidationError | null {
+  if (isValidAndroidPackageName(packageName)) return null
+
+  return {
+    message:
+      `"${packageName}" is not a valid Android package name.
+` +
+      'Use two or more segments, such as com.mystudio.mygame. Each segment starts with a letter and holds letters, numbers, and underscores only.',
+    ref: ANDROID_APPLICATION_ID_DOCS,
+  }
+}
+
+function validateIosBundleId(bundleId: string): DetailsValidationError | null {
+  if (isValidIosBundleId(bundleId)) return null
+
+  return {
+    message:
+      `"${bundleId}" is not a valid iOS bundle ID.\n` +
+      'Apple accepts letters, numbers, and hyphens only. ShipThis expects the usual reverse-DNS form, such as com.mystudio.mygame.' +
+      (bundleId.includes('_') ? '\nAn underscore is not allowed.' : ''),
+    ref: APPLE_BUNDLE_ID_DOCS,
+  }
+}
+
+function validateLiquidGlassIconPath(iconPath: string): DetailsValidationError | null {
+  const trimmed = iconPath.trim()
+  if (trimmed.length === 0) return null // An empty value clears the field
+
+  if (!/\.icon$/i.test(trimmed)) {
+    return {
+      message: `"${iconPath}" is not a Liquid Glass icon. The path must name a .icon folder.`,
+      ref: GLASS_DOCS,
+    }
+  }
+
+  if (!fs.existsSync(trimmed)) {
+    return {message: `Liquid Glass icon not found: ${iconPath}`, ref: GLASS_DOCS}
+  }
+
+  if (!fs.statSync(trimmed).isDirectory()) {
+    return {message: `"${iconPath}" is a file. A Liquid Glass icon is a folder.`, ref: GLASS_DOCS}
+  }
+
+  return null
+}
+
+/**
+ * Checks the details values a user gave. Returns the first problem, or null when they all
+ * pass. A field that is undefined is skipped, so a caller passes its whole flags object.
+ * The order below fixes which field reports first when a command sets several at once.
+ */
+export function validateDetailsValues(values: DetailsValues): DetailsValidationError | null {
+  const {
+    androidPackageName,
+    buildNumber,
+    gameEngine,
+    gameEngineVersion,
+    iosBundleId,
+    liquidGlassIconPath,
+    name,
+    semanticVersion,
+  } = values
+
+  const errors = [
+    name === undefined ? null : validateName(name),
+    gameEngine === undefined ? null : validateGameEngine(gameEngine),
+    gameEngineVersion === undefined ? null : validateGameEngineVersion(gameEngineVersion),
+    semanticVersion === undefined ? null : validateSemanticVersion(semanticVersion),
+    buildNumber === undefined ? null : validateBuildNumber(buildNumber),
+    androidPackageName === undefined ? null : validateAndroidPackageName(androidPackageName),
+    iosBundleId === undefined ? null : validateIosBundleId(iosBundleId),
+    liquidGlassIconPath === undefined ? null : validateLiquidGlassIconPath(liquidGlassIconPath),
+  ]
+
+  return errors.find((error) => error !== null) ?? null
+}
+
+/** Returns the warnings for values that pass validation but are likely wrong. */
+export function getDetailsWarnings(values: DetailsValues): string[] {
+  const warnings: string[] = []
+
+  const {androidPackageName} = values
+  if (androidPackageName && /^com\.example\./i.test(androidPackageName.trim())) {
+    warnings.push(
+      `Google Play rejects a package name that starts with "com.example.".\n` +
+        `Use a domain you own, such as com.mystudio.mygame.`,
+    )
+  }
+
+  return warnings
+}
diff --git a/test/utils/validation.test.ts b/test/utils/validation.test.ts
new file mode 100644
index 00000000..35347de4
--- /dev/null
+++ b/test/utils/validation.test.ts
@@ -0,0 +1,266 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import {fileURLToPath} from 'node:url'
+
+import {expect} from 'chai'
+
+import {SUPPORTED_GODOT_VERSIONS} from '../../src/constants/godot.js'
+import {detectGodotVersion} from '../../src/utils/godot.js'
+import {
+  getDetailsWarnings,
+  isSupportedGodotVersion,
+  isValidAndroidPackageName,
+  isValidIosBundleId,
+  isValidStoreVersion,
+  MAX_BUILD_NUMBER,
+  validateDetailsValues,
+} from '../../src/utils/validation.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+describe('isSupportedGodotVersion', () => {
+  const accepted = ['3.6', '4.0', '4.2', '4.2.1', '4.7', ' 4.2 ']
+  const rejected = ['4', '4.9', '3.5', 'v4.2', '4.2-stable', '4.2.stable', '', 'godot']
+
+  for (const version of accepted) {
+    it(`accepts "${version}"`, () => {
+      expect(isSupportedGodotVersion(version)).to.equal(true)
+    })
+  }
+
+  for (const version of rejected) {
+    it(`rejects "${version}"`, () => {
+      expect(isSupportedGodotVersion(version)).to.equal(false)
+    })
+  }
+
+  it('accepts every version in the supported list', () => {
+    for (const version of SUPPORTED_GODOT_VERSIONS) {
+      expect(isSupportedGodotVersion(version), version).to.equal(true)
+    }
+  })
+})
+
+// Binds the validator to detection. A fixture the CLI reads must pass the check that
+// game create runs against it, or a real project warns for no reason.
+describe('isSupportedGodotVersion (against the fixtures)', () => {
+  const originalCwd = process.cwd()
+
+  afterEach(() => {
+    process.chdir(originalCwd)
+  })
+
+  for (const fixture of ['v3_5', 'v4_2']) {
+    it(`accepts the version detected in ${fixture}`, () => {
+      process.chdir(path.resolve(__dirname, '../fixtures/godot', fixture))
+      const detected = detectGodotVersion()
+      expect(detected).to.be.a('string')
+      expect(isSupportedGodotVersion(detected as string), `${detected}`).to.equal(true)
+    })
+  }
+})
+
+describe('isValidStoreVersion', () => {
+  const accepted = ['1.2.3', '0.0.1', '10.20.30']
+  const rejected = ['1.2', '1', '1.2.3-beta', '1.2.3+001', '01.2.3', 'v1.2.3', '1.2.3.4', '']
+
+  for (const version of accepted) {
+    it(`accepts "${version}"`, () => {
+      expect(isValidStoreVersion(version)).to.equal(true)
+    })
+  }
+
+  for (const version of rejected) {
+    it(`rejects "${version}"`, () => {
+      expect(isValidStoreVersion(version)).to.equal(false)
+    })
+  }
+})
+
+describe('isValidAndroidPackageName', () => {
+  // "com.new.game" holds a Java keyword. Google Play accepts it, so the CLI does too - the
+  // build tools are what reject one, and their keyword list differs by language.
+  const accepted = ['com.mystudio.mygame', 'com.my_studio.game2', 'a.b.c.d', 'com.new.game', 'is.shipth.game']
+
+  const rejected = ['game', 'com.my-studio.game', '1com.mystudio', 'com..game', 'com.mystudio.', '']
+
+  for (const name of accepted) {
+    it(`accepts "${name}"`, () => {
+      expect(isValidAndroidPackageName(name)).to.equal(true)
+    })
+  }
+
+  for (const name of rejected) {
+    it(`rejects "${name}"`, () => {
+      expect(isValidAndroidPackageName(name)).to.equal(false)
+    })
+  }
+})
+
+describe('isValidIosBundleId', () => {
+  const accepted = ['com.mystudio.mygame', 'com.mystudio.my-game', 'com.mystudio.game2']
+  const rejected = ['game', 'com.mystudio_game', 'com.mystudio.', 'com..game', '']
+
+  for (const id of accepted) {
+    it(`accepts "${id}"`, () => {
+      expect(isValidIosBundleId(id)).to.equal(true)
+    })
+  }
+
+  for (const id of rejected) {
+    it(`rejects "${id}"`, () => {
+      expect(isValidIosBundleId(id)).to.equal(false)
+    })
+  }
+})
+
+describe('validateDetailsValues', () => {
+  it('returns null when nothing is set', () => {
+    expect(validateDetailsValues({})).to.equal(null)
+  })
+
+  it('returns null for a set of good values', () => {
+    const error = validateDetailsValues({
+      androidPackageName: 'com.mystudio.mygame',
+      buildNumber: 5,
+      gameEngine: 'godot',
+      gameEngineVersion: '4.2',
+      iosBundleId: 'com.mystudio.mygame',
+      name: 'Space Invaders',
+      semanticVersion: '1.2.3',
+    })
+    expect(error).to.equal(null)
+  })
+
+  it('ignores the fields it does not check', () => {
+    const error = validateDetailsValues({
+      gcpProjectId: 'anything at all',
+      gcpServiceAccountId: 'anything at all',
+      useDemoCredentials: 'true',
+    } as never)
+    expect(error).to.equal(null)
+  })
+
+  it('links the semantic version error to the versioning guide', () => {
+    const error = validateDetailsValues({semanticVersion: '1.2'})
+    expect(error?.ref).to.equal('https://shipth.is/docs/guides/versioning')
+    expect(error?.suggestions).to.deep.equal(['--semanticVersion 1.2.0'])
+  })
+
+  it('names the App Store when the semantic version has a prerelease suffix', () => {
+    const error = validateDetailsValues({semanticVersion: '1.2.3-beta'})
+    expect(error?.message).to.contain('App Store')
+    expect(error?.suggestions).to.deep.equal(['--semanticVersion 1.2.3'])
+  })
+
+  it('links the engine version error to the Godot versioning guide', () => {
+    const error = validateDetailsValues({gameEngineVersion: '4.9'})
+    expect(error?.ref).to.equal('https://shipth.is/docs/guides/godot-versioning')
+    expect(error?.suggestions).to.equal(undefined)
+  })
+
+  it('suggests the plain version when the engine version carries a suffix', () => {
+    const error = validateDetailsValues({gameEngineVersion: '4.2-stable'})
+    expect(error?.suggestions).to.deep.equal(['--gameEngineVersion 4.2'])
+  })
+
+  it('suggests the plain version when the engine version carries a v prefix', () => {
+    const error = validateDetailsValues({gameEngineVersion: 'v4.2'})
+    expect(error?.suggestions).to.deep.equal(['--gameEngineVersion 4.2'])
+  })
+
+  it('rejects a build number below 1', () => {
+    const error = validateDetailsValues({buildNumber: 0})
+    expect(error?.ref).to.equal('https://shipth.is/docs/guides/versioning')
+  })
+
+  it('rejects a build number above the Google Play limit', () => {
+    expect(validateDetailsValues({buildNumber: MAX_BUILD_NUMBER})).to.equal(null)
+    expect(validateDetailsValues({buildNumber: MAX_BUILD_NUMBER + 1})).to.not.equal(null)
+  })
+
+  it('links a badly shaped Android package name to the application ID rules', () => {
+    const error = validateDetailsValues({androidPackageName: 'game'})
+    expect(error?.ref).to.equal('https://developer.android.com/build/configure-app-module#set-application-id')
+  })
+
+  it('accepts a package name that holds a Java keyword, which Google Play also accepts', () => {
+    expect(validateDetailsValues({androidPackageName: 'com.new.game'})).to.equal(null)
+  })
+
+  it('names the underscore in an iOS bundle ID error', () => {
+    const error = validateDetailsValues({iosBundleId: 'com.mystudio_game'})
+    expect(error?.message).to.contain('underscore')
+    expect(error?.ref).to.equal(
+      'https://developer.apple.com/documentation/bundleresources/information-property-list/cfbundleidentifier',
+    )
+  })
+
+  it('rejects an empty game name', () => {
+    expect(validateDetailsValues({name: '   '})?.message).to.contain('cannot be empty')
+  })
+
+  it('rejects a game name over the length limit', () => {
+    expect(validateDetailsValues({name: 'a'.repeat(65)})?.message).to.contain('limit is 64')
+  })
+
+  it('rejects a game engine that is not godot', () => {
+    const error = validateDetailsValues({gameEngine: 'unity'})
+    expect(error?.suggestions).to.deep.equal(['--gameEngine godot'])
+  })
+
+  it('reports the first field in the fixed order', () => {
+    const error = validateDetailsValues({buildNumber: 0, semanticVersion: '1.2'})
+    expect(error?.message).to.contain('semantic version')
+  })
+})
+
+describe('validateDetailsValues (liquidGlassIconPath)', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'shipthis-icon-'))
+  const iconDir = path.join(tmpDir, 'AppIcon.icon')
+  const iconFile = path.join(tmpDir, 'NotAFolder.icon')
+
+  before(() => {
+    fs.mkdirSync(iconDir)
+    fs.writeFileSync(iconFile, '')
+  })
+
+  after(() => {
+    fs.rmSync(tmpDir, {force: true, recursive: true})
+  })
+
+  it('accepts a .icon folder that exists', () => {
+    expect(validateDetailsValues({liquidGlassIconPath: iconDir})).to.equal(null)
+  })
+
+  it('accepts an empty value, which clears the field', () => {
+    expect(validateDetailsValues({liquidGlassIconPath: ''})).to.equal(null)
+  })
+
+  it('rejects a path that does not end with .icon', () => {
+    const error = validateDetailsValues({liquidGlassIconPath: path.join(tmpDir, 'icon.png')})
+    expect(error?.message).to.contain('.icon folder')
+  })
+
+  it('rejects a .icon path that is missing', () => {
+    const error = validateDetailsValues({liquidGlassIconPath: path.join(tmpDir, 'Missing.icon')})
+    expect(error?.message).to.contain('not found')
+  })
+
+  it('rejects a .icon path that is a file', () => {
+    const error = validateDetailsValues({liquidGlassIconPath: iconFile})
+    expect(error?.message).to.contain('is a file')
+  })
+})
+
+describe('getDetailsWarnings', () => {
+  it('warns about a com.example package name', () => {
+    const [warning] = getDetailsWarnings({androidPackageName: 'com.example.game'})
+    expect(warning).to.contain('com.example.')
+  })
+
+  it('says nothing about a package name a user owns', () => {
+    expect(getDetailsWarnings({androidPackageName: 'com.mystudio.mygame'})).to.deep.equal([])
+  })
+})

From e3e604bb7a7ecc107a80ce2f247e061cee7dfb1e Mon Sep 17 00:00:00 2001
From: David Sutherland <sutherland.dave@gmail.com>
Date: Thu, 27 Aug 2026 16:10:59 +0100
Subject: [PATCH 2/5] Get list of supported versions from the backend

---
 src/api/index.ts              | 20 ++++++++++++-
 src/commands/game/create.ts   | 20 +++++++------
 src/commands/game/details.tsx |  8 ++++--
 src/commands/game/ship.tsx    | 10 +++++--
 src/constants/godot.ts        |  5 +++-
 src/utils/validation.ts       | 38 +++++++++++++++++--------
 test/utils/validation.test.ts | 53 +++++++++++++++++++++++++++++++++++
 7 files changed, 127 insertions(+), 27 deletions(-)

diff --git a/src/api/index.ts b/src/api/index.ts
index 297d0124..7de7e228 100644
--- a/src/api/index.ts
+++ b/src/api/index.ts
@@ -2,7 +2,7 @@ import * as fs from 'node:fs'
 
 import axios from 'axios'
 
-import {API_URL, WEB_URL} from '@cli/constants/index.js'
+import {API_URL, SUPPORTED_GODOT_VERSIONS, WEB_URL} from '@cli/constants/index.js'
 import {
   AgreementVersion,
   APIKey,
@@ -28,6 +28,7 @@ import {
 } from '@cli/types'
 import {castArrayObjectDates, castJobDates, castObjectDates} from '@cli/utils/dates.js'
 import {toHandledError} from '@cli/utils/index.js'
+import {isVersionList} from '@cli/utils/validation.js'
 
 export * from './credentials/index.js'
 
@@ -47,6 +48,23 @@ export function getAuthedHeaders() {
   }
 }
 
+// How long to wait for the Godot version list before using the built-in one.
+const GODOT_VERSIONS_TIMEOUT_MS = 3000
+
+/**
+ * The Godot versions the build server has templates for. The route is public, so this needs
+ * no token. Any failure - no network, a timeout, a body of another shape - answers with the
+ * built-in list, because a version check must never be the reason a command cannot run.
+ */
+export async function getSupportedGodotVersions(): Promise<string[]> {
+  try {
+    const {data} = await axios.get(`${API_URL}/godot/versions`, {timeout: GODOT_VERSIONS_TIMEOUT_MS})
+    return isVersionList(data) ? data : SUPPORTED_GODOT_VERSIONS
+  } catch {
+    return SUPPORTED_GODOT_VERSIONS
+  }
+}
+
 export interface CreateProjectProps {
   details: ProjectDetails
   name: string
diff --git a/src/commands/game/create.ts b/src/commands/game/create.ts
index 76894ab2..d17c3329 100644
--- a/src/commands/game/create.ts
+++ b/src/commands/game/create.ts
@@ -1,8 +1,8 @@
 import {Flags} from '@oclif/core'
 
-import {createProject} from '@cli/api/index.js'
+import {createProject, getSupportedGodotVersions} from '@cli/api/index.js'
 import {BaseAuthenticatedCommand} from '@cli/baseCommands/index.js'
-import {DEFAULT_PLATFORM_GLOBS, DetailsFlags, SUPPORTED_GODOT_VERSIONS} from '@cli/constants/index.js'
+import {DEFAULT_PLATFORM_GLOBS, DetailsFlags} from '@cli/constants/index.js'
 import {GameEngine, ProjectDetails} from '@cli/types'
 import {getGodotProjectName, getGodotVersion, isCWDGodotGame} from '@cli/utils/godot.js'
 import {
@@ -31,7 +31,11 @@ export default class GameCreate extends BaseAuthenticatedCommand<typeof GameCrea
 
     const {force, name: flagName, quiet, ...details} = flags
 
-    this.validateOrError(details)
+    // create always needs the list: it checks the flag, and it warns about the version it
+    // reads from project.godot. One call answers both.
+    const godotVersions = await getSupportedGodotVersions()
+
+    this.validateOrError(details, godotVersions)
 
     for (const warning of getDetailsWarnings(details)) this.warn(warning)
 
@@ -51,7 +55,7 @@ export default class GameCreate extends BaseAuthenticatedCommand<typeof GameCrea
     }
 
     const name = await getName()
-    this.validateOrError({name})
+    this.validateOrError({name}, godotVersions)
 
     const gameEngine = GameEngine.GODOT
 
@@ -61,11 +65,11 @@ export default class GameCreate extends BaseAuthenticatedCommand<typeof GameCrea
     const detectedVersion = getGodotVersion()
     const gameEngineVersion = details.gameEngineVersion || detectedVersion
 
-    if (!details.gameEngineVersion && !isSupportedGodotVersion(detectedVersion)) {
+    if (!details.gameEngineVersion && !isSupportedGodotVersion(detectedVersion, godotVersions)) {
       this.warn(
         `Your project.godot targets Godot ${detectedVersion}, which this version of ShipThis does not know about.\n` +
           `If the build fails, pin a supported version:\n\n` +
-          `  shipthis game details --gameEngineVersion ${SUPPORTED_GODOT_VERSIONS.at(-1)} --force\n\n` +
+          `  shipthis game details --gameEngineVersion ${godotVersions.at(-1)} --force\n\n` +
           `See https://shipth.is/docs/guides/godot-versioning`,
       )
     }
@@ -88,8 +92,8 @@ export default class GameCreate extends BaseAuthenticatedCommand<typeof GameCrea
   }
 
   // Stops the command on the first bad value, with the docs link for that field.
-  private validateOrError(values: DetailsValues): void {
-    const error = validateDetailsValues(values)
+  private validateOrError(values: DetailsValues, godotVersions: string[]): void {
+    const error = validateDetailsValues(values, godotVersions)
     if (!error) return
     this.error(error.message, {exit: 1, ref: error.ref, suggestions: error.suggestions})
   }
diff --git a/src/commands/game/details.tsx b/src/commands/game/details.tsx
index c9b7613a..a08f903e 100644
--- a/src/commands/game/details.tsx
+++ b/src/commands/game/details.tsx
@@ -1,9 +1,10 @@
 import {Flags} from '@oclif/core'
 import {render} from 'ink'
 
+import {getSupportedGodotVersions} from '@cli/api/index.js'
 import {BaseGameCommand} from '@cli/baseCommands/index.js'
 import {Command, StatusTable} from '@cli/components/index.js'
-import {DetailsFlags} from '@cli/constants/index.js'
+import {DetailsFlags, SUPPORTED_GODOT_VERSIONS} from '@cli/constants/index.js'
 import {GameEngine} from '@cli/types'
 import {getDetailsWarnings, validateDetailsValues} from '@cli/utils/index.js'
 
@@ -42,9 +43,12 @@ export default class GameDetails extends BaseGameCommand<typeof GameDetails> {
       useDemoCredentials,
     } = valueFlags
 
+    // Only ask the server which versions it builds when there is a version to check.
+    const godotVersions = gameEngineVersion ? await getSupportedGodotVersions() : SUPPORTED_GODOT_VERSIONS
+
     // The values are checked before the --force gate, so a user who typed a wrong value and
     // left out --force sees both faults in one go.
-    const validationError = validateDetailsValues(valueFlags)
+    const validationError = validateDetailsValues(valueFlags, godotVersions)
     if (validationError) {
       this.error(validationError.message, {
         exit: 1,
diff --git a/src/commands/game/ship.tsx b/src/commands/game/ship.tsx
index 1c0bae04..f5dfc0b8 100644
--- a/src/commands/game/ship.tsx
+++ b/src/commands/game/ship.tsx
@@ -1,9 +1,10 @@
 import {Flags} from '@oclif/core'
 import {render} from 'ink'
 
-import {downloadBuildById, getJob} from '@cli/api/index.js'
+import {downloadBuildById, getJob, getSupportedGodotVersions} from '@cli/api/index.js'
 import {BaseGameCommand} from '@cli/baseCommands/baseGameCommand.js'
 import {CommandGame, Ship} from '@cli/components/index.js'
+import {SUPPORTED_GODOT_VERSIONS} from '@cli/constants/index.js'
 import {Job} from '@cli/types/api.js'
 import {getErrorMessage} from '@cli/utils/errors.js'
 import {validateDetailsValues} from '@cli/utils/validation.js'
@@ -79,8 +80,11 @@ export default class GameShip extends BaseGameCommand<typeof GameShip> {
   }
 
   public async run(): Promise<void> {
-    // Checked before the zip and the upload, so a typo costs no wait.
-    const validationError = validateDetailsValues({gameEngineVersion: this.flags.gameEngineVersion})
+    // Checked before the zip and the upload, so a typo costs no wait. Without the flag there
+    // is nothing to check, and the command asks the server nothing.
+    const {gameEngineVersion} = this.flags
+    const godotVersions = gameEngineVersion ? await getSupportedGodotVersions() : SUPPORTED_GODOT_VERSIONS
+    const validationError = validateDetailsValues({gameEngineVersion}, godotVersions)
     if (validationError) {
       this.error(validationError.message, {
         exit: 1,
diff --git a/src/constants/godot.ts b/src/constants/godot.ts
index 3b626996..496c3850 100644
--- a/src/constants/godot.ts
+++ b/src/constants/godot.ts
@@ -1,5 +1,8 @@
 // The Godot major.minor versions the build server has export templates for.
 // The server picks the patch, so this list holds no patch numbers - a user can still
-// pin one, such as 4.2.1. Add an entry when ShipThis adds support for a Godot release.
+// pin one, such as 4.2.1.
+//
+// This is the fallback. The CLI asks GET /godot/versions for the live list, and only uses
+// this one when that call cannot answer. A stale entry here costs nothing until then.
 // https://shipth.is/docs/guides/godot-versioning
 export const SUPPORTED_GODOT_VERSIONS = ['3.6', '4.0', '4.1', '4.2', '4.3', '4.4', '4.5', '4.6', '4.7']
diff --git a/src/utils/validation.ts b/src/utils/validation.ts
index 36dee8c8..92b9b3ba 100644
--- a/src/utils/validation.ts
+++ b/src/utils/validation.ts
@@ -46,22 +46,31 @@ const STORE_VERSION_SHAPE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/
 const ANDROID_SEGMENT_SHAPE = /^[A-Za-z][\dA-Za-z_]*$/
 const IOS_SEGMENT_SHAPE = /^[\dA-Za-z-]+$/
 
+/**
+ * True when the body of GET /godot/versions is a bare array of major.minor strings.
+ * The answer decides which versions the CLI accepts, so a body of another shape - an HTML
+ * error page from a proxy, an empty array - has to fall back rather than reject everything.
+ */
+export function isVersionList(data: unknown): data is string[] {
+  return Array.isArray(data) && data.length > 0 && data.every((item) => typeof item === 'string' && /^\d+\.\d+$/.test(item))
+}
+
 /** True when ShipThis has export templates for this Godot version. */
-export function isSupportedGodotVersion(version: string): boolean {
+export function isSupportedGodotVersion(version: string, versions: string[] = SUPPORTED_GODOT_VERSIONS): boolean {
   if (!GODOT_VERSION_SHAPE.test(version.trim())) return false
   const [major, minor] = version.trim().split('.')
-  return SUPPORTED_GODOT_VERSIONS.includes(`${major}.${minor}`)
+  return versions.includes(`${major}.${minor}`)
 }
 
 /**
  * Reduces a near miss to a supported version, so the error can suggest it.
  * "v4.2" and "4.2-stable" both reduce to "4.2". Returns null when nothing sensible comes out.
  */
-function getSuggestedGodotVersion(value: string): null | string {
+function getSuggestedGodotVersion(value: string, versions: string[]): null | string {
   const match = value.trim().replace(/^v/i, '').match(/^(\d+)\.(\d+)/)
   if (!match) return null
   const majorMinor = `${Number(match[1])}.${Number(match[2])}`
-  return SUPPORTED_GODOT_VERSIONS.includes(majorMinor) ? majorMinor : null
+  return versions.includes(majorMinor) ? majorMinor : null
 }
 
 /** True when the version is three numbers, which is what the App Store accepts. */
@@ -117,14 +126,14 @@ function validateGameEngine(gameEngine: string): DetailsValidationError | null {
   }
 }
 
-function validateGameEngineVersion(version: string): DetailsValidationError | null {
-  if (isSupportedGodotVersion(version)) return null
+function validateGameEngineVersion(version: string, versions: string[]): DetailsValidationError | null {
+  if (isSupportedGodotVersion(version, versions)) return null
 
-  const suggested = getSuggestedGodotVersion(version)
+  const suggested = getSuggestedGodotVersion(version, versions)
   return {
     message:
       `"${version}" is not a Godot version that ShipThis builds.\n` +
-      `Supported versions: ${SUPPORTED_GODOT_VERSIONS.join(', ')}. ` +
+      `Supported versions: ${versions.join(', ')}. ` +
       `You can also pin a patch, such as 4.2.1.`,
     ref: GODOT_VERSIONING_DOCS,
     ...(suggested && {suggestions: [`--gameEngineVersion ${suggested}`]}),
@@ -161,8 +170,7 @@ function validateAndroidPackageName(packageName: string): DetailsValidationError
 
   return {
     message:
-      `"${packageName}" is not a valid Android package name.
-` +
+      `"${packageName}" is not a valid Android package name.\n` +
       'Use two or more segments, such as com.mystudio.mygame. Each segment starts with a letter and holds letters, numbers, and underscores only.',
     ref: ANDROID_APPLICATION_ID_DOCS,
   }
@@ -206,8 +214,14 @@ function validateLiquidGlassIconPath(iconPath: string): DetailsValidationError |
  * Checks the details values a user gave. Returns the first problem, or null when they all
  * pass. A field that is undefined is skipped, so a caller passes its whole flags object.
  * The order below fixes which field reports first when a command sets several at once.
+ *
+ * `versions` holds the Godot versions the build server has templates for. A caller that has
+ * asked the server passes its answer. The built-in list is the fallback.
  */
-export function validateDetailsValues(values: DetailsValues): DetailsValidationError | null {
+export function validateDetailsValues(
+  values: DetailsValues,
+  versions: string[] = SUPPORTED_GODOT_VERSIONS,
+): DetailsValidationError | null {
   const {
     androidPackageName,
     buildNumber,
@@ -222,7 +236,7 @@ export function validateDetailsValues(values: DetailsValues): DetailsValidationE
   const errors = [
     name === undefined ? null : validateName(name),
     gameEngine === undefined ? null : validateGameEngine(gameEngine),
-    gameEngineVersion === undefined ? null : validateGameEngineVersion(gameEngineVersion),
+    gameEngineVersion === undefined ? null : validateGameEngineVersion(gameEngineVersion, versions),
     semanticVersion === undefined ? null : validateSemanticVersion(semanticVersion),
     buildNumber === undefined ? null : validateBuildNumber(buildNumber),
     androidPackageName === undefined ? null : validateAndroidPackageName(androidPackageName),
diff --git a/test/utils/validation.test.ts b/test/utils/validation.test.ts
index 35347de4..e805fb37 100644
--- a/test/utils/validation.test.ts
+++ b/test/utils/validation.test.ts
@@ -10,6 +10,7 @@ import {detectGodotVersion} from '../../src/utils/godot.js'
 import {
   getDetailsWarnings,
   isSupportedGodotVersion,
+  isVersionList,
   isValidAndroidPackageName,
   isValidIosBundleId,
   isValidStoreVersion,
@@ -61,6 +62,43 @@ describe('isSupportedGodotVersion (against the fixtures)', () => {
   }
 })
 
+describe('isVersionList', () => {
+  it('accepts a bare array of major.minor strings', () => {
+    expect(isVersionList(['3.6', '4.7'])).to.equal(true)
+  })
+
+  const rejected: [string, unknown][] = [
+    ['an empty array', []],
+    ['a version with no minor', ['4']],
+    ['numbers', [1, 2]],
+    ['the object form', {versions: ['4.7']}],
+    ['an HTML error page', '<!doctype html><html>4.2</html>'],
+    ['null', null],
+    ['undefined', undefined],
+  ]
+
+  for (const [what, data] of rejected) {
+    it(`rejects ${what}`, () => {
+      expect(isVersionList(data)).to.equal(false)
+    })
+  }
+})
+
+describe('isSupportedGodotVersion (with a list from the server)', () => {
+  it('accepts a version the server lists but the built-in list does not hold', () => {
+    expect(isSupportedGodotVersion('4.8')).to.equal(false)
+    expect(isSupportedGodotVersion('4.8', ['4.7', '4.8'])).to.equal(true)
+  })
+
+  it('rejects a version the server dropped', () => {
+    expect(isSupportedGodotVersion('3.6', ['4.7', '4.8'])).to.equal(false)
+  })
+
+  it('still checks the shape against a server list', () => {
+    expect(isSupportedGodotVersion('4.8-stable', ['4.8'])).to.equal(false)
+  })
+})
+
 describe('isValidStoreVersion', () => {
   const accepted = ['1.2.3', '0.0.1', '10.20.30']
   const rejected = ['1.2', '1', '1.2.3-beta', '1.2.3+001', '01.2.3', 'v1.2.3', '1.2.3.4', '']
@@ -154,6 +192,21 @@ describe('validateDetailsValues', () => {
     expect(error?.suggestions).to.deep.equal(['--semanticVersion 1.2.3'])
   })
 
+  it('accepts a version from the list it is given', () => {
+    expect(validateDetailsValues({gameEngineVersion: '4.8'}, ['4.7', '4.8'])).to.equal(null)
+  })
+
+  it('names the versions it was given, and suggests from them', () => {
+    const error = validateDetailsValues({gameEngineVersion: 'v4.8'}, ['4.7', '4.8'])
+    expect(error?.message).to.contain('4.7, 4.8')
+    expect(error?.suggestions).to.deep.equal(['--gameEngineVersion 4.8'])
+  })
+
+  it('falls back to the built-in list when it is given none', () => {
+    const error = validateDetailsValues({gameEngineVersion: '4.8'})
+    expect(error?.message).to.contain(SUPPORTED_GODOT_VERSIONS.join(', '))
+  })
+
   it('links the engine version error to the Godot versioning guide', () => {
     const error = validateDetailsValues({gameEngineVersion: '4.9'})
     expect(error?.ref).to.equal('https://shipth.is/docs/guides/godot-versioning')

From a17491a5b3078e904b26ee9b7eb5727ddad4e85f Mon Sep 17 00:00:00 2001
From: David Sutherland <sutherland.dave@gmail.com>
Date: Thu, 27 Aug 2026 16:23:00 +0100
Subject: [PATCH 3/5] Better error messages if we dont validate the flag range

---
 src/constants/index.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/constants/index.ts b/src/constants/index.ts
index 326bfd2f..e3a1d03a 100644
--- a/src/constants/index.ts
+++ b/src/constants/index.ts
@@ -6,9 +6,9 @@ export * from './godot.js'
 
 export const DetailsFlags = {
   androidPackageName: Flags.string({char: 'a', description: 'Set the Android package name'}),
-  // The range matches MIN_BUILD_NUMBER and MAX_BUILD_NUMBER in utils/validation.ts. The
-  // parser message carries no docs link, so the validator repeats the check.
-  buildNumber: Flags.integer({char: 'b', description: 'Set the build number', max: 2_100_000_000, min: 1}),
+  // No min or max here. The parser runs before run(), so a bound set here would answer first
+  // with a message that carries no docs link. validateBuildNumber holds the range instead.
+  buildNumber: Flags.integer({char: 'b', description: 'Set the build number'}),
   // The value is not imported from the GameEngine enum - importing types here has caused a
   // circular import before (see the DetailsFlags fix in 4a7357f).
   gameEngine: Flags.string({char: 'e', description: 'Set the game engine', options: ['godot']}),

From 8ee4084485a3f25975f6c0c9247f30bc5845f668 Mon Sep 17 00:00:00 2001
From: David Sutherland <sutherland.dave@gmail.com>
Date: Thu, 27 Aug 2026 16:30:27 +0100
Subject: [PATCH 4/5] Remove the com.example package name warning - out of
 scope

---
 docs/game/details.md          |  2 +-
 src/commands/game/create.ts   | 15 ++++-----------
 src/commands/game/details.tsx |  4 +---
 src/utils/validation.ts       | 14 --------------
 test/utils/validation.test.ts | 11 -----------
 5 files changed, 6 insertions(+), 40 deletions(-)

diff --git a/docs/game/details.md b/docs/game/details.md
index 97e3e870..86fbe73d 100644
--- a/docs/game/details.md
+++ b/docs/game/details.md
@@ -33,7 +33,7 @@ use is reported here, in a second, rather than in a failed build minutes later.
 | **gameEngineVersion** | A supported Godot version, such as `4.2`. You can pin a patch, such as `4.2.1`. See [Godot versioning](/docs/guides/godot-versioning). |
 | **semanticVersion** | Three numbers, such as `1.2.3`. The App Store rejects a suffix such as `-beta`. See [versioning](/docs/guides/versioning). |
 | **buildNumber** | A whole number from 1 to 2100000000. The top value is the largest Google Play accepts as a versionCode. |
-| **androidPackageName** | Two or more segments, such as `com.mystudio.mygame`. Each segment starts with a letter and holds letters, numbers, and underscores only. See the [Android application ID rules](https://developer.android.com/build/configure-app-module#set-application-id). |
+| **androidPackageName** | Two or more segments, such as `com.mystudio.mygame`. Each segment starts with a letter and holds letters, numbers, and underscores only. See the [Android application ID rules](https://developer.android.com/build/configure-app-module#set-application-id). Use a domain you own. Google Play rejects a name that starts with `com.example.` at upload. |
 | **iosBundleId** | The usual reverse-DNS form, such as `com.mystudio.mygame`. Letters, numbers, and hyphens only. See [CFBundleIdentifier](https://developer.apple.com/documentation/bundleresources/information-property-list/cfbundleidentifier). |
 | **liquidGlassIconPath** | A `.icon` folder that exists on your machine. See the [Liquid Glass guide](/docs/guides/liquid-glass). |
 
diff --git a/src/commands/game/create.ts b/src/commands/game/create.ts
index d17c3329..06dd6fc9 100644
--- a/src/commands/game/create.ts
+++ b/src/commands/game/create.ts
@@ -5,13 +5,7 @@ import {BaseAuthenticatedCommand} from '@cli/baseCommands/index.js'
 import {DEFAULT_PLATFORM_GLOBS, DetailsFlags} from '@cli/constants/index.js'
 import {GameEngine, ProjectDetails} from '@cli/types'
 import {getGodotProjectName, getGodotVersion, isCWDGodotGame} from '@cli/utils/godot.js'
-import {
-  DetailsValues,
-  getDetailsWarnings,
-  getInput,
-  isSupportedGodotVersion,
-  validateDetailsValues,
-} from '@cli/utils/index.js'
+import {DetailsValues, getInput, isSupportedGodotVersion, validateDetailsValues} from '@cli/utils/index.js'
 
 export default class GameCreate extends BaseAuthenticatedCommand<typeof GameCreate> {
   static override args = {}
@@ -37,8 +31,6 @@ export default class GameCreate extends BaseAuthenticatedCommand<typeof GameCrea
 
     this.validateOrError(details, godotVersions)
 
-    for (const warning of getDetailsWarnings(details)) this.warn(warning)
-
     if (this.hasProjectConfig() && !force) {
       throw new Error('This directory already has a ShipThis project. Use --force to overwrite.')
     }
@@ -65,9 +57,10 @@ export default class GameCreate extends BaseAuthenticatedCommand<typeof GameCrea
     const detectedVersion = getGodotVersion()
     const gameEngineVersion = details.gameEngineVersion || detectedVersion
 
-    if (!details.gameEngineVersion && !isSupportedGodotVersion(detectedVersion, godotVersions)) {
+    // --quiet promises no output except interactions and errors, and this is neither.
+    if (!quiet && !details.gameEngineVersion && !isSupportedGodotVersion(detectedVersion, godotVersions)) {
       this.warn(
-        `Your project.godot targets Godot ${detectedVersion}, which this version of ShipThis does not know about.\n` +
+        `Your project.godot targets Godot ${detectedVersion}, which is not in the list of versions ShipThis builds.\n` +
           `If the build fails, pin a supported version:\n\n` +
           `  shipthis game details --gameEngineVersion ${godotVersions.at(-1)} --force\n\n` +
           `See https://shipth.is/docs/guides/godot-versioning`,
diff --git a/src/commands/game/details.tsx b/src/commands/game/details.tsx
index a08f903e..87d82bf4 100644
--- a/src/commands/game/details.tsx
+++ b/src/commands/game/details.tsx
@@ -6,7 +6,7 @@ import {BaseGameCommand} from '@cli/baseCommands/index.js'
 import {Command, StatusTable} from '@cli/components/index.js'
 import {DetailsFlags, SUPPORTED_GODOT_VERSIONS} from '@cli/constants/index.js'
 import {GameEngine} from '@cli/types'
-import {getDetailsWarnings, validateDetailsValues} from '@cli/utils/index.js'
+import {validateDetailsValues} from '@cli/utils/index.js'
 
 export default class GameDetails extends BaseGameCommand<typeof GameDetails> {
   static override args = {}
@@ -57,8 +57,6 @@ export default class GameDetails extends BaseGameCommand<typeof GameDetails> {
       })
     }
 
-    for (const warning of getDetailsWarnings(valueFlags)) this.warn(warning)
-
     if ((gameEngine || gameEngineVersion || iosBundleId || androidPackageName) && !force)
       throw new Error('Use --force to set the restricted fields')
 
diff --git a/src/utils/validation.ts b/src/utils/validation.ts
index 92b9b3ba..c6edb1e4 100644
--- a/src/utils/validation.ts
+++ b/src/utils/validation.ts
@@ -247,17 +247,3 @@ export function validateDetailsValues(
   return errors.find((error) => error !== null) ?? null
 }
 
-/** Returns the warnings for values that pass validation but are likely wrong. */
-export function getDetailsWarnings(values: DetailsValues): string[] {
-  const warnings: string[] = []
-
-  const {androidPackageName} = values
-  if (androidPackageName && /^com\.example\./i.test(androidPackageName.trim())) {
-    warnings.push(
-      `Google Play rejects a package name that starts with "com.example.".\n` +
-        `Use a domain you own, such as com.mystudio.mygame.`,
-    )
-  }
-
-  return warnings
-}
diff --git a/test/utils/validation.test.ts b/test/utils/validation.test.ts
index e805fb37..be29446c 100644
--- a/test/utils/validation.test.ts
+++ b/test/utils/validation.test.ts
@@ -8,7 +8,6 @@ import {expect} from 'chai'
 import {SUPPORTED_GODOT_VERSIONS} from '../../src/constants/godot.js'
 import {detectGodotVersion} from '../../src/utils/godot.js'
 import {
-  getDetailsWarnings,
   isSupportedGodotVersion,
   isVersionList,
   isValidAndroidPackageName,
@@ -307,13 +306,3 @@ describe('validateDetailsValues (liquidGlassIconPath)', () => {
   })
 })
 
-describe('getDetailsWarnings', () => {
-  it('warns about a com.example package name', () => {
-    const [warning] = getDetailsWarnings({androidPackageName: 'com.example.game'})
-    expect(warning).to.contain('com.example.')
-  })
-
-  it('says nothing about a package name a user owns', () => {
-    expect(getDetailsWarnings({androidPackageName: 'com.mystudio.mygame'})).to.deep.equal([])
-  })
-})

From 87560600c57119851f3d3af1fe69b21a6ce99d54 Mon Sep 17 00:00:00 2001
From: David Sutherland <sutherland.dave@gmail.com>
Date: Thu, 27 Aug 2026 16:37:45 +0100
Subject: [PATCH 5/5] Comment fix and trimming flag values

---
 src/commands/game/details.tsx |  4 ++--
 src/commands/game/ship.tsx    |  2 ++
 src/constants/index.ts        | 20 ++++++++++++--------
 3 files changed, 16 insertions(+), 10 deletions(-)

diff --git a/src/commands/game/details.tsx b/src/commands/game/details.tsx
index 87d82bf4..11bd6ee0 100644
--- a/src/commands/game/details.tsx
+++ b/src/commands/game/details.tsx
@@ -46,8 +46,8 @@ export default class GameDetails extends BaseGameCommand<typeof GameDetails> {
     // Only ask the server which versions it builds when there is a version to check.
     const godotVersions = gameEngineVersion ? await getSupportedGodotVersions() : SUPPORTED_GODOT_VERSIONS
 
-    // The values are checked before the --force gate, so a user who typed a wrong value and
-    // left out --force sees both faults in one go.
+    // Values come before the --force gate, so a wrong value is named without --force.
+    // this.error() exits, so only this fault prints.
     const validationError = validateDetailsValues(valueFlags, godotVersions)
     if (validationError) {
       this.error(validationError.message, {
diff --git a/src/commands/game/ship.tsx b/src/commands/game/ship.tsx
index f5dfc0b8..4513815d 100644
--- a/src/commands/game/ship.tsx
+++ b/src/commands/game/ship.tsx
@@ -70,6 +70,8 @@ export default class GameShip extends BaseGameCommand<typeof GameShip> {
     }),
     gameEngineVersion: Flags.string({
       description: 'Override the specified game engine version for this build',
+      // Trim, as DetailsFlags does - what run() checks is what the job reads.
+      parse: async (input: string) => input.trim(),
       required: false,
     }),
     dryRun: Flags.boolean({
diff --git a/src/constants/index.ts b/src/constants/index.ts
index e3a1d03a..06028c4c 100644
--- a/src/constants/index.ts
+++ b/src/constants/index.ts
@@ -4,22 +4,26 @@ export * from './cacheKeys.js'
 export * from './config.js'
 export * from './godot.js'
 
+// Trim here so run() checks the same string it stores and sends. The flags with `options`
+// need none - oclif checks an option list against the raw input, before parse.
+const trimmed = async (input: string): Promise<string> => input.trim()
+
 export const DetailsFlags = {
-  androidPackageName: Flags.string({char: 'a', description: 'Set the Android package name'}),
+  androidPackageName: Flags.string({char: 'a', description: 'Set the Android package name', parse: trimmed}),
   // No min or max here. The parser runs before run(), so a bound set here would answer first
   // with a message that carries no docs link. validateBuildNumber holds the range instead.
   buildNumber: Flags.integer({char: 'b', description: 'Set the build number'}),
   // The value is not imported from the GameEngine enum - importing types here has caused a
   // circular import before (see the DetailsFlags fix in 4a7357f).
   gameEngine: Flags.string({char: 'e', description: 'Set the game engine', options: ['godot']}),
-  gameEngineVersion: Flags.string({char: 'v', description: 'Set the game engine version'}),
+  gameEngineVersion: Flags.string({char: 'v', description: 'Set the game engine version', parse: trimmed}),
   // No short char: -g is reserved CLI-wide for --gameId (see BaseGameCommand)
-  gcpProjectId: Flags.string({description: 'Set the GCP project ID'}),
-  gcpServiceAccountId: Flags.string({char: 'c', description: 'Set the GCP service account ID'}),
-  iosBundleId: Flags.string({char: 'i', description: 'Set the iOS bundle ID'}),
-  liquidGlassIconPath: Flags.string({char: 'l', description: 'Set the Liquid Glass icon path'}),
-  name: Flags.string({char: 'n', description: 'The name of the game'}),
-  semanticVersion: Flags.string({char: 's', description: 'Set the semantic version'}),
+  gcpProjectId: Flags.string({description: 'Set the GCP project ID', parse: trimmed}),
+  gcpServiceAccountId: Flags.string({char: 'c', description: 'Set the GCP service account ID', parse: trimmed}),
+  iosBundleId: Flags.string({char: 'i', description: 'Set the iOS bundle ID', parse: trimmed}),
+  liquidGlassIconPath: Flags.string({char: 'l', description: 'Set the Liquid Glass icon path', parse: trimmed}),
+  name: Flags.string({char: 'n', description: 'The name of the game', parse: trimmed}),
+  semanticVersion: Flags.string({char: 's', description: 'Set the semantic version', parse: trimmed}),
   useDemoCredentials: Flags.string({
     char: 'd',
     description: 'Use demo credentials for this project',