feat(nevermore-cli): pin and promote base place versions in deploy config (#734)

* feat(nevermore-cli): pin base place versions in deploy config

Deploys that use a basePlace always downloaded the latest published
version of that place, so a broken Studio edit to a base place shipped on
the next deploy even when the code hadn't changed.

Add an optional basePlace.version pin to deploy.nevermore.json. When set,
the deploy downloads exactly that version instead of the latest, making
deploys reproducible. Omitting it keeps the previous latest-pull behavior,
so existing configs are unaffected.

Add `nevermore deploy version upgrade [target]` to bump the pins: it
resolves each basePlace's current latest published version via the Open
Cloud Assets API (reusing the legacy-asset:manage scope), prints an
old -> new table, and writes the new versions back to the config after a
confirmation prompt. Supports --dryrun and --yes, and scopes to a single
target when named. Base places shared across targets are resolved once.

* feat(nevermore-cli): add `deploy version promote` to copy pins between targets

Promoting a validated build usually means shipping the exact base-place
versions a demo/staging target was verified against, not re-pinning to
whatever is newest.

Add `nevermore deploy version promote <from> <to>`, which copies basePlace
version pins from one target onto another (e.g. production-demo ->
production). Places are matched by base place id rather than name, so the
same source content lines up even when targets name their places
differently. Destination places with no matching pin are left untouched
and reported, and an inconsistent source (one base place pinned to two
versions) is rejected. It's a pure edit of deploy.nevermore.json with no
network calls, gated behind the same --dryrun / confirmation flow as
`version upgrade`.

Author: Quenty

docs/cli.md

@@ -157,13 +157,14 @@ nevermore test --cloud --script-text 'print("hi")'    # run arbitrary Luau to de
 
 ### `nevermore deploy`
 
-Builds a Rojo project and uploads it to a Roblox place. `deploy` has two subcommands; `run` is the default, so `nevermore deploy` and `nevermore deploy <target>` both deploy. Full walkthrough in [Deploying with the CLI](deploy.md).
+Builds a Rojo project and uploads it to a Roblox place. `run` is the default subcommand, so `nevermore deploy` and `nevermore deploy <target>` both deploy. Full walkthrough in [Deploying with the CLI](deploy.md).
 
 ```bash
-nevermore deploy init                  # create deploy.nevermore.json (interactive)
-nevermore deploy run                   # build + upload, saved (not live)
-nevermore deploy run --publish         # build + upload and publish live
-nevermore deploy production --publish  # 'run' is implied; deploy the 'production' target
+nevermore deploy init                    # create deploy.nevermore.json (interactive)
+nevermore deploy run                     # build + upload, saved (not live)
+nevermore deploy run --publish           # build + upload and publish live
+nevermore deploy production --publish    # 'run' is implied; deploy the 'production' target
+nevermore deploy version upgrade         # re-pin base place versions to latest
 ```
 
 **`nevermore deploy init`** — writes a `deploy.nevermore.json` for the current package.
@@ -188,6 +189,16 @@ nevermore deploy production --publish  # 'run' is implied; deploy the 'productio
 | `--output <file>` | Write JSON results to a file. |
 | `--logs` | Show build/upload logs even on success. |
 
+**`nevermore deploy version upgrade [target]`** — re-pins every `basePlace` in `deploy.nevermore.json` to its current latest published version, so deploys pull a fixed, git-tracked base place instead of whatever is live. Without a target it walks every target. See [Pinning base place versions](deploy.md#pinning-base-place-versions).
+
+| Flag | Description |
+|------|-------------|
+| `--dryrun` | Print the old → new version table without writing. |
+| `--yes` | Skip the confirmation prompt (for scripting/CI). |
+| `--api-key <key>` | Open Cloud API key. Otherwise resolved from login/env. |
+
+**`nevermore deploy version promote <from> <to>`** — copies base-place version pins from one target to another (e.g. promote validated `production-demo` pins to `production`). Places are matched by base place id, so content lines up even when the targets name their places differently. Pure config edit — no network. Supports `--dryrun` and `--yes`. See [Promoting pins between targets](deploy.md#promoting-pins-between-targets).
+
 ### `nevermore batch`
 
 Runs `test` or `deploy` across many packages at once, using git change detection so PRs only touch what changed. Scans the pnpm workspace for packages with a matching deploy target. See [Test Infrastructure](testing/testing.md) and [Deploying](deploy.md) for how targets are configured.

docs/deploy.md

@@ -155,6 +155,7 @@ Other flags:
 | `targets.<name>.project` | yes | Path to the Rojo project file, relative to the package directory. |
 | `targets.<name>.scriptTemplate` | no | Luau file `nevermore test` executes via Open Cloud after upload. Not used by `nevermore deploy` itself. |
 | `targets.<name>.basePlace` | no | Universe/place to download and merge with the rojo build before uploading. See [Merging with an existing place](testing/integration-testing.md#merging-with-an-existing-place-baseplace). |
+| `targets.<name>.basePlace.version` | no | Pin the base place to a specific published version instead of pulling the latest. See [Pinning base place versions](#pinning-base-place-versions). |
 
 You can declare any number of targets. A common setup is one `test` target for CI and a separate `production` or `staging` target for live deploys:
 
@@ -230,6 +231,66 @@ nevermore deploy run --place-file ./build/my-place.rbxl
 
 The `project` field in `deploy.nevermore.json` is ignored when `--place-file` is set, but `universeId` and `placeId` are still required.
 
+## Pinning base place versions
+
+If a target uses a [`basePlace`](testing/integration-testing.md#merging-with-an-existing-place-baseplace), `nevermore deploy` downloads that place and merges your rojo build into it. By default it pulls **the latest published version** of the base place — so a broken Studio edit to the base place ships on the very next deploy, even when your code hasn't changed.
+
+To make deploys reproducible, pin the base place to a specific version with an optional `version` field:
+
+```json
+{
+  "targets": {
+    "production": {
+      "universeId": 12345,
+      "placeId": 67890,
+      "project": "default.project.json",
+      "basePlace": {
+        "universeId": 12345,
+        "placeId": 11111,
+        "version": 42
+      }
+    }
+  }
+}
+```
+
+With `version` set, the deploy downloads exactly that version of the base place. Omit it to keep pulling the latest (the previous behaviour — nothing changes for configs that don't opt in).
+
+### Bumping the pin
+
+When you actually want to roll base places forward, run:
+
+```bash
+# Re-pin every basePlace in the config to its current latest published version
+nevermore deploy version upgrade
+
+# Only upgrade one target
+nevermore deploy version upgrade production
+
+# Preview the change set without writing
+nevermore deploy version upgrade --dryrun
+```
+
+`upgrade` walks every `basePlace` in `deploy.nevermore.json` (or just the named target), resolves each place's current latest published version, prints an old → new table, and — after a confirmation prompt — writes the new `version` values back into the file. Base places shared by several targets are resolved once. Pass `--yes` to skip the prompt (for scripting), or `--dryrun` to preview only.
+
+Commit the updated `deploy.nevermore.json`, then deploy as usual. This gives you a reviewable, git-tracked record of exactly which base-place content each deploy shipped.
+
+Resolving the latest version uses the same `legacy-asset:manage` scope already required for `basePlace` downloads, so no extra credentials are needed.
+
+### Promoting pins between targets
+
+Once you've validated a target — say a `production-demo` universe — you usually want to ship those exact same base-place versions to `production`, not re-pin to whatever is newest. `promote` copies the pins across:
+
+```bash
+# Copy every base place pin from production-demo onto production
+nevermore deploy version promote production-demo production
+
+# Preview without writing
+nevermore deploy version promote production-demo production --dryrun
+```
+
+Places are matched by **base place id**, not by name, so the same source content lines up even when the two targets name their places differently (e.g. a demo `chapter6` and a prod `chapter8` that share one base place). Places in the destination with no matching pin in the source are left untouched and reported. This is a pure edit of `deploy.nevermore.json` — no network calls — so it's safe to run offline and review as a diff.
+
 ## Batch deploys
 
 If you want to deploy every game affected by a code change (for example, on every PR), use `nevermore batch deploy` instead. It scans the pnpm workspace for packages with a matching deploy target, uses `pnpm ls --filter` to figure out which ones changed since `origin/main`, and runs them in parallel.

docs/testing/integration-testing.md

@@ -218,6 +218,8 @@ Add `basePlace` to your deploy target:
 
 The `basePlace` place is the source of truth for Studio-authored content. The target `placeId` is where the merged result gets uploaded. These can be in the same universe or different ones.
 
+By default the CLI downloads the **latest published version** of the base place on every deploy. To make deploys reproducible — so a broken Studio edit can't leak into a deploy — pin a specific version with an optional `basePlace.version`, and bump it deliberately with `nevermore deploy version upgrade`. See [Pinning base place versions](../deploy.md#pinning-base-place-versions).
+
 ### How the merge works
 
 The merge is driven by your rojo project file. Each entry in the tree is treated as one of two kinds:

tools/nevermore-cli/src/commands/deploy-command/index.ts

@@ -36,6 +36,11 @@ import {
   resolveDeployTargetPlaces,
 } from '../../utils/build/deploy-config.js';
 import { handleInitAsync } from './deploy-init.js';
+import {
+  handleVersionUpgradeAsync,
+  handleVersionPromoteAsync,
+  type VersionPromoteArgs,
+} from './version-command.js';
 import { selectTargetAsync } from './select-target.js';
 
 const MULTI_PLACE_CONCURRENCY = 10;
@@ -109,6 +114,72 @@ export class DeployCommand<T> implements CommandModule<T, DeployArgs> {
       }
     );
 
+    args.command(
+      'version',
+      'Manage pinned base place versions in deploy.nevermore.json',
+      (yargs) => {
+        return yargs
+          .command(
+            'upgrade [target]',
+            'Re-pin every basePlace to its latest published version',
+            (upgradeYargs) => {
+              return upgradeYargs
+                .positional('target', {
+                  describe:
+                    'Only upgrade this target (default: all targets in the config)',
+                  type: 'string',
+                })
+                .option('api-key', {
+                  describe: 'Roblox Open Cloud API key',
+                  type: 'string',
+                });
+            },
+            async (upgradeArgs) => {
+              try {
+                await handleVersionUpgradeAsync(
+                  upgradeArgs as unknown as DeployArgs
+                );
+              } catch (err) {
+                OutputHelper.error(
+                  err instanceof Error ? err.message : String(err)
+                );
+                process.exit(1);
+              }
+            }
+          )
+          .command(
+            'promote <from> <to>',
+            'Promote base place version pins from one target to another',
+            (promoteYargs) => {
+              return promoteYargs
+                .positional('from', {
+                  describe:
+                    'Target to promote pins from (e.g. production-demo)',
+                  type: 'string',
+                })
+                .positional('to', {
+                  describe: 'Target to promote pins to (e.g. production)',
+                  type: 'string',
+                });
+            },
+            async (promoteArgs) => {
+              try {
+                await handleVersionPromoteAsync(
+                  promoteArgs as unknown as VersionPromoteArgs
+                );
+              } catch (err) {
+                OutputHelper.error(
+                  err instanceof Error ? err.message : String(err)
+                );
+                process.exit(1);
+              }
+            }
+          )
+          .demandCommand(1, 'Specify a version action, e.g. "upgrade".');
+      },
+      () => {}
+    );
+
     args.command(
       ['run [target]', '$0 [target]'],
       'Deploy a target from deploy.nevermore.json',