Dev port allocation and leasing
State: open/verified · Kind: module · Audience: system
Summary
Section titled “Summary”- One allocation table (
dev-ports.yaml) for every development port in the repo, and a resolver that turns a declared port into one a process can actually bind. - Replaces three independent port-picking schemes (a copied shell script, a hand-kept markdown table, literals in config) that could collide invisibly.
Statement
Section titled “Statement”Development ports are assigned from a single root-level registry banded by owning directory
(packages/ts, solutions/determined, solutions/ontological, solutions/augmented, apps/*,
sites), so a stray port is visibly wrong without lookup and a commit guard can reject it. The
resolver hands back the declared port almost always; when the same project runs twice (two
worktrees, a leftover dev server), it searches upward within the owning band only, skipping
browser-unsafe ports. A candidate must win an O_EXCL lease file before a liveness probe, closing
the check-then-act race that let two simultaneous launches pick the same block.
What it provides
Section titled “What it provides”resolveDevPort/resolveDevPortslibrary API and adev-portsCLI (get,resolve,list,free,check) for shell scripts, package.json scripts, and justfiles.- A shared Tauri wrapper (
tauri-wrapper.mjs) that resolves an app’s whole port block (app, storybook, mcp, http) and exports it to the child process. - A commit-time guard (
scripts/guard-dev-ports.ts) that reuses the same parser to fail configs binding or referencing an out-of-band or browser-unsafe port. - A
DEV_PORT_<NAME>env-var escape hatch that bypasses the resolver for manual pinning.
Underlying implementation
Section titled “Underlying implementation”- packages/ts/dev-ports/registry.ts — pure parser over dev-ports.yaml, band/port lookups
- packages/ts/dev-ports/resolve.ts — lease-then-probe fall-forward resolver, using @sksizer/fleet for the lease directory
- packages/ts/dev-ports/cli.ts — CLI surface
- scripts/guard-dev-ports.ts — repo-level pre-commit enforcement, monorepo-specific per lib/ conventions so it stays out of solutions/ontological
Locations
Section titled “Locations”packages/ts/dev-ports/dev-ports.yamlscripts/guard-dev-ports.ts