diff --git a/docs/release-control/v6/internal/subsystems/deployment-installability.md b/docs/release-control/v6/internal/subsystems/deployment-installability.md index d17dcb293a..7896ec0656 100644 --- a/docs/release-control/v6/internal/subsystems/deployment-installability.md +++ b/docs/release-control/v6/internal/subsystems/deployment-installability.md @@ -208,6 +208,11 @@ though it is the managed control surface underneath the wrappers, its usage guidance must still point operators to the canonical repo-root `npm run dev` entrypoint for routine startup instead of teaching direct script invocation as the primary habit. +That operator-guidance rule also applies to the managed launcher's recovery and +diagnostic messages: when `hot-dev-bg` tells users how to start, restart, +verify, or inspect the routine local dev runtime, it must route them to the +repo-root `npm run dev`, `npm run dev:verify`, and `npm run dev:logs` wrappers +instead of teaching direct raw script invocations for those day-to-day flows. That same dev-runtime helper boundary also includes the auxiliary operator controls that start, stop, restart, or recover local development. The repo-root Makefile targets, `scripts/toggle-mock.sh`, and `scripts/clean-mock-alerts.sh` must diff --git a/scripts/hot-dev-bg.sh b/scripts/hot-dev-bg.sh index dbe58f9319..7f74c766ed 100755 --- a/scripts/hot-dev-bg.sh +++ b/scripts/hot-dev-bg.sh @@ -370,7 +370,7 @@ start_bg() { log "Unmanaged listeners are already using the dev ports." describe_listener "${FRONTEND_DEV_PORT}" "" || true describe_listener "${PULSE_DEV_API_PORT}" "" || true - fail "Refusing to take over unmanaged listeners. Stop them first or rerun with: ./scripts/hot-dev-bg.sh start --takeover" + fail "Refusing to take over unmanaged listeners. Stop them first or rerun with: npm run dev" fi log "Taking over existing unmanaged listeners on the dev ports." describe_listener "${FRONTEND_DEV_PORT}" "" || true @@ -439,7 +439,7 @@ PY if ! wait_for_managed_listener "${FRONTEND_DEV_PORT}" "${pid}" 90; then log "Backend is up, but a managed frontend listener on port ${FRONTEND_DEV_PORT} is not ready yet." - log "Check logs with: ./scripts/hot-dev-bg.sh logs" + log "Check logs with: npm run dev:logs" fi log "Frontend: http://127.0.0.1:${FRONTEND_DEV_PORT}" @@ -650,7 +650,7 @@ verify_bg() { managed_pid="$(managed_session_pid)" if [[ -n "${managed_pid}" ]] && has_unmanaged_listeners "${managed_pid}"; then if [[ "${takeover}" != "true" ]]; then - fail "Managed runtime has split ownership. Rerun with: ./scripts/hot-dev-bg.sh verify --takeover" + fail "Managed runtime has split ownership. Rerun with: npm run dev:verify" fi log "Managed runtime has split ownership. Reclaiming ports before verification..." stop_bg diff --git a/scripts/tests/test-hot-dev-bg.sh b/scripts/tests/test-hot-dev-bg.sh index fe8b798f46..8e09e463b5 100755 --- a/scripts/tests/test-hot-dev-bg.sh +++ b/scripts/tests/test-hot-dev-bg.sh @@ -323,10 +323,12 @@ test_hot_dev_script_advertises_foreground_escape_hatch() { test_hot_dev_bg_script_advertises_managed_entrypoint() { local output - output="$(sed -n '1,20p' "${ROOT_DIR}/scripts/hot-dev-bg.sh")" + output="$(sed -n '1,720p' "${ROOT_DIR}/scripts/hot-dev-bg.sh")" assert_contains "hot-dev-bg usage points to managed runtime first" "${output}" "npm run dev # Canonical managed dev runtime" assert_contains "hot-dev-bg still documents direct launcher start" "${output}" "./scripts/hot-dev-bg.sh start [--takeover]" + assert_contains "hot-dev-bg routes log guidance to managed wrapper" "${output}" "Check logs with: npm run dev:logs" + assert_contains "hot-dev-bg routes verify guidance to managed wrapper" "${output}" "Rerun with: npm run dev:verify" } test_clean_mock_alerts_prefers_managed_runtime() { @@ -546,6 +548,7 @@ test_detects_unmanaged_listeners() { )" assert_contains "start refuses unmanaged takeover by default" "${start_output}" "Refusing to take over unmanaged listeners." + assert_contains "start recommends canonical managed entrypoint" "${start_output}" "npm run dev" assert_contains "start returns failure for unmanaged takeover" "${start_output}" "exit_code=1" }