Repository navigation
Build Test and Release
-
Development has ONE entry point; production has two builds.
bun run devrunssrc/server/index.ts, which importsindex.html; Bun bundles that page's script, styles and assets and serves them from its own routing table (/_bun/asset/*and/_bun/client/*), so there is no client watcher, nodist/clientto have been built first, and no second port.bun run buildis different: the client is built fromindex.htmlwithsplitting: trueand the server fromsrc/server/index.tswithsplitting: falseand*.htmlexternal, because a single build cannot split the client without emitting the server's own chunks intodist/client/static/— a pathplugins/static.tsserves to anyone (measured: 325 chunks, 67-98 of them the server's). Production therefore reads the shell fromdist/client/index.htmlinstead of importing the HTML bundle; see the build bullet below. -
HMR is real and Bun owns it.
Bun.serve({ development: true })injects its own client and pushes updates overimport.meta.hot; saving a client file is applied in the browser, saving a server file restarts the process (bun run --hot). Thedev-assets.tsproxy that forwarded rsbuild's hot-update chunks is gone with rsbuild. -
Dev assets are proxied through the server, because Bun's own dev asset routes cannot be cached and that is what made every page load re-download the bundle. In
development: trueBun answers/_bun/client/*and/_bun/asset/*from its routing table with anETagit then ignores (If-None-Match→ always200+ full body), noCache-Control, and no compression — measured on 1.4.2: a 19.7 MB unminified dev bundle was re-sent in full on every load, against 9.5 MB once in production.lib/assets/dev-assets.server.tscloses it:ssr.tsrewrites the shell's/_bun/client|asset/urls to/_dev-assets/*(Bun's table wins for the paths it declares, so a route on/_bun/*is never reached — verified), and that module fetches the bytes back from the listener to addCache-Control, a contentETagand the304, plus the compressionplugins/compress.tsalready provides (19.7 MB → 3.3 MB zstd)./_bun/hmr(the WebSocket) and/_bun/unref(the beacon) deliberately stay on Bun. The rewrite runs BEFORE the bootstrap payload is injected, so a/_bun/string inside a user's settings is untouched.no-cache, neverimmutable: the bundle's name is a build-generation hash that changes per rebuild, but the CSS asset names are NOT content-addressed — appending a rule totailwind.csschanged the bytes at the same/_bun/asset/<hash>.cssURL — soimmutablethere would pin stale styles for a year. -
The dev bundle is held by the service worker, not the HTTP cache, because the HTTP cache physically cannot hold it. Chrome declines to store a response whose decoded body reaches ~5 MB — measured with
Cache-Control: no-cacheand a workingETag: 1 MB and 4 MB answered304on the next load, while 5/6/7/8/16/20 MB were re-fetched in full and never sentIf-None-Match. So the proxy alone still left the 19.7 MB bundle re-downloading every load.public/sw.jstherefore caches/_dev-assets/client/*in Cache Storage (no per-entry limit; verified: the second load reportstransfer: 0and the cache holds one entry). It keeps ONE generation — storing a new bundle deletes the others, so a rebuild cannot accumulate bundles — and it deliberately does NOT cache/_dev-assets/asset/*, whose names survive a content change; those go to the network and revalidate through the proxy'sETag. -
developmentis derived, not configured: Elysia's Bun adapter passesdevelopment: !isProductiontoBun.servefromNODE_ENV, sobun run devandbun run startdiffer by that one variable and nothing else. The proxy and the shell rewrite are gated on the same variable (DEV_ASSETS_ENABLED), so production is untouched: its assets are content-hashed and already answered with a working304andimmutableby Bun's table (runtime) orplugins/static.ts(AOT). -
Production assets and the shell ARE compressed; Bun's runtime-prod chunks are not, and cannot be from here.
maybeCompressreaches the API routes (route-adapter.ts), the dev proxy andplugins/static.ts(a built asset, keyed per ETag inlib/assets/compressed-cache.server.ts) and the SSR shell — the shell isno-storeand served on every navigation, and/fonts.cssis 4 KB on every load, so both were the repeated cost. Measured on this repo's own bundle: 10.5 MB → 2.26 MB zstd / 2.45 MB gzip / 2.16 MB brotli, one 20 ms pass per build (2 ms warm). AVary: accept-encodingrides EVERY response of a compressible type, the304included — a shared cache that stored the identity variant would otherwise hand it to a client that accepts onlybr. The shell itself is now ~5 KB of markup: the two generated stylesheets (182 KB) are a content-hashed,immutable/theme-<hash>.cssinstead of inline<style>blocks. -
A dev server walks toward the descriptor cliff, and the surface now says so before the breakage.
development: truekeeps the whole client module graph open for HMR — measured 3,545 descriptors after a single page load for this app, against 17 withdevelopment: false— and a macOS reload never closes the previous generation's (bun#40706; the pre-exec sweep exists only on Linux), so the count climbs with every rebuild (measured +2…+9 per edit, ~17/min on this repo while agents edit it). At Darwin'sOPEN_MAX(10,240)posix_spawnstarts answeringEBADF: bad file descriptor, posix_spawn '/bin/sh'— verified A/B: 10,230 descriptors spawn fine, 10,240 fails — and from then on every spawn in the process fails at once: the PTY shell, the omp child,git,rg, until the instance is restarted.lib/lifecycle/fd-pressure.tskeeps the count visible:GET /api/healthcarriesfds: { open, highest, limit, nearCliff }(afcntl(F_GETFD)sweep capped at the cliff, ~1 ms, null where the host cannot answer) andkabmo statusprints it with a restart hint. A long-lived session belongs on a production server: 17 descriptors, not 3.5k. -
Process-wide state that owns a descriptor belongs on
globalThis, not in a module binding.bun --hotre-evaluates a changed module in place, so a module-level cache is reset while its handle lives on and the old one is never closed.db.server.tsleaked abun:sqlitehandle per reload of that file — measureddb.sqliteanddb.sqlite-walat 19 descriptors, +2 per edit, each one 2 descriptors closer to the cliff above. The slot isglobalThis.__kabmoDb, for the same reason the terminal store, the flock host and the provider cache are anchored there. -
lib/assets/conditional.server.tsowns the one "is the client's copy still good?" decision, because two routes hand out bytes and they must agree:plugins/static.ts(a file on disk) andlib/assets/dev-assets.server.ts(bytes fetched back through Bun's dev asset routes). A rule applied to one and not the other would make one asset kind revalidate differently from another for no reason a caller could see. The load-bearing part is precedence — RFC 9110 §13.1.3: a recipient MUST ignoreIf-Modified-Sincewhen the request carriesIf-None-Match, so the presence ofIf-None-Matchsettles the response on its own and a non-match means "stale" (200), never a reason to consult the date. Every branch errs toward "not modified = false": a false costs one full response, a wrong true hands the client a stale asset with no way to notice. The file route mints a WEAK validator from size+mtime (W/"<size>-<mtimeSec>") — a content hash would mean reading every asset on every request, the opposite of the point, and a wrong 304 from size+mtime needs both a same-size edit and a preserved mtime, which no build or editor does. The mtime is floored to whole seconds before comparing: HTTP dates carry one-second resolution, so a file whose mtime has a fractional part would otherwise be permanently "newer" than theLast-Modifiedthis server just sent for it and could never revalidate (measured:IMSon an unfloored mtime answered200every time). Verified end to end in both prod modes —/sw.js(the onlymax-age=3600asset, so the only one that ever revalidates) now answers304toIf-None-Matchand to a freshIf-Modified-Since, and200+ the new bytes once the file actually changes. The AOT bundle had no validator at all before this, so every hour each client re-downloaded it in full; runtime mode already had one from Bun. -
A unit suite's temp directory is the suite's to remove, and
afterAllis the only hook that actually runs.bun testdoes NOT fire aprocess.on('exit', …)a test file registers (measured: the marker file never appeared), sosrc/server/lib/btw/schema.server.test.ts's exit hook had never deleted anything — three.sqlite+-wal+-shmtriples per run, forever. The measured leak inventory for one fullbun testin an isolatedTMPDIR, before and after: 30 entries / 3 GB-scale accumulation → 2 entries. The shapes that leaked, each now fixed: an array ofmkdtempSyncroots collected and never swept (fs-path.test.ts, 5 dirs); removing the CHILD of amkdtempinstead of the parent (plugins/static.test.tsremovedpublic/,plugins/build-server.test.tsremoved the copied plugin — 3 empty parents);path.join(roots[0] ?? tmpdir(), …)falling through to$TMPDIRitself onceafterEachhad emptied the array (db.server.test.ts's blocker files); and nine inlinemkdtempSynccalls in one file with no teardown at all (marketplace/plugins/command-runner/src/server/resolve.test.ts). The audit command isTMPDIR=/tmp/audit bun test && ls /tmp/audit— a fresh$TMPDIRis the only way to see the leak, because the developer's own$TMPDIRis already full of it. Two entries are expected and correct:kabmo-test-bins(the compiled-fixture cache, pruned by age) andripgrep-wasm-<hash>.wasm(theripgreppackage's own cache, keyed by its wasm hash). -
bun run build(scripts/build-client.ts) runs TWO builds intodist/client: the client fromindex.htmlwithsplitting: trueandminChunkSize: 16384, then the server fromsrc/server/index.tswithsplitting: falseandexternal: ['*.html']. The server bundle is whatkabmo serveexecutes (fromdist/clientas its cwd); the client bundle is what the shell links. Why split: without it everyimport()is inlined into one entry — measured 13.40 MB raw / 3.26 MB gzip, with@shikijs/langs3.07 MB,@shikijs/themes1.26 MB, mermaid 1.60 MB and xlsx 0.48 MB all on the boot path, which defeats the lazy grammar/theme design inshiki-langs.ts. With it the boot chunk is 1.90 MB raw / 590 KB gzip and 143 dynamic chunks resolve over HTTP (verified 143/143200). Why two builds: one build withsplitting: truealso splits the server, and its chunks land underdist/client/static/— publicly served, and/static/is auth-exempt.Bun.buildvia the JS API, neverbun build: the CLI does not readbunfig.toml's[serve.static]plugins (verified:bun build --target=bun --productionemitted Tailwind's@themeverbatim, zero utility classes). -
bunfig.toml's[serve.static].pluginsis the dev and prod plugin list. One entry,src/server/lib/bundler/css.ts, which expands Tailwind v4 (@theme/@import "tailwindcss"are PostCSS syntax Bun's CSS parser rejects), flattens nested at-rules (nested-at-rules.ts, registered after Tailwind), and lifts@font-faceblocks out of the bundle.scripts/build-client.tspasses that same module toBun.buildexplicitly. -
That plugin makes the Tailwind toolchain a RUNTIME dependency, not build tooling.
Bun.serveloads it whenever an HTML route is bundled — everykabmo serve --devand everybun run start— so@tailwindcss/postcss,postcssandtailwindcssare all declared independencies. They were not:@tailwindcss/postcsswas a devDependency andpostcsswas declared nowhere, which no local run could reveal (a checkout has the whole tree) but a published install cannot load. Measured on a production-only install of the published tarball: the server came up and answered503on every page, loggingerror: Failed to load plugins for Bun.serve: Cannot find package 'postcss';bun add -gfailed one dependency later on@tailwindcss/postcss.tailwindcssitself is direct rather than transitive because@import "tailwindcss"insrc/client/tailwind.cssis resolved by Tailwind's own resolver from the project root — verified by forcing the package out of the root (nested under@tailwindcss/nodeonly): the bundle then fails with anenhanced-resolveerror.src/server/lib/bundler/dependencies.test.tswalks every bare import insrc/and fails if one is missing fromdependencies(adevDependencycounts as missing), which is what keeps a build-shaped module from drifting back into the build-only list. -
Nested at-rules must be flattened before Bun sees them, because Bun's minifier re-nests them into a form Chrome drops. For
target: 'bun'(which this build needs — its entrypoint is the server) Bun emits a rule's nested at-rule as@supports (…) { & { … } }, and a nested rule whose parent selector names a pseudo-element is inert in Chrome:&under::placeholderor::-webkit-scrollbar-thumbnever applies, so the rule's earlier fallback declaration wins. Tailwind emits its colour fallbacks in exactly that shape (color: var(--x); @supports (color: color-mix(…)) { color: color-mix(…) }), so the whole app's placeholder and scrollbar colours collapsed to full ink — and the same shape also cost--ink-secondary/--ink-muted/--ink-hairline,--theme-info-hover/--theme-warning-hover, and the.prose-content/.shiki .find-matchrefinements.flattenNestedAtRules(nested-at-rules.ts) hoists each nested at-rule out of its rule with the parent selector resolved, preserving declaration order and the containing@layer, so the emitted CSS is@supports (…) { .sel::placeholder { … } }at the top level and no minifier has anything left to re-nest. The rsbuild pipeline this replaced compiled for browsers and flattened the nesting itself, which is why the migration surfaced it.css.test.tsbuilds a fixture through the real plugin with the production options and fails if&survives — asserting on the flattener's own output would not catch it. -
Font faces cannot be bundled. Bun's CSS loader resolves EVERY local
url(): withfileit inlines the font as base64 (592 kB stylesheet, ~377 kB gzipped, every face downloaded whether or not a formula renders) and withdataurlit writes the ABSOLUTE FILESYSTEM PATH into the CSS. A same-origin path is not an escape hatch —url("/fonts/x.woff2")fails the build with "Could not resolve"; measured against Bun 1.4.2, onlydata:,http(s):and protocol-relative urls are left alone. So the faces leave the bundle: the plugin rewrites them to/fonts/<basename>and strips them from the module, and the server re-declares them on/fonts.cssby reading the same source stylesheets undersrc/on every request (lib/assets/font-faces.tsholds the extraction, shared by both ends) whilelib/assets/fonts.server.tsresolves each basename back to the installed package. The server derives the sheet from source rather than from a directory the bundler wrote, because that artifact is produced once per process and can never be repaired — anrm -rfwhile the server runs, or a fresh clone that never built, left/fonts.cssempty for the rest of the process and the terminal's Nerd symbols face silently vanished (tofu boxes, no error). The shell links it throughapp-head— a<link href="/fonts.css">inindex.htmlwould be resolved by the HTML loader and fail the same way. -
index.html's own asset references are relative (./public/icon.svg), because the HTML loader resolves them and emits hashed copies; an absolute/icon.svgfails the whole build. The manifest's OWN icon entries stay absolute (/icon.svg): Bun does not rewrite inside a copied JSON file, andpublic/is served directly. -
public/sw.jsis served by a route, not by the bundler — it is referenced only from an inline<script>, which the HTML loader does not scan, so it is never copied.tryServeStaticanswers it frompublic/. -
Asset roots are resolved from the package, not the cwd (
lib/assets/fonts.server.tswalks up fromimport.meta.dir). An installed package runs the AOT bundle withdist/clientas its cwd, where a cwd-relativepublic/ornode_modules/does not exist. Two questions, two resolvers, and they are NOT the same directory in every install shape:packageRoot()is the first root holdingnode_modules(where the DEPENDENCIES are — fonts are served from there), whilepackageDir()is the first root holdingsrc/(where the PACKAGE is — the source stylesheets/fonts.cssis assembled from live there). A hoisted install puts the package undernode_modules/kabmo/and its dependencies in the parentnode_modules/, sopackageRoot()is the PARENT — resolvingsrc/through it found nothing, served an empty/fonts.css, and silently dropped every@font-face(the Nerd symbols face among them). Verified against a simulated hoisted published install: empty sheet throughpackageRoot(), full 4064-byte sheet throughpackageDir(). -
The shell is a Bun HTML route in development and a built file in production. Development fetches the server's own
/_shellroute, because Bun renders an HTML route only while serving and there is no in-process API for anHTMLBundle—new Response(bundle)yields "[object HTMLBundle]" andapp.handle('/_shell')answers 404, because the route lives inBun.serve's routing table rather than Elysia's. Production readsdist/client/index.htmlonce and caches it for the process (a rebuild needs a restart, exactly as Bun's cached route did), which also removes a loopback HTTP request and a full HTML transfer from every navigation. The import is dynamic and guarded (lib/lifecycle/shell-entry.server.ts) so the server build can mark*.htmlexternal; a static import would bundle the client graph into the server and production would resolve an HTML bundle it never serves. -
A shell that would not render reports the EDIT that broke it, and a
200is not proof it rendered.renderShellused to check only!response.ok, so a failed client bundle surfaced as "Shell route answered 500." — while the file, line and message sat inside Bun's own "Build Failed" page as a binary payload (Uint8Array.from(atob(…))) with no server-side reader.lib/bundler/build-errors.server.tsobtains them the supported way instead: after a failure, it rebuilds the same entrypoint withBun.build({ target: 'browser', throw: false })and the pluginsbunfig.tomlnames, and formats eachlog.positionasfile:line:column messageplus the offending source line. The probe is not a subset of the route's failures, deliberately: a missing named export is answered200by the route while Bun swaps the bundle for a 104-byte stub that only callslocation.reload(), so the page cannot run and is reported as the real failure it is; an unresolved import that tree-shaking drops fails nothing and stays silent (verified against the route on Bun 1.4.2 — both500shapes reported, both200shapes handled as above). The check is on the MARKUP, not the status: withdevelopment: falseBun caches the HTML route's output, and a build that failed on the FIRST request leaves it caching an empty body answered200for every later request — measuredreq1 500 len=0,req2..n 200 len=0, still empty after the source was fixed, because production never rebuilds that cached output.SHELL_MARKER(<!--app-bootstrap-->, shared with the SSR route's substitution) is what distinguishes real markup from a cached failure; when the bundle builds cleanly but the markup is not the shell, the page says the fix is a RESTART, because that is the only thing that rebuilds it. Both the reason and the marker travel through the same 503 page, HTML-escaped — the reason carries arbitrary source lines, and a<in one would truncate the page at the first tag. -
serve.routesand Elysia's routes coexist:new Elysia({ serve: { routes: { '/_shell': shell } } })— Bun's table wins for the paths it declares, everything else reachesapp.fetch, and Elysia'swebsockethandler is composed alongside.
-
The layer above
bun test, and the only one that sees the assembled product. Unit and component tests mount a tree in happy-dom; route suites call handlers in-process. Neither sees the SSR shell, the client bundle through Bun's asset routes, the realtime socket, a spawnedompchild, or a real panel width. Every bug that reached a user this cycle lived there — a stream indicator that died 450 ms in, a toolbar clipped at 296px, a wiki link that opened a tab. The specs are the regression net for that class. -
The MOCK update popup opens over the app on every boot, and a spec must dismiss it — with a locator HANDLER, not a click.
MOCK=trueanswers "an update is available" (MOCK_CURRENT_VERSION/MOCK_LATEST_VERSIONinlib/updates/check.ts), so the Update dialog'sfixed inset-0backdrop swallows every click. The check is ASYNCHRONOUS, so a click issued atdomcontentloadedlands before the dialog exists and the later popup then blocks the next action — the flake this pins.fixtures/app.ts'sopenApp/installOverlayHandlerregister apage.addLocatorHandleron the popup's "Later" button, which fires whenever it appears (and again on a reload). Do not "fix" this by disabling the popup or by sleeping. -
A spec waits on a CONDITION, never a duration, and the condition must be the one the action needs. Three real flakes were found and pinned this way: a send issued before the sidebar's folder list loaded had no
cwd, fell to the mock path, and rendered nothing (the folder's name on screen is the gate); a reload issued before the 600 mssession-statedebounce landed read the previous layout back (page.waitForResponseon thePOSTis the gate); and keystrokes typed as soon as[data-terminal-root]was visible were written to a socket with no shell behind them and lost (thereadyframe on the terminal socket is the gate). AwaitForTimeoutwould have been too short on a loaded runner and wasted time on an idle one, in all three cases. -
A gate must be the thing the action needs, not a state the app is free to skip — and an absent state is not a gate.
editor-scroll.e2e.ts's reload spec waited for the editor to readSelect a file to openbefore reopening its file. But the tab list is itself persisted (layout.openedFiles), so whether the panel draws that placeholder or the file it already had open depends on the order the restored blob lands in — a race the spec does not own (and the root-change wipe is gone:useFileTabsnow closes tabs only on a genuine root CHANGE, never on the first known root or a transientnull). Measured on the failing CI leg: the placeholder was never drawn and the assertion timed out for 15s while the panel was already correct, and the spec then passed on retry. The session-state GET is the gate (the blob is what the click needs); reopening a file that already has a tab reuses that tab, so the placeholder adds nothing. -
A "platform limit" is a claim to verify, not a reason to skip. Both
terminal-capacity.e2e.tsspecs andterminal.e2e.tsskipped Windows on the belief that the PTY child could not stay alive there. It could: the cause was Kabmo's own spawn (detachedon Windows =DETACHED_PROCESS= no console, socmd.exeexited 1 immediately), and once fixed all three specs pass on that leg — the ConPTY byte-difference theterminal.e2e.tsskip also cited never mattered, because neither of its assertions compares bytes (a prompt character class and a unique marker). The cap's WINDOWS BRANCH stays covered independently bystore-liveness.test.ts, which injectsplatform: 'win32'. A skip that outlives its cause is worse than no skip: it reports the platform as unverifiable and hides the product bug that made it look that way. Before adding one, reproduce the failure against the real spawn and name the exact option/API that causes it. The same file now carries ONE skip that passed that test, and it names its two inputs:a stream can be scrolled and selected fromtypes a POSIXshloop into the shell and copies withMeta+C. On Windows the shell iscmd.exe, soclearresolved to Git-for-Windows'clear.exe, printed its usage, and left thewhileloop as ARGUMENTS — the buffer never grew past one screen, the wheel had nothing to scroll into andLatestnever appeared (measured on shard 4/4 of run43112230252, with the screenshot in that run's artifact); copy isMeta+Conly inghostty-web'sdist/ghostty-web.js, a chord Windows does not deliver. Revisit when the spec streams through PowerShell or a terminal copy chord that is not macOS-only — and note the product gap the skip exposes: a Windows desktop has no keyboard copy in the terminal, becauseTerminalKeyBarrenders only on touch. -
Assert the observable that actually changes, not the control you clicked. The editor's saved state is an icon swap and its
aria-labeldoes not move, so the spec asserts the FILE ON DISK; the terminal paints to a canvas with no text nodes, so the terminal spec asserts the terminal socket's frames — and, where the claim is about paint, the canvas pixels (the cell padding, the DOM caret), never the wrapper's class list. -
A dialog's state is initialized by MOUNTING it fresh, never by a reset effect — and this spec is what found that.
NewWorkspaceModalkept one mounted form and cleared its fields in auseEffectkeyed onisOpen; Preact runs effects AFTER paint, so the dialog was on screen and its fields focusable before the reset landed, and anything written in that window was discarded. Measured through this layer: a path typed into the field was wiped and the listing stayed on the home directory; the same bug inDirectoryList's new-folder field left it empty with the submit button disabled. The fix is structural —if (!isOpen) return nulland mount the form — so there is no ordering question to get wrong. The related lesson is thatfill()is a legitimate way to find this: it writes synchronously after the element exists, which is exactly the window an effect-based reset loses. -
getByRole(name:)matches a SUBSTRING, so a fixture's locator handler can click the wrong thing.installOverlayHandleraddresses the update popup's "Later" button; a spec that put a row namedappeared-lateron screen had that row matched and CLICKED by the handler, which navigated the dialog into the folder and made the row vanish — a failure that looked like a broken refresh. The handler's locator carriesexact: true. Check every locator used inaddLocatorHandler(and any handler that fires on a page-wide match) for this: the popup's own control is exactly "Later". -
Two runners, disjoint globs, on purpose.
bun testowns*.spec.ts; Playwright owns*.e2e.ts(testMatchintests/e2e/playwright.config.ts). The first version of this layer used.spec.tsandbun testimported the Playwright file into its own process, wheretest.describethrows "Playwright Test did not expect test.describe() to be called here". Never let the globs overlap — neither runner can be told to ignore a file the other owns without also hiding a real suite. -
The runner is Playwright's own, in
tests/e2e/, neverbun test. A browser spec needs a per-file context, a per-file server and a trace artifact — a lifecycle Bun's runner does not own, and one that fights its single-process, shared-globalThismodel (the reasontest-support/isolated-db.tsexists). -
fixtures/server.tsboots a REAL server subprocess, not an in-process Elysia app, because the thing under test is the assembled product. It is runtime-agnostic (node:child_process,node:net,globalThis.fetch) — it runs in a Playwright WORKER, which is Node, so aBun.spawnthere is a ReferenceError. -
Isolation is the contract, and it is why
getDatabasePathwas fixed. Every path the server writes is redirected under one temp root removed at teardown:KABMO_DATA_DIR,KABMO_DB_PATH,PI_CODING_AGENT_DIR, plusSYNC_WORKSPACE=false.getDatabasePathput the MOCK branch BEFORE theKABMO_DB_PATHcheck, so aMOCK=trueserver started from a checkout wrote the repository's ownworkspace.dbno matter what the caller set — verified, and pinned bysrc/server/db.server.test.ts. An explicit override now wins over BOTH defaults. Do not reorder those branches; a test that leaks into~/.kabmoor the checkout'sworkspace.dbcorrupts the developer's machine. -
Readiness is polled on
GET /api/health, and the PORT is compared, never parsed from the boot log. The route is a stable shape (ok,mock,port); a log line is prose a future edit may reword. Comparing the port is what stops a stale instance or a lost port race from being adopted silently. -
fixtures/fake-omp.tsis the keystone, and it is a real protocol CLIENT, not a mock. It speaks omp's NDJSON wire (ready,{type:'response'}withcommand/success/data, and the session event frames), so the code under test is the real spawn path, frame reader, frame fold, realtime topic and renderer. A double that stubbed any of those would test the double — the same argumenttest-support/realtime-server.tsmakes. It honors the argv Kabmo actually builds (--mode rpc-ui --cwd … --resume … --approval-mode …) and prompts select behaviour:delay:<ms>,tool:<name>,edit:<pairs>,ask:<text>,error:<text>,retry:<n>,slow, defaultResponse to: <prompt>.edit:<pairs>emits a realeditcard whosedetails.diffis omp's EXCERPT dialect of that many removed/added PAIRS — every row a change, because the card renderscontentMode: 'diff'and a patch of context lines collapses back under the 288px ceiling, where the scroller's range is 0 and a spec built on it proves nothing (measured). It is the only way a browser spec can observe the diff card's own scroller. -
The fake must emit the FULL accumulated
message_updateframes Kabmo requests.configureChildsendsset_event_filter {messageUpdates:"full"}, so everymessage_updatecarries the whole message again — that is what the client folds. The fake re-sends the accumulated content on each delta (and the tool-call fixture re-sends its block with the name/id), so a spec observes the same shapes a real child sends. -
A builtin that opens no turn must be acked
agentInvoked:false, and the ack must be the ONLY response. The wrapper readsagentInvoked:trueas "this dispatch claimed the turn slot" and holdspromptRunninguntil the agent-start watchdog fires; theprompt_result {agentInvoked:false}that follows is then suppressed by the run-attribution rule inframe-fold.ts(see Chat-Stream-and-Tools), so nothing clears the flag early. Measured on the release run of 2026-11-18 (44249018348): the fake acked every prompttruebefore dispatching on the message, so the client's/kabmo-modeplan-review republish left the session reporting busy for ~10 s after the answer landed —rename.e2e.tswas refused with "This session is working" on a session that had finished, 4 of 10 shards red, and 1 flake in 6 locally./renameand/kabmo-modenow answerfalseand nothing else; the dispatcher's own decline path emits the settle frame when it owns the slot. -
FAKE_OMP_RECORD_PATHappends every RECEIVED frame as JSONL, so a spec can assert what Kabmo sent (that the event filter was requested, that a reload reached a live child) rather than inferring it. -
Two modes, chosen per spec.
mockuses the seeded demo presets and needs noompinstall (fast, no fake).realrunsMOCK=falsewithKABMO_OMP_BINpointed at a shim that execsfake-omp.tsunder Bun — the shim exists because the server spawns the path directly, so it must be executable. There is no model and no network in either mode. -
Fixture data is created through the REAL API (
fixtures/seed.ts→POST /api/folders), never by writing the database. A hand-written row skips the route that resolvesproject_pathand the scan the sidebar reads, so it tests a state the app cannot produce. -
Every temp directory is REGISTERED the moment it exists, because the per-spec teardown is not the whole story.
fixtures/temp-root.tsowns the registry and is the only place this layer mints a temp dir (makeTempDirfor test scope,makeProcessTempDirfor the compiled fakeomp, which outlives the test that built it). Three shapes leak without it, and each was measured: a spec that FAILS or is retried mid-body skips everydispose()at the end of that body (a probe spec seeding a workspace and a working repo left 2 + 2 directories on each of its two attempts), a Ctrl-C kills the worker before any teardown runs, and a SIGKILLed worker runs nothing at all. So the registry has two scopes and one sweep: the_tempRootsauto fixture opens a test scope before every body and sweeps it after — which is the failure path adispose()cannot reach — and process exit plus SIGINT/SIGTERM sweep the process scope.auto: trueis what makes the ORDER right (an automatic fixture tears down after the spec's own), soserver.stop()has already released the directory handles; a workspace the server still had open would fail to delete on Windows.HarnessServer.stop()still removes its own run root and then callsuntrackTempDir, and its removals are individually try/caught — a fixture teardown that throws is reported as the SPEC's failure. The one case no in-worker hook can reach is a SIGKILL, and that isglobalSetup's job:sweepStaleTempDirs()runs once before the first worker and deletesomc-e2e-*directories older than two hours (mtime, not birthtime — a directory keeps being written while its spec runs), which is what stops the accumulation. Measured on this machine before the fix: 964 directories and 1.3 GB in$TMPDIRover four days, dominated by 310 seeded workspaces and 369 run roots; after it, a passing run, a failing run and a Ctrl-C'd run each leave 0.sweepStaleTempDirstakes an injectablerootbecause it deletes BY NAME — the first version of its unit test ran against the real$TMPDIRand reclaimed the developer's 964 directories, which is exactly the hazard the option removes.fixtures/temp-root.test.tscovers both scopes and every sweep rule against a private root, andtests/e2e/tsconfig.jsonexcludes**/*.test.tsbecause those files importbun:testwhile the program deliberately hastypes: ["node"]only (addingbun-typesthere would also let a SPEC reachBun.*, a ReferenceError in a Playwright worker). -
The compiled-fixture cache is NOT a temp root: it is a shared, deliberately persistent directory, and its key is a hash of the stub's SOURCE.
src/test-support/executable-stub.tscompiles a stub to a real executable (Bun.build({compile:true}), ~90 MB on disk because the Bun runtime is embedded) into$TMPDIR/kabmo-test-bins/<label>-<sha256(source)>, because libuv'ssearch_pathstarts only.com/.exeand a#!/bin/shfixture is unspawnable on Windows. Two consequences, both measured: a source that embeds a PER-RUN value — amkdtempSyncpath baked in withJSON.stringify— misses the cache on every run and leaves the previous binary forever (bun testgrew the directory by ~200 MB per run from two suites, reaching 40 GB before anyone noticed; a version answer baked per case did the same for theomp --versionstub), and a source that does NOT is compiled once and reused indefinitely (a fullbun testnow leaves 12 directories / 1.2 GB on the first run and the same 12 / 1.2 GB on the second — verified). Pass per-run values through the environment instead: every spawn site that runs a fixture hands the child an explicitenvbuilt fromBun.envat spawn time (childEnv()), so aBun.env.X = …assignment made in-process DOES reach the child — the claim in the old comment, thatBun.spawnonly ever sees the STARTUP environ, holds only for a spawn that passes noenvat all (verified on Bun 1.4.4: runtime-set visible with{...process.env}, invisible without). The sweeper for it issrc/test-support/stub-cache.ts(pruneStubCache, a week by mtime, node-only so both layers can import it):executableStubruns it once per process, and the E2EglobalSetupruns it too —sweepStaleTempDirsdeletes by theomc-e2e-name prefix, so it can never reach this directory, and a stale binary from a changed source would otherwise sit there for good. -
data-testidonly where no stable accessible name exists. The preference isgetByRole+ accessible name (the toolbars already carrytitle/aria-labelon every icon-only button), then visible text, then a testid for a container to scope a query, a virtualized row, or a canvas. Measured:src/had ZERO testids before this layer; the set added isapp-root(both layouts) andcomposer-input. Message rows already carryid={msg.id}, so a spec addresses a row by its id rather than by a new attribute. Add a testid as part of the spec that needs it, with a stable domain name — never speculatively, never layout detail. -
The E2E project is typechecked separately (
bun run typecheck:e2e→tsc -p tests/e2e) because it runs under Node, not Bun, and the root tsconfig covers onlysrc/andpackages/.ci.ymlruns this gate so a broken spec fails the cheap job, not only the browser one. -
The browser layer runs on a pull request only when the
e2elabel is applied, plus nightly and manual dispatch (.github/workflows/e2e.yml). A push tomainruns the SAME suite insiderelease.yml, whosee2ejob callse2e-specs.ymlandneeds:it before anything is tagged — so the merge is verified without a second workflow, and the label stays the cheap-PR escape hatch. Measured on 26333b1, apush:trigger one2e.ymlmade every merge run the matrix twice (E2E 25m17s besideE2E specs / Chromiumin the Release run), and the duplicate pair is a second chance for a flake to read as a redmain. The nightly cron still coversmain's tip when nothing has been pushed. Chromium is required; firefox/webkit are opt-in projects not yet run in CI. Failure artifacts (trace, screenshot, HTML report) are uploaded only on failure. -
The browser suite is SHARDED across runners, and
workersis not the lever. Measured on the release run of 2026-11-11 (42955898928): 33m02s wall, of which the gate was 28m45s andE2E specs / Chromium (Windows)alone was 28m45s — 87% of the run, with every other job under 8 min. The suite is 163 tests atworkers: 1; raising it to 2 bought 12% (1.7m → 1.5m over 21 tests) and made two specs flake, because two servers and two browsers contend for one CPU and the assertions are timing-sensitive. A shard is a separate MACHINE, so it keeps the one-worker-per-machine property the config depends on and scales linearly: 3 shards on Linux (60/53/50 tests) and 4 on Windows (41/48/36/38). Windows is the bound of the run at ~7 min; the Linux leg lands at ~5 min, so it is no longer sized to finish together with Windows.--shardbalances by TEST COUNT, not duration, so the shards are not exactly equal — the job timeouts are ~3x the expected shard, which is still a hang detector.fail-fast: falseis load-bearing: a red shard must not cancel the others, because every shard's failure artifacts are what a reader needs. -
bun test --shardis NOT usable on this suite yet, and the reason is a real bug. Measured 2026-11-12:--shard=1/2failed 6 cases insrc/server/lib/sessions/spawn.server.test.tswithUNIQUE constraint failed: workspace_folders.id,--shard=2/2failed 3 more, while the unsharded run was 11259 pass / 0 fail. The file passes alone and passes in the full run, so the cause is cross-file env leakage: an earlier file leavesPI_CODING_AGENT_DIR(orSYNC_WORKSPACE) set,getDb()then seeds workspace folders from discovery into the database the next file expects to be empty, and the seed takes id 1. Sharding only changes which file runs before it. Fix the leak before sharding the unit gate — and note it buys nothing today anyway, because the browser shards land at ~7 min and the Windows unit job is 6m36s. -
A suite that installs a DOM window puts it back through
test-support/pristine-globals.ts, andEventtravels WITHEventTarget. The Linux leg of release run43379328083failed 15 cases across files that could not have caused them.terminal-panel/scroll-hold.test.tsdied withArgument 1 ('event') to EventTarget.dispatchEvent must be an instance of Eventbecauseworkspace/editor/plugin-rail.test.tsxinstalled a happy-dom window per case and never restored it, andhooks/ui/ui-listeners.test.tsinstalled eight globals inbeforeAllwhile its own comment claimed a matchingafterAllthat did not exist. Bun discovers files from the filesystem, so which suite follows changes between checkouts — such a leak is latent until an unrelated file is added. The shared helper captures the runner's values on the FIRST install; a local save-and-restore loop captures whatever the previous file left behind and then restores the leak.EventTargetis in its list for the same reasonEventis: a target from one realm refuses an event from another, so installing half the pair turns any laterdispatchEventinto a TypeError.fetchis on that list too, and a stub that the TEST settles is the worst kind to leave behind.packages/kabmo-ui/src/fetch.test.tsxreplacedglobalThis.fetchwith one that returns a promise its own case resolves later, and itsafterEachrestored the DOM globals but notfetch. Every later file that made a real request then awaited a promise nothing would ever settle: the Linux gate's foursrc/cli/lib/commands/session.test.jscases each died at bun's 5000ms timeout, in a suite that names neither the installer nor the component. Reproduced deterministically by running the two files in one process (bun test packages/kabmo-ui/src/fetch.test.tsx src/cli/lib/commands/session.test.js— 4 pass, 4 fail before; 8 pass after). Restore throughBun.fetch, never a captured value: the handle is the runner's own whatever ran before. The same run-wide sharing is why a suite that mints a PERSISTED slice id must mint it process-wide —editor/find-harness.test-util.tskeyed its session id on a per-file counter, so the second file'stest-session-2read the first file's persistedalphaback and the "an empty selection seeds nothing" case failed withReceived: "alpha"on the Ubuntu gate; the counter now lives onglobalThis. The same lesson applies to a helper that SPAWNS something: assert the state the code under test actually reads, not the state you asked for.test-support/peer-harness.tswaited for the session lease to be held and returned, but the ownership guard matches the holder's PARENT against an instance record and thesh -cwrapper reparents it a moment LATER — so the record was written with a guessedpid: 1and the Linux gate (43568904108) answered locally withownerCalls === []. The helper now waits for the reparenting and returns{ pid, parentPid }, and each caller writes the record with the pid it got back. -
A module-level client cache is voided together with its in-flight read.
fetchModelsDatakeepsinFlightto dedupe concurrent callers, andinvalidateModelsCacheused to clear onlycached— so a read started before an invalidation was handed to a caller that invalidated on purpose (the stale-picker bug it exists to prevent), and a read that never settled owned the slot for the rest of the process. Measured on the same run's Linux leg: five cases timed out at the runner's 5 s budget (models.test.ts,provider-ui.test.ts) and three morewaitForDoms gave up with a healthy stub installed, one file after another. The fix is a generation counter — an invalidation bumps it and dropsinFlight, and only a read from the current generation may write the cache — pinned bymodels.test.ts's "an invalidation also retires a read that is still in flight". -
A preact tree that is DETACHED is still subscribed, and its next re-render happens after the window is gone. Release run
44213261035's Windows shard failed 8 cases inclient/lib/plugins/list-slots.test.tswithReferenceError: document is not definedinside preact's flush — a file that mounts nothing. The cause was one file earlier in the shard:chat-timeline/MessageList.test.tsmounted twoMessageListtrees per test and only dropped the container, soAiMessageFooter's plugin strip kept itsuseListSlotRows('messageAction')listener alive; the firstregisterListSlotin the next file published, preact queued an update, and the flush readdocumentafterafterAllhad removed it. The same tree never failed on macOS, where the deferred flush landed inside a test. Unmount (render(null, container)) inafterEachand put the globals back throughpristine-globals.ts; a0unmount count in a file that callsrender()is the shape to grep for. Order-dependent failures name the file that SURFACED them, not the file that leaked.
- Route modules keep the ported Remix shape: an exported
loader(GET) and/oraction(mutating verbs).actionowns method dispatch — it branches onrequest.methodand returns its own405 { error: 'Method not allowed' }. - Because of that,
bindingsFor/actionBindingsmountactionon all four mutating verbs, and add a 405 GET fallback when the path has noloader. Registering only the "supported" verb would turn a wrong-verb call into a 404 and hide the real problem. -
One parameter name per path position. Elysia's router rejects
/api/files/:sessionIdand/api/files/:fileId/togglein the same tree. When two routes share a segment position, unify the name (the handlers map it to their own local variable). Current shared names:sessions/:sessionId(also carries a folder id forGET /api/sessions/:sessionId),files/:fileId. -
A STATIC segment that shares a position with a parameter route is registered BEFORE it, and as its own explicit binding.
/api/sessions/batch-deleteand/api/folders/batch-deleteare POST-only entries placed above the:sessionId/:folderIdfamilies, because a parameter route winning the match answers 405 (its handler dispatches on verb) and the batch silently becomes "method not allowed" instead of an unknown path.actionBindingsis deliberately not used for them either — it mounts all four mutating verbs, and a batch verb should not answer PUT/PATCH.
Using Kabmo
How it is built
- Architecture
- Runtime and toolchain
- App shell and layout
- Chat stream and tools
- omp engine and settings
- Plugins, skills and automation
- Desktop integration
- Workspace panels
- Providers
- Harnesses
- Tool panels
Shipping it
History