154 lines
6.8 KiB
Markdown
154 lines
6.8 KiB
Markdown
---
|
|
spec: docs/specs/platform/requirements/dev-preview-title-prefixes.md
|
|
created: 2026-08-10
|
|
status: complete
|
|
---
|
|
|
|
# Implementation Plan: Keep Debug Start on the Production Profile
|
|
|
|
## Overview
|
|
|
|
`make start-debug` sets the legacy pprof debug variable. The profile loader
|
|
currently treats that variable as a development selector, so it applies the
|
|
`Dev` title prefix. Make `KANDEV_DEBUG_DEV_MODE` the only development selector,
|
|
keep pprof as debug behavior, and preserve `Dev Kandev` for `make dev`. The
|
|
debug launcher supplies `Debug` as the default title prefix, producing
|
|
`Debug Kandev` without selecting the development profile.
|
|
|
|
The work proceeds from the backend profile contract to the launcher checks and
|
|
then to the browser regression test and public documentation.
|
|
|
|
The confirmed root cause is in `profiles.DetectEnvironment`: its dev branch
|
|
checks `KANDEV_DEBUG_PPROF_ENABLED` even though the release debug launcher sets
|
|
that variable without selecting the development profile.
|
|
|
|
## Backend and launchers
|
|
|
|
### Profile selection
|
|
|
|
- `apps/backend/internal/profiles/profiles.go`: make
|
|
`KANDEV_DEBUG_DEV_MODE=true` the only non-e2e signal for the `dev` profile.
|
|
Keep `KANDEV_DEBUG_PPROF_ENABLED` available to the debug configuration and
|
|
pprof routes.
|
|
- `apps/backend/internal/profiles/profiles_test.go`: add a pprof-only
|
|
regression case that resolves to `prod`, keeps the title prefix out of the
|
|
profile defaults, and keeps production feature defaults.
|
|
|
|
### Debug title default
|
|
|
|
- `apps/backend/internal/launcher/env.go`: when the native debug launcher is
|
|
used, supply `KANDEV_WEB_TITLE_PREFIX=Debug` only when the caller has not
|
|
already supplied a prefix. Keep the explicit environment override contract.
|
|
- `apps/backend/internal/launcher/start_test.go`: verify the debug launcher
|
|
supplies `Debug` by default and preserves an explicit prefix.
|
|
- `apps/backend/internal/launcher/supervisor.go`: preserve the title prefix in
|
|
the restart manifest so a supervised restart keeps `Debug Kandev`.
|
|
- `apps/backend/internal/launcher/supervisor_test.go`: cover the allowlisted
|
|
title prefix in the restart manifest.
|
|
|
|
### Make targets
|
|
|
|
- `apps/backend/Makefile`: make the direct `dev` target export the canonical
|
|
`KANDEV_DEBUG_DEV_MODE=true` selector. Make the direct `start-debug` target
|
|
default to the `Debug` prefix while preserving an explicitly supplied
|
|
`KANDEV_WEB_TITLE_PREFIX`. The debug target continues to export pprof and
|
|
debug logging without the dev selector.
|
|
- `scripts/check-make-shells`: update the expected `dev` command for Unix,
|
|
native Windows, and Git Bash/MSYS, plus the direct `start-debug` title
|
|
environment.
|
|
|
|
### Durable decision record
|
|
|
|
- `docs/decisions/0007-runtime-feature-flags.md`: reconcile the profile
|
|
selector table with the corrected contract.
|
|
- `docs/decisions/2026-08-10-debug-launcher-profile-selection.md`: preserve the
|
|
reason for separating diagnostic behavior from environment identity.
|
|
- `docs/decisions/INDEX.md`: index the new decision.
|
|
|
|
## Frontend
|
|
|
|
No frontend production code changes are required. The existing server-shell
|
|
and SPA title composition already uses `KANDEV_WEB_TITLE_PREFIX` correctly.
|
|
|
|
The existing title-prefix browser test will cover the debug-start result. This
|
|
is browser metadata, not a layout or interaction surface. Desktop and phone
|
|
viewports therefore have the same expected title, and no mobile-specific
|
|
interaction test is required.
|
|
|
|
## Public documentation
|
|
|
|
- `docs/public/configuration.md`: state that `make start-debug` keeps the
|
|
production profile and uses the `Debug Kandev` title while enabling
|
|
diagnostics.
|
|
- `docs/public/cli.md`: explain that `--debug` does not select the development
|
|
profile; `make dev` is the development-profile launcher.
|
|
- `docs/configuration.md`: keep the internal configuration reference aligned.
|
|
|
|
## Tests
|
|
|
|
- **What:** pprof-only startup selects `prod` and does not apply `Dev`.
|
|
**File:** `apps/backend/internal/profiles/profiles_test.go`.
|
|
**How:** isolated environment unit test through `ApplyProfile`.
|
|
- **What:** the native debug launcher supplies the `Debug` prefix by default
|
|
and preserves an explicit prefix.
|
|
**File:** `apps/backend/internal/launcher/start_test.go`.
|
|
**How:** inspect the environment assembled for debug and non-debug starts.
|
|
- **What:** supervised restarts preserve the debug title prefix.
|
|
**File:** `apps/backend/internal/launcher/supervisor_test.go`.
|
|
**How:** assert the debug prefix survives the restart manifest allowlist.
|
|
- **What:** direct `make dev` emits the canonical dev selector across shells.
|
|
**File:** `scripts/check-make-shells`.
|
|
**How:** run the existing deterministic `make -n` shell matrix.
|
|
- **What:** the debug-start launcher uses the distinct debug title.
|
|
**File:** `apps/web/e2e/tests/system/title-prefix.spec.ts`.
|
|
**How:** restart the fixture with pprof enabled and both profile selectors
|
|
disabled plus the launcher's `Debug` prefix, navigate to `/`, and assert
|
|
`Debug Kandev`.
|
|
- **What:** development and preview title behavior remains unchanged.
|
|
**File:** `apps/web/e2e/tests/system/title-prefix.spec.ts`.
|
|
**How:** retain the existing `Dev Kandev` and `Preview Kandev` assertions.
|
|
|
|
## E2E Tests
|
|
|
|
- **Scenario:** GIVEN a backend restarted with pprof/debug behavior and no
|
|
development or e2e selector, WHEN the browser opens Kandev, THEN the title is
|
|
`Debug Kandev`.
|
|
- **Scenario:** GIVEN a backend restarted with the development selector, WHEN
|
|
the browser opens Kandev, THEN the title is `Dev Kandev`.
|
|
- **Scenario:** GIVEN a backend with an explicit `Preview` prefix, WHEN the
|
|
browser opens Kandev, THEN the title is `Preview Kandev`.
|
|
- **File:** `apps/web/e2e/tests/system/title-prefix.spec.ts`.
|
|
- **Mobile note:** `document.title` is viewport-independent. The existing
|
|
browser metadata assertion covers the same user outcome on a phone, so no
|
|
`mobile-*.spec.ts` file is needed.
|
|
|
|
## Verification Results
|
|
|
|
- `make test-backend` — passed (full backend test suite).
|
|
- `make lint-backend` — passed (0 issues).
|
|
- `make build-backend` — passed (backend binaries built).
|
|
- `cd apps/backend && make check-make-shells` — passed for Unix, native
|
|
Windows, and Git Bash/MSYS dispatch, including explicit prefixes with spaces.
|
|
- `cd apps/web && pnpm e2e:run --project chromium tests/system/title-prefix.spec.ts`
|
|
— passed (3 tests).
|
|
- `node --test scripts/validate-public-docs.test.mjs` — passed (58 tests).
|
|
- `node scripts/validate-public-docs.mjs` — passed (41 published docs pages).
|
|
- `git diff --check` — passed.
|
|
|
|
## Implementation Waves And Parallel Candidates
|
|
|
|
Wave 1 (sequential):
|
|
|
|
- [x] [task-01-profile-selector-contract](task-01-profile-selector-contract.md)
|
|
|
|
Wave 2 (sequential, depends on Wave 1):
|
|
|
|
- [x] [task-02-title-regression-docs](task-02-title-regression-docs.md)
|
|
|
|
Parallel delegation is not authorized by this plan. The work stays in the
|
|
primary session and follows the dependency order above.
|
|
|
|
## Open Questions
|
|
|
|
None.
|