feat: Add better deploy UX including preview and stuff (#694)

Quenty · web-flow · commit a3e9458670ec · 2026-05-19T14:33:35.000-07:00
diff --git a/docs/_AI_INDEX.md b/docs/_AI_INDEX.md
@@ -37,6 +37,7 @@ This file is an index for AI agents. The `_` prefix keeps it out of Docusaurus.
 |-----|-------------|
 | [intro.md](intro.md) | Getting started with Nevermore, why use it, key packages |
 | [install.md](install.md) | Installation methods: NPM + CLI, existing Rojo projects, plugins |
+| [deploy.md](deploy.md) | `nevermore deploy`: login, `deploy init`, `deploy run`, config schema, flag reference, common workflows |
 | [architecture/](architecture/index.md) | Architecture: workspace layout, design philosophy, ServiceBag, dependency injection |
 | [architecture/patterns.md](architecture/patterns.md) | Core patterns: Maid, BaseObject, Binder, Rx, Brio, Blend, AdorneeData, TieDefinition |
 | [build.md](build.md) | Contributing: local setup, tools, versioning, custom Rojo |
diff --git a/docs/deploy.md b/docs/deploy.md
@@ -0,0 +1,277 @@
+---
+title: Deploying with the CLI
+sidebar_position: 3
+---
+
+# Deploying places with `nevermore deploy`
+
+`nevermore deploy` builds a Rojo project, uploads it to a Roblox place via the [Open Cloud API](https://create.roblox.com/docs/cloud), and (optionally) publishes the new version so players see it. `nevermore test` is built on the same pipeline, so everything that runs in a Roblox place goes through this command.
+
+This guide walks you from zero to your first uploaded place. For advanced features (merging with a Studio-authored base place, smoke tests, batch deploys, CI), see [Integration Testing](testing/integration-testing.md).
+
+:::tip New to Nevermore?
+Start with the [Intro](intro.md) for an overview and [Install](install.md) for setting up Node, Rojo, and the Nevermore CLI itself. This guide assumes the CLI is already on your `PATH`.
+:::
+
+## When should I use this?
+
+For most Roblox projects, especially solo work and small teams, you don't need this. Open Roblox Studio, click **Save to Roblox** or **Publish to Roblox**, and you're done. That's normally the right answer.
+
+You probably want `nevermore deploy` when:
+
+- Your code lives in a git repository and Studio is just where you preview it. Deploys should come from the same commit history that reviews and tests run against, not from whichever developer's Studio happens to be open.
+- More than one programmer ships to the same place. Studio's publish flow is last-writer-wins, and a CLI deploy from CI gives you one path from "merge to main" to "live in game", traceable to a specific commit.
+- You want one config to drive both tests and deploys. `nevermore deploy` and `nevermore test` both read `deploy.nevermore.json`, so the place you smoke-test against on every PR is configured exactly like the one you ship to. See [Test Infrastructure](testing/testing.md).
+- You want CI to gate releases. Batch deploys plug into PR checks, so a deploy only runs after lint, tests, and smoke tests pass, and shows up as a PR comment instead of an ad-hoc Studio session.
+
+If none of those apply, stick with Studio Publish. Come back when you outgrow it.
+
+## What deploy actually does
+
+When you run `nevermore deploy run`:
+
+1. Reads `deploy.nevermore.json` in your current directory and resolves the target you asked for (default: `test`).
+2. Runs `rojo build` on the target's `project` file to produce an `.rbxl` place file in a temp directory.
+3. Uploads the `.rbxl` to the configured `universeId` / `placeId` over Open Cloud.
+4. Saves the new version as a draft. If `--publish` is passed, it is also published as the live version.
+
+That's the whole pipeline. There are no deploy hooks or post-processing steps to register.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) v18+ and the Nevermore CLI installed. The [Install guide](install.md) walks through both. The short version is `npm install -g @quenty/nevermore-cli`, or use `npx nevermore ...` from any package that depends on it.
+- [Rojo](https://rojo.space/docs/v7/getting-started/installation/) v7+ on your `PATH`.
+- A Roblox universe and place you own. You can create both at [create.roblox.com/dashboard/creations](https://create.roblox.com/dashboard/creations).
+- A Roblox Open Cloud API key. See [Logging in](#logging-in) below.
+
+## Logging in
+
+`nevermore deploy` authenticates against Open Cloud with an API key. Create one at [create.roblox.com/dashboard/credentials](https://create.roblox.com/dashboard/credentials) and grant it these scopes for the universe you want to deploy to:
+
+| Scope | Used for |
+|-------|----------|
+| `universe-places:write` | Uploading new place versions |
+| `universe.place.luau-execution-session:write` | Running scripts (used by `nevermore test` and smoke tests) |
+| `universe.place.luau-execution-session:read` | Reading script execution results |
+| `legacy-asset:manage` | Downloading a [base place](testing/integration-testing.md#merging-with-an-existing-place-baseplace) (only needed if you use `basePlace`) |
+
+Save the key to your machine once:
+
+```bash
+nevermore login
+```
+
+This stores the key at `~/.nevermore/credentials.json` (mode `0700`) after validating it against Open Cloud. Other useful flags:
+
+- `nevermore login --force` swaps the stored key.
+- `nevermore login --clear` removes it.
+- `nevermore login --status` shows what's loaded and re-validates it.
+
+### How the CLI finds your key
+
+The CLI resolves credentials in this order (first match wins):
+
+1. The `--api-key` CLI flag
+2. The `ROBLOX_OPEN_CLOUD_API_KEY` environment variable
+3. The `ROBLOX_UNIT_TEST_API_KEY` environment variable (kept for backwards compatibility)
+4. `~/.nevermore/credentials.json` (from `nevermore login`)
+
+In CI, set `ROBLOX_OPEN_CLOUD_API_KEY` as a secret. `nevermore login` is for local developer machines.
+
+## Setting up a package for deploy
+
+`deploy.nevermore.json` is the only file the CLI needs to know about. The fastest way to create one is the interactive `init` wizard.
+
+### `nevermore deploy init`
+
+From inside the directory you want to deploy from (a package under `src/`, a game under `games/`, or any directory with a `package.json`):
+
+```bash
+nevermore deploy init
+```
+
+The wizard:
+
+- Detects a `test/default.project.json` if one exists and offers it as the default Rojo project.
+- Detects `test/scripts/Server/ServerMain.server.lua` (or `.luau`) and offers it as the default script template.
+- Walks up the filesystem looking for a parent `deploy.nevermore.json` with a `universeId` and reuses it. Once you have one game configured, sibling packages can inherit the universe automatically.
+- Lists every existing place in the universe so you can pick one, or offers to create a new place.
+- Prints the resulting config and asks you to confirm before writing it.
+
+#### Non-interactive setup
+
+Pass `--yes` to skip prompts. You must supply enough flags for the wizard to resolve everything without asking:
+
+```bash
+nevermore deploy init --yes \
+  --universe-id 12345 \
+  --place-id 67890 \
+  --project default.project.json \
+  --target test
+```
+
+If you have the universe but no place yet, use `--create-place` to create one. Place creation is not exposed in Open Cloud, so this uses your `.ROBLOSECURITY` cookie instead. It only works on a machine that's logged in to Roblox.
+
+```bash
+nevermore deploy init --yes \
+  --universe-id 12345 \
+  --create-place \
+  --project default.project.json
+```
+
+Other flags:
+
+| Flag | Description |
+|------|-------------|
+| `--target <name>` | Name of the target to create (default: `test`) |
+| `--script-template <path>` | Set the Luau script template that `nevermore test` will run |
+| `--force` | Overwrite an existing `deploy.nevermore.json` |
+
+### The `deploy.nevermore.json` schema
+
+```json
+{
+  "targets": {
+    "test": {
+      "universeId": 12345,
+      "placeId": 67890,
+      "project": "default.project.json",
+      "scriptTemplate": "test/scripts/Server/ServerMain.server.lua",
+      "basePlace": {
+        "universeId": 12345,
+        "placeId": 11111
+      }
+    }
+  }
+}
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `targets` | yes | Map of target name to deploy config. Most packages start with a single `test` target. |
+| `targets.<name>.universeId` | yes | Roblox universe ID to deploy into. |
+| `targets.<name>.placeId` | yes | Roblox place ID. The build is uploaded here as a new version. |
+| `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). |
+
+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:
+
+```json
+{
+  "targets": {
+    "test":       { "universeId": 1, "placeId": 10, "project": "test/default.project.json" },
+    "production": { "universeId": 1, "placeId": 20, "project": "default.project.json" }
+  }
+}
+```
+
+## Running a deploy
+
+From the directory containing `deploy.nevermore.json`:
+
+```bash
+# Build + upload to the default "test" target as a saved (draft) version
+nevermore deploy run
+
+# Same, but publish so the new version is live for players
+nevermore deploy run --publish
+
+# Deploy a specific target
+nevermore deploy run production --publish
+```
+
+`nevermore deploy run` and the bare `nevermore deploy <target>` form are equivalent. `run` is the default subcommand.
+
+On success you'll see one of:
+
+```
+Saved v42 — not yet live.
+Published v42 — live in game.
+```
+
+A "saved" version is uploaded but not visible to players. You can publish it later from the Roblox dashboard, or re-run with `--publish` to publish a fresh build. That version number matches what you'll see on the place page.
+
+### Run flags
+
+| Flag | Description |
+|------|-------------|
+| `--publish` | Publish the new version (default: save only) |
+| `--api-key <key>` | Open Cloud API key (overrides credential lookup) |
+| `--universe-id <id>` | Override the target's `universeId` |
+| `--place-id <id>` | Override the target's `placeId` |
+| `--place-file <path>` | Skip the rojo build and upload an existing `.rbxl` instead |
+| `--output <path>` | Write a JSON record of the deploy result to this path |
+
+Global flags (available on every `nevermore` command):
+
+| Flag | Description |
+|------|-------------|
+| `--yes` | Non-interactive (fails fast instead of prompting) |
+| `--dryrun` | Print what would happen without doing it |
+| `--verbose` | Verbose logging (rojo output, upload details) |
+
+### Overriding the configured place
+
+`--universe-id` and `--place-id` let you redirect a single deploy without editing the config. This is useful when you want to push the same build to a personal staging place for a one-off test:
+
+```bash
+nevermore deploy run --universe-id 999 --place-id 8888
+```
+
+### Uploading a pre-built place
+
+If you already have a `.rbxl` (for example, one produced by `rojo build` in an upstream CI step), skip the rebuild:
+
+```bash
+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.
+
+## 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.
+
+See [Integration Testing → Batch deploy](testing/integration-testing.md#batch-deploy) for the full flag list and CI usage.
+
+## Common workflows
+
+### First-time setup for a new game
+
+If you're starting from a clean directory, [`nevermore init`](install.md#fast-track-installing-via-npm-and-the-nevermore-cli-recommended) scaffolds a working Nevermore game template: a `default.project.json`, server/client entry scripts, and the default packages (`loader`, `servicebag`, `binder`, etc.). After that, `nevermore deploy init` only needs your universe and place IDs.
+
+```bash
+mkdir my-game && cd my-game
+nevermore init                                 # scaffold a Nevermore game template
+nevermore deploy init                          # configure the deploy target (interactive)
+nevermore deploy run                           # first upload, draft only
+nevermore deploy run --publish                 # publish when ready
+```
+
+The wizard auto-detects the project file `nevermore init` creates, so you only answer prompts for universe and place. See [Install](install.md) for the full breakdown of what `nevermore init` produces, and [Integration Testing → Setting up a new integration game](testing/integration-testing.md#setting-up-a-new-integration-game) if you're building a game inside the Nevermore/Raven monorepo instead.
+
+### Promoting a tested build to production
+
+If you have separate `test` and `production` targets, the common pattern is to run the test target on every PR and only deploy production from `main`:
+
+```bash
+# In CI on main
+nevermore deploy run production --publish
+```
+
+There is no separate "promote" command. You deploy the same code to whichever target you want.
+
+### Debugging a failed deploy
+
+- Pass `--verbose` to see the rojo build output and the raw Open Cloud responses.
+- Pass `--dryrun` to confirm which target, universe, place, and project the CLI would use without uploading anything.
+- Check `nevermore login --status` if you suspect a credential problem.
+- Place uploads can fail with HTTP 403 when the API key is missing the `universe-places:write` scope for that specific universe. The scope is granted per-universe, not globally.
+
+## See also
+
+- [Intro](intro.md) — Why Nevermore, the major packages, and how the library is organized.
+- [Install](install.md) — Setting up Node, Rojo, the Nevermore CLI, and scaffolding a project with `nevermore init`.
+- [Integration Testing](testing/integration-testing.md) — `basePlace` merging, smoke tests, batch deploys, CI integration.
+- [Test Infrastructure](testing/testing.md) — How `nevermore test` reuses the deploy config to run Jest specs in Open Cloud.
diff --git a/tools/nevermore-cli-helpers/src/find-git-repo-root.ts b/tools/nevermore-cli-helpers/src/find-git-repo-root.ts
@@ -0,0 +1,31 @@
+import * as fsPromises from 'fs/promises';
+import * as path from 'path';
+
+async function pathExistsAsync(filePath: string): Promise<boolean> {
+  try {
+    await fsPromises.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Walks up from `fromDirectory` looking for a `.git` entry and returns the
+ * directory that contains it. Returns `undefined` if no git root is found.
+ */
+export async function findGitRepoRootAsync(
+  fromDirectory: string
+): Promise<string | undefined> {
+  let current = path.resolve(fromDirectory);
+  while (true) {
+    if (await pathExistsAsync(path.join(current, '.git'))) {
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return undefined;
+    }
+    current = parent;
+  }
+}
diff --git a/tools/nevermore-cli-helpers/src/utils.ts b/tools/nevermore-cli-helpers/src/utils.ts
@@ -1,5 +1,7 @@
 export { VersionChecker } from './version-checker.js';
 
+export { findGitRepoRootAsync } from './find-git-repo-root.js';
+
 export {
   getRobloxCookieAsync,
   createPlaceInUniverseAsync,
diff --git a/tools/nevermore-cli/src/commands/deploy-command/deploy-init-utils.ts b/tools/nevermore-cli/src/commands/deploy-command/deploy-init-utils.ts
@@ -1,13 +1,51 @@
+import * as fs from 'fs/promises';
 import * as path from 'path';
 import { fileExistsAsync } from '../../utils/nevermore-cli-utils.js';
 
+/**
+ * Auto-detects the default deploy target name for a package.
+ *
+ * A package whose root `default.project.json` defines a full place
+ * (`tree.$className === "DataModel"`) is treated as a game and defaults
+ * to "integration". Otherwise (library — with or without a `test/` folder)
+ * defaults to "test".
+ */
+export async function detectTargetNameAsync(
+  packagePath: string
+): Promise<'test' | 'integration'> {
+  if (await _isRootProjectDataModelAsync(packagePath)) {
+    return 'integration';
+  }
+  return 'test';
+}
+
+async function _isRootProjectDataModelAsync(
+  packagePath: string
+): Promise<boolean> {
+  const rootProject = path.join(packagePath, 'default.project.json');
+  try {
+    const content = await fs.readFile(rootProject, 'utf-8');
+    const parsed = JSON.parse(content) as { tree?: { $className?: string } };
+    return parsed.tree?.$className === 'DataModel';
+  } catch {
+    return false;
+  }
+}
+
 export async function detectProjectFileAsync(
   packagePath: string
 ): Promise<string | undefined> {
-  const candidate = path.join(packagePath, 'test', 'default.project.json');
-  if (await fileExistsAsync(candidate)) {
-    return 'test/default.project.json';
+  const candidates = [
+    path.join(packagePath, 'test', 'default.project.json'),
+    path.join(packagePath, 'default.project.json'),
+  ];
+
+  for (const candidate of candidates) {
+    if (await fileExistsAsync(candidate)) {
+      return path.relative(packagePath, candidate);
+    }
   }
+
   return undefined;
 }
 
@@ -17,6 +55,8 @@ export async function detectScriptFileAsync(
   const candidates = [
     'test/scripts/Server/ServerMain.server.lua',
     'test/scripts/Server/ServerMain.server.luau',
+    'scripts/Server/ServerMain.server.lua',
+    'scripts/Client/ClientMain.server.luau',
   ];
   for (const candidate of candidates) {
     if (await fileExistsAsync(path.join(packagePath, candidate))) {
diff --git a/tools/nevermore-cli/src/commands/deploy-command/deploy-init.ts b/tools/nevermore-cli/src/commands/deploy-command/deploy-init.ts
diff --git a/tools/nevermore-cli/src/commands/deploy-command/index.ts b/tools/nevermore-cli/src/commands/deploy-command/index.ts
