[refactor] Dreamverse 2/5: launch backend through installed CLI (#1314)

apps/dreamverse/README.md

@@ -24,16 +24,11 @@ those commands without the `[dreamverse]` extra exits immediately with a message
 to install `fastvideo[dreamverse]`, because the cloud prompt runtime
 dependencies are intentionally gated by the extra.
 
-## Repo-Local Backend Launch
+## Launch Dreamverse
 
-Use the repo-local wrappers from the FastVideo checkout root:
+Start the backend with the installed Dreamverse commands:
 
 ```bash
-apps/dreamverse/scripts/dreamverse-server --port 8009
-apps/dreamverse/scripts/dreamverse-mock-server --port 8009
+dreamverse-server --port 8009
+dreamverse-mock-server --port 8009
 ```
-
-The workspace member keeps `[tool.uv] package = false`, so the wrappers remain
-the most explicit way to launch the backend from a source checkout. If
-`dreamverse-server` appears earlier on `PATH`, confirm it points at this
-checkout or reinstall FastVideo with the `dreamverse` extra.

apps/dreamverse/design.md

@@ -318,7 +318,7 @@ Expected shape:
 
 ```bash
 uv sync --extra server
-apps/dreamverse/scripts/dreamverse-server --host 0.0.0.0 --port 8009
+dreamverse-server --host 0.0.0.0 --port 8009
 
 cd apps/dreamverse/web
 npm ci
@@ -465,7 +465,7 @@ Add or tighten tests for:
 
 The first manual smoke checklist should be:
 
-1. start `apps/dreamverse/scripts/dreamverse-server`
+1. start `dreamverse-server`
 2. confirm `GET /healthz` returns 200
 3. confirm `GET /readyz` returns 200 after warmup
 4. start `apps/web`

apps/dreamverse/scripts/dreamverse-mock-server

@@ -1,9 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-REPO_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
-PYTHON="${DREAMVERSE_PYTHON:-${HOME}/miniconda3/envs/fv-main/bin/python}"
-[[ -x "${PYTHON}" ]] \
-  || { echo "error: python not executable at ${PYTHON} (set DREAMVERSE_PYTHON to override)" >&2; exit 1; }
-PYTHONPATH="${REPO_ROOT}/apps/dreamverse:${REPO_ROOT}:${PYTHONPATH:-}" \
-  exec "${PYTHON}" -m dreamverse.mock_server "$@"

apps/dreamverse/scripts/dreamverse-server

@@ -1,9 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-REPO_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
-PYTHON="${DREAMVERSE_PYTHON:-${HOME}/miniconda3/envs/fv-main/bin/python}"
-[[ -x "${PYTHON}" ]] \
-  || { echo "error: python not executable at ${PYTHON} (set DREAMVERSE_PYTHON to override)" >&2; exit 1; }
-PYTHONPATH="${REPO_ROOT}/apps/dreamverse:${REPO_ROOT}:${PYTHONPATH:-}" \
-  exec "${PYTHON}" -m dreamverse.server_entry "$@"

apps/dreamverse/scripts/launch/launch_backend_dreamverse.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Launch the Dreamverse-flavored backend via the repo-local wrapper.
+# Launch the Dreamverse-flavored backend via the installed console command.
 #
 # This is the path the Next.js frontend expects today — it serves
 # ``/healthz``, ``/readyz``, ``/status``, ``/curated-presets``, and the
@@ -41,6 +41,11 @@ export FASTVIDEO_PROMPT_AUTO_TIMEOUT_MS="${FASTVIDEO_PROMPT_AUTO_TIMEOUT_MS:-180
 
 cd "${DREAMVERSE_ROOT}"
 
-echo "[launch-demo] starting apps/dreamverse/scripts/dreamverse-server"
+if ! command -v dreamverse-server >/dev/null 2>&1; then
+  echo "error: dreamverse-server not found on PATH. Install FastVideo with the dreamverse extra." >&2
+  exit 1
+fi
+
+echo "[launch-demo] starting dreamverse-server"
 echo "  args: $*"
-exec "${DREAMVERSE_ROOT}/scripts/dreamverse-server" "$@"
+exec dreamverse-server "$@"

apps/dreamverse/scripts/smoke_local.sh

@@ -58,10 +58,12 @@ if ! probe_json "/healthz" >/dev/null 2>&1; then
     exit 1
   fi
 
+  require_command dreamverse-server
+
   echo "Starting Dreamverse backend on ${BASE_URL}..."
   (
     cd "${ROOT_DIR}"
-    exec "${ROOT_DIR}/scripts/dreamverse-server" --host "${HOST}" --port "${PORT}"
+    exec dreamverse-server --host "${HOST}" --port "${PORT}"
   ) >"${BACKEND_LOG_PATH}" 2>&1 &
   backend_pid=$!
   started_backend=1

docs/contributing/dreamverse-development.md

@@ -14,17 +14,19 @@ uv run --locked --package dreamverse --extra test pytest apps/dreamverse/server/
 
 ## Backend launch
 
-Launch the migrated backend through the repo-local wrappers:
+Launch the migrated backend through the installed console commands:
 
 ```bash
-apps/dreamverse/scripts/dreamverse-server --port 8009
-apps/dreamverse/scripts/dreamverse-mock-server --port 8009
+dreamverse-server --port 8009
+dreamverse-mock-server --port 8009
 ```
 
-Do not rely on a bare `dreamverse-server` found on `PATH` during the migration.
-With `[tool.uv] package = false`, uv does not register this workspace member's
-console scripts, so a PATH binary can still point at an old Dreamverse editable
-install outside this monorepo.
+If `dreamverse-server` is missing, install FastVideo with the `dreamverse`
+extra from the checkout:
+
+```bash
+uv pip install -e ".[dreamverse]"
+```
 
 ## Frontend build and tests
 
@@ -47,8 +49,7 @@ that GPU appear as logical GPU 0 inside the process, preserving the previous
 Dreamverse deployment behavior.
 
 ```bash
-CUDA_VISIBLE_DEVICES=4 apps/dreamverse/scripts/dreamverse-server \
-  --host 0.0.0.0 --port 8009
+CUDA_VISIBLE_DEVICES=4 dreamverse-server --host 0.0.0.0 --port 8009
 ```
 
 In another shell, verify the service:
@@ -93,7 +94,7 @@ export CUDAHOSTCXX=/usr/bin/g++-13
 export NVCC_PREPEND_FLAGS="-ccbin /usr/bin/gcc-13 -allow-unsupported-compiler"
 ```
 
-The `apps/dreamverse/scripts/dreamverse-server` wrapper does NOT set these —
-they need to come from the launching shell. The `dreamverse-deploy` skill
+`dreamverse-server` does NOT set these — they need to come from the launching
+shell. The `dreamverse-deploy` skill
 ([`.agents/skills/dreamverse-deploy/`](../../.agents/skills/dreamverse-deploy/SKILL.md))
 sets them for you and is the recommended local-deploy path.