fix(opencode): support base-path web routing behind Jupyter proxy

[picbeats]

Summary

• add opencode web --base-path with normalization and prefixed URL output/open behavior
• serve API + UI under base path, add local web app dir override (OPENCODE_WEB_APP_DIR) for proxied deployments
• fix prefixed navigation/session behavior by injecting base-path history patch and using router base in web entry
• add server tests for base-path behavior and path-rewrite regressions
• document --base-path usage in web + CLI docs

Verification

• bun test test/server/base-path.test.ts (packages/opencode)
• bun typecheck (packages/opencode)
• bun typecheck (packages/app)
• built binary with ./packages/opencode/script/build.ts --single and validated in Jupyter proxy deployment

Notes

• repository issues are disabled on this fork, so no issue link could be added

[Copilot]

Pull request overview

Adds first-class support for running OpenCode’s web UI/API under a configurable base path (for reverse-proxy/Jupyter proxy deployments), including server-side path mounting/rewriting, app-side router base integration, tests, and documentation.

Changes:

• Add opencode web --base-path and update CLI output/browser-open behavior to include the prefix.
• Serve API + UI under a base prefix in the server, with optional local UI directory override (OPENCODE_WEB_APP_DIR) and URL rewrite/history patching for prefixed navigation.
• Add base-path regression tests and update docs for web + CLI.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
packages/web/src/content/docs/web.mdx	Documents --base-path and reverse-proxy example configuration.
packages/web/src/content/docs/cli.mdx	Adds --base-path flag to CLI docs.
packages/opencode/src/cli/cmd/web.ts	Implements --base-path flag parsing/normalization and prefixed URL display/open.
packages/opencode/src/server/server.ts	Mounts server under base path; adds UI proxy/local dir serving and content rewrites for base-path correctness.
packages/opencode/src/flag/flag.ts	Introduces OPENCODE_WEB_APP_URL and OPENCODE_WEB_APP_DIR env flags.
packages/opencode/src/file/index.ts	Adjusts directory search fallback to return root directories when index has none.
packages/opencode/test/server/base-path.test.ts	Adds coverage for base-path routing and rewrite behaviors.
packages/app/src/entry.tsx	Configures Solid Router base and server URL derivation from injected base path.
packages/app/src/pages/session.tsx	Adds base-path–gated polling to keep session/todo state fresh in proxied deployments.
packages/app/src/context/sync.tsx	Adds sync.session.refresh() used by the new polling logic.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

Pull request overview

Adds first-class support for running OpenCode Web behind a reverse proxy on a sub-path (e.g. JupyterHub), including CLI flagging, server-side base-path routing/proxy rewriting, and app-side router/session behavior fixes.

Changes:

• Add opencode web --base-path and update URL output/open behavior accordingly.
• Serve API + UI under a configurable base path (with optional local UI directory override) and patch client navigation/history to keep the prefix.
• Add server tests for base-path routing and rewrite behavior; update docs for the new flag.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/web/src/content/docs/web.mdx	Documents base-path usage and nginx reverse-proxy example.
packages/web/src/content/docs/cli.mdx	Adds --base-path flag documentation to CLI docs.
packages/opencode/test/server/base-path.test.ts	Introduces tests for base-path routing and proxy rewrite behavior.
packages/opencode/src/server/server.ts	Implements base-path routing, proxy/local-dir UI serving, and HTML/JS/CSS rewriting + history patch injection.
packages/opencode/src/flag/flag.ts	Adds OPENCODE_WEB_APP_URL / OPENCODE_WEB_APP_DIR env flags.
packages/opencode/src/file/index.ts	Adds a short-lived cache for empty-query directory fallback in file search.
packages/opencode/src/cli/cmd/web.ts	Adds --base-path flag parsing/normalization and prefixed URL display/open behavior.
packages/app/src/pages/session.tsx	Adds visibility/active-session-gated refresh polling for base-path deployments.
packages/app/src/entry.tsx	Sets router base + server URL base using injected __OPENCODE_BASE_PATH.
packages/app/src/context/sync.tsx	Adds sync.session.refresh() to refresh session + messages without the sync() early-return shortcut.

Comments suppressed due to low confidence (1)

packages/opencode/src/server/server.ts:310

• /doc is generated via openAPIRouteHandler(inner, ...), so when basePath is configured the OpenAPI spec will still list unprefixed paths (e.g. /event) even though the server only serves /base/event. This will break Swagger/clients in base-path deployments; consider generating the spec from the base-mounted app (or setting servers/base path in the OpenAPI doc) so the emitted paths/servers reflect the configured prefix.

      .get(
        "/doc",
        openAPIRouteHandler(inner, {
          documentation: {
            info: {
              title: "opencode",
              version: "0.0.3",
              description: "opencode api",
            },
            openapi: "3.1.1",
          },
        }),

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.