Repository navigation
fix(frontend): keep the dashboard served while a frontend build runs - #16217
Conversation
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS Check by hand that an open dashboard keeps rendering through [UX-REVIEWED] 8c600e9 Description read[DESCRIPTION-READ] 91c21c4d9400a705a2783190f8bf5651e06973d5e3dd4a10d378af6ca10b556c That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Design Review (Opus 5.5) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS On Windows every Vite build now depends on renaming Watch
[DESIGN-REVIEWED] 8c600e9 Description read[DESCRIPTION-READ] 4f931afad8cb45717c20cc5368bf8cebd417935e72e73f7d355a158b65973357 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS The edition gateway now copies the whole bundle at boot, waiting up to 5 s for the lock. The fix doesn't need this, and no reported edition defect backs it. Not justified as shipped
What this change shipsInventory (10 items) — 8 justifiedIntent: keep a source-checkout dashboard served through a frontend rebuild, and pick up new builds without a restart. This is a FIX.
[FIRST-PRINCIPLES-REVIEWED] 8c600e9 Description read[DESCRIPTION-READ] e616b7b18bd027b4e551e09d6e720ef92b9e80fa4b7066a622771663a69f04d9 That sha256 names the PR description this verdict read. Recompute it with |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
474cf4c to
fdead1f
Compare
|
|
|
fdead1f to
7393d4b
Compare
|
|
|
|
The /assets, /sprites, /fonts, /vendor and /app-assets mounts were add_static routes, which resolve their directory once at registration, and they were registered only when static/dist existed at start. On a source checkout static/dist is a link, and index.html, the PWA files and the stale-asset watchdog read through it on every request. So once anything re-pointed the link, index.html referenced chunks the pinned routes could not serve, a blank dashboard until a restart, and a gateway started before the first build never served one at all. Each build prefix is now a GET route registered whether or not a build exists, which resolves static/dist on every request, off the event loop as aiohttp's own static handler does. A resolved file must sit inside the resolved subdirectory, the same confinement add_static applies without follow_symlinks; a tail that names a root, a drive or a share is refused before any lookup, as add_static refuses it; and a miss is a no-store 404. App window entries are still enumerated at start but resolved per request the same way, so a window first built after start needs a restart. FileResponse keeps the precompressed siblings, ranges and conditional requests.
On a source checkout static/dist links to website/dist, and every Vite build emptied website/dist and rewrote it in place, so for the whole build a running gateway served no bundle and the stale-asset watchdog read the gap as a vanished install. A Vite plugin (website/scripts/publish-dist.mjs), registered last, builds every mode except --watch into a per-build scratch sibling and, in the last closeBundle hook and only once its post-order writeBundle has run, renames the live tree aside and the new one over it. A failed build, wherever it fails, leaves website/dist as it was and keeps its own error. Scratch a killed build strands is swept at the next build; a live tree that cannot be renamed (a mount point) is rewritten in place, copying before it removes. The sw.js stamp and precompression follow the resolved outDir. Staging only ever re-points static/dist, which the dashboard now resolves per request: at website/dist for a stock build that publishes this way, otherwise at a fresh immutable copy in static/.dist.<id> (an edition bundle, an older target revision that still builds in place, which is moved to such a copy before it builds). On POSIX that is one rename of a link over a link; on Windows the old junction is removed first, which touches no tree. The link always carries an absolute target, copies are matched to the served one by file identity rather than path spelling, and nothing is swept while static/dist resolves nowhere. A stage that retires the directory an older gateway resolved at start (a real static/dist turned into the link, or the copy an in-place target's gateway started on) says to restart that gateway, and every copy carries its own "*" .gitignore, so a target whose .gitignore predates the copies' names still reads clean. The tree-rename swap, its rollback and its retry budgets are gone, and so is gateway start's wait for a dangling link: outside an edition, a dangling link to this checkout's website/dist is kept and serves the build once it lands. An edition start stages its private copy off the event loop, waits at most 5 s for the staging lock, and otherwise serves what it found through the link with a warning. A build counts as published only if it replaced website/dist/index.html, compared by mtime_ns and inode rather than against the wall clock. make and make.ps1 stage through python -m kiro_crew.frontend stage in build and wheel, after the backend install, so backend-bin needs no Python for it. A stock checkout started before anything is built links static/dist to its unbuilt website/dist, so the first build is served without a restart. The stage command refuses a directory that is not a checkout before creating anything in it. This removes the build-time asset gap that #13960's watchdog stand-down otherwise has to cover. Link-screen gate: _live_link_target, _point_static_dist_at and _sweep_staged_locked are recorded, not held. They follow or replace the operator's own link beside static/dist on purpose; the no-follow hold would refuse that link, a sweep only ever unlinks a link it finds, and a link planted between screen and use chooses only what is served, which a planted link already does.
7393d4b to
8c600e9
Compare
Problem / Motivation
Goal: A source-checkout dashboard keeps serving a complete bundle while the frontend is rebuilt, and picks up the new build without a gateway restart.
On a source checkout
src/kiro_crew/static/distis a link towebsite/dist. Every Vite build emptiedwebsite/distand rewrote it in place, so for the wholenpm run builda running gateway served no bundle: the dashboard went blank and the stale-asset watchdog read the gap as a vanished install. Every builder hits this: gateway auto-apply,POST /api/update,kirocrew updateand Dev Fleet's Pull+Build. Separately, the/assets,/sprites,/fonts,/vendorand/app-assetsroutes wereadd_staticmounts that resolve their directory once at start, and were registered only if a build existed then. So re-pointingstatic/distleftindex.htmlreferencing chunks the pinned routes could not serve, and a gateway started before the first build never served one.Why it matters
Every frontend rebuild on a source checkout (the dev and Dev Fleet path, and every update that rebuilds the frontend) blanks the dashboard for the length of the build. A gateway started before the first build stays on the "not built" page until it is restarted. #13960's watchdog stand-down exists only to cover this gap.
Not a goal
outDir. An edition bundle is still staged as a private copy.install.sh's ownrm -rf+ copy through the stager. That is documented as not covered.What changed (motivation → approach → change)
Symptom → cause: the served tree was emptied and rewritten in place, and the build routes were pinned to whatever directory they resolved at start.
Approach: the served tree is never rewritten. A build publishes into
website/distby rename, and staging only re-points a link. Every build route resolvesstatic/distper request, so a running gateway follows either change at once. An alternative was to copy the current bundle aside before each build (#15834's proposal). That still leaves the routes pinned, so it was not taken.Change, in two commits:
dashboard/server.py). Each build prefix and each app-window entry is now a GET route, registered whether or not a build exists, that resolvesstatic/diston every request off the event loop. It applies the same confinement asadd_static: the resolved file must sit inside the resolved subdirectory, and a rooted, drive or share tail is refused before any lookup. A miss is a no-store 404.FileResponsestill serves precompressed siblings, ranges and conditional requests.security.md's/vendorparagraph is updated in this commit.frontend.py,website/scripts/publish-dist.mjs).--watchinto a scratch sibling. It renames that overwebsite/distonly after its post-orderwriteBundlehas run, so a failed build leaveswebsite/distalone.precompress.mjsand thesw.jsstamp follow the resolved outDir.static/dist: atwebsite/distfor a stock build that publishes this way, otherwise at a fresh immutablestatic/.dist.<id>copy. An older target revision that still builds in place has its served bundle moved to such a copy before it builds. The tree-rename swap and its rollback are removed. A build counts as published only if it replacedindex.html, compared by(st_mtime_ns, st_ino).static/distto its unbuiltwebsite/dist, so the first build is served once it lands.cli_server.py, off the event loop. It waits at most 5 s for the lock, and otherwise serves what it found with a warning.python -m kiro_crew.frontend stage [REPO]is the one stage entry point.make/make.ps1run it inbuildandwheelafter the backend install.setup.py's warning, the clean targets (scripts/clean.sh),MANIFEST.in,.gitignore,website/.gitignore, jscpd,scripts/docs_lint.py, Dev Fleet (runtime.py,worktree_ops.pycomments) andkirocrew-worktree-dev/SKILL.mdall cover the new names. No dependency changes:website/package.jsononly extends itscleanscript.Specs and docs updated in the same commits:
docs/system-specs/modules/dev-fleet.md,learn-cron-dashboard.md,security.md,docs/guides/install.md,docs/guides/windows-install.md,docs/build/gui-user-test.md,CONTRIBUTING.md,website/README.md.npm run buildstatic/distwebsite/distleft half-writtenwebsite/distuntouched🟩 added · 🟨 changed · 🟥 removed · 🟦 unchanged
Backwards compatibility
Compatible: nothing main accepts is rejected.
static/distis still a directory or a link to one, and every route still answers at the same prefix. A gateway still running pre-PR code across the transition from a realstatic/distto a link is told in the stage log to restart (documented indev-fleet.mdandinstall.md).Reader: src/kiro_crew/dashboard/server.py:_register_dist_static_routes -- entry: crew page -- the removed
add_staticmounts are replaced by per-request routes at the same prefixes | test_every_build_prefix_is_registered_whatever_the_build_holdsReader: src/kiro_crew/frontend.py:_stage_dist_locked (removed tree swap /
.dist.staging.*/.dist.previous.*) -- entry: release -- residue of the old names is swept by_sweep_staged_locked| test_stage_built_dist_sweeps_abandoned_staging_dirsReader: Makefile:frontend (no longer stages) -- entry: release --
buildandwheelstage afterbackend;install.mdsays so | test_documented_target_table_covers_every_targetReader: make.ps1:Invoke-Frontend (no longer stages) -- entry: release --
Invoke-Build/Invoke-WheelcallInvoke-StageDashboard| test_makefile_and_powershell_expose_the_same_targetsTests
test/integration/test_route_sweep.py:/assets,/fontsand/vendor, public by design (token_authbypass), are listed as unguarded 404s now that they are registered with no build.test/test_dashboard_static_routes.py: every prefix is registered with no build. A build that lands after start is served. A re-pointed link is followed on the next request. Traversal, an escaping link and anchored tails are refused before any lookup. The/assetsroot fallback and precompressed siblings still work.test/test_dashboard_asset_404_cache.py: a file swept after it was resolved is a no-store 404.test/test_frontend_dist_resolve.py: link versus copy staging, re-pointing any occupant, sweeps by identity, failed re-points leave the served tree, the restart notice,.gitignorein copies, the build-exits-0-without-publishing guard, the link made before the first build, an in-place target copied before it builds, gateway-start lock budgets, the stage CLI (relative REPO, non-checkout refusal, held lock), and_print_safeon narrow or absent consoles. Shared completeness fixtures pin the Python and JS rules equal.test/test_frontend_edition_build.pyandtest/test_cli_server_more_coverage.py: the edition stage runs off the event loop.website/src/test/publishDist.test.ts: the swap, a first build, an incomplete build refused, the in-place fallback, the rollback budget, Windows retry, and the plugin publishing last and never after a failedwriteBundle.website/src/test/publishDistBuild.test.ts: a real Vite build publishes on success. A failure in transform,writeBundle, anenforce: 'post'plugin or anorder: 'post'hook publishes nothing and keeps its own error.Manual verification
publishDistBuild.test.ts, a real Vite run rather than a mock) publishes only on success, and each injected failure keeps its own error in Vite's output.unshare -rm,mount --bind): the served copy survives a re-stage and is still served.Related Issues
Fixes #15834
Pattern harvest
Rule candidate: review-prompt
Pattern: "a route or handle resolved once at startup over a path that is re-pointed at runtime"
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)