feat(deploy): support build-time subpath deployments

[SyedMuhamadYasir]

Closes #369.

Studio can now be built for a path such as /tools/libredb and served through a proxy that preserves that prefix. Previously, root-relative APIs, editor assets, redirects and cookies broke deployments on a shared domain.

• Validate BASE_PATH at build time and bake it into Next routing and a shared helper for browser requests, native navigation, metadata and Monaco. Keep Next Link/router paths app-relative so they are prefixed once.
• Scope session and OIDC state cookies to the mount path, delete them with the same path, and prefix OIDC callback/return/error URLs. Match the bare mount path as well as its children: the real browser test caught Next's catch-all skipping /tools/libredb after logout.
• Add the Docker build argument and Compose support. Chart config.basePath prefixes the three default health probes while preserving custom probes. Bump chart 0.1.61 to 0.1.62 (app 0.15.0) and mirror it into the operator.
• Document source/Docker builds, Nginx, Traefik, Ingress, HTTPRoute, auth and npm embedding in docs/SUBPATH.md; retire backlog N3. Add a production browser test to CI through a path-routing proxy that returns 404 outside the mount.

The branch includes upstream 0.15.0. Its catalog-layout error now retains the original error cause, correcting upstream lint and formatting failures; all 77 catalog regression tests pass.

Validation:

• bun run test: 14,637 passed, zero failed; all 34 isolated component groups passed.
• bun run test:coverage && bun run coverage:check: 46,218/46,218 source lines, 100.00%.
• Chromium production flow at /~/libredb through the proxy: login, actual SQLite employee-count query, API calls, self-hosted Monaco, native admin links, server redirects, RBAC, cookie deletion and cross-origin write rejection. No failed app requests or page errors.
• Built and ran the actual Docker image with --build-arg BASE_PATH=/tools/libredb, without a runtime BASE_PATH; the same browser/query flow passed through the proxy. Default root deployment also passed the auth/editor/API/admin/logout browser flow.
• OIDC unit tests verify prefixed callback and logout URLs, state-cookie scope/deletion and callback exchange URL preservation. The production browser test verifies the missing-config OIDC error redirect. A live identity-provider exchange was not run.
• Formatting, lint (zero errors; 133 existing warnings), TypeScript, Knip, README/chart/channel/security guards, strict chart sync, Helm lint, production build, library build, packed-package type resolution, and launcher gofmt/vet/tests passed.

Next.js fixes basePath at build time. The published root image cannot be relocated by a runtime environment variable; operators must rebuild a custom image and preserve the prefix at their proxy. The chart value configures probe paths, not runtime app routing.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cevheri]

I am developing kubernetes operator now, use rebease, upstream please,

[cevheri]

help-wanted @ducminhle

[cevheri]

this is the big-one :) reviewing

[cevheri]

Minor nits (non-blocking)

Three small things found while verifying the subpath work. None is worth holding the PR for.

• Chart schema vs readBasePath. readBasePath("/") accepts / and normalizes it to root (""), while values.schema.json rejects it: config/basePath': '/' does not match pattern '^$|^(/[A-Za-z0-9._~-]+)+$'. Harmless, since the message steers you to "", but a one-line note in the config.basePath description would close the gap.

• Probe helper, explicit path equal to the default. libredb-studio.probe keys off the path value, so an explicit custom probe that sets exactly /api/db/health is indistinguishable from the chart default and gets prefixed too. Measured: --set livenessProbe.httpGet.path=/custom-health stays put, --set livenessProbe.httpGet.path=/api/db/health becomes /tools/libredb/api/db/health. Prefixing is almost certainly what an operator wants there, so this is only about the chart README line "Explicit custom probe paths are preserved" being a little overbroad.

• scripts/operator-catalog-submission.mjs. The { cause: error } fix is already on main in 45f196b with byte-identical content, so this hunk drops out on rebase and the description's note about correcting upstream lint becomes moot.