Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Drift guard for the server's owned URL prefixes, in both directions.
*
* Under `npm run dev` (and under PM2, which runs the UI as the Vite dev server)
* the browser talks to :5554, so anything the API serves must be proxied to
* :5555 — and anything the CLIENT routes must NOT be. Both mistakes fail
* quietly, which is why they are pinned here rather than left to review:
*
* - a MISSING proxy context is answered by Vite's SPA fallback with
* index.html and a 200, so a binary loader parses HTML and reports
* something unrelated to the cause (`/data/image-to-3d` was absent, and the
* GLB viewer died on "Unexpected token '<' ... is not valid JSON");
* - an OVER-BROAD context steals a page: Vite matches a plain context with a
* bare `url.startsWith`, so a `'/data'` key would also capture the `/data`
* and `/datadog` routes and hand the browser the API's built index.html.
*
* Production has the same hole on the other side — the SPA fallback in
* `server/index.js` skips a request only when its path carries a file
* extension. `SERVER_OWNED_PREFIXES` is what closes it, and the third section
* below covers the one failure neither the proxy nor the terminator can see
* alone: a client route added UNDER a server-owned prefix, which the terminator
* would 404 with nothing failing near the new route.
*
* Full story in docs/PORTS.md.
*/
import { describe, it, expect } from 'vitest';
import { readFileSync } from 'fs';
import { dirname, join } from 'path';
import { fileURLToPath } from 'url';
import { NAV_COMMANDS } from '../server/lib/navManifest.js';
import { ASSET_ROUTE_PREFIXES, SERVER_OWNED_PREFIXES } from '../server/lib/assetRoutePrefixes.js';
import { ASSET_MOUNTS } from '../server/services/assetMounts.js';
const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
const read = (rel) => readFileSync(join(REPO_ROOT, rel), 'utf8');
/**
* Every proxy context in the dev server config.
*
* Read out of the source text rather than by importing the config and calling
* it: this suite runs on the SERVER test runner, whose CI job installs only the
* server's dependencies, so `import('../client/vite.config.js')` dies on
* `@vitejs/plugin-react` with ERR_MODULE_NOT_FOUND (it passes locally, where
* every workspace is installed — don't "improve" it back into an import).
* The capture keeps a leading `^` because that character is what makes a
* context a regex, and telling those apart is the whole point below.
*/
function devProxyContexts(source) {
const proxyBlock = source.slice(source.indexOf('proxy: {'));
return [...proxyBlock.matchAll(/['"](\^?\/[^'"]*)['"]\s*:\s*\{/g)].map(([, context]) => context);
}
/**
* Vite's own matcher, mirrored from `doesProxyContextMatchUrl` — a leading `^`
* makes the context a regex, anything else is a bare prefix test. Re-deriving
* it here is the point: the bug this guards is a context whose match is wider
* than it looks.
*/
const proxyMatches = (context, url) =>
(context[0] === '^' && new RegExp(context).test(url)) || url.startsWith(context);
const navPaths = NAV_COMMANDS.map((command) => command.path);
/**
* Every path the client router declares, with nesting resolved.
*
* NOT just `NAV_COMMANDS`: `client/src/AGENTS.md` requires a selectable view to
* register only its BASE path in the nav manifest while its `:id` detail route
* lives in `App.jsx` alone. A convention-following `<Route path="data/:category">`
* would therefore be invisible to a nav-manifest-only check — and the terminator
* would 404 it in production with nothing failing near the new route.
*
* Nesting has to be RESOLVED, not read off each tag, because App.jsx nests:
* `<Route path="media" …><Route path="image" …/></Route>` is `/media/image`.
* That takes both halves — matching each opener's real end, and popping on its
* closer — and getting either wrong fails SILENTLY, as a guard that passes.
* Hence the hand-rolled scan below rather than a regex per tag: a tag's
* attributes contain `>` inside JSX expressions (`element={<MediaGen />}`), so
* anything matching `<Route[^>]*>` ends the tag mid-attribute. Parsing properly
* would mean pulling a JSX parser into the SERVER test runner, whose CI job
* installs only the server's dependencies — so this tracks depth itself.
*/
function clientRoutePaths(source) {
const paths = [];
const stack = [];
// Drive off BOTH tags: the closer is what unwinds nesting. Reading only
// openers makes the stack grow forever, so everything after the first
// container route inherits its segment (`/sprites` becomes `/media/sprites`)
// and a later `/data/...` page hides behind that prefix — a silent false pass
// in exactly the case this scan exists for.
const TAGS = /<Route(?![A-Za-z])|<\/Route\s*>/g;
let match;
while ((match = TAGS.exec(source)) !== null) {
if (match[0][1] === '/') { stack.pop(); continue; }
// Find the real end of the tag. `>` also appears INSIDE attributes
// (`element={<MediaGen />}`), so track brace depth and quotes rather than
// stopping at the first one.
let depth = 0;
let quote = null;
let end = -1;
for (let j = TAGS.lastIndex; j < source.length; j++) {
const char = source[j];
if (quote) { if (char === quote) quote = null; continue; }
if (char === '"' || char === "'" || char === '`') { quote = char; continue; }
if (char === '{') depth += 1;
else if (char === '}') depth -= 1;
else if (char === '>' && depth === 0) { end = j; break; }
}
if (end === -1) break;
const attrs = source.slice(TAGS.lastIndex, end);
const selfClosing = attrs.trimEnd().endsWith('/');
// An index route (no `path`) resolves to its parent, and a pathless layout
// route adds no segment — both are a null frame on the stack.
const path = attrs.match(/\bpath="([^"]*)"/)?.[1] ?? null;
if (path !== null) {
const joined = [...stack, path].filter((segment) => segment).join('/').replace(/\/+/g, '/');
paths.push(joined.startsWith('/') ? joined : `/${joined}`);
}
if (!selfClosing) stack.push(path);
TAGS.lastIndex = end + 1;
}
return paths;
}
describe('vite dev proxy vs the server and the client router', () => {
// The mounts come from the table `server/index.js` mounts from, not from a
// regex over its source — that table is why the two cannot disagree.
const contexts = devProxyContexts(read('client/vite.config.js'));
it('finds the prefixes and the proxy contexts it is comparing', () => {
// An empty list on either side would make every assertion below vacuously
// true — this is the one that fails if the wiring itself breaks.
expect(ASSET_ROUTE_PREFIXES.length).toBeGreaterThan(5);
expect(contexts).toContain('^/api(?:/|$)');
expect(navPaths.length).toBeGreaterThan(5);
});
it('proxies an asset under every mount the server serves', () => {
const unproxied = ASSET_ROUTE_PREFIXES.filter(
(route) => !contexts.some((context) => proxyMatches(context, `${route}/probe.bin`)),
);
expect(unproxied).toEqual([]);
});
it('leaves every client route to the dev server', () => {
const stolen = navPaths.filter(
(path) => contexts.some((context) => proxyMatches(context, path)),
);
expect(stolen).toEqual([]);
});
});
describe('the asset table vs what the server mounts', () => {
it('has a mount, in order, for every asset route prefix', () => {
// `ASSET_MOUNTS` is what actually gets mounted; the prefix list is what the
// dev proxy is checked against. A route in one and not the other is drift.
expect(ASSET_MOUNTS.map((mount) => mount.route)).toEqual(ASSET_ROUTE_PREFIXES);
expect(ASSET_MOUNTS.every((mount) => typeof mount.dir === 'function')).toBe(true);
});
it('serves every asset route from inside a terminated namespace', () => {
// A mount outside every `SERVER_OWNED_PREFIXES` entry keeps the pre-#4688
// behaviour: an extensionless path under it answered with the SPA index.
const prefixes = SERVER_OWNED_PREFIXES.map(({ prefix }) => prefix);
const unterminated = ASSET_ROUTE_PREFIXES.filter(
(route) => !prefixes.some((prefix) => route.startsWith(`${prefix}/`)),
);
expect(unterminated).toEqual([]);
});
});
describe('server-owned prefixes vs the client router', () => {
const routePaths = [...new Set([...navPaths, ...clientRoutePaths(read('client/src/App.jsx'))])];
it('resolves App.jsx\'s nesting in BOTH directions', () => {
// Asserting on the UNION would prove nothing — NAV_COMMANDS alone satisfies
// it, so `clientRoutePaths` could return [] and stay green. Both halves of
// the scan get their own probe because each fails silently, as a PASS:
const scanned = clientRoutePaths(read('client/src/App.jsx'));
// ...a child must inherit its parent's segment (a per-tag regex ends at the
// `>` inside `element={<MediaGen />}` and reads this as a sibling, `/image`);
expect(scanned).toContain('/media/image');
expect(scanned).not.toContain('/image');
// ...and a closer must POP it again. Without that the stack only grows, and
// every route declared after the first container inherits its prefix — which
// is what hides a later `/data/...` page from the check below.
expect(scanned).toContain('/sprites');
expect(scanned).toContain('/writers-room');
expect(routePaths).toContain('/data');
});
it('declares every client route that lives under a server-owned prefix', () => {
// The failure this catches: someone adds a `/data/backups` page. The
// terminator 404s it, the page simply does not exist, and nothing points at
// `assetRoutePrefixes.js`. Adding the route to that entry's `spaPaths` is
// the fix — this test is what says so.
const undeclared = SERVER_OWNED_PREFIXES.flatMap(({ prefix, spaPaths }) => (
routePaths.filter((path) => (
(path === prefix || path.startsWith(`${prefix}/`)) && !spaPaths.includes(path)
))
));
expect(undeclared).toEqual([]);
});
});
describe('server/index.js route registration order', () => {
// `mountAssetRoutes` installs a terminating 404 on /api and /sdapi, so
// registration order became load-bearing: a router added BELOW the call is
// shadowed by that 404 and never runs. Nothing else reads this file any
// more — the drift guard reads the tables — so this is what catches it.
const source = read('server/index.js');
it('registers every API router above the terminators', () => {
const mountIndex = source.indexOf('mountAssetRoutes(app)');
expect(mountIndex).toBeGreaterThan(0);
const apiMounts = [...source.matchAll(/app\.use\(\s*'(\/(?:api|sdapi)[^']*)'/g)];
// A refactor to non-literal mounts would leave the regex matching nothing
// and the assertion below vacuously true.
expect(apiMounts.length).toBeGreaterThan(20);
const shadowed = apiMounts
.filter((match) => match.index > mountIndex)
.map(([, route]) => route);
expect(shadowed).toEqual([]);
});
it('leaves no asset mount behind in the file the table replaced', () => {
// An inline `app.use('/data/x', express.static(…))` added back here would sit
// BELOW the terminator and be dead — and would miss the dev proxy too.
expect(source).not.toMatch(/app\.use\(\s*'\/data[^']*',\s*express\.static/);
});
});